2 .\" MAN PAGE COMMENTS to
5 .\" Case Western Reserve University
6 .\" chet.ramey@case.edu
8 .\" Last Change: Mon Sep 19 11:13:21 EDT 2022
10 .\" bash_builtins, strip all but Built-Ins section
13 .TH BASH 1 "2022 September 19" "GNU Bash 5.2"
15 .\" There's some problem with having a `@'
16 .\" in a tagged paragraph with the BSD man macros.
17 .\" It has to do with `@' appearing in the }1 macro.
18 .\" This is a problem on 4.3 BSD and Ultrix, but Sun
19 .\" appears to have fixed it.
20 .\" If you're seeing the characters
21 .\" `@u-3p' appearing before the lines reading
22 .\" `possible-hostname-completions
23 .\" and `complete-hostname' down in READLINE,
24 .\" then uncomment this redefinition.
29 .\" .if !"\\$1"" .nr )I \\$1n
32 .\" .in \\n()Ru+\\n(INu+\\n()Iu
34 .\" .ie !\\n()Iu+\\n()Ru-\w
\a\\*(]X
\au-3p \{\\*(]X
36 .\" .el \\*(]X\h
\a|\\n()Iu+\\n()Ru
\a\c
40 .\" File Name macro. This used to be `.PN', for Path Name,
41 .\" but Sun doesn't seem to like that very much.
47 bash \- GNU Bourne-Again SHell
51 [command_string | file]
53 .if n Bash is Copyright (C) 1989-2022 by the Free Software Foundation, Inc.
54 .if t Bash is Copyright \(co 1989-2022 by the Free Software Foundation, Inc.
57 is an \fBsh\fR-compatible command language interpreter that
58 executes commands read from the standard input or from a file.
60 also incorporates useful features from the \fIKorn\fP and \fIC\fP
61 shells (\fBksh\fP and \fBcsh\fP).
64 is intended to be a conformant implementation of the
65 Shell and Utilities portion of the IEEE POSIX specification
66 (IEEE Standard 1003.1).
68 can be configured to be POSIX-conformant by default.
70 All of the single-character shell options documented in the
71 description of the \fBset\fR builtin command, including \fB\-o\fP,
72 can be used as options when the shell is invoked.
73 In addition, \fBbash\fR
74 interprets the following options when it is invoked:
81 option is present, then commands are read from the first non-option argument
83 If there are arguments after the
85 the first argument is assigned to
87 and any remaining arguments are assigned to the positional parameters.
90 sets the name of the shell, which is used in warning and error messages.
95 option is present, the shell is
101 act as if it had been invoked as a login shell (see
109 option is present, the shell becomes
113 .B "RESTRICTED SHELL"
119 option is present, or if no arguments remain after option
120 processing, then commands are read from the standard input.
121 This option allows the positional parameters to be set
122 when invoking an interactive shell or when reading input
126 A list of all double-quoted strings preceded by \fB$\fP
127 is printed on the standard output.
128 These are the strings that
129 are subject to language translation when the current locale
130 is not \fBC\fP or \fBPOSIX\fP.
131 This implies the \fB\-n\fP option; no commands will be executed.
133 .B [\-+]O [\fIshopt_option\fP]
134 \fIshopt_option\fP is one of the shell options accepted by the
135 \fBshopt\fP builtin (see
137 .B SHELL BUILTIN COMMANDS
139 If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option;
141 If \fIshopt_option\fP is not supplied, the names and values of the shell
142 options accepted by \fBshopt\fP are printed on the standard output.
143 If the invocation option is \fB+O\fP, the output is displayed in a format
144 that may be reused as input.
149 signals the end of options and disables further option processing.
150 Any arguments after the
152 are treated as filenames and arguments. An argument of
154 is equivalent to \fB\-\-\fP.
158 also interprets a number of multi-character options.
159 These options must appear on the command line before the
160 single-character options to be recognized.
165 Arrange for the debugger profile to be executed before the shell
167 Turns on extended debugging mode (see the description of the
173 .B \-\-dump\-po\-strings
174 Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP
175 \fBpo\fP (portable object) file format.
178 Equivalent to \fB\-D\fP.
181 Display a usage message on standard output and exit successfully.
183 \fB\-\-init\-file\fP \fIfile\fP
186 \fB\-\-rcfile\fP \fIfile\fP
188 Execute commands from
190 instead of the standard personal initialization file
192 if the shell is interactive (see
198 Equivalent to \fB\-l\fP.
203 library to read command lines when the shell is interactive.
206 Do not read either the system-wide startup file
208 or any of the personal initialization files
209 .IR ~/.bash_profile ,
215 reads these files when it is invoked as a login shell (see
221 Do not read and execute the personal initialization file
223 if the shell is interactive.
224 This option is on by default if the shell is invoked as
228 Change the behavior of \fBbash\fP where the default operation differs
229 from the POSIX standard to match the standard (\fIposix mode\fP).
233 below for a reference to a document that details how posix mode affects
237 The shell becomes restricted (see
239 .B "RESTRICTED SHELL"
243 Equivalent to \fB\-v\fP.
246 Show version information for this instance of
248 on the standard output and exit successfully.
251 If arguments remain after option processing, and neither the
255 option has been supplied, the first argument is assumed to
256 be the name of a file containing shell commands.
259 is invoked in this fashion,
261 is set to the name of the file, and the positional parameters
262 are set to the remaining arguments.
264 reads and executes commands from this file, then exits.
265 \fBBash\fP's exit status is the exit status of the last command
266 executed in the script.
267 If no commands are executed, the exit status is 0.
268 An attempt is first made to open the file in the current directory, and,
269 if no file is found, then the shell searches the directories in
274 A \fIlogin shell\fP is one whose first character of argument zero is a
276 or one started with the
280 An \fIinteractive\fP shell is one started without non-option arguments
281 (unless \fB\-s\fP is specified)
285 whose standard input and error are
286 both connected to terminals (as determined by
288 or one started with the
300 allowing a shell script or a startup file to test this state.
302 The following paragraphs describe how
304 executes its startup files.
305 If any of the files exist but cannot be read,
308 Tildes are expanded in filenames as described below under
317 is invoked as an interactive login shell, or as a non-interactive shell
318 with the \fB\-\-login\fP option, it first reads and
319 executes commands from the file \fI/etc/profile\fP, if that
321 After reading that file, it looks for \fI~/.bash_profile\fP,
322 \fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads
323 and executes commands from the first one that exists and is readable.
326 option may be used when the shell is started to inhibit this behavior.
328 When an interactive login shell exits,
329 or a non-interactive login shell executes the \fBexit\fP builtin command,
331 reads and executes commands from the file \fI~/.bash_logout\fP, if it
334 When an interactive shell that is not a login shell is started,
336 reads and executes commands from \fI~/.bashrc\fP, if that file exists.
337 This may be inhibited by using the
340 The \fB\-\-rcfile\fP \fIfile\fP option will force
342 to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP.
346 is started non-interactively, to run a shell script, for example, it
347 looks for the variable
350 in the environment, expands its value if it appears there, and uses the
351 expanded value as the name of a file to read and execute.
353 behaves as if the following command were executed:
356 .if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP
357 .if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
363 variable is not used to search for the filename.
367 is invoked with the name
369 it tries to mimic the startup behavior of historical versions of
371 as closely as possible,
372 while conforming to the POSIX standard as well.
373 When invoked as an interactive login shell, or a non-interactive
374 shell with the \fB\-\-login\fP option, it first attempts to
375 read and execute commands from
382 option may be used to inhibit this behavior.
383 When invoked as an interactive shell with the name
386 looks for the variable
389 expands its value if it is defined, and uses the
390 expanded value as the name of a file to read and execute.
391 Since a shell invoked as
393 does not attempt to read and execute commands from any other startup
396 option has no effect.
397 A non-interactive shell invoked with the name
399 does not attempt to read any other startup files.
405 mode after the startup files are read.
413 command line option, it follows the POSIX standard for startup files.
414 In this mode, interactive shells expand the
417 variable and commands are read and executed from the file
418 whose name is the expanded value.
419 No other startup files are read.
422 attempts to determine when it is being run with its standard input
423 connected to a network connection, as when executed by
424 the historical remote shell daemon, usually \fIrshd\fP,
425 or the secure shell daemon \fIsshd\fP.
428 determines it is being run non-interactively in this fashion,
429 it reads and executes commands from \fI~/.bashrc\fP,
430 if that file exists and is readable.
431 It will not do this if invoked as \fBsh\fP.
434 option may be used to inhibit this behavior, and the
436 option may be used to force another file to be read, but neither
437 \fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options
438 or allow them to be specified.
440 If the shell is started with the effective user (group) id not equal to the
441 real user (group) id, and the \fB\-p\fP option is not supplied, no startup
442 files are read, shell functions are not inherited from the environment, the
452 variables, if they appear in the environment, are ignored,
453 and the effective user id is set to the real user id.
454 If the \fB\-p\fP option is supplied at invocation, the startup behavior is
455 the same, but the effective user id is not reset.
457 The following definitions are used throughout the rest of this
465 A sequence of characters considered as a single unit by the shell.
472 consisting only of alphanumeric characters and underscores, and
473 beginning with an alphabetic character or an underscore. Also
478 A character that, when unquoted, separates words. One of the following:
482 .if t \fB| & ; ( ) < > space tab newline\fP
483 .if n \fB| & ; ( ) < > space tab newline\fP
487 A \fItoken\fP that performs a control function. It is one of the following
491 .if t \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
492 .if n \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP
496 \fIReserved words\fP are words that have a special meaning to the shell.
497 The following words are recognized as reserved when unquoted and either
498 the first word of a command (see
501 below), the third word of a
506 (only \fBin\fP is valid), or the third word of a
508 command (only \fBin\fP and \fBdo\fP are valid):
512 .if n ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
513 .if t ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
516 This section describes the syntax of the various forms of shell commands.
518 A \fIsimple command\fP is a sequence of optional variable assignments
519 followed by \fBblank\fP-separated words and redirections, and
520 terminated by a \fIcontrol operator\fP. The first word
521 specifies the command to be executed, and is passed as argument zero.
522 The remaining words are passed as arguments to the invoked command.
524 The return value of a \fIsimple command\fP is its exit status, or
525 128+\fIn\^\fP if the command is terminated by signal
528 A \fIpipeline\fP is a sequence of one or more commands separated by
529 one of the control operators
532 The format for a pipeline is:
535 [\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] \fIcommand2\fP ... ]
538 The standard output of
540 is connected via a pipe to the standard input of
542 This connection is performed before any redirections specified by the
547 If \fB|&\fP is used, \fIcommand1\fP's standard error, in addition to its
548 standard output, is connected to
549 \fIcommand2\fP's standard input through the pipe;
550 it is shorthand for \fB2>&1 |\fP.
551 This implicit redirection of the standard error to the standard output is
552 performed after any redirections specified by \fIcommand1\fP.
554 The return status of a pipeline is the exit status of the last
555 command, unless the \fBpipefail\fP option is enabled.
556 If \fBpipefail\fP is enabled, the pipeline's return status is the
557 value of the last (rightmost) command to exit with a non-zero status,
558 or zero if all commands exit successfully.
561 precedes a pipeline, the exit status of that pipeline is the logical
562 negation of the exit status as described above.
563 The shell waits for all commands in the pipeline to
564 terminate before returning a value.
568 reserved word precedes a pipeline, the elapsed as well as user and
569 system time consumed by its execution are reported when the pipeline
571 The \fB\-p\fP option changes the output format to that specified by POSIX.
572 When the shell is in \fIposix mode\fP, it does not recognize
573 \fBtime\fP as a reserved word if the next token begins with a `-'.
577 variable may be set to a format string that specifies how the timing
578 information should be displayed; see the description of
585 When the shell is in \fIposix mode\fP, \fBtime\fP
586 may be followed by a newline. In this case, the shell displays the
587 total user and system time consumed by the shell and its children.
591 variable may be used to specify the format of
592 the time information.
594 Each command in a multi-command pipeline,
595 where pipes are created,
596 is executed in a \fIsubshell\fP, which is a
600 \fBCOMMAND EXECUTION ENVIRONMENT\fP
601 for a description of subshells and a subshell environment.
602 If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin
603 (see the description of \fBshopt\fP below),
604 the last element of a pipeline may be run by the shell process
605 when job control is not active.
607 A \fIlist\fP is a sequence of one or more pipelines separated by one
614 and optionally terminated by one of
620 Of these list operators,
624 have equal precedence, followed by
628 which have equal precedence.
630 A sequence of one or more newlines may appear in a \fIlist\fP instead
631 of a semicolon to delimit commands.
633 If a command is terminated by the control operator
635 the shell executes the command in the \fIbackground\fP
637 The shell does not wait for the command to
638 finish, and the return status is 0.
639 These are referred to as \fIasynchronous\fP commands.
640 Commands separated by a
642 are executed sequentially; the shell waits for each
643 command to terminate in turn. The return status is the
644 exit status of the last command executed.
646 AND and OR lists are sequences of one or more pipelines separated by the
647 \fB&&\fP and \fB||\fP control operators, respectively.
648 AND and OR lists are executed with left associativity.
649 An AND list has the form
652 \fIcommand1\fP \fB&&\fP \fIcommand2\fP
656 is executed if, and only if,
658 returns an exit status of zero (success).
660 An OR list has the form
663 \fIcommand1\fP \fB||\fP \fIcommand2\fP
667 is executed if, and only if,
669 returns a non-zero exit status.
671 AND and OR lists is the exit status of the last command
672 executed in the list.
673 .SS Compound Commands
674 A \fIcompound command\fP is one of the following.
675 In most cases a \fIlist\fP in a command's description may be separated from
676 the rest of the command by one or more newlines, and may be followed by a
677 newline in place of a semicolon.
680 \fIlist\fP is executed in a subshell (see
682 \fBCOMMAND EXECUTION ENVIRONMENT\fP
683 below for a description of a subshell environment).
684 Variable assignments and builtin
685 commands that affect the shell's environment do not remain in effect
686 after the command completes. The return status is the exit status of
690 \fIlist\fP is simply executed in the current shell environment.
691 \fIlist\fP must be terminated with a newline or semicolon.
692 This is known as a \fIgroup command\fP.
693 The return status is the exit status of
695 Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and
696 \fB}\fP are \fIreserved words\fP and must occur where a reserved
697 word is permitted to be recognized. Since they do not cause a word
698 break, they must be separated from \fIlist\fP by whitespace or another
702 The \fIexpression\fP is evaluated according to the rules described
705 .BR "ARITHMETIC EVALUATION" .
706 If the value of the expression is non-zero, the return status is 0;
707 otherwise the return status is 1.
709 undergoes the same expansions
710 as if it were within double quotes,
711 but double quote characters in \fIexpression\fP are not treated specially
714 \fB[[\fP \fIexpression\fP \fB]]\fP
715 Return a status of 0 or 1 depending on the evaluation of
716 the conditional expression \fIexpression\fP.
717 Expressions are composed of the primaries described below under
719 .BR "CONDITIONAL EXPRESSIONS" .
720 The words between the \fB[[\fP and \fB]]\fP do not undergo word splitting
721 and pathname expansion.
722 The shell performs tilde expansion, parameter and
723 variable expansion, arithmetic expansion, command substitution, process
724 substitution, and quote removal on those words
725 (the expansions that would occur if the words were enclosed in double quotes).
726 Conditional operators such as \fB\-f\fP must be unquoted to be recognized
730 When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
731 lexicographically using the current locale.
734 When the \fB==\fP and \fB!=\fP operators are used, the string to the
735 right of the operator is considered a pattern and matched according
736 to the rules described below under \fBPattern Matching\fP,
737 as if the \fBextglob\fP shell option were enabled.
738 The \fB=\fP operator is equivalent to \fB==\fP.
741 shell option is enabled, the match is performed without regard to the case
742 of alphabetic characters.
743 The return value is 0 if the string matches (\fB==\fP) or does not match
744 (\fB!=\fP) the pattern, and 1 otherwise.
745 Any part of the pattern may be quoted to force the quoted portion
746 to be matched as a string.
749 An additional binary operator, \fB=~\fP, is available, with the same
750 precedence as \fB==\fP and \fB!=\fP.
751 When it is used, the string to the right of the operator is considered
752 a POSIX extended regular expression and matched accordingly
753 (using the POSIX \fIregcomp\fP and \fIregexec\fP interfaces
754 usually described in \fIregex\fP(3)).
755 The return value is 0 if the string matches
756 the pattern, and 1 otherwise.
757 If the regular expression is syntactically incorrect, the conditional
758 expression's return value is 2.
761 shell option is enabled, the match is performed without regard to the case
762 of alphabetic characters.
763 If any part of the pattern is quoted, the quoted portion is matched literally.
764 This means every character in the quoted portion matches itself,
765 instead of having any special pattern matching meaning.
766 If the pattern is stored in a shell variable, quoting the variable
767 expansion forces the entire pattern to be matched literally.
768 Treat bracket expressions in regular expressions carefully,
769 since normal quoting and pattern characters lose their meanings
773 The pattern will match if it matches any part of the string.
774 Anchor the pattern using the \fB^\fP and \fB$\fP regular expression
775 operators to force it to match the entire string.
779 records which parts of the string matched the pattern.
783 with index 0 contains the portion of
784 the string matching the entire regular expression.
785 Substrings matched by parenthesized subexpressions within the regular
786 expression are saved in the remaining
789 indices. The element of
792 with index \fIn\fP is the portion of the
793 string matching the \fIn\fPth parenthesized subexpression.
797 in the global scope; declaring it as a local variable will lead to
801 Expressions may be combined using the following operators, listed
802 in decreasing order of precedence:
808 .B ( \fIexpression\fP )
809 Returns the value of \fIexpression\fP.
810 This may be used to override the normal precedence of operators.
812 .B ! \fIexpression\fP
817 \fIexpression1\fP \fB&&\fP \fIexpression2\fP
824 \fIexpression1\fP \fB||\fP \fIexpression2\fP
832 The \fB&&\fP and \fB||\fP
833 operators do not evaluate \fIexpression2\fP if the value of
834 \fIexpression1\fP is sufficient to determine the return value of
835 the entire conditional expression.
838 \fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
839 The list of words following \fBin\fP is expanded, generating a list
841 The variable \fIname\fP is set to each element of this list
842 in turn, and \fIlist\fP is executed each time.
843 If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes
844 \fIlist\fP once for each positional parameter that is set (see
848 The return status is the exit status of the last command that executes.
849 If the expansion of the items following \fBin\fP results in an empty
850 list, no commands are executed, and the return status is 0.
852 \fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP
853 First, the arithmetic expression \fIexpr1\fP is evaluated according
854 to the rules described below under
856 .BR "ARITHMETIC EVALUATION" .
857 The arithmetic expression \fIexpr2\fP is then evaluated repeatedly
858 until it evaluates to zero.
859 Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is
860 executed and the arithmetic expression \fIexpr3\fP is evaluated.
861 If any expression is omitted, it behaves as if it evaluates to 1.
862 The return value is the exit status of the last command in \fIlist\fP
863 that is executed, or false if any of the expressions is invalid.
865 \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP
866 The list of words following \fBin\fP is expanded, generating a list
867 of items, and the set of expanded words is printed on the standard
868 error, each preceded by a number. If the \fBin\fP
869 \fIword\fP is omitted, the positional parameters are printed (see
877 prompt and reads a line from the standard input.
878 If the line consists of a number corresponding to one of
879 the displayed words, then the value of
882 If the line is empty, the words and prompt are displayed again.
883 If EOF is read, the \fBselect\fP command completes and returns 1.
884 Any other value read causes
886 to be set to null. The line read is saved in the variable
891 is executed after each selection until a
896 is the exit status of the last command executed in
898 or zero if no commands were executed.
900 \fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
901 ... ) \fIlist\fP ;; ] ... \fBesac\fP
902 A \fBcase\fP command first expands \fIword\fP, and tries to match
903 it against each \fIpattern\fP in turn, using the matching rules
907 The \fIword\fP is expanded using tilde
908 expansion, parameter and variable expansion, arithmetic expansion,
909 command substitution, process substitution and quote removal.
910 Each \fIpattern\fP examined is expanded using tilde
911 expansion, parameter and variable expansion, arithmetic expansion,
912 command substitution, process substitution, and quote removal.
915 shell option is enabled, the match is performed without regard to the case
916 of alphabetic characters.
917 When a match is found, the corresponding \fIlist\fP is executed.
918 If the \fB;;\fP operator is used, no subsequent matches are attempted after
919 the first pattern match.
920 Using \fB;&\fP in place of \fB;;\fP causes execution to continue with
921 the \fIlist\fP associated with the next set of patterns.
922 Using \fB;;&\fP in place of \fB;;\fP causes the shell to test the next
923 pattern list in the statement, if any, and execute any associated \fIlist\fP
924 on a successful match,
925 continuing the case statement execution as if the pattern list had not matched.
926 The exit status is zero if no
927 pattern matches. Otherwise, it is the exit status of the
928 last command executed in \fIlist\fP.
930 \fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \
931 [ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
932 [ \fBelse\fP \fIlist\fP; ] \fBfi\fP
936 is executed. If its exit status is zero, the
937 \fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP
938 \fIlist\fP is executed in turn, and if its exit status is zero,
939 the corresponding \fBthen\fP \fIlist\fP is executed and the
940 command completes. Otherwise, the \fBelse\fP \fIlist\fP is
941 executed, if present. The exit status is the exit status of the
942 last command executed, or zero if no condition tested true.
944 \fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
947 \fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP
949 The \fBwhile\fP command continuously executes the list
950 \fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns
951 an exit status of zero. The \fBuntil\fP command is identical
952 to the \fBwhile\fP command, except that the test is negated:
954 is executed as long as the last command in
956 returns a non-zero exit status.
957 The exit status of the \fBwhile\fP and \fBuntil\fP commands
959 of the last command executed in \fIlist-2\fP, or zero if
962 A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved
964 A coprocess is executed asynchronously in a subshell, as if the command
965 had been terminated with the \fB&\fP control operator, with a two-way pipe
966 established between the executing shell and the coprocess.
968 The syntax for a coprocess is:
971 \fBcoproc\fP [\fINAME\fP] \fIcommand\fP [\fIredirections\fP]
974 This creates a coprocess named \fINAME\fP.
975 \fIcommand\fP may be either a simple command or a compound
977 \fINAME\fP is a shell variable name.
978 If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP.
980 The recommended form to use for a coprocess is
983 \fBcoproc\fP \fINAME\fP { \fIcommand\fP [\fIredirections\fP]; }
986 This form is recommended because simple commands result in the coprocess
987 always being named \fBCOPROC\fP, and it is simpler to use and more complete
988 than the other compound commands.
990 If \fIcommand\fP is a compound command, \fINAME\fP is optional. The
991 word following \fBcoproc\fP determines whether that word is interpreted
992 as a variable name: it is interpreted as \fINAME\fP if it is not a
993 reserved word that introduces a compound command.
994 If \fIcommand\fP is a simple command, \fINAME\fP is not allowed; this
995 is to avoid confusion between \fINAME\fP and the first word of the simple
998 When the coprocess is executed, the shell creates an array variable (see
1000 below) named \fINAME\fP in the context of the executing shell.
1001 The standard output of
1003 is connected via a pipe to a file descriptor in the executing shell,
1004 and that file descriptor is assigned to \fINAME\fP[0].
1005 The standard input of
1007 is connected via a pipe to a file descriptor in the executing shell,
1008 and that file descriptor is assigned to \fINAME\fP[1].
1009 This pipe is established before any redirections specified by the
1014 The file descriptors can be utilized as arguments to shell commands
1015 and redirections using standard word expansions.
1016 Other than those created to execute command and process substitutions,
1017 the file descriptors are not available in subshells.
1019 The process ID of the shell spawned to execute the coprocess is
1020 available as the value of the variable \fINAME\fP_PID.
1022 builtin command may be used to wait for the coprocess to terminate.
1024 Since the coprocess is created as an asynchronous command,
1025 the \fBcoproc\fP command always returns success.
1026 The return status of a coprocess is the exit status of \fIcommand\fP.
1027 .SS Shell Function Definitions
1028 A shell function is an object that is called like a simple command and
1029 executes a compound command with a new set of positional parameters.
1030 Shell functions are declared as follows:
1032 \fIfname\fP () \fIcompound\-command\fP [\fIredirection\fP]
1035 \fBfunction\fP \fIfname\fP [()] \fIcompound\-command\fP [\fIredirection\fP]
1037 This defines a function named \fIfname\fP.
1038 The reserved word \fBfunction\fP is optional.
1039 If the \fBfunction\fP reserved word is supplied, the parentheses are optional.
1040 The \fIbody\fP of the function is the compound command
1041 .I compound\-command
1042 (see \fBCompound Commands\fP above).
1043 That command is usually a \fIlist\fP of commands between { and }, but
1044 may be any command listed under \fBCompound Commands\fP above.
1045 If the \fBfunction\fP reserved word is used, but the
1046 parentheses are not supplied, the braces are recommended.
1047 \fIcompound\-command\fP is executed whenever \fIfname\fP is specified as the
1048 name of a simple command.
1049 When in \fIposix mode\fP, \fIfname\fP must be a valid shell \fIname\fP
1050 and may not be the name of one of the
1051 POSIX \fIspecial builtins\fP.
1052 In default mode, a function name can be any unquoted shell word that does
1053 not contain \fB$\fP.
1054 Any redirections (see
1057 below) specified when a function is defined are performed
1058 when the function is executed.
1059 The exit status of a function definition is zero unless a syntax error
1060 occurs or a readonly function with the same name already exists.
1061 When executed, the exit status of a function is the exit status of the
1062 last command executed in the body. (See
1067 In a non-interactive shell, or an interactive shell in which the
1068 .B interactive_comments
1071 builtin is enabled (see
1073 .B "SHELL BUILTIN COMMANDS"
1074 below), a word beginning with
1076 causes that word and all remaining characters on that line to
1077 be ignored. An interactive shell without the
1078 .B interactive_comments
1079 option enabled does not allow comments. The
1080 .B interactive_comments
1081 option is on by default in interactive shells.
1083 \fIQuoting\fP is used to remove the special meaning of certain
1084 characters or words to the shell. Quoting can be used to
1085 disable special treatment for special characters, to prevent
1086 reserved words from being recognized as such, and to prevent
1087 parameter expansion.
1089 Each of the \fImetacharacters\fP listed above under
1092 has special meaning to the shell and must be quoted if it is to
1095 When the command history expansion facilities are being used
1098 .B HISTORY EXPANSION
1100 \fIhistory expansion\fP character, usually \fB!\fP, must be quoted
1101 to prevent history expansion.
1103 There are three quoting mechanisms: the
1104 .IR "escape character" ,
1105 single quotes, and double quotes.
1107 A non-quoted backslash (\fB\e\fP) is the
1108 .IR "escape character" .
1109 It preserves the literal value of the next character that follows,
1110 with the exception of <newline>. If a \fB\e\fP<newline> pair
1111 appears, and the backslash is not itself quoted, the \fB\e\fP<newline>
1112 is treated as a line continuation (that is, it is removed from the
1113 input stream and effectively ignored).
1115 Enclosing characters in single quotes preserves the literal value
1116 of each character within the quotes. A single quote may not occur
1117 between single quotes, even when preceded by a backslash.
1119 Enclosing characters in double quotes preserves the literal value
1120 of all characters within the quotes, with the exception of
1124 and, when history expansion is enabled,
1126 When the shell is in \fIposix mode\fP, the \fB!\fP has no special meaning
1127 within double quotes, even when history expansion is enabled.
1132 retain their special meaning within double quotes. The backslash
1133 retains its special meaning only when followed by one of the following
1141 A double quote may be quoted within double quotes by preceding it with
1143 If enabled, history expansion will be performed unless an
1145 appearing in double quotes is escaped using a backslash.
1146 The backslash preceding the
1150 The special parameters
1154 have special meaning when in double
1160 Character sequences of the form \fB$\fP\(aq\fIstring\fP\(aq are treated
1161 as a special variant of single quotes.
1162 The sequence expands to \fIstring\fP, with backslash-escaped characters
1163 in \fIstring\fP replaced as specified by the ANSI C standard.
1164 Backslash escape sequences, if present, are decoded as follows:
1207 the eight-bit character whose value is the octal value \fInnn\fP
1208 (one to three octal digits)
1211 the eight-bit character whose value is the hexadecimal value \fIHH\fP
1212 (one or two hex digits)
1215 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1216 \fIHHHH\fP (one to four hex digits)
1218 .B \eU\fIHHHHHHHH\fP
1219 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
1220 \fIHHHHHHHH\fP (one to eight hex digits)
1223 a control-\fIx\fP character
1227 The expanded result is single-quoted, as if the dollar sign had
1230 A double-quoted string preceded by a dollar sign (\fB$\fP\(dq\fIstring\fP\(dq)
1231 will cause the string to be translated according to the current locale.
1232 The \fIgettext\fP infrastructure performs the lookup and
1233 translation, using the \fBLC_MESSAGES\fP, \fBTEXTDOMAINDIR\fP,
1234 and \fBTEXTDOMAIN\fP shell variables.
1235 If the current locale is \fBC\fP or \fBPOSIX\fP,
1236 if there are no translations available,
1237 or if the string is not translated,
1238 the dollar sign is ignored.
1239 This is a form of double quoting, so the string remains double-quoted
1240 by default, whether or not it is translated and replaced.
1241 If the \fBnoexpand_translation\fP option is enabled
1242 using the \fBshopt\fP builtin,
1243 translated strings are single-quoted instead of double-quoted.
1244 See the description of
1248 .BR SHELL BUILTIN COMMANDS .
1252 is an entity that stores values.
1255 a number, or one of the special characters listed below under
1256 .BR "Special Parameters" .
1259 is a parameter denoted by a
1261 A variable has a \fIvalue\fP and zero or more \fIattributes\fP.
1262 Attributes are assigned using the
1264 builtin command (see
1268 .BR "SHELL BUILTIN COMMANDS" ).
1270 A parameter is set if it has been assigned a value. The null string is
1271 a valid value. Once a variable is set, it may be unset only by using
1274 builtin command (see
1276 .B SHELL BUILTIN COMMANDS
1281 may be assigned to by a statement of the form
1284 \fIname\fP=[\fIvalue\fP]
1289 is not given, the variable is assigned the null string. All
1291 undergo tilde expansion, parameter and variable expansion,
1292 command substitution, arithmetic expansion, and quote
1296 below). If the variable has its
1300 is evaluated as an arithmetic expression even if the $((...)) expansion is
1302 .B "Arithmetic Expansion"
1304 Word splitting and pathname expansion are not performed.
1305 Assignment statements may also appear as arguments to the
1313 builtin commands (\fIdeclaration\fP commands).
1314 When in \fIposix mode\fP, these builtins may appear in a command after
1315 one or more instances of the \fBcommand\fP builtin and retain these
1316 assignment statement properties.
1318 In the context where an assignment statement is assigning a value
1319 to a shell variable or array index, the += operator can be used to
1320 append to or add to the variable's previous value.
1321 This includes arguments to builtin commands such as \fBdeclare\fP that
1322 accept assignment statements (\fIdeclaration\fP commands).
1323 When += is applied to a variable for which the \fBinteger\fP attribute has been
1324 set, \fIvalue\fP is evaluated as an arithmetic expression and added to the
1325 variable's current value, which is also evaluated.
1326 When += is applied to an array variable using compound assignment (see
1329 variable's value is not unset (as it is when using =), and new values are
1330 appended to the array beginning at one greater than the array's maximum index
1331 (for indexed arrays) or added as additional key\-value pairs in an
1333 When applied to a string-valued variable, \fIvalue\fP is expanded and
1334 appended to the variable's value.
1336 A variable can be assigned the \fInameref\fP attribute using the
1337 \fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands
1338 (see the descriptions of \fBdeclare\fP and \fBlocal\fP below)
1339 to create a \fInameref\fP, or a reference to another variable.
1340 This allows variables to be manipulated indirectly.
1341 Whenever the nameref variable is referenced, assigned to, unset, or has
1342 its attributes modified (other than using or changing the \fInameref\fP
1343 attribute itself), the
1344 operation is actually performed on the variable specified by the nameref
1346 A nameref is commonly used within shell functions to refer to a variable
1347 whose name is passed as an argument to the function.
1348 For instance, if a variable name is passed to a shell function as its first
1352 .if t \f(CWdeclare -n ref=$1\fP
1353 .if n declare -n ref=$1
1356 inside the function creates a nameref variable \fBref\fP whose value is
1357 the variable name passed as the first argument.
1358 References and assignments to \fBref\fP, and changes to its attributes,
1359 are treated as references, assignments, and attribute modifications
1360 to the variable whose name was passed as \fB$1\fP.
1361 If the control variable in a \fBfor\fP loop has the nameref attribute,
1362 the list of words can be a list of shell variables, and a name reference
1363 will be established for each word in the list, in turn, when the loop is
1365 Array variables cannot be given the \fBnameref\fP attribute.
1366 However, nameref variables can reference array variables and subscripted
1368 Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin.
1369 Otherwise, if \fBunset\fP is executed with the name of a nameref variable
1370 as an argument, the variable referenced by the nameref variable will be unset.
1371 .SS Positional Parameters
1373 .I positional parameter
1374 is a parameter denoted by one or more
1375 digits, other than the single digit 0. Positional parameters are
1376 assigned from the shell's arguments when it is invoked,
1377 and may be reassigned using the
1379 builtin command. Positional parameters may not be assigned to
1380 with assignment statements. The positional parameters are
1381 temporarily replaced when a shell function is executed (see
1386 When a positional parameter consisting of more than a single
1387 digit is expanded, it must be enclosed in braces (see
1391 .SS Special Parameters
1392 The shell treats several parameters specially. These parameters may
1393 only be referenced; assignment to them is not allowed.
1397 Expands to the positional parameters, starting from one.
1398 When the expansion is not within double quotes, each positional parameter
1399 expands to a separate word.
1400 In contexts where it is performed, those words
1401 are subject to further word splitting and pathname expansion.
1402 When the expansion occurs within double quotes, it expands to a single word
1403 with the value of each parameter separated by the first character of the
1406 special variable. That is, "\fB$*\fP" is equivalent
1407 to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where
1409 is the first character of the value of the
1415 is unset, the parameters are separated by spaces.
1419 is null, the parameters are joined without intervening separators.
1422 Expands to the positional parameters, starting from one.
1423 In contexts where word splitting is performed, this expands each
1424 positional parameter to a separate word; if not within double
1425 quotes, these words are subject to word splitting.
1426 In contexts where word splitting is not performed,
1427 this expands to a single word
1428 with each positional parameter separated by a space.
1430 expansion occurs within double quotes, each parameter expands to a
1431 separate word. That is, "\fB$@\fP" is equivalent to
1432 "\fB$1\fP" "\fB$2\fP" ...
1433 If the double-quoted expansion occurs within a word, the expansion of
1434 the first parameter is joined with the beginning part of the original
1435 word, and the expansion of the last parameter is joined with the last
1436 part of the original word.
1437 When there are no positional parameters, "\fB$@\fP" and
1439 expand to nothing (i.e., they are removed).
1442 Expands to the number of positional parameters in decimal.
1445 Expands to the exit status of the most recently executed foreground
1449 Expands to the current option flags as specified upon invocation,
1452 builtin command, or those set by the shell itself
1458 Expands to the process ID of the shell. In a subshell, it
1459 expands to the process ID of the current shell, not the
1463 Expands to the process ID of the job most recently placed into the
1464 background, whether executed as an asynchronous command or using
1465 the \fBbg\fP builtin (see
1471 Expands to the name of the shell or shell script. This is set at
1472 shell initialization. If
1474 is invoked with a file of commands,
1476 is set to the name of that file. If
1482 is set to the first argument after the string to be
1483 executed, if one is present. Otherwise, it is set
1484 to the filename used to invoke
1486 as given by argument zero.
1489 The following variables are set by the shell:
1494 At shell startup, set to the pathname used to invoke the
1495 shell or shell script being executed as passed in the environment
1497 Subsequently, expands to the last argument to the previous simple
1498 command executed in the foreground, after expansion.
1499 Also set to the full pathname used to invoke each command executed
1500 and placed in the environment exported to that command.
1501 When checking mail, this parameter holds the name of the mail file
1502 currently being checked.
1505 Expands to the full filename used to invoke this instance of
1509 A colon-separated list of enabled shell options. Each word in
1510 the list is a valid argument for the
1514 builtin command (see
1516 .B "SHELL BUILTIN COMMANDS"
1517 below). The options appearing in
1520 are those reported as
1523 If this variable is in the environment when
1525 starts up, each shell option in the list will be enabled before
1526 reading any startup files.
1527 This variable is read-only.
1530 Expands to the process ID of the current \fBbash\fP process.
1531 This differs from \fB$$\fP under certain circumstances, such as subshells
1532 that do not require \fBbash\fP to be re-initialized.
1539 is unset, it loses its special properties, even if it is
1543 An associative array variable whose members correspond to the internal
1544 list of aliases as maintained by the \fBalias\fP builtin.
1545 Elements added to this array appear in the alias list; however,
1546 unsetting array elements currently does not cause aliases to be removed
1547 from the alias list.
1550 is unset, it loses its special properties, even if it is
1554 An array variable whose values are the number of parameters in each
1555 frame of the current \fBbash\fP execution call stack.
1557 parameters to the current subroutine (shell function or script executed
1558 with \fB.\fP or \fBsource\fP) is at the top of the stack.
1559 When a subroutine is executed, the number of parameters passed is pushed onto
1565 only when in extended debugging mode (see the description of the
1570 Setting \fBextdebug\fP after the shell has started to execute a script,
1571 or referencing this variable when \fBextdebug\fP is not set,
1572 may result in inconsistent values.
1575 An array variable containing all of the parameters in the current \fBbash\fP
1576 execution call stack. The final parameter of the last subroutine call
1577 is at the top of the stack; the first parameter of the initial call is
1578 at the bottom. When a subroutine is executed, the parameters supplied
1585 only when in extended debugging mode
1586 (see the description of the
1591 Setting \fBextdebug\fP after the shell has started to execute a script,
1592 or referencing this variable when \fBextdebug\fP is not set,
1593 may result in inconsistent values.
1596 When referenced, this variable expands to the name of the shell or shell
1597 script (identical to
1599 see the description of special parameter 0 above).
1602 causes the value assigned to also be assigned to \fB$0\fP.
1605 is unset, it loses its special properties, even if it is
1609 An associative array variable whose members correspond to the internal
1610 hash table of commands as maintained by the \fBhash\fP builtin.
1611 Elements added to this array appear in the hash table; however,
1612 unsetting array elements currently does not cause command names to be removed
1613 from the hash table.
1616 is unset, it loses its special properties, even if it is
1620 The command currently being executed or about to be executed, unless the
1621 shell is executing a command as the result of a trap,
1622 in which case it is the command executing at the time of the trap.
1625 is unset, it loses its special properties, even if it is
1628 .B BASH_EXECUTION_STRING
1629 The command argument to the \fB\-c\fP invocation option.
1632 An array variable whose members are the line numbers in source files
1633 where each corresponding member of
1637 \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source
1638 file (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP) where
1639 \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called
1640 (or \fB${BASH_LINENO[\fP\fI$i-1\fP\fB]}\fP if referenced within another
1645 to obtain the current line number.
1647 .B BASH_LOADABLES_PATH
1648 A colon-separated list of directories in which the shell looks for
1649 dynamically loadable builtins specified by the
1654 An array variable whose members are assigned by the \fB=~\fP binary
1655 operator to the \fB[[\fP conditional command.
1656 The element with index 0 is the portion of the string
1657 matching the entire regular expression.
1658 The element with index \fIn\fP is the portion of the
1659 string matching the \fIn\fPth parenthesized subexpression.
1662 An array variable whose members are the source filenames
1663 where the corresponding shell function names in the
1666 array variable are defined.
1668 \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file
1669 \fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from
1670 \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP.
1673 Incremented by one within each subshell or subshell environment when
1674 the shell begins executing in that environment.
1675 The initial value is 0.
1678 is unset, it loses its special properties, even if it is
1682 A readonly array variable whose members hold version information for
1685 The values assigned to the array members are as follows:
1689 .B BASH_VERSINFO[\fR0\fP]
1690 The major version number (the \fIrelease\fP).
1692 .B BASH_VERSINFO[\fR1\fP]
1693 The minor version number (the \fIversion\fP).
1695 .B BASH_VERSINFO[\fR2\fP]
1698 .B BASH_VERSINFO[\fR3\fP]
1701 .B BASH_VERSINFO[\fR4\fP]
1702 The release status (e.g., \fIbeta1\fP).
1704 .B BASH_VERSINFO[\fR5\fP]
1711 Expands to a string describing the version of this instance of
1715 An index into \fB${COMP_WORDS}\fP of the word containing the current
1717 This variable is available only in shell functions invoked by the
1718 programmable completion facilities (see \fBProgrammable Completion\fP
1722 The key (or final key of a key sequence) used to invoke the current
1723 completion function.
1726 The current command line.
1727 This variable is available only in shell functions and external
1728 commands invoked by the
1729 programmable completion facilities (see \fBProgrammable Completion\fP
1733 The index of the current cursor position relative to the beginning of
1734 the current command.
1735 If the current cursor position is at the end of the current command,
1736 the value of this variable is equal to \fB${#COMP_LINE}\fP.
1737 This variable is available only in shell functions and external
1738 commands invoked by the
1739 programmable completion facilities (see \fBProgrammable Completion\fP
1743 Set to an integer value corresponding to the type of completion attempted
1744 that caused a completion function to be called:
1745 \fITAB\fP, for normal completion,
1746 \fI?\fP, for listing completions after successive tabs,
1747 \fI!\fP, for listing alternatives on partial word completion,
1748 \fI@\fP, to list completions if the word is not unmodified,
1750 \fI%\fP, for menu completion.
1751 This variable is available only in shell functions and external
1752 commands invoked by the
1753 programmable completion facilities (see \fBProgrammable Completion\fP
1757 The set of characters that the \fBreadline\fP library treats as word
1758 separators when performing word completion.
1762 is unset, it loses its special properties, even if it is
1766 An array variable (see \fBArrays\fP below) consisting of the individual
1767 words in the current command line.
1768 The line is split into words as \fBreadline\fP would split it, using
1772 This variable is available only in shell functions invoked by the
1773 programmable completion facilities (see \fBProgrammable Completion\fP
1777 An array variable (see \fBArrays\fP below) created to hold the file descriptors
1778 for output from and input to an unnamed coprocess (see \fBCoprocesses\fP
1782 An array variable (see
1784 below) containing the current contents of the directory stack.
1785 Directories appear in the stack in the order they are displayed by the
1788 Assigning to members of this array variable may be used to modify
1789 directories already in the stack, but the
1793 builtins must be used to add and remove directories.
1794 Assignment to this variable will not change the current directory.
1798 is unset, it loses its special properties, even if it is
1802 Each time this parameter is referenced, it expands to the number of seconds
1803 since the Unix Epoch (see \fItime\fP\fR(3)\fP) as a floating point value
1804 with micro-second granularity.
1812 is unset, it loses its special properties, even if it is
1816 Each time this parameter is referenced, it expands to the number of seconds
1817 since the Unix Epoch (see \fItime\fP\fR(3)\fP).
1825 is unset, it loses its special properties, even if it is
1829 Expands to the effective user ID of the current user, initialized at
1830 shell startup. This variable is readonly.
1833 An array variable containing the names of all shell functions
1834 currently in the execution call stack.
1835 The element with index 0 is the name of any currently-executing
1837 The bottom-most element (the one with the highest index) is
1838 .if t \f(CW"main"\fP.
1840 This variable exists only when a shell function is executing.
1848 is unset, it loses its special properties, even if it is
1852 This variable can be used with \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP.
1853 Each element of \fBFUNCNAME\fP has corresponding elements in
1854 \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP to describe the call stack.
1855 For instance, \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called from the file
1856 \fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP at line number
1857 \fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP.
1858 The \fBcaller\fP builtin displays the current call stack using this
1862 An array variable containing the list of groups of which the current
1871 is unset, it loses its special properties, even if it is
1875 The history number, or index in the history list, of the current
1884 is unset, it loses its special properties, even if it is
1888 Automatically set to the name of the current host.
1891 Automatically set to a string that uniquely
1892 describes the type of machine on which
1895 The default is system-dependent.
1898 Each time this parameter is referenced, the shell substitutes
1899 a decimal number representing the current sequential line number
1900 (starting with 1) within a script or function. When not in a
1901 script or function, the value substituted is not guaranteed to
1906 is unset, it loses its special properties, even if it is
1910 Automatically set to a string that fully describes the system
1913 is executing, in the standard GNU \fIcpu-company-system\fP format.
1914 The default is system-dependent.
1917 An array variable (see \fBArrays\fP below) created to hold the text
1918 read by the \fBmapfile\fP builtin when no variable name is supplied.
1921 The previous working directory as set by the
1926 The value of the last option argument processed by the
1928 builtin command (see
1930 .B SHELL BUILTIN COMMANDS
1934 The index of the next argument to be processed by the
1936 builtin command (see
1938 .B SHELL BUILTIN COMMANDS
1942 Automatically set to a string that
1943 describes the operating system on which
1946 The default is system-dependent.
1949 An array variable (see
1951 below) containing a list of exit status values from the processes
1952 in the most-recently-executed foreground pipeline (which may
1953 contain only a single command).
1956 The process ID of the shell's parent. This variable is readonly.
1959 The current working directory as set by the
1964 Each time this parameter is referenced, it expands to a random integer
1965 between 0 and 32767.
1970 initializes (seeds) the sequence of random numbers.
1974 is unset, it loses its special properties, even if it is
1977 .B READLINE_ARGUMENT
1978 Any numeric argument given to a readline command that was defined using
1979 .if t \f(CWbind -x\fP
1983 .B "SHELL BUILTIN COMMANDS"
1985 when it was invoked.
1990 line buffer, for use with
1991 .if t \f(CWbind -x\fP
1995 .B "SHELL BUILTIN COMMANDS"
1999 The position of the mark (saved insertion point) in the
2001 line buffer, for use with
2002 .if t \f(CWbind -x\fP
2006 .B "SHELL BUILTIN COMMANDS"
2008 The characters between the insertion point and the mark are often
2009 called the \fIregion\fP.
2012 The position of the insertion point in the
2014 line buffer, for use with
2015 .if t \f(CWbind -x\fP
2019 .B "SHELL BUILTIN COMMANDS"
2023 Set to the line of input read by the
2025 builtin command when no arguments are supplied.
2028 Each time this parameter is
2029 referenced, it expands to the number of seconds since shell invocation.
2030 If a value is assigned to
2033 the value returned upon subsequent
2035 the number of seconds since the assignment plus the value assigned.
2036 The number of seconds at shell invocation and the current time are always
2037 determined by querying the system clock.
2041 is unset, it loses its special properties, even if it is
2045 A colon-separated list of enabled shell options. Each word in
2046 the list is a valid argument for the
2050 builtin command (see
2052 .B "SHELL BUILTIN COMMANDS"
2053 below). The options appearing in
2056 are those reported as
2059 If this variable is in the environment when
2061 starts up, each shell option in the list will be enabled before
2062 reading any startup files.
2063 This variable is read-only.
2066 Incremented by one each time an instance of
2071 This variable expands to a 32-bit pseudo-random number each time it is
2072 referenced. The random number generator is not linear on systems that
2073 support \f(CW/dev/urandom\fP or \fIarc4random\fP, so each returned number
2074 has no relationship to the numbers preceding it.
2075 The random number generator cannot be seeded, so assignments to this
2076 variable have no effect.
2080 is unset, it loses its special properties,
2081 even if it is subsequently reset.
2084 Expands to the user ID of the current user, initialized at shell startup.
2085 This variable is readonly.
2088 The following variables are used by the shell. In some cases,
2090 assigns a default value to a variable; these cases are noted
2096 The value is used to set the shell's compatibility level.
2099 .B "SHELL COMPATIBILITY MODE"
2100 below for a description of the various compatibility
2101 levels and their effects.
2102 The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
2103 corresponding to the desired compatibility level.
2104 If \fBBASH_COMPAT\fP is unset or set to the empty string, the compatibility
2105 level is set to the default for the current version.
2106 If \fBBASH_COMPAT\fP is set to a value that is not one of the valid
2107 compatibility levels, the shell prints an error message and sets the
2108 compatibility level to the default for the current version.
2109 The valid values correspond to the compatibility levels
2110 described below under
2112 .BR "SHELL COMPATIBILITY MODE" .
2113 For example, 4.2 and 42 are valid values that correspond
2114 to the \fBcompat42\fP \fBshopt\fP option
2115 and set the compatibility level to 42.
2116 The current version is also a valid value.
2119 If this parameter is set when \fBbash\fP is executing a shell script,
2120 its value is interpreted as a filename containing commands to
2121 initialize the shell, as in
2126 is subjected to parameter expansion, command substitution, and arithmetic
2127 expansion before being interpreted as a filename.
2130 is not used to search for the resultant filename.
2133 If set to an integer corresponding to a valid file descriptor, \fBbash\fP
2134 will write the trace output generated when
2135 .if t \f(CWset -x\fP
2137 is enabled to that file descriptor.
2138 The file descriptor is closed when
2141 is unset or assigned a new value.
2145 or assigning it the empty string causes the
2146 trace output to be sent to the standard error.
2150 to 2 (the standard error file
2151 descriptor) and then unsetting it will result in the standard error
2155 The search path for the
2158 This is a colon-separated list of directories in which the shell looks
2159 for destination directories specified by the
2163 .if t \f(CW".:~:/usr"\fP.
2167 Set the number of exited child status values for the shell to remember.
2168 Bash will not allow this value to be decreased below a POSIX-mandated
2169 minimum, and there is a maximum value (currently 8192) that this may
2171 The minimum value is system-dependent.
2174 Used by the \fBselect\fP compound command to determine the terminal width
2175 when printing selection lists.
2176 Automatically set if the
2178 option is enabled or in an interactive shell upon receipt of a
2183 An array variable from which \fBbash\fP reads the possible completions
2184 generated by a shell function invoked by the programmable completion
2185 facility (see \fBProgrammable Completion\fP below).
2186 Each array element contains one possible completion.
2189 If \fBbash\fP finds this variable in the environment when the shell starts
2193 it assumes that the shell is running in an Emacs shell buffer and disables
2197 Expanded and executed similarly to
2200 (see \fBINVOCATION\fP above)
2201 when an interactive shell is invoked in \fIposix mode\fP.
2204 A colon-separated list of shell patterns (see \fBPattern Matching\fP)
2205 defining the list of filenames to be ignored by command search using
2207 Files whose full pathnames match one of these patterns are not considered
2208 executable files for the purposes of completion and command execution
2209 via \fBPATH\fP lookup.
2210 This does not affect the behavior of the \fB[\fP, \fBtest\fP, and \fB[[\fP
2212 Full pathnames in the command hash table are not subject to \fBEXECIGNORE\fP.
2213 Use this variable to ignore shared library files that have the executable
2214 bit set, but are not executable files.
2215 The pattern matching honors the setting of the \fBextglob\fP shell
2219 The default editor for the
2224 A colon-separated list of suffixes to ignore when performing
2225 filename completion (see
2229 A filename whose suffix matches one of the entries in
2232 is excluded from the list of matched filenames.
2234 .if t \f(CW".o:~"\fP.
2238 If set to a numeric value greater than 0, defines a maximum function
2239 nesting level. Function invocations that exceed this nesting level
2240 will cause the current command to abort.
2243 A colon-separated list of patterns defining the set of file names to
2244 be ignored by pathname expansion.
2245 If a file name matched by a pathname expansion pattern also matches one
2249 it is removed from the list of matches.
2252 A colon-separated list of values controlling how commands are saved on
2254 If the list of values includes
2256 lines which begin with a
2258 character are not saved in the history list.
2261 causes lines matching the previous history entry to not be saved.
2264 is shorthand for \fIignorespace\fP and \fIignoredups\fP.
2267 causes all previous lines matching the current line to be removed from
2268 the history list before that line is saved.
2269 Any value not in the above list is ignored.
2273 is unset, or does not include a valid value,
2274 all lines read by the shell parser are saved on the history list,
2275 subject to the value of
2278 The second and subsequent lines of a multi-line compound command are
2279 not tested, and are added to the history regardless of the value of
2284 The name of the file in which command history is saved (see
2287 below). The default value is \fI~/.bash_history\fP. If unset, the
2288 command history is not saved when a shell exits.
2291 The maximum number of lines contained in the history file. When this
2292 variable is assigned a value, the history file is truncated, if
2294 to contain no more than that number of lines by removing the oldest entries.
2295 The history file is also truncated to this size after
2296 writing it when a shell exits.
2297 If the value is 0, the history file is truncated to zero size.
2298 Non-numeric values and numeric values less than zero inhibit truncation.
2299 The shell sets the default value to the value of \fBHISTSIZE\fP
2300 after reading any startup files.
2303 A colon-separated list of patterns used to decide which command lines
2304 should be saved on the history list. Each pattern is anchored at the
2305 beginning of the line and must match the complete line (no implicit
2306 `\fB*\fP' is appended). Each pattern is tested against the line
2307 after the checks specified by
2311 In addition to the normal shell pattern matching characters, `\fB&\fP'
2312 matches the previous history line. `\fB&\fP' may be escaped using a
2313 backslash; the backslash is removed before attempting a match.
2314 The second and subsequent lines of a multi-line compound command are
2315 not tested, and are added to the history regardless of the value of
2318 The pattern matching honors the setting of the \fBextglob\fP shell
2322 The number of commands to remember in the command history (see
2326 If the value is 0, commands are not saved in the history list.
2327 Numeric values less than zero result in every command being saved
2328 on the history list (there is no limit).
2329 The shell sets the default value to 500 after reading any startup files.
2332 If this variable is set and not null, its value is used as a format string
2333 for \fIstrftime\fP(3) to print the time stamp associated with each history
2334 entry displayed by the \fBhistory\fP builtin.
2335 If this variable is set, time stamps are written to the history file so
2336 they may be preserved across shell sessions.
2337 This uses the history comment character to distinguish timestamps from
2338 other history lines.
2341 The home directory of the current user; the default argument for the
2342 \fBcd\fP builtin command.
2343 The value of this variable is also used when performing tilde expansion.
2346 Contains the name of a file in the same format as
2348 that should be read when the shell needs to complete a
2350 The list of possible hostname completions may be changed while the
2352 the next time hostname completion is attempted after the
2355 adds the contents of the new file to the existing list.
2359 is set, but has no value, or does not name a readable file,
2360 \fBbash\fP attempts to read
2362 to obtain the list of possible hostname completions.
2366 is unset, the hostname list is cleared.
2370 .I Internal Field Separator
2372 for word splitting after expansion and to
2373 split lines into words with the
2375 builtin command. The default value is
2376 ``<space><tab><newline>''.
2380 action of an interactive shell on receipt of an
2383 character as the sole input. If set, the value is the number of
2387 characters which must be
2388 typed as the first characters on an input line before
2390 exits. If the variable exists but does not have a numeric value, or
2391 has no value, the default value is 10. If it does not exist,
2394 signifies the end of input to the shell.
2397 The filename for the
2399 startup file, overriding the default of
2407 If this variable appears in the environment when the shell starts,
2408 \fBbash\fP assumes that it is running inside an Emacs shell buffer
2409 and may disable line editing, depending on the value of \fBTERM\fP.
2412 Used to determine the locale category for any category not specifically
2413 selected with a variable starting with \fBLC_\fP.
2416 This variable overrides the value of
2420 \fBLC_\fP variable specifying a locale category.
2423 This variable determines the collation order used when sorting the
2424 results of pathname expansion, and determines the behavior of range
2425 expressions, equivalence classes, and collating sequences within
2426 pathname expansion and pattern matching.
2429 This variable determines the interpretation of characters and the
2430 behavior of character classes within pathname expansion and pattern
2434 This variable determines the locale used to translate double-quoted
2435 strings preceded by a \fB$\fP.
2438 This variable determines the locale category used for number formatting.
2441 This variable determines the locale category used for data and time
2445 Used by the \fBselect\fP compound command to determine the column length
2446 for printing selection lists.
2447 Automatically set if the
2449 option is enabled or in an interactive shell upon receipt of a
2454 If this parameter is set to a file or directory name and the
2457 variable is not set,
2459 informs the user of the arrival of mail in the specified file or
2460 Maildir-format directory.
2466 checks for mail. The default is 60 seconds. When it is time to check
2467 for mail, the shell does so before displaying the primary prompt.
2468 If this variable is unset, or set to a value that is not a number
2469 greater than or equal to zero, the shell disables mail checking.
2472 A colon-separated list of filenames to be checked for mail.
2473 The message to be printed when mail arrives in a particular file
2474 may be specified by separating the filename from the message with a `?'.
2475 When used in the text of the message, \fB$_\fP expands to the name of
2476 the current mailfile.
2480 \fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"\(aq
2483 can be configured to supply
2484 a default value for this variable (there is no value by default),
2485 but the location of the user
2486 mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP).
2490 If set to the value 1,
2492 displays error messages generated by the
2494 builtin command (see
2496 .B SHELL BUILTIN COMMANDS
2500 is initialized to 1 each time the shell is invoked or a shell
2504 The search path for commands. It
2505 is a colon-separated list of directories in which
2506 the shell looks for commands (see
2508 .B COMMAND EXECUTION
2510 A zero-length (null) directory name in the value of
2513 indicates the current directory.
2514 A null directory name may appear as two adjacent colons, or as an initial
2516 The default path is system-dependent,
2517 and is set by the administrator who installs
2521 .if t \f(CW/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin\fP.
2522 .if n ``/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin''.
2526 If this variable is in the environment when \fBbash\fP starts, the shell
2527 enters \fIposix mode\fP before reading the startup files, as if the
2529 invocation option had been supplied. If it is set while the shell is
2530 running, \fBbash\fP enables \fIposix mode\fP, as if the command
2531 .if t \f(CWset -o posix\fP
2532 .if n \fIset -o posix\fP
2534 When the shell enters \fIposix mode\fP, it sets this variable if it was
2538 If this variable is set, and is an array,
2539 the value of each set element is executed as a command
2540 prior to issuing each primary prompt.
2541 If this is set but not an array variable,
2542 its value is used as a command to execute instead.
2545 If set to a number greater than zero, the value is used as the number of
2546 trailing directory components to retain when expanding the \fB\ew\fP and
2547 \fB\eW\fP prompt string escapes (see
2550 below). Characters removed are replaced with an ellipsis.
2553 The value of this parameter is expanded (see
2556 below) and displayed by interactive shells after reading a command
2557 and before the command is executed.
2560 The value of this parameter is expanded (see
2563 below) and used as the primary prompt string. The default value is
2564 ``\fB\es\-\ev\e$ \fP''.
2567 The value of this parameter is expanded as with
2570 and used as the secondary prompt string. The default is
2574 The value of this parameter is used as the prompt for the
2582 The value of this parameter is expanded as with
2585 and the value is printed before each command
2587 displays during an execution trace. The first character of
2588 the expanded value of
2591 is replicated multiple times, as necessary, to indicate multiple
2592 levels of indirection. The default is ``\fB+ \fP''.
2595 This variable expands to the full pathname to the shell.
2596 If it is not set when the shell starts,
2598 assigns to it the full pathname of the current user's login shell.
2601 The value of this parameter is used as a format string specifying
2602 how the timing information for pipelines prefixed with the
2604 reserved word should be displayed.
2605 The \fB%\fP character introduces an escape sequence that is
2606 expanded to a time value or other information.
2607 The escape sequences and their meanings are as follows; the
2608 braces denote optional portions.
2617 The elapsed time in seconds.
2620 The number of CPU seconds spent in user mode.
2623 The number of CPU seconds spent in system mode.
2626 The CPU percentage, computed as (%U + %S) / %R.
2630 The optional \fIp\fP is a digit specifying the \fIprecision\fP,
2631 the number of fractional digits after a decimal point.
2632 A value of 0 causes no decimal point or fraction to be output.
2633 At most three places after the decimal point may be specified;
2634 values of \fIp\fP greater than 3 are changed to 3.
2635 If \fIp\fP is not specified, the value 3 is used.
2637 The optional \fBl\fP specifies a longer format, including
2638 minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs.
2639 The value of \fIp\fP determines whether or not the fraction is
2642 If this variable is not set, \fBbash\fP acts as if it had the
2643 value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\(aq\fP.
2644 If the value is null, no timing information is displayed.
2645 A trailing newline is added when the format string is displayed.
2649 If set to a value greater than zero,
2653 default timeout for the \fBread\fP builtin.
2654 The \fBselect\fP command terminates if input does not arrive
2658 seconds when input is coming from a terminal.
2659 In an interactive shell, the value is interpreted as the
2660 number of seconds to wait for a line of input after issuing the
2663 terminates after waiting for that number of seconds if a complete
2664 line of input does not arrive.
2667 If set, \fBbash\fP uses its value as the name of a directory in which
2668 \fBbash\fP creates temporary files for the shell's use.
2671 This variable controls how the shell interacts with the user and
2672 job control. If this variable is set, single word simple
2673 commands without redirections are treated as candidates for resumption
2674 of an existing stopped job. There is no ambiguity allowed; if there is
2675 more than one job beginning with the string typed, the job most recently
2676 accessed is selected. The
2678 of a stopped job, in this context, is the command line used to
2682 the string supplied must match the name of a stopped job exactly;
2685 the string supplied needs to match a substring of the name of a
2688 value provides functionality analogous to the
2693 below). If set to any other value, the supplied string must
2694 be a prefix of a stopped job's name; this provides functionality
2695 analogous to the \fB%\fP\fIstring\fP job identifier.
2698 The two or three characters which control history expansion
2699 and tokenization (see
2701 .B HISTORY EXPANSION
2702 below). The first character is the \fIhistory expansion\fP character,
2703 the character which signals the start of a history
2704 expansion, normally `\fB!\fP'.
2705 The second character is the \fIquick substitution\fP
2706 character, which is used as shorthand for re-running the previous
2707 command entered, substituting one string for another in the command.
2708 The default is `\fB^\fP'.
2709 The optional third character is the character
2710 which indicates that the remainder of the line is a comment when found
2711 as the first character of a word, normally `\fB#\fP'. The history
2712 comment character causes history substitution to be skipped for the
2713 remaining words on the line. It does not necessarily cause the shell
2714 parser to treat the rest of the line as a comment.
2718 provides one-dimensional indexed and associative array variables.
2719 Any variable may be used as an indexed array; the
2721 builtin will explicitly declare an array.
2723 limit on the size of an array, nor any requirement that members
2724 be indexed or assigned contiguously.
2725 Indexed arrays are referenced using integers (including arithmetic
2726 expressions) and are zero-based; associative arrays are referenced
2727 using arbitrary strings.
2728 Unless otherwise noted, indexed array indices must be non-negative integers.
2730 An indexed array is created automatically if any variable is assigned to
2731 using the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP. The
2733 is treated as an arithmetic expression that must evaluate to a number.
2734 To explicitly declare an indexed array, use
2735 .B declare \-a \fIname\fP
2738 .B SHELL BUILTIN COMMANDS
2740 .B declare \-a \fIname\fP[\fIsubscript\fP]
2741 is also accepted; the \fIsubscript\fP is ignored.
2743 Associative arrays are created using
2744 .BR "declare \-A \fIname\fP" .
2747 specified for an array variable using the
2751 builtins. Each attribute applies to all members of an array.
2753 Arrays are assigned to using compound assignments of the form
2754 \fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each
2755 \fIvalue\fP may be of the form [\fIsubscript\fP]=\fIstring\fP.
2756 Indexed array assignments do not require anything but \fIstring\fP.
2757 Each \fIvalue\fP in the list is expanded using all the shell expansions
2758 described below under
2761 When assigning to indexed arrays, if the optional brackets and subscript
2762 are supplied, that index is assigned to;
2763 otherwise the index of the element assigned is the last index assigned
2764 to by the statement plus one. Indexing starts at zero.
2766 When assigning to an associative array, the words in a compound assignment
2767 may be either assignment statements, for which the subscript is required,
2768 or a list of words that is interpreted as a sequence of alternating keys
2770 \fIname\fP=\fB( \fP\fIkey1 value1 key2 value2\fP ...\fB)\fP.
2771 These are treated identically to
2772 \fIname\fP=\fB(\fP [\fIkey1\fP]=\fIvalue1\fP [\fIkey2\fP]=\fIvalue2\fP ...\fB)\fP.
2773 The first word in the list determines how the remaining words
2774 are interpreted; all assignments in a list must be of the same type.
2775 When using key/value pairs, the keys may not be missing or empty;
2776 a final missing value is treated like the empty string.
2778 This syntax is also accepted by the
2780 builtin. Individual array elements may be assigned to using the
2781 \fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above.
2782 When assigning to an indexed array, if
2784 is subscripted by a negative number, that number is
2785 interpreted as relative to one greater than the maximum index of
2786 \fIname\fP, so negative indices count back from the end of the
2787 array, and an index of \-1 references the last element.
2789 The += operator will append to an array variable when assigning
2790 using the compound assignment syntax; see
2795 Any element of an array may be referenced using
2796 ${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid
2797 conflicts with pathname expansion. If
2798 \fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to
2799 all members of \fIname\fP. These subscripts differ only when the
2800 word appears within double quotes. If the word is double-quoted,
2801 ${\fIname\fP[*]} expands to a single
2802 word with the value of each array member separated by the first
2806 special variable, and ${\fIname\fP[@]} expands each element of
2807 \fIname\fP to a separate word. When there are no array members,
2808 ${\fIname\fP[@]} expands to nothing.
2809 If the double-quoted expansion occurs within a word, the expansion of
2810 the first parameter is joined with the beginning part of the original
2811 word, and the expansion of the last parameter is joined with the last
2812 part of the original word.
2813 This is analogous to the expansion
2814 of the special parameters \fB*\fP and \fB@\fP (see
2815 .B Special Parameters
2816 above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of
2817 ${\fIname\fP[\fIsubscript\fP]}. If \fIsubscript\fP is \fB*\fP or
2818 \fB@\fP, the expansion is the number of elements in the array.
2821 used to reference an element of an indexed array
2822 evaluates to a number less than zero, it is
2823 interpreted as relative to one greater than the maximum index of the array,
2824 so negative indices count back from the end of the
2825 array, and an index of \-1 references the last element.
2827 Referencing an array variable without a subscript is equivalent to
2828 referencing the array with a subscript of 0.
2829 Any reference to a variable using a valid subscript is legal, and
2831 will create an array if necessary.
2833 An array variable is considered set if a subscript has been assigned a
2834 value. The null string is a valid value.
2836 It is possible to obtain the keys (indices) of an array as well as the values.
2837 ${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]}
2838 expand to the indices assigned in array variable \fIname\fP.
2839 The treatment when in double quotes is similar to the expansion of the
2840 special parameters \fI@\fP and \fI*\fP within double quotes.
2844 builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP]
2845 destroys the array element at index \fIsubscript\fP,
2846 for both indexed and associative arrays.
2847 Negative subscripts to indexed arrays are interpreted as described above.
2848 Unsetting the last element of an array variable does not unset the variable.
2849 \fBunset\fP \fIname\fP, where \fIname\fP is an array,
2850 removes the entire array.
2851 \fBunset\fP \fIname\fP[\fIsubscript\fP], where
2852 \fIsubscript\fP is \fB*\fP or \fB@\fP, behaves differently depending on
2853 whether \fIname\fP is an indexed or associative array.
2854 If \fIname\fP is an associative array, this unsets the element with
2855 subscript \fB*\fP or \fB@\fP.
2856 If \fIname\fP is an indexed array, unset removes all of the elements but
2857 does not remove the array itself.
2859 When using a variable name with a subscript as an argument to a command,
2860 such as with \fBunset\fP, without using the word expansion syntax
2861 described above, the argument is subject to pathname expansion.
2862 If pathname expansion is not desired, the argument should be quoted.
2869 builtins each accept a
2871 option to specify an indexed array and a
2873 option to specify an associative array.
2874 If both options are supplied,
2881 option to assign a list of words read from the standard input
2886 builtins display array values in a way that allows them to be
2887 reused as assignments.
2889 Expansion is performed on the command line after it has been split into
2890 words. There are seven kinds of expansion performed:
2891 .IR "brace expansion" ,
2892 .IR "tilde expansion" ,
2893 .IR "parameter and variable expansion" ,
2894 .IR "command substitution" ,
2895 .IR "arithmetic expansion" ,
2896 .IR "word splitting" ,
2898 .IR "pathname expansion" .
2900 The order of expansions is:
2902 tilde expansion, parameter and variable expansion, arithmetic expansion,
2903 and command substitution (done in a left-to-right fashion);
2905 and pathname expansion.
2907 On systems that can support it, there is an additional expansion
2908 available: \fIprocess substitution\fP.
2909 This is performed at the
2910 same time as tilde, parameter, variable, and arithmetic expansion and
2911 command substitution.
2913 After these expansions are performed, quote characters present in the
2914 original word are removed unless they have been quoted themselves
2915 (\fIquote removal\fP).
2917 Only brace expansion, word splitting, and pathname expansion
2918 can increase the number of words of the expansion; other expansions
2919 expand a single word to a single word.
2920 The only exceptions to this are the expansions of
2921 "\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP",
2922 and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
2923 as explained above (see
2927 .I "Brace expansion"
2928 is a mechanism by which arbitrary strings
2929 may be generated. This mechanism is similar to
2930 \fIpathname expansion\fP, but the filenames generated
2931 need not exist. Patterns to be brace expanded take
2932 the form of an optional
2934 followed by either a series of comma-separated strings or
2935 a sequence expression between a pair of braces, followed by
2938 The preamble is prefixed to each string contained
2939 within the braces, and the postscript is then appended
2940 to each resulting string, expanding left to right.
2942 Brace expansions may be nested. The results of each expanded
2943 string are not sorted; left to right order is preserved.
2944 For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'.
2946 A sequence expression takes the form
2947 \fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]}\fP,
2948 where \fIx\fP and \fIy\fP are either integers or single letters,
2949 and \fIincr\fP, an optional increment, is an integer.
2950 When integers are supplied, the expression expands to each number between
2951 \fIx\fP and \fIy\fP, inclusive.
2952 Supplied integers may be prefixed with \fI0\fP to force each term to have the
2954 When either \fIx\fP or \fPy\fP begins with a zero, the shell
2955 attempts to force all generated terms to contain the same number of digits,
2956 zero-padding where necessary.
2957 When letters are supplied, the expression expands to each character
2958 lexicographically between \fIx\fP and \fIy\fP, inclusive,
2959 using the default C locale.
2960 Note that both \fIx\fP and \fIy\fP must be of the same type
2961 (integer or letter).
2962 When the increment is supplied, it is used as the difference between
2963 each term. The default increment is 1 or \-1 as appropriate.
2965 Brace expansion is performed before any other expansions,
2966 and any characters special to other expansions are preserved
2967 in the result. It is strictly textual.
2969 does not apply any syntactic interpretation to the context of the
2970 expansion or the text between the braces.
2972 A correctly-formed brace expansion must contain unquoted opening
2973 and closing braces, and at least one unquoted comma or a valid
2974 sequence expression.
2975 Any incorrectly formed brace expansion is left unchanged.
2976 A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its
2977 being considered part of a brace expression.
2978 To avoid conflicts with parameter expansion, the string \fB${\fP
2979 is not considered eligible for brace expansion, and inhibits brace
2980 expansion until the closing \fB}\fP.
2982 This construct is typically used as shorthand when the common
2983 prefix of the strings to be generated is longer than in the
2987 mkdir /usr/local/src/bash/{old,new,dist,bugs}
2991 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
2994 Brace expansion introduces a slight incompatibility with
2995 historical versions of
2998 does not treat opening or closing braces specially when they
2999 appear as part of a word, and preserves them in the output.
3001 removes braces from words as a consequence of brace
3002 expansion. For example, a word entered to
3005 appears identically in the output. The same word is
3010 If strict compatibility with
3016 option or disable brace expansion with the
3022 .B SHELL BUILTIN COMMANDS
3025 If a word begins with an unquoted tilde character (`\fB~\fP'), all of
3026 the characters preceding the first unquoted slash (or all characters,
3027 if there is no unquoted slash) are considered a \fItilde-prefix\fP.
3028 If none of the characters in the tilde-prefix are quoted, the
3029 characters in the tilde-prefix following the tilde are treated as a
3030 possible \fIlogin name\fP.
3031 If this login name is the null string, the tilde is replaced with the
3032 value of the shell parameter
3038 is unset, the home directory of the user executing the shell is
3039 substituted instead.
3040 Otherwise, the tilde-prefix is replaced with the home directory
3041 associated with the specified login name.
3043 If the tilde-prefix is a `~+', the value of the shell variable
3046 replaces the tilde-prefix.
3047 If the tilde-prefix is a `~\-', the value of the shell variable
3050 if it is set, is substituted.
3051 If the characters following the tilde in the tilde-prefix consist
3052 of a number \fIN\fP, optionally prefixed
3053 by a `+' or a `\-', the tilde-prefix is replaced with the corresponding
3054 element from the directory stack, as it would be displayed by the
3056 builtin invoked with the tilde-prefix as an argument.
3057 If the characters following the tilde in the tilde-prefix consist of a
3058 number without a leading `+' or `\-', `+' is assumed.
3060 If the login name is invalid, or the tilde expansion fails, the word
3063 Each variable assignment is checked for unquoted tilde-prefixes immediately
3068 In these cases, tilde expansion is also performed.
3069 Consequently, one may use filenames with tildes in assignments to
3077 and the shell assigns the expanded value.
3079 Bash also performs tilde expansion on words satisfying the conditions of
3080 variable assignments (as described above under
3083 when they appear as arguments to simple commands.
3084 Bash does not do this, except for the \fIdeclaration\fP commands listed
3085 above, when in \fIposix mode\fP.
3086 .SS Parameter Expansion
3087 The `\fB$\fP' character introduces parameter expansion,
3088 command substitution, or arithmetic expansion. The parameter name
3089 or symbol to be expanded may be enclosed in braces, which
3090 are optional but serve to protect the variable to be expanded from
3091 characters immediately following it which could be
3092 interpreted as part of the name.
3094 When braces are used, the matching ending brace is the first `\fB}\fP'
3095 not escaped by a backslash or within a quoted string, and not within an
3096 embedded arithmetic expansion, command substitution, or parameter
3102 The value of \fIparameter\fP is substituted. The braces are required
3105 is a positional parameter with more than one digit,
3108 is followed by a character which is not to be
3109 interpreted as part of its name.
3110 The \fIparameter\fP is a shell parameter as described above
3111 \fBPARAMETERS\fP) or an array reference (\fBArrays\fP).
3114 If the first character of \fIparameter\fP is an exclamation point (\fB!\fP),
3115 and \fIparameter\fP is not a \fInameref\fP,
3116 it introduces a level of indirection.
3117 \fBBash\fP uses the value formed by expanding the rest of
3118 \fIparameter\fP as the new \fIparameter\fP; this is then
3119 expanded and that value is used in the rest of the expansion, rather
3120 than the expansion of the original \fIparameter\fP.
3121 This is known as \fIindirect expansion\fP.
3122 The value is subject to tilde expansion,
3123 parameter expansion, command substitution, and arithmetic expansion.
3124 If \fIparameter\fP is a nameref, this expands to the name of the
3125 parameter referenced by \fIparameter\fP instead of performing the
3126 complete indirect expansion.
3127 The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and
3128 ${\fB!\fP\fIname\fP[\fI@\fP]} described below.
3129 The exclamation point must immediately follow the left brace in order to
3130 introduce indirection.
3132 In each of the cases below, \fIword\fP is subject to tilde expansion,
3133 parameter expansion, command substitution, and arithmetic expansion.
3135 When not performing substring expansion, using the forms documented below
3137 \fBbash\fP tests for a parameter that is unset or null. Omitting the colon
3138 results in a test only for a parameter that is unset.
3142 ${\fIparameter\fP\fB:\-\fP\fIword\fP}
3143 \fBUse Default Values\fP. If
3145 is unset or null, the expansion of
3147 is substituted. Otherwise, the value of
3151 ${\fIparameter\fP\fB:=\fP\fIword\fP}
3152 \fBAssign Default Values\fP.
3155 is unset or null, the expansion of
3161 is then substituted. Positional parameters and special parameters may
3162 not be assigned to in this way.
3164 ${\fIparameter\fP\fB:?\fP\fIword\fP}
3165 \fBDisplay Error if Null or Unset\fP.
3168 is null or unset, the expansion of \fIword\fP (or a message to that effect
3171 is not present) is written to the standard error and the shell, if it
3172 is not interactive, exits. Otherwise, the value of \fIparameter\fP is
3175 ${\fIparameter\fP\fB:+\fP\fIword\fP}
3176 \fBUse Alternate Value\fP.
3179 is null or unset, nothing is substituted, otherwise the expansion of
3183 ${\fIparameter\fP\fB:\fP\fIoffset\fP}
3186 ${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
3188 \fBSubstring Expansion\fP.
3189 Expands to up to \fIlength\fP characters of the value of \fIparameter\fP
3190 starting at the character specified by \fIoffset\fP.
3191 If \fIparameter\fP is \fB@\fP or \fB*\fP, an indexed array subscripted by
3192 \fB@\fP or \fB*\fP, or an associative array name, the results differ as
3194 If \fIlength\fP is omitted, expands to the substring of the value of
3195 \fIparameter\fP starting at the character specified by \fIoffset\fP
3196 and extending to the end of the value.
3197 \fIlength\fP and \fIoffset\fP are arithmetic expressions (see
3200 ARITHMETIC EVALUATION
3203 If \fIoffset\fP evaluates to a number less than zero, the value
3204 is used as an offset in characters
3205 from the end of the value of \fIparameter\fP.
3206 If \fIlength\fP evaluates to a number less than zero,
3207 it is interpreted as an offset in characters
3208 from the end of the value of \fIparameter\fP rather than
3209 a number of characters, and the expansion is the characters between
3210 \fIoffset\fP and that result.
3211 Note that a negative offset must be separated from the colon by at least
3212 one space to avoid being confused with the \fB:-\fP expansion.
3214 If \fIparameter\fP is \fB@\fP or \fB*\fP, the result is \fIlength\fP
3215 positional parameters beginning at \fIoffset\fP.
3216 A negative \fIoffset\fP is taken relative to one greater than the greatest
3217 positional parameter, so an offset of \-1 evaluates to the last positional
3219 It is an expansion error if \fIlength\fP evaluates to a number less than
3222 If \fIparameter\fP is an indexed array name subscripted by @ or *,
3223 the result is the \fIlength\fP
3224 members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
3225 A negative \fIoffset\fP is taken relative to one greater than the maximum
3226 index of the specified array.
3227 It is an expansion error if \fIlength\fP evaluates to a number less than
3230 Substring expansion applied to an associative array produces undefined
3233 Substring indexing is zero-based unless the positional parameters
3234 are used, in which case the indexing starts at 1 by default.
3235 If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is
3236 prefixed to the list.
3238 ${\fB!\fP\fIprefix\fP\fB*\fP}
3241 ${\fB!\fP\fIprefix\fP\fB@\fP}
3243 \fBNames matching prefix\fP.
3244 Expands to the names of variables whose names begin with \fIprefix\fP,
3245 separated by the first character of the
3249 When \fI@\fP is used and the expansion appears within double quotes, each
3250 variable name expands to a separate word.
3252 ${\fB!\fP\fIname\fP[\fI@\fP]}
3255 ${\fB!\fP\fIname\fP[\fI*\fP]}
3257 \fBList of array keys\fP.
3258 If \fIname\fP is an array variable, expands to the list of array indices
3259 (keys) assigned in \fIname\fP.
3260 If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null
3262 When \fI@\fP is used and the expansion appears within double quotes, each
3263 key expands to a separate word.
3265 ${\fB#\fP\fIparameter\fP}
3266 \fBParameter length\fP.
3267 The length in characters of the value of \fIparameter\fP is substituted.
3274 the value substituted is the number of positional parameters.
3277 is an array name subscripted by
3281 the value substituted is the number of elements in the array.
3284 is an indexed array name subscripted by a negative number, that number is
3285 interpreted as relative to one greater than the maximum index of
3286 \fIparameter\fP, so negative indices count back from the end of the
3287 array, and an index of \-1 references the last element.
3289 ${\fIparameter\fP\fB#\fP\fIword\fP}
3292 ${\fIparameter\fP\fB##\fP\fIword\fP}
3294 \fBRemove matching prefix pattern\fP.
3297 is expanded to produce a pattern just as in pathname
3298 expansion, and matched against the expanded value of
3300 using the rules described under
3303 If the pattern matches the beginning of
3306 then the result of the expansion is the expanded value of
3308 with the shortest matching pattern (the ``\fB#\fP'' case) or the
3309 longest matching pattern (the ``\fB##\fP'' case) deleted.
3316 the pattern removal operation is applied to each positional
3317 parameter in turn, and the expansion is the resultant list.
3320 is an array variable subscripted with
3324 the pattern removal operation is applied to each member of the
3325 array in turn, and the expansion is the resultant list.
3327 ${\fIparameter\fP\fB%\fP\fIword\fP}
3330 ${\fIparameter\fP\fB%%\fP\fIword\fP}
3332 \fBRemove matching suffix pattern\fP.
3333 The \fIword\fP is expanded to produce a pattern just as in
3334 pathname expansion, and matched against the expanded value of
3336 using the rules described under
3339 If the pattern matches a trailing portion of the expanded value of
3341 then the result of the expansion is the expanded value of
3343 with the shortest matching pattern (the ``\fB%\fP'' case) or the
3344 longest matching pattern (the ``\fB%%\fP'' case) deleted.
3351 the pattern removal operation is applied to each positional
3352 parameter in turn, and the expansion is the resultant list.
3355 is an array variable subscripted with
3359 the pattern removal operation is applied to each member of the
3360 array in turn, and the expansion is the resultant list.
3362 ${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3365 ${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3367 ${\fIparameter\fP\fB/#\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3369 ${\fIparameter\fP\fB/%\fP\fIpattern\fP\fB/\fP\fIstring\fP}
3371 \fBPattern substitution\fP.
3372 The \fIpattern\fP is expanded to produce a pattern just as in
3374 \fIParameter\fP is expanded and the longest match of \fIpattern\fP
3375 against its value is replaced with \fIstring\fP.
3376 \fIstring\fP undergoes tilde expansion, parameter and variable expansion,
3377 arithmetic expansion, command and process substitution, and quote removal.
3378 The match is performed using the rules described under
3381 In the first form above, only the first match is replaced.
3382 If there are two slashes separating \fIparameter\fP and \fIpattern\fP
3383 (the second form above), all matches of \fIpattern\fP are
3384 replaced with \fIstring\fP.
3385 If \fIpattern\fP is preceded by \fB#\fP (the third form above),
3386 it must match at the beginning of the expanded value of \fIparameter\fP.
3387 If \fIpattern\fP is preceded by \fB%\fP (the fourth form above),
3388 it must match at the end of the expanded value of \fIparameter\fP.
3389 If the expansion of \fIstring\fP is null,
3390 matches of \fIpattern\fP are deleted.
3391 If \fIstring\fP is null,
3392 matches of \fIpattern\fP are deleted
3393 and the \fB/\fP following \fIpattern\fP may be omitted.
3395 If the \fBpatsub_replacement\fP shell option is enabled using \fBshopt\fP,
3396 any unquoted instances of \fB&\fP in \fIstring\fP are replaced with the
3397 matching portion of \fIpattern\fP.
3399 Quoting any part of \fIstring\fP inhibits replacement in the
3400 expansion of the quoted portion, including replacement strings stored
3402 Backslash will escape \fB&\fP in \fIstring\fP; the backslash is removed
3403 in order to permit a literal \fB&\fP in the replacement string.
3404 Backslash can also be used to escape a backslash; \fB\e\e\fP results in
3405 a literal backslash in the replacement.
3406 Users should take care if \fIstring\fP is double-quoted to avoid
3407 unwanted interactions between the backslash and double-quoting, since
3408 backslash has special meaning within double quotes.
3409 Pattern substitution performs the check for unquoted \fB&\fP after
3410 expanding \fIstring\fP;
3411 shell programmers should quote any occurrences of \fB&\fP
3412 they want to be taken literally in the replacement
3413 and ensure any instances of \fB&\fP they want to be replaced are unquoted.
3417 shell option is enabled, the match is performed without regard to the case
3418 of alphabetic characters.
3425 the substitution operation is applied to each positional
3426 parameter in turn, and the expansion is the resultant list.
3429 is an array variable subscripted with
3433 the substitution operation is applied to each member of the
3434 array in turn, and the expansion is the resultant list.
3436 ${\fIparameter\fP\fB^\fP\fIpattern\fP}
3439 ${\fIparameter\fP\fB^^\fP\fIpattern\fP}
3441 ${\fIparameter\fP\fB,\fP\fIpattern\fP}
3443 ${\fIparameter\fP\fB,,\fP\fIpattern\fP}
3445 \fBCase modification\fP.
3446 This expansion modifies the case of alphabetic characters in \fIparameter\fP.
3447 The \fIpattern\fP is expanded to produce a pattern just as in
3449 Each character in the expanded value of \fIparameter\fP is tested against
3450 \fIpattern\fP, and, if it matches the pattern, its case is converted.
3451 The pattern should not attempt to match more than one character.
3452 The \fB^\fP operator converts lowercase letters matching \fIpattern\fP
3453 to uppercase; the \fB,\fP operator converts matching uppercase letters
3455 The \fB^^\fP and \fB,,\fP expansions convert each matched character in the
3456 expanded value; the \fB^\fP and \fB,\fP expansions match and convert only
3457 the first character in the expanded value.
3458 If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches
3466 the case modification operation is applied to each positional
3467 parameter in turn, and the expansion is the resultant list.
3470 is an array variable subscripted with
3474 the case modification operation is applied to each member of the
3475 array in turn, and the expansion is the resultant list.
3477 ${\fIparameter\fP\fB@\fP\fIoperator\fP}
3478 \fBParameter transformation\fP.
3479 The expansion is either a transformation of the value of \fIparameter\fP
3480 or information about \fIparameter\fP itself, depending on the value of
3481 \fIoperator\fP. Each \fIoperator\fP is a single letter:
3487 The expansion is a string that is the value of \fIparameter\fP with lowercase
3488 alphabetic characters converted to uppercase.
3491 The expansion is a string that is the value of \fIparameter\fP with the first
3492 character converted to uppercase, if it is alphabetic.
3495 The expansion is a string that is the value of \fIparameter\fP with uppercase
3496 alphabetic characters converted to lowercase.
3499 The expansion is a string that is the value of \fIparameter\fP quoted in a
3500 format that can be reused as input.
3503 The expansion is a string that is the value of \fIparameter\fP with backslash
3504 escape sequences expanded as with the \fB$\(aq...\(aq\fP quoting mechanism.
3507 The expansion is a string that is the result of expanding the value of
3508 \fIparameter\fP as if it were a prompt string (see \fBPROMPTING\fP below).
3511 The expansion is a string in the form of
3512 an assignment statement or \fBdeclare\fP command that, if
3513 evaluated, will recreate \fIparameter\fP with its attributes and value.
3516 Produces a possibly-quoted version of the value of \fIparameter\fP,
3517 except that it prints the values of
3518 indexed and associative arrays as a sequence of quoted key-value pairs
3519 (see \fBArrays\fP above).
3522 The expansion is a string consisting of flag values representing
3523 \fIparameter\fP's attributes.
3526 Like the K transformation, but expands the keys and values of
3527 indexed and associative arrays to separate words after word splitting.
3536 the operation is applied to each positional
3537 parameter in turn, and the expansion is the resultant list.
3540 is an array variable subscripted with
3544 the operation is applied to each member of the
3545 array in turn, and the expansion is the resultant list.
3547 The result of the expansion is subject to word splitting and pathname
3548 expansion as described below.
3550 .SS Command Substitution
3551 \fICommand substitution\fP allows the output of a command to replace
3552 the command name. There are two forms:
3555 \fB$(\fP\fIcommand\fP\|\fB)\fP
3559 \fB\`\fP\fIcommand\fP\fB\`\fP
3563 performs the expansion by executing \fIcommand\fP in a subshell environment
3564 and replacing the command substitution with the standard output of the
3565 command, with any trailing newlines deleted.
3566 Embedded newlines are not deleted, but they may be removed during
3568 The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by
3569 the equivalent but faster \fB$(< \fIfile\fP)\fR.
3571 When the old-style backquote form of substitution is used,
3572 backslash retains its literal meaning except when followed by
3577 The first backquote not preceded by a backslash terminates the
3578 command substitution.
3579 When using the $(\^\fIcommand\fP\|) form, all characters between the
3580 parentheses make up the command; none are treated specially.
3582 Command substitutions may be nested. To nest when using the backquoted form,
3583 escape the inner backquotes with backslashes.
3585 If the substitution appears within double quotes, word splitting and
3586 pathname expansion are not performed on the results.
3587 .SS Arithmetic Expansion
3588 Arithmetic expansion allows the evaluation of an arithmetic expression
3589 and the substitution of the result. The format for arithmetic expansion is:
3592 \fB$((\fP\fIexpression\fP\fB))\fP
3597 undergoes the same expansions
3598 as if it were within double quotes,
3599 but double quote characters in \fIexpression\fP are not treated specially
3601 All tokens in the expression undergo parameter and variable expansion,
3602 command substitution, and quote removal.
3603 The result is treated as the arithmetic expression to be evaluated.
3604 Arithmetic expansions may be nested.
3606 The evaluation is performed according to the rules listed below under
3608 .BR "ARITHMETIC EVALUATION" .
3613 prints a message indicating failure and no substitution occurs.
3614 .SS Process Substitution
3615 \fIProcess substitution\fP allows a process's input or output to be
3616 referred to using a filename.
3617 It takes the form of
3618 \fB<(\fP\fIlist\^\fP\fB)\fP
3620 \fB>(\fP\fIlist\^\fP\fB)\fP.
3621 The process \fIlist\fP is run asynchronously, and its input or output
3622 appears as a filename.
3624 passed as an argument to the current command as the result of the
3626 If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
3627 the file will provide input for \fIlist\fP. If the
3628 \fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an
3629 argument should be read to obtain the output of \fIlist\fP.
3630 Process substitution is supported on systems that support named
3631 pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files.
3633 When available, process substitution is performed
3634 simultaneously with parameter and variable expansion,
3635 command substitution,
3636 and arithmetic expansion.
3638 The shell scans the results of
3639 parameter expansion,
3640 command substitution,
3642 arithmetic expansion
3643 that did not occur within double quotes for
3644 .IR "word splitting" .
3646 The shell treats each character of
3649 as a delimiter, and splits the results of the other
3650 expansions into words using these characters as field terminators.
3656 .BR <space><tab><newline> ,
3663 at the beginning and end of the results of the previous
3664 expansions are ignored, and
3668 characters not at the beginning or end serves to delimit words.
3672 has a value other than the default, then sequences of
3673 the whitespace characters
3678 are ignored at the beginning and end of the
3679 word, as long as the whitespace character is in the
3686 whitespace character).
3693 whitespace, along with any adjacent
3696 whitespace characters, delimits a field.
3700 whitespace characters is also treated as a delimiter.
3704 is null, no word splitting occurs.
3706 Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained
3707 and passed to commands as empty strings.
3708 Unquoted implicit null arguments, resulting from the expansion of
3709 parameters that have no values, are removed.
3710 If a parameter with no value is expanded within double quotes, a
3711 null argument results and is retained
3712 and passed to a command as an empty string.
3713 When a quoted null argument appears as part of a word whose expansion is
3714 non-null, the null argument is removed.
3716 \f(CW\-d\(aq\^\(aq\fP becomes \f(CW\-d\fP after word splitting and
3717 null argument removal.
3719 Note that if no expansion occurs, no splitting
3721 .SS Pathname Expansion
3722 After word splitting,
3725 option has been set,
3727 scans each word for the characters
3732 If one of these characters appears, and is not quoted, then the word is
3735 and replaced with an alphabetically sorted list of
3736 filenames matching the pattern
3739 .B "Pattern Matching"
3741 If no matching filenames are found,
3742 and the shell option
3744 is not enabled, the word is left unchanged.
3747 option is set, and no matches are found,
3748 the word is removed.
3751 shell option is set, and no matches are found, an error message
3752 is printed and the command is not executed.
3755 is enabled, the match is performed without regard to the case
3756 of alphabetic characters.
3757 When a pattern is used for pathname expansion,
3760 at the start of a name or immediately following a slash
3761 must be matched explicitly, unless the shell option
3764 In order to match the filenames
3768 the pattern must begin with ``.'' (for example, ``.?''),
3774 shell option is enabled, the filenames
3778 are never matched, even if the pattern begins with a
3780 When not matching pathnames, the
3782 character is not treated specially.
3783 When matching a pathname, the slash character must always be
3784 matched explicitly by a slash in the pattern, but in other matching
3785 contexts it can be matched by a special pattern character as described
3788 .BR "Pattern Matching" .
3789 See the description of
3793 .B SHELL BUILTIN COMMANDS
3794 for a description of the
3806 shell variable may be used to restrict the set of file names matching a
3811 is set, each matching file name that also matches one of the patterns in
3814 is removed from the list of matches.
3815 If the \fBnocaseglob\fP option is set, the matching against the patterns in
3818 is performed without regard to case.
3823 are always ignored when
3826 is set and not null. However, setting
3829 to a non-null value has the effect of enabling the
3831 shell option, so all other filenames beginning with a
3834 To get the old behavior of ignoring filenames beginning with a
3838 one of the patterns in
3843 option is disabled when
3847 The pattern matching honors the setting of the \fBextglob\fP shell
3850 \fBPattern Matching\fP
3852 Any character that appears in a pattern, other than the special pattern
3853 characters described below, matches itself. The NUL character may not
3854 occur in a pattern. A backslash escapes the following character; the
3855 escaping backslash is discarded when matching.
3856 The special pattern characters must be quoted if
3857 they are to be matched literally.
3859 The special pattern characters have the following meanings:
3865 Matches any string, including the null string.
3866 When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in
3867 a pathname expansion context, two adjacent \fB*\fPs used as a single
3868 pattern will match all files and zero or more directories and
3870 If followed by a \fB/\fP, two adjacent \fB*\fPs will match only directories
3874 Matches any single character.
3877 Matches any one of the enclosed characters. A pair of characters
3878 separated by a hyphen denotes a
3879 \fIrange expression\fP;
3880 any character that falls between those two characters, inclusive,
3881 using the current locale's collating sequence and character set,
3882 is matched. If the first character following the
3888 then any character not enclosed is matched.
3889 The sorting order of characters in range expressions,
3890 and the characters included in the range,
3892 the current locale and the values of the
3898 shell variables, if set.
3899 To obtain the traditional interpretation of range expressions, where
3912 may be matched by including it as the first or last character
3916 may be matched by including it as the first character
3925 \fIcharacter classes\fP can be specified using the syntax
3926 \fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the
3927 following classes defined in the POSIX standard:
3931 .if n alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit
3932 .if t alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit
3934 A character class matches any character belonging to that class.
3935 The \fBword\fP character class matches letters, digits, and the character _.
3943 an \fIequivalence class\fP can be specified using the syntax
3944 \fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the
3945 same collation weight (as defined by the current locale) as
3946 the character \fIc\fP.
3954 the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol
3960 If the \fBextglob\fP shell option is enabled using the \fBshopt\fP
3961 builtin, the shell recognizes several extended pattern matching operators.
3962 In the following description, a \fIpattern-list\fP is a list of one
3963 or more patterns separated by a \fB|\fP.
3964 Composite patterns may be formed using one or more of the following
3970 \fB?(\fP\^\fIpattern-list\^\fP\fB)\fP
3971 Matches zero or one occurrence of the given patterns
3973 \fB*(\fP\^\fIpattern-list\^\fP\fB)\fP
3974 Matches zero or more occurrences of the given patterns
3976 \fB+(\fP\^\fIpattern-list\^\fP\fB)\fP
3977 Matches one or more occurrences of the given patterns
3979 \fB@(\fP\^\fIpattern-list\^\fP\fB)\fP
3980 Matches one of the given patterns
3982 \fB!(\fP\^\fIpattern-list\^\fP\fB)\fP
3983 Matches anything except one of the given patterns
3987 The\fBextglob\fP option changes the behavior of the parser, since the
3988 parentheses are normally treated as operators with syntactic meaning.
3989 To ensure that extended matching patterns are parsed correctly, make sure
3990 that \fBextglob\fP is enabled before parsing constructs containing the
3991 patterns, including shell functions and command substitutions.
3993 When matching filenames, the \fBdotglob\fP shell option determines
3994 the set of filenames that are tested:
3995 when \fBdotglob\fP is enabled, the set of filenames includes all files
3996 beginning with ``.'', but ``.'' and ``..'' must be matched by a
3997 pattern or sub-pattern that begins with a dot;
3998 when it is disabled, the set does not
3999 include any filenames beginning with ``.'' unless the pattern
4000 or sub-pattern begins with a ``.''.
4001 As above, ``.'' only has a special meaning when matching filenames.
4003 Complicated extended pattern matching against long strings is slow,
4004 especially when the patterns contain alternations and the strings
4005 contain multiple matches.
4006 Using separate matches against shorter strings, or using arrays of
4007 strings instead of a single long string, may be faster.
4009 After the preceding expansions, all unquoted occurrences of the
4013 and \^\f3"\fP\^ that did not result from one of the above
4014 expansions are removed.
4016 Before a command is executed, its input and output
4019 using a special notation interpreted by the shell.
4020 \fIRedirection\fP allows commands' file handles to be
4021 duplicated, opened, closed,
4022 made to refer to different files,
4023 and can change the files the command reads from and writes to.
4024 Redirection may also be used to modify file handles in the
4025 current shell execution environment.
4026 The following redirection
4027 operators may precede or appear anywhere within a
4031 Redirections are processed in the order they appear, from
4034 Each redirection that may be preceded by a file descriptor number
4035 may instead be preceded by a word of the form {\fIvarname\fP}.
4036 In this case, for each redirection operator except
4037 >&- and <&-, the shell will allocate a file descriptor greater
4038 than or equal to 10 and assign it to \fIvarname\fP.
4039 If >&- or <&- is preceded
4040 by {\fIvarname\fP}, the value of \fIvarname\fP defines the file
4041 descriptor to close.
4042 If {\fIvarname\fP} is supplied, the redirection persists beyond
4043 the scope of the command, allowing the shell programmer to manage
4044 the file descriptor's lifetime manually.
4045 The \fBvarredir_close\fP shell option manages this behavior.
4047 In the following descriptions, if the file descriptor number is
4048 omitted, and the first character of the redirection operator is
4050 the redirection refers to the standard input (file descriptor
4051 0). If the first character of the redirection operator is
4053 the redirection refers to the standard output (file descriptor
4056 The word following the redirection operator in the following
4057 descriptions, unless otherwise noted, is subjected to
4058 brace expansion, tilde expansion, parameter and variable expansion,
4059 command substitution, arithmetic expansion, quote removal,
4060 pathname expansion, and word splitting.
4061 If it expands to more than one word,
4065 Note that the order of redirections is significant. For example,
4069 ls \fB>\fP dirlist 2\fB>&\fP1
4072 directs both standard output and standard error to the file
4077 ls 2\fB>&\fP1 \fB>\fP dirlist
4080 directs only the standard output to file
4082 because the standard error was duplicated from the standard output
4083 before the standard output was redirected to
4086 \fBBash\fP handles several filenames specially when they are used in
4087 redirections, as described in the following table.
4088 If the operating system on which \fBbash\fP is running provides these
4089 special files, bash will use them; otherwise it will emulate them
4090 internally with the behavior described below.
4096 If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated.
4099 File descriptor 0 is duplicated.
4102 File descriptor 1 is duplicated.
4105 File descriptor 2 is duplicated.
4107 .B /dev/tcp/\fIhost\fP/\fIport\fP
4108 If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
4109 is an integer port number or service name, \fBbash\fP attempts to open
4110 the corresponding TCP socket.
4112 .B /dev/udp/\fIhost\fP/\fIport\fP
4113 If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP
4114 is an integer port number or service name, \fBbash\fP attempts to open
4115 the corresponding UDP socket.
4119 A failure to open or create a file causes the redirection to fail.
4121 Redirections using file descriptors greater than 9 should be used with
4122 care, as they may conflict with file descriptors the shell uses
4124 .SS Redirecting Input
4125 Redirection of input causes the file whose name results from
4128 to be opened for reading on file descriptor
4130 or the standard input (file descriptor 0) if
4134 The general format for redirecting input is:
4137 [\fIn\fP]\fB<\fP\fIword\fP
4139 .SS Redirecting Output
4140 Redirection of output causes the file whose name results from
4143 to be opened for writing on file descriptor
4145 or the standard output (file descriptor 1) if
4147 is not specified. If the file does not exist it is created;
4148 if it does exist it is truncated to zero size.
4150 The general format for redirecting output is:
4153 [\fIn\fP]\fB>\fP\fIword\fP
4156 If the redirection operator is
4162 builtin has been enabled, the redirection will fail if the file
4163 whose name results from the expansion of \fIword\fP exists and is
4165 If the redirection operator is
4167 or the redirection operator is
4173 builtin command is not enabled, the redirection is attempted even
4174 if the file named by \fIword\fP exists.
4175 .SS Appending Redirected Output
4176 Redirection of output in this fashion
4177 causes the file whose name results from
4180 to be opened for appending on file descriptor
4182 or the standard output (file descriptor 1) if
4184 is not specified. If the file does not exist it is created.
4186 The general format for appending output is:
4189 [\fIn\fP]\fB>>\fP\fIword\fP
4191 .SS Redirecting Standard Output and Standard Error
4192 This construct allows both the
4193 standard output (file descriptor 1) and
4194 the standard error output (file descriptor 2)
4195 to be redirected to the file whose name is the
4199 There are two formats for redirecting standard output and
4210 Of the two forms, the first is preferred.
4211 This is semantically equivalent to
4214 \fB>\fP\fIword\fP 2\fB>&\fP1
4217 When using the second form, \fIword\fP may not expand to a number or
4218 \fB\-\fP. If it does, other redirection operators apply
4219 (see \fBDuplicating File Descriptors\fP below) for compatibility
4221 .SS Appending Standard Output and Standard Error
4222 This construct allows both the
4223 standard output (file descriptor 1) and
4224 the standard error output (file descriptor 2)
4225 to be appended to the file whose name is the
4229 The format for appending standard output and standard error is:
4235 This is semantically equivalent to
4238 \fB>>\fP\fIword\fP 2\fB>&\fP1
4241 (see \fBDuplicating File Descriptors\fP below).
4243 This type of redirection instructs the shell to read input from the
4244 current source until a line containing only
4246 (with no trailing blanks)
4248 the lines read up to that point are then used as the standard
4249 input (or file descriptor \fIn\fP if \fIn\fP is specified) for a command.
4251 The format of here-documents is:
4255 [\fIn\fP]\fB<<\fP[\fB\-\fP]\fIword\fP
4261 No parameter and variable expansion, command substitution,
4262 arithmetic expansion, or pathname expansion is performed on
4268 is the result of quote removal on
4270 and the lines in the here-document are not expanded.
4271 If \fIword\fP is unquoted,
4272 all lines of the here-document are subjected to
4273 parameter expansion, command substitution, and arithmetic expansion,
4274 the character sequence
4278 must be used to quote the characters
4284 If the redirection operator is
4286 then all leading tab characters are stripped from input lines and the
4290 here-documents within shell scripts to be indented in a
4293 A variant of here documents, the format is:
4297 [\fIn\fP]\fB<<<\fP\fIword\fP
4301 The \fIword\fP undergoes
4302 tilde expansion, parameter and variable expansion,
4303 command substitution, arithmetic expansion, and quote removal.
4304 Pathname expansion and word splitting are not performed.
4305 The result is supplied as a single string, with a newline appended,
4306 to the command on its
4307 standard input (or file descriptor \fIn\fP if \fIn\fP is specified).
4308 .SS "Duplicating File Descriptors"
4309 The redirection operator
4312 [\fIn\fP]\fB<&\fP\fIword\fP
4315 is used to duplicate input file descriptors.
4318 expands to one or more digits, the file descriptor denoted by
4320 is made to be a copy of that file descriptor.
4323 do not specify a file descriptor open for input, a redirection error occurs.
4332 is not specified, the standard input (file descriptor 0) is used.
4337 [\fIn\fP]\fB>&\fP\fIword\fP
4340 is used similarly to duplicate output file descriptors. If
4342 is not specified, the standard output (file descriptor 1) is used.
4345 do not specify a file descriptor open for output, a redirection error occurs.
4353 As a special case, if \fIn\fP is omitted, and \fIword\fP does not
4354 expand to one or more digits or \fB\-\fP, the standard output and standard
4355 error are redirected as described previously.
4356 .SS "Moving File Descriptors"
4357 The redirection operator
4360 [\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP
4363 moves the file descriptor \fIdigit\fP to file descriptor
4365 or the standard input (file descriptor 0) if \fIn\fP is not specified.
4366 \fIdigit\fP is closed after being duplicated to \fIn\fP.
4368 Similarly, the redirection operator
4371 [\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP
4374 moves the file descriptor \fIdigit\fP to file descriptor
4376 or the standard output (file descriptor 1) if \fIn\fP is not specified.
4377 .SS "Opening File Descriptors for Reading and Writing"
4378 The redirection operator
4381 [\fIn\fP]\fB<>\fP\fIword\fP
4384 causes the file whose name is the expansion of
4386 to be opened for both reading and writing on file descriptor
4388 or on file descriptor 0 if
4390 is not specified. If the file does not exist, it is created.
4392 \fIAliases\fP allow a string to be substituted for a word when it is used
4393 as the first word of a simple command.
4394 The shell maintains a list of aliases that may be set and unset with the
4398 builtin commands (see
4400 .B SHELL BUILTIN COMMANDS
4402 The first word of each simple command, if unquoted,
4403 is checked to see if it has an
4404 alias. If so, that word is replaced by the text of the alias.
4405 The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and
4406 any of the shell \fImetacharacters\fP or quoting characters
4407 listed above may not appear in an alias name.
4408 The replacement text may contain any valid shell input,
4409 including shell metacharacters.
4410 The first word of the replacement text is tested
4411 for aliases, but a word that is identical to an alias being expanded
4412 is not expanded a second time.
4413 This means that one may alias
4419 does not try to recursively expand the replacement text.
4420 If the last character of the alias value is a
4422 then the next command
4423 word following the alias is also checked for alias expansion.
4425 Aliases are created and listed with the
4427 command, and removed with the
4431 There is no mechanism for using arguments in the replacement text.
4432 If arguments are needed, use a shell function (see
4437 Aliases are not expanded when the shell is not interactive, unless
4440 shell option is set using
4442 (see the description of
4446 \fBSHELL BUILTIN COMMANDS\fP
4449 The rules concerning the definition and use of aliases are
4452 always reads at least one complete line of input,
4453 and all lines that make up a compound command,
4454 before executing any of the commands on that line or the compound command.
4455 Aliases are expanded when a
4456 command is read, not when it is executed. Therefore, an
4457 alias definition appearing on the same line as another
4458 command does not take effect until the next line of input is read.
4459 The commands following the alias definition
4460 on that line are not affected by the new alias.
4461 This behavior is also an issue when functions are executed.
4462 Aliases are expanded when a function definition is read,
4463 not when the function is executed, because a function definition
4464 is itself a command. As a consequence, aliases
4465 defined in a function are not available until after that
4466 function is executed. To be safe, always put
4467 alias definitions on a separate line, and do not use
4469 in compound commands.
4471 For almost every purpose, aliases are superseded by
4474 A shell function, defined as described above under
4476 .BR "SHELL GRAMMAR" ,
4477 stores a series of commands for later execution.
4478 When the name of a shell function is used as a simple command name,
4479 the list of commands associated with that function name is executed.
4480 Functions are executed in the context of the
4481 current shell; no new process is created to interpret
4482 them (contrast this with the execution of a shell script).
4483 When a function is executed, the arguments to the
4484 function become the positional parameters
4485 during its execution.
4486 The special parameter
4488 is updated to reflect the change. Special parameter \fB0\fP
4490 The first element of the
4493 variable is set to the name of the function while the function
4496 All other aspects of the shell execution
4497 environment are identical between a function and its caller
4498 with these exceptions: the
4503 traps (see the description of the
4507 .B SHELL BUILTIN COMMANDS
4508 below) are not inherited unless the function has been given the
4509 \fBtrace\fP attribute (see the description of the
4512 builtin below) or the
4513 \fB\-o functrace\fP shell option has been enabled with
4514 the \fBset\fP builtin
4515 (in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps),
4519 trap is not inherited unless the \fB\-o errtrace\fP shell option has
4522 Variables local to the function may be declared with the
4524 builtin command (\fIlocal variables\fP).
4525 Ordinarily, variables and their values
4526 are shared between the function and its caller.
4527 If a variable is declared \fBlocal\fP, the variable's visible scope
4528 is restricted to that function and its children (including the functions
4531 In the following description, the \fIcurrent scope\fP is a currently-
4533 Previous scopes consist of that function's caller and so on,
4534 back to the "global" scope, where the shell is not executing
4536 Consequently, a local variable at the current scope is a variable
4537 declared using the \fBlocal\fP or \fBdeclare\fP builtins in the
4538 function that is currently executing.
4540 Local variables "shadow" variables with the same name declared at
4542 For instance, a local variable declared in a function
4543 hides a global variable of the same name: references and assignments
4544 refer to the local variable, leaving the global variable unmodified.
4545 When the function returns, the global variable is once again visible.
4547 The shell uses \fIdynamic scoping\fP to control a variable's visibility
4549 With dynamic scoping, visible variables and their values
4550 are a result of the sequence of function calls that caused execution
4551 to reach the current function.
4552 The value of a variable that a function sees depends
4553 on its value within its caller, if any, whether that caller is
4554 the "global" scope or another shell function.
4555 This is also the value that a local variable
4556 declaration "shadows", and the value that is restored when the function
4559 For example, if a variable \fIvar\fP is declared as local in function
4560 \fIfunc1\fP, and \fIfunc1\fP calls another function \fIfunc2\fP,
4561 references to \fIvar\fP made from within \fIfunc2\fP will resolve to the
4562 local variable \fIvar\fP from \fIfunc1\fP, shadowing any global variable
4565 The \fBunset\fP builtin also acts using the same dynamic scope: if a
4566 variable is local to the current scope, \fBunset\fP will unset it;
4567 otherwise the unset will refer to the variable found in any calling scope
4569 If a variable at the current local scope is unset, it will remain so
4570 (appearing as unset)
4571 until it is reset in that scope or until the function returns.
4572 Once the function returns, any instance of the variable at a previous
4573 scope will become visible.
4574 If the unset acts on a variable at a previous scope, any instance of a
4575 variable with that name that had been shadowed will become visible
4576 (see below how the \fBlocalvar_unset\fP shell option changes this behavior).
4578 The \fBFUNCNEST\fP variable, if set to a numeric value greater
4579 than 0, defines a maximum function nesting level. Function
4580 invocations that exceed the limit cause the entire command to
4583 If the builtin command
4585 is executed in a function, the function completes and
4586 execution resumes with the next command after the function
4588 Any command associated with the \fBRETURN\fP trap is executed
4589 before execution resumes.
4590 When a function completes, the values of the
4591 positional parameters and the special parameter
4593 are restored to the values they had prior to the function's
4596 Function names and definitions may be listed with the
4602 builtin commands. The
4608 will list the function names only
4609 (and optionally the source file and line number, if the \fBextdebug\fP
4610 shell option is enabled).
4611 Functions may be exported so that child shell processes
4612 (those created when executing a separate shell invocation)
4613 automatically have them defined with the
4618 A function definition may be deleted using the \fB\-f\fP option to
4623 Functions may be recursive.
4624 The \fBFUNCNEST\fP variable may be used to limit the depth of the
4625 function call stack and restrict the number of function invocations.
4626 By default, no limit is imposed on the number of recursive calls.
4627 .SH "ARITHMETIC EVALUATION"
4628 The shell allows arithmetic expressions to be evaluated, under
4629 certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin
4630 commands, the \fB((\fP compound command, and \fBArithmetic Expansion\fP).
4631 Evaluation is done in fixed-width integers with no check for overflow,
4632 though division by 0 is trapped and flagged as an error.
4633 The operators and their precedence, associativity, and values
4634 are the same as in the C language.
4635 The following list of operators is grouped into levels of
4636 equal-precedence operators.
4637 The levels are listed in order of decreasing precedence.
4641 .B \fIid\fP++ \fIid\fP\-\-
4642 variable post-increment and post-decrement
4645 unary minus and plus
4647 .B ++\fIid\fP \-\-\fIid\fP
4648 variable pre-increment and pre-decrement
4651 logical and bitwise negation
4657 multiplication, division, remainder
4660 addition, subtraction
4663 left and right bitwise shifts
4669 equality and inequality
4675 bitwise exclusive OR
4686 .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
4687 conditional operator
4689 .B = *= /= %= += \-= <<= >>= &= ^= |=
4692 .B \fIexpr1\fP , \fIexpr2\fP
4696 Shell variables are allowed as operands; parameter expansion is
4697 performed before the expression is evaluated.
4698 Within an expression, shell variables may also be referenced by name
4699 without using the parameter expansion syntax.
4700 A shell variable that is null or unset evaluates to 0 when referenced
4701 by name without using the parameter expansion syntax.
4702 The value of a variable is evaluated as an arithmetic expression
4703 when it is referenced, or when a variable which has been given the
4704 \fIinteger\fP attribute using \fBdeclare \-i\fP is assigned a value.
4705 A null value evaluates to 0.
4706 A shell variable need not have its \fIinteger\fP attribute
4707 turned on to be used in an expression.
4709 Integer constants follow the C language definition, without suffixes or
4710 character constants.
4711 Constants with a leading 0 are interpreted as octal numbers.
4712 A leading 0x or 0X denotes hexadecimal.
4713 Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP
4714 is a decimal number between 2 and 64 representing the arithmetic
4715 base, and \fIn\fP is a number in that base.
4716 If \fIbase#\fP is omitted, then base 10 is used.
4717 When specifying \fIn\fP,
4718 if a non-digit is required,
4719 the digits greater than 9 are represented by the lowercase letters,
4720 the uppercase letters, @, and _, in that order.
4721 If \fIbase\fP is less than or equal to 36, lowercase and uppercase
4722 letters may be used interchangeably to represent numbers between 10
4725 Operators are evaluated in order of precedence. Sub-expressions in
4726 parentheses are evaluated first and may override the precedence
4728 .SH "CONDITIONAL EXPRESSIONS"
4729 Conditional expressions are used by the \fB[[\fP compound command and
4730 the \fBtest\fP and \fB[\fP builtin commands to test file attributes
4731 and perform string and arithmetic comparisons.
4732 The \fBtest\fP and \fB[\fP commands determine their behavior based on
4733 the number of arguments; see the descriptions of those commands for any
4734 other command-specific actions.
4736 Expressions are formed from the following unary or binary primaries.
4737 \fBBash\fP handles several filenames specially when they are used in
4739 If the operating system on which \fBbash\fP is running provides these
4740 special files, bash will use them; otherwise it will emulate them
4741 internally with this behavior:
4742 If any \fIfile\fP argument to one of the primaries is of the form
4743 \fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked.
4744 If the \fIfile\fP argument to one of the primaries is one of
4745 \fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file
4746 descriptor 0, 1, or 2, respectively, is checked.
4748 Unless otherwise specified, primaries that operate on files follow symbolic
4749 links and operate on the target of the link, rather than the link itself.
4752 When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort
4753 lexicographically using the current locale.
4754 The \fBtest\fP command sorts using ASCII ordering.
4759 True if \fIfile\fP exists.
4762 True if \fIfile\fP exists and is a block special file.
4765 True if \fIfile\fP exists and is a character special file.
4768 True if \fIfile\fP exists and is a directory.
4771 True if \fIfile\fP exists.
4774 True if \fIfile\fP exists and is a regular file.
4777 True if \fIfile\fP exists and is set-group-id.
4780 True if \fIfile\fP exists and is a symbolic link.
4783 True if \fIfile\fP exists and its ``sticky'' bit is set.
4786 True if \fIfile\fP exists and is a named pipe (FIFO).
4789 True if \fIfile\fP exists and is readable.
4792 True if \fIfile\fP exists and has a size greater than zero.
4795 True if file descriptor
4797 is open and refers to a terminal.
4800 True if \fIfile\fP exists and its set-user-id bit is set.
4803 True if \fIfile\fP exists and is writable.
4806 True if \fIfile\fP exists and is executable.
4809 True if \fIfile\fP exists and is owned by the effective group id.
4812 True if \fIfile\fP exists and is a symbolic link.
4815 True if \fIfile\fP exists and has been modified since it was last read.
4818 True if \fIfile\fP exists and is owned by the effective user id.
4821 True if \fIfile\fP exists and is a socket.
4823 \fIfile1\fP \fB\-ef\fP \fIfile2\fP
4824 True if \fIfile1\fP and \fIfile2\fP refer to the same device and
4827 \fIfile1\fP \-\fBnt\fP \fIfile2\fP
4828 True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP,
4829 or if \fIfile1\fP exists and \fPfile2\fP does not.
4831 \fIfile1\fP \-\fBot\fP \fIfile2\fP
4832 True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists
4833 and \fIfile1\fP does not.
4835 .B \-o \fIoptname\fP
4836 True if the shell option
4839 See the list of options under the description of the
4845 .B \-v \fIvarname\fP
4846 True if the shell variable
4848 is set (has been assigned a value).
4850 .B \-R \fIvarname\fP
4851 True if the shell variable
4853 is set and is a name reference.
4856 True if the length of \fIstring\fP is zero.
4863 True if the length of
4867 \fIstring1\fP \fB==\fP \fIstring2\fP
4870 \fIstring1\fP \fB=\fP \fIstring2\fP
4872 True if the strings are equal. \fB=\fP should be used
4873 with the \fBtest\fP command for POSIX conformance.
4874 When used with the \fB[[\fP command, this performs pattern matching as
4875 described above (\fBCompound Commands\fP).
4877 \fIstring1\fP \fB!=\fP \fIstring2\fP
4878 True if the strings are not equal.
4880 \fIstring1\fP \fB<\fP \fIstring2\fP
4881 True if \fIstring1\fP sorts before \fIstring2\fP lexicographically.
4883 \fIstring1\fP \fB>\fP \fIstring2\fP
4884 True if \fIstring1\fP sorts after \fIstring2\fP lexicographically.
4886 .I \fIarg1\fP \fBOP\fP \fIarg2\fP
4897 These arithmetic binary operators return true if \fIarg1\fP
4898 is equal to, not equal to, less than, less than or equal to,
4899 greater than, or greater than or equal to \fIarg2\fP, respectively.
4903 may be positive or negative integers.
4904 When used with the \fB[[\fP command,
4908 are evaluated as arithmetic expressions (see
4910 .B "ARITHMETIC EVALUATION"
4913 .SH "SIMPLE COMMAND EXPANSION"
4914 When a simple command is executed, the shell performs the following
4915 expansions, assignments, and redirections, from left to right, in
4916 the following order.
4918 The words that the parser has marked as variable assignments (those
4919 preceding the command name) and redirections are saved for later
4922 The words that are not variable assignments or redirections are
4923 expanded. If any words remain after expansion, the first word
4924 is taken to be the name of the command and the remaining words are
4927 Redirections are performed as described above under
4931 The text after the \fB=\fP in each variable assignment undergoes tilde
4932 expansion, parameter expansion, command substitution, arithmetic expansion,
4933 and quote removal before being assigned to the variable.
4935 If no command name results, the variable assignments affect the current
4937 In the case of such a command (one that consists only of assignment
4938 statements and redirections), assignment statements are performed before
4940 Otherwise, the variables are added to the environment
4941 of the executed command and do not affect the current shell environment.
4942 If any of the assignments attempts to assign a value to a readonly variable,
4943 an error occurs, and the command exits with a non-zero status.
4945 If no command name results, redirections are performed, but do not
4946 affect the current shell environment. A redirection error causes the
4947 command to exit with a non-zero status.
4949 If there is a command name left after expansion, execution proceeds as
4950 described below. Otherwise, the command exits. If one of the expansions
4951 contained a command substitution, the exit status of the command is
4952 the exit status of the last command substitution performed. If there
4953 were no command substitutions, the command exits with a status of zero.
4954 .SH "COMMAND EXECUTION"
4955 After a command has been split into words, if it results in a
4956 simple command and an optional list of arguments, the following
4959 If the command name contains no slashes, the shell attempts to
4960 locate it. If there exists a shell function by that name, that
4961 function is invoked as described above in
4964 If the name does not match a function, the shell searches for
4965 it in the list of shell builtins. If a match is found, that
4968 If the name is neither a shell function nor a builtin,
4969 and contains no slashes,
4971 searches each element of the
4974 for a directory containing an executable file by that name.
4976 uses a hash table to remember the full pathnames of executable
4981 .B "SHELL BUILTIN COMMANDS"
4983 A full search of the directories in
4986 is performed only if the command is not found in the hash table.
4987 If the search is unsuccessful, the shell searches for a defined shell
4988 function named \fBcommand_not_found_handle\fP.
4989 If that function exists, it is invoked in a separate execution environment
4990 with the original command and
4991 the original command's arguments as its arguments, and the function's
4992 exit status becomes the exit status of that subshell.
4993 If that function is not defined, the shell prints an error
4994 message and returns an exit status of 127.
4996 If the search is successful, or if the command name contains
4997 one or more slashes, the shell executes the named program in a
4998 separate execution environment.
4999 Argument 0 is set to the name given, and the remaining arguments
5000 to the command are set to the arguments given, if any.
5002 If this execution fails because the file is not in executable
5003 format, and the file is not a directory, it is assumed to be
5004 a \fIshell script\fP, a file
5005 containing shell commands, and the shell creates a
5006 new instance of itself
5008 This subshell reinitializes itself, so
5009 that the effect is as if a new shell had been invoked
5010 to handle the script, with the exception that the locations of
5011 commands remembered by the parent (see
5015 \fBSHELL BUILTIN COMMANDS\fP)
5016 are retained by the child.
5018 If the program is a file beginning with
5020 the remainder of the first line specifies an interpreter
5021 for the program. The shell executes the
5022 specified interpreter on operating systems that do not
5023 handle this executable format themselves. The arguments to the
5024 interpreter consist of a single optional argument following the
5025 interpreter name on the first line of the program, followed
5026 by the name of the program, followed by the command
5028 .SH COMMAND EXECUTION ENVIRONMENT
5029 The shell has an \fIexecution environment\fP, which consists of the
5032 open files inherited by the shell at invocation, as modified by
5033 redirections supplied to the \fBexec\fP builtin
5035 the current working directory as set by \fBcd\fP, \fBpushd\fP, or
5036 \fBpopd\fP, or inherited by the shell at invocation
5038 the file creation mode mask as set by \fBumask\fP or inherited from
5041 current traps set by \fBtrap\fP
5043 shell parameters that are set by variable assignment or with \fBset\fP
5044 or inherited from the shell's parent in the environment
5046 shell functions defined during execution or inherited from the shell's
5047 parent in the environment
5049 options enabled at invocation (either by default or with command-line
5050 arguments) or by \fBset\fP
5052 options enabled by \fBshopt\fP
5054 shell aliases defined with \fBalias\fP
5056 various process IDs, including those of background jobs, the value
5057 of \fB$$\fP, and the value of
5061 When a simple command other than a builtin or shell function
5062 is to be executed, it
5063 is invoked in a separate execution environment that consists of
5065 Unless otherwise noted, the values are inherited from the shell.
5068 the shell's open files, plus any modifications and additions specified
5069 by redirections to the command
5071 the current working directory
5073 the file creation mode mask
5075 shell variables and functions marked for export, along with variables
5076 exported for the command, passed in the environment
5078 traps caught by the shell are reset to the values inherited from the
5079 shell's parent, and traps ignored by the shell are ignored
5081 A command invoked in this separate environment cannot affect the
5082 shell's execution environment.
5084 A \fIsubshell\fP is a copy of the shell process.
5086 Command substitution, commands grouped with parentheses,
5087 and asynchronous commands are invoked in a
5088 subshell environment that is a duplicate of the shell environment,
5089 except that traps caught by the shell are reset to the values
5090 that the shell inherited from its parent at invocation. Builtin
5091 commands that are invoked as part of a pipeline are also executed in a
5092 subshell environment. Changes made to the subshell environment
5093 cannot affect the shell's execution environment.
5095 Subshells spawned to execute command substitutions inherit the value of
5096 the \fB\-e\fP option from the parent shell. When not in \fIposix mode\fP,
5097 \fBbash\fP clears the \fB\-e\fP option in such subshells.
5099 If a command is followed by a \fB&\fP and job control is not active, the
5100 default standard input for the command is the empty file \fI/dev/null\fP.
5101 Otherwise, the invoked command inherits the file descriptors of the calling
5102 shell as modified by redirections.
5104 When a program is invoked it is given an array of strings
5108 \fIname\fP\-\fIvalue\fP pairs, of the form
5109 .IR "name\fR=\fPvalue" .
5111 The shell provides several ways to manipulate the environment.
5112 On invocation, the shell scans its own environment and
5113 creates a parameter for each name found, automatically marking
5116 to child processes. Executed commands inherit the environment.
5121 commands allow parameters and functions to be added to and
5122 deleted from the environment. If the value of a parameter
5123 in the environment is modified, the new value becomes part
5124 of the environment, replacing the old. The environment
5125 inherited by any executed command consists of the shell's
5126 initial environment, whose values may be modified in the shell,
5127 less any pairs removed by the
5129 command, plus any additions via the
5135 The environment for any
5137 or function may be augmented temporarily by prefixing it with
5138 parameter assignments, as described above in
5141 These assignment statements affect only the environment seen
5146 option is set (see the
5148 builtin command below), then
5150 parameter assignments are placed in the environment for a command,
5151 not just those that precede the command name.
5155 invokes an external command, the variable
5157 is set to the full filename of the command and passed to that
5158 command in its environment.
5160 The exit status of an executed command is the value returned by the
5161 \fIwaitpid\fP system call or equivalent function. Exit statuses
5162 fall between 0 and 255, though, as explained below, the shell may
5163 use values above 125 specially. Exit statuses from shell builtins and
5164 compound commands are also limited to this range. Under certain
5165 circumstances, the shell will use special values to indicate specific
5168 For the shell's purposes, a command which exits with a
5169 zero exit status has succeeded. An exit status of zero
5170 indicates success. A non-zero exit status indicates failure.
5171 When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses
5172 the value of 128+\fIN\fP as the exit status.
5174 If a command is not found, the child process created to
5175 execute it returns a status of 127. If a command is found
5176 but is not executable, the return status is 126.
5178 If a command fails because of an error during expansion or redirection,
5179 the exit status is greater than zero.
5181 Shell builtin commands return a status of 0 (\fItrue\fP) if
5182 successful, and non-zero (\fIfalse\fP) if an error occurs
5184 All builtins return an exit status of 2 to indicate incorrect usage,
5185 generally invalid options or missing arguments.
5187 The exit status of the last command is available in the special
5190 \fBBash\fP itself returns the exit status of the last command
5191 executed, unless a syntax error occurs, in which case it exits
5192 with a non-zero value. See also the \fBexit\fP builtin
5195 When \fBbash\fP is interactive, in the absence of any traps, it ignores
5198 (so that \fBkill 0\fP does not kill an interactive shell),
5202 is caught and handled (so that the \fBwait\fP builtin is interruptible).
5203 In all cases, \fBbash\fP ignores
5206 If job control is in effect,
5217 Non-builtin commands run by \fBbash\fP have signal handlers
5218 set to the values inherited by the shell from its parent.
5219 When job control is not in effect, asynchronous commands
5226 in addition to these inherited handlers.
5227 Commands run as a result of command substitution ignore the
5228 keyboard-generated job control signals
5237 The shell exits by default upon receipt of a
5240 Before exiting, an interactive shell resends the
5243 to all jobs, running or stopped.
5244 Stopped jobs are sent
5247 to ensure that they receive the
5250 To prevent the shell from
5251 sending the signal to a particular job, it should be removed from the
5256 .B "SHELL BUILTIN COMMANDS"
5266 shell option has been set with
5272 to all jobs when an interactive login shell exits.
5274 If \fBbash\fP is waiting for a command to complete and receives a signal
5275 for which a trap has been set, the trap will not be executed until
5276 the command completes.
5277 When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP
5278 builtin, the reception of a signal for which a trap has been set will
5279 cause the \fBwait\fP builtin to return immediately with an exit status
5280 greater than 128, immediately after which the trap is executed.
5282 When job control is not enabled, and \fBbash\fP is waiting for a foreground
5283 command to complete, the shell receives keyboard-generated signals
5287 (usually generated by \fB^C\fP) that users commonly intend to send
5289 This happens because the shell and the command are in the
5290 same process group as the terminal, and \fB^C\fP sends
5293 to all processes in that process group.
5295 When \fBbash\fP is running without job control enabled and receives
5298 while waiting for a foreground command, it waits until that foreground
5299 command terminates and then decides what to do about the
5303 If the command terminates due to the
5306 \fBbash\fP concludes
5307 that the user meant to end the entire script, and acts on the
5313 trap or exiting itself);
5315 If the command does not terminate due to
5318 the program handled the
5321 itself and did not treat it as a fatal signal.
5322 In that case, \fBbash\fP does not treat
5325 as a fatal signal, either, instead assuming that the
5328 was used as part of the program's normal operation
5329 (e.g., emacs uses it to abort editing
5330 commands) or deliberately discarded.
5331 However, \fBbash\fP will run any
5335 as it does with any other trapped signal it
5336 receives while it is waiting for the foreground command to
5337 complete, for compatibility.
5340 refers to the ability to selectively stop (\fIsuspend\fP)
5341 the execution of processes and continue (\fIresume\fP)
5342 their execution at a later point. A user typically employs
5343 this facility via an interactive interface supplied jointly
5344 by the operating system kernel's terminal driver and
5347 The shell associates a
5349 with each pipeline. It keeps a table of currently executing
5350 jobs, which may be listed with the
5354 starts a job asynchronously (in the
5356 it prints a line that looks like:
5362 indicating that this job is job number 1 and that the process ID
5363 of the last process in the pipeline associated with this job is 25647.
5364 All of the processes in a single pipeline are members of the same job.
5368 abstraction as the basis for job control.
5370 To facilitate the implementation of the user interface to job
5371 control, the operating system maintains the notion of a \fIcurrent terminal
5372 process group ID\fP. Members of this process group (processes whose
5373 process group ID is equal to the current terminal process group ID)
5374 receive keyboard-generated signals such as
5377 These processes are said to be in the
5380 processes are those whose process group ID differs from the terminal's;
5381 such processes are immune to keyboard-generated signals.
5382 Only foreground processes are allowed to read from or, if the
5383 user so specifies with \f(CWstty tostop\fP, write to the
5385 Background processes which attempt to read from (write to when
5386 \f(CWstty tostop\fP is in effect) the
5389 .B SIGTTIN (SIGTTOU)
5390 signal by the kernel's terminal driver,
5391 which, unless caught, suspends the process.
5393 If the operating system on which
5398 contains facilities to use it.
5401 character (typically
5403 Control-Z) while a process is running
5404 causes that process to be stopped and returns control to
5407 .I "delayed suspend"
5408 character (typically
5410 Control-Y) causes the process to be stopped when it
5411 attempts to read input from the terminal, and control to
5414 The user may then manipulate the state of this job, using the
5416 command to continue it in the background, the
5418 command to continue it in the foreground, or
5421 command to kill it. A \fB^Z\fP takes effect immediately,
5422 and has the additional side effect of causing pending output
5423 and typeahead to be discarded.
5425 There are a number of ways to refer to a job in the shell.
5428 introduces a job specification (\fIjobspec\fP). Job number
5430 may be referred to as
5432 A job may also be referred to using a prefix of the name used to
5433 start it, or using a substring that appears in its command line.
5437 job whose command name begins with
5439 If a prefix matches more than one job,
5441 reports an error. Using
5443 on the other hand, refers to any job containing the string
5445 in its command line. If the substring matches more than one job,
5447 reports an error. The symbols
5451 refer to the shell's notion of the
5453 which is the last job stopped while it was in
5454 the foreground or started in the background.
5457 may be referenced using
5459 If there is only a single job, \fB%+\fP and \fB%\-\fP can both be used
5460 to refer to that job.
5461 In output pertaining to jobs (e.g., the output of the
5463 command), the current job is always flagged with a
5465 and the previous job with a
5467 A single % (with no accompanying job specification) also refers to the
5470 Simply naming a job can be used to bring it into the
5475 bringing job 1 from the background into the foreground.
5478 resumes job 1 in the background, equivalent to
5481 The shell learns immediately whenever a job changes state.
5484 waits until it is about to print a prompt before reporting
5485 changes in a job's status so as to not interrupt
5486 any other output. If the
5493 reports such changes immediately.
5497 is executed for each child that exits.
5499 If an attempt to exit
5501 is made while jobs are stopped (or, if the \fBcheckjobs\fP shell option has
5502 been enabled using the \fBshopt\fP builtin, running), the shell prints a
5503 warning message, and, if the \fBcheckjobs\fP option is enabled, lists the
5504 jobs and their statuses.
5507 command may then be used to inspect their status.
5508 If a second attempt to exit is made without an intervening command,
5509 the shell does not print another warning, and any stopped
5510 jobs are terminated.
5512 When the shell is waiting for a job or process using the \fBwait\fP
5513 builtin, and job control is enabled, \fBwait\fP will return when the
5514 job changes state. The \fB\-f\fP option causes \fBwait\fP to wait
5515 until the job or process terminates before returning.
5517 When executing interactively,
5519 displays the primary prompt
5522 when it is ready to read a command, and the secondary prompt
5525 when it needs more input to complete a command.
5530 after it reads a command but before executing it.
5536 before tracing each command when the \fB\-x\fP option is enabled.
5538 allows these prompt strings to be customized by inserting a number of
5539 backslash-escaped special characters that are decoded as follows:
5544 an ASCII bell character (07)
5547 the date in "Weekday Month Date" format (e.g., "Tue May 26")
5549 .B \eD{\fIformat\fP}
5550 the \fIformat\fP is passed to \fIstrftime\fP(3) and the result is inserted
5551 into the prompt string; an empty \fIformat\fP results in a locale-specific
5552 time representation. The braces are required
5555 an ASCII escape character (033)
5558 the hostname up to the first `.'
5564 the number of jobs currently managed by the shell
5567 the basename of the shell's terminal device name
5576 the name of the shell, the basename of
5578 (the portion following the final slash)
5581 the current time in 24-hour HH:MM:SS format
5584 the current time in 12-hour HH:MM:SS format
5587 the current time in 12-hour am/pm format
5590 the current time in 24-hour HH:MM format
5593 the username of the current user
5596 the version of \fBbash\fP (e.g., 2.00)
5599 the release of \fBbash\fP, version + patch level (e.g., 2.00.0)
5602 the value of the \fBPWD\fP shell variable (\fB$PWD\fP),
5606 abbreviated with a tilde
5607 (uses the value of the
5613 the basename of \fB$PWD\fP,
5617 abbreviated with a tilde
5620 the history number of this command
5623 the command number of this command
5626 if the effective UID is 0, a
5632 the character corresponding to the octal number \fInnn\fP
5638 begin a sequence of non-printing characters, which could be used to
5639 embed a terminal control sequence into the prompt
5642 end a sequence of non-printing characters
5646 The command number and the history number are usually different:
5647 the history number of a command is its position in the history
5648 list, which may include commands restored from the history file
5652 below), while the command number is the position in the sequence
5653 of commands executed during the current shell session.
5654 After the string is decoded, it is expanded via
5655 parameter expansion, command substitution, arithmetic
5656 expansion, and quote removal, subject to the value of the
5658 shell option (see the description of the
5662 .B "SHELL BUILTIN COMMANDS"
5664 This can have unwanted side effects if escaped portions of the string
5665 appear within command substitution or contain characters special to
5668 This is the library that handles reading input when using an interactive
5671 option is given at shell invocation.
5672 Line editing is also used when using the \fB\-e\fP option to the
5674 By default, the line editing commands are similar to those of Emacs.
5675 A vi-style line editing interface is also available.
5676 Line editing can be enabled at any time using the
5684 .B SHELL BUILTIN COMMANDS
5686 To turn off line editing after the shell is running, use the
5693 .SS "Readline Notation"
5694 In this section, the Emacs-style notation is used to denote
5695 keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
5696 means Control\-N. Similarly,
5698 keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards
5701 key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
5704 key. This makes ESC the \fImeta prefix\fP.
5705 The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
5706 or press the Escape key
5707 then hold the Control key while pressing the
5711 Readline commands may be given numeric
5713 which normally act as a repeat count.
5714 Sometimes, however, it is the sign of the argument that is significant.
5715 Passing a negative argument to a command that acts in the forward
5716 direction (e.g., \fBkill\-line\fP) causes that command to act in a
5718 Commands whose behavior with arguments deviates from this are noted
5721 When a command is described as \fIkilling\fP text, the text
5722 deleted is saved for possible future retrieval
5723 (\fIyanking\fP). The killed text is saved in a
5724 \fIkill ring\fP. Consecutive kills cause the text to be
5725 accumulated into one unit, which can be yanked all at once.
5726 Commands which do not kill text separate the chunks of text
5728 .SS "Readline Initialization"
5729 Readline is customized by putting commands in an initialization
5730 file (the \fIinputrc\fP file).
5731 The name of this file is taken from the value of the
5734 variable. If that variable is unset, the default is
5736 If that file does not exist or cannot be read, the ultimate default is
5738 When a program which uses the readline library starts up, the
5739 initialization file is read, and the key bindings and variables
5741 There are only a few basic constructs allowed in the
5742 readline initialization file.
5743 Blank lines are ignored.
5744 Lines beginning with a \fB#\fP are comments.
5745 Lines beginning with a \fB$\fP indicate conditional constructs.
5746 Other lines denote key bindings and variable settings.
5748 The default key-bindings may be changed with an
5751 Other programs that use this library may add their own commands
5754 For example, placing
5757 M\-Control\-u: universal\-argument
5761 C\-Meta\-u: universal\-argument
5765 would make M\-C\-u execute the readline command
5766 .IR universal\-argument .
5768 The following symbolic character names are recognized:
5781 In addition to command names, readline allows keys to be bound
5782 to a string that is inserted when the key is pressed (a \fImacro\fP).
5783 .SS "Readline Key Bindings"
5784 The syntax for controlling key bindings in the
5786 file is simple. All that is required is the name of the
5787 command or the text of a macro and a key sequence to which
5788 it should be bound. The name may be specified in one of two ways:
5789 as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
5790 prefixes, or as a key sequence.
5792 When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP,
5794 is the name of a key spelled out in English. For example:
5797 Control-u: universal\-argument
5799 Meta-Rubout: backward-kill-word
5801 Control-o: "> output"
5804 In the above example,
5806 is bound to the function
5807 .BR universal\-argument ,
5809 is bound to the function
5810 .BR backward\-kill\-word ,
5813 is bound to run the macro
5814 expressed on the right hand side (that is, to insert the text
5815 .if t \f(CW> output\fP
5819 In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
5823 above in that strings denoting
5824 an entire key sequence may be specified by placing the sequence
5825 within double quotes. Some GNU Emacs style key escapes can be
5826 used, as in the following example, but the symbolic character names
5830 "\eC\-u": universal\-argument
5832 "\eC\-x\eC\-r": re\-read\-init\-file
5834 "\ee[11~": "Function Key 1"
5839 is again bound to the function
5840 .BR universal\-argument .
5842 is bound to the function
5843 .BR re\-read\-init\-file ,
5846 is bound to insert the text
5847 .if t \f(CWFunction Key 1\fP.
5848 .if n ``Function Key 1''.
5850 The full set of GNU Emacs style escape sequences is
5874 In addition to the GNU Emacs style escape sequences, a second
5875 set of backslash escapes is available:
5904 the eight-bit character whose value is the octal value \fInnn\fP
5905 (one to three digits)
5908 the eight-bit character whose value is the hexadecimal value \fIHH\fP
5909 (one or two hex digits)
5913 When entering the text of a macro, single or double quotes must
5914 be used to indicate a macro definition.
5915 Unquoted text is assumed to be a function name.
5916 In the macro body, the backslash escapes described above are expanded.
5917 Backslash will quote any other character in the macro text,
5918 including " and \(aq.
5921 allows the current readline key bindings to be displayed or modified
5924 builtin command. The editing mode may be switched during interactive
5929 builtin command (see
5931 .B SHELL BUILTIN COMMANDS
5933 .SS "Readline Variables"
5934 Readline has variables that can be used to further customize its
5935 behavior. A variable may be set in the
5937 file with a statement of the form
5940 \fBset\fP \fIvariable\-name\fP \fIvalue\fP
5942 or using the \fBbind\fP builtin command (see
5944 .B SHELL BUILTIN COMMANDS
5947 Except where noted, readline variables can take the values
5951 (without regard to case).
5952 Unrecognized variable names are ignored.
5953 When a variable value is read, empty or null values, "on" (case-insensitive),
5954 and "1" are equivalent to \fBOn\fP. All other values are equivalent to
5956 The variables and their default values are:
5960 .B active\-region\-start\-color
5961 A string variable that controls the text color and background when displaying
5962 the text in the active region (see the description of
5963 \fBenable\-active\-region\fP below).
5964 This string must not take up any physical character positions on the display,
5965 so it should consist only of terminal escape sequences.
5966 It is output to the terminal before displaying the text in the active region.
5967 This variable is reset to the default value whenever the terminal type changes.
5968 The default value is the string that puts the terminal in standout mode,
5969 as obtained from the terminal's terminfo description.
5970 A sample value might be \f(CW"\ee[01;33m"\fP.
5972 .B active\-region\-end\-color
5973 A string variable that "undoes" the effects of \fBactive\-region\-start\-color\fP
5974 and restores "normal" terminal display appearance after displaying text
5975 in the active region.
5976 This string must not take up any physical character positions on the display,
5977 so it should consist only of terminal escape sequences.
5978 It is output to the terminal after displaying the text in the active region.
5979 This variable is reset to the default value whenever the terminal type changes.
5980 The default value is the string that restores the terminal from standout mode,
5981 as obtained from the terminal's terminfo description.
5982 A sample value might be \f(CW"\ee[0m"\fP.
5984 .B bell\-style (audible)
5985 Controls what happens when readline wants to ring the terminal bell.
5986 If set to \fBnone\fP, readline never rings the bell. If set to
5987 \fBvisible\fP, readline uses a visible bell if one is available.
5988 If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
5990 .B bind\-tty\-special\-chars (On)
5991 If set to \fBOn\fP, readline attempts to bind the control characters
5992 treated specially by the kernel's terminal driver to their readline
5995 .B blink\-matching\-paren (Off)
5996 If set to \fBOn\fP, readline attempts to briefly move the cursor to an
5997 opening parenthesis when a closing parenthesis is inserted.
5999 .B colored\-completion\-prefix (Off)
6000 If set to \fBOn\fP, when listing completions, readline displays the
6001 common prefix of the set of possible completions using a different color.
6002 The color definitions are taken from the value of the \fBLS_COLORS\fP
6003 environment variable.
6004 If there is a color definition in \fB$LS_COLORS\fP for the custom suffix
6005 "readline-colored-completion-prefix", readline uses this color for
6006 the common prefix instead of its default.
6008 .B colored\-stats (Off)
6009 If set to \fBOn\fP, readline displays possible completions using different
6010 colors to indicate their file type.
6011 The color definitions are taken from the value of the \fBLS_COLORS\fP
6012 environment variable.
6014 .B comment\-begin (``#'')
6015 The string that is inserted when the readline
6017 command is executed.
6018 This command is bound to
6020 in emacs mode and to
6024 .B completion\-display\-width (\-1)
6025 The number of screen columns used to display possible matches
6026 when performing completion.
6027 The value is ignored if it is less than 0 or greater than the terminal
6029 A value of 0 will cause matches to be displayed one per line.
6030 The default value is \-1.
6032 .B completion\-ignore\-case (Off)
6033 If set to \fBOn\fP, readline performs filename matching and completion
6034 in a case\-insensitive fashion.
6036 .B completion\-map\-case (Off)
6037 If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline
6038 treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when
6039 performing case\-insensitive filename matching and completion.
6041 .B completion\-prefix\-display\-length (0)
6042 The length in characters of the common prefix of a list of possible
6043 completions that is displayed without modification. When set to a
6044 value greater than zero, common prefixes longer than this value are
6045 replaced with an ellipsis when displaying possible completions.
6047 .B completion\-query\-items (100)
6048 This determines when the user is queried about viewing
6049 the number of possible completions
6050 generated by the \fBpossible\-completions\fP command.
6051 It may be set to any integer value greater than or equal to zero.
6052 If the number of possible completions is greater than
6053 or equal to the value of this variable,
6054 readline will ask whether or not the user wishes to view them;
6055 otherwise they are simply listed on the terminal.
6056 A zero value means readline should never ask; negative values are
6059 .B convert\-meta (On)
6060 If set to \fBOn\fP, readline will convert characters with the
6061 eighth bit set to an ASCII key sequence
6062 by stripping the eighth bit and prefixing an
6063 escape character (in effect, using escape as the \fImeta prefix\fP).
6064 The default is \fIOn\fP, but readline will set it to \fIOff\fP if the
6065 locale contains eight-bit characters.
6066 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
6067 may change if the locale is changed.
6069 .B disable\-completion (Off)
6070 If set to \fBOn\fP, readline will inhibit word completion. Completion
6071 characters will be inserted into the line as if they had been
6072 mapped to \fBself-insert\fP.
6074 .B echo\-control\-characters (On)
6075 When set to \fBOn\fP, on operating systems that indicate they support it,
6076 readline echoes a character corresponding to a signal generated from the
6079 .B editing\-mode (emacs)
6080 Controls whether readline begins with a set of key bindings similar
6081 to \fIEmacs\fP or \fIvi\fP.
6083 can be set to either
6088 .B emacs\-mode\-string (@)
6089 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
6090 this string is displayed immediately before the last line of the primary
6091 prompt when emacs editing mode is active. The value is expanded like a
6092 key binding, so the standard set of meta- and control prefixes and
6093 backslash escape sequences is available.
6094 Use the \e1 and \e2 escapes to begin and end sequences of
6095 non-printing characters, which can be used to embed a terminal control
6096 sequence into the mode string.
6098 .B enable\-active\-region (On)
6099 The \fIpoint\fP is the current cursor position, and \fImark\fP refers
6100 to a saved cursor position.
6101 The text between the point and mark is referred to as the \fIregion\fP.
6102 When this variable is set to \fIOn\fP, readline allows certain commands
6103 to designate the region as \fIactive\fP.
6104 When the region is active, readline highlights the text in the region using
6105 the value of the \fBactive\-region\-start\-color\fP, which defaults to the
6107 the terminal's standout mode.
6108 The active region shows the text inserted by bracketed-paste and any
6109 matching text found by incremental and non-incremental history searches.
6111 .B enable\-bracketed\-paste (On)
6112 When set to \fBOn\fP, readline configures the terminal to insert each
6113 paste into the editing buffer as a single string of characters, instead
6114 of treating each character as if it had been read from the keyboard.
6115 This prevents readline from executing any editing commands bound to key
6116 sequences appearing in the pasted text.
6118 .B enable\-keypad (Off)
6119 When set to \fBOn\fP, readline will try to enable the application
6120 keypad when it is called. Some systems need this to enable the
6123 .B enable\-meta\-key (On)
6124 When set to \fBOn\fP, readline will try to enable any meta modifier
6125 key the terminal claims to support when it is called. On many terminals,
6126 the meta key is used to send eight-bit characters.
6128 .B expand\-tilde (Off)
6129 If set to \fBOn\fP, tilde expansion is performed when readline
6130 attempts word completion.
6132 .B history\-preserve\-point (Off)
6133 If set to \fBOn\fP, the history code attempts to place point at the
6134 same location on each history line retrieved with \fBprevious-history\fP
6135 or \fBnext-history\fP.
6137 .B history\-size (unset)
6138 Set the maximum number of history entries saved in the history list.
6139 If set to zero, any existing history entries are deleted and no new entries
6141 If set to a value less than zero, the number of history entries is not
6143 By default, the number of history entries is set to the value of the
6144 \fBHISTSIZE\fP shell variable.
6145 If an attempt is made to set \fIhistory\-size\fP to a non-numeric value,
6146 the maximum number of history entries will be set to 500.
6148 .B horizontal\-scroll\-mode (Off)
6149 When set to \fBOn\fP, makes readline use a single line for display,
6150 scrolling the input horizontally on a single screen line when it
6151 becomes longer than the screen width rather than wrapping to a new line.
6152 This setting is automatically enabled for terminals of height 1.
6154 .B input\-meta (Off)
6155 If set to \fBOn\fP, readline will enable eight-bit input (that is,
6156 it will not strip the eighth bit from the characters it reads),
6157 regardless of what the terminal claims it can support. The name
6159 is a synonym for this variable.
6160 The default is \fIOff\fP, but readline will set it to \fIOn\fP if the
6161 locale contains eight-bit characters.
6162 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
6163 may change if the locale is changed.
6165 .B isearch\-terminators (``C\-[C\-J'')
6166 The string of characters that should terminate an incremental
6167 search without subsequently executing the character as a command.
6168 If this variable has not been given a value, the characters
6169 \fIESC\fP and \fIC\-J\fP will terminate an incremental search.
6172 Set the current readline keymap. The set of valid keymap names is
6173 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
6176 \fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is
6177 equivalent to \fIemacs\-standard\fP. The default value is
6181 also affects the default keymap.
6183 .B keyseq\-timeout (500)
6184 Specifies the duration \fIreadline\fP will wait for a character when reading an
6185 ambiguous key sequence (one that can form a complete key sequence using
6186 the input read so far, or can take additional input to complete a longer
6188 If no input is received within the timeout, \fIreadline\fP will use the shorter
6189 but complete key sequence.
6190 The value is specified in milliseconds, so a value of 1000 means that
6191 \fIreadline\fP will wait one second for additional input.
6192 If this variable is set to a value less than or equal to zero, or to a
6193 non-numeric value, \fIreadline\fP will wait until another key is pressed to
6194 decide which key sequence to complete.
6196 .B mark\-directories (On)
6197 If set to \fBOn\fP, completed directory names have a slash
6200 .B mark\-modified\-lines (Off)
6201 If set to \fBOn\fP, history lines that have been modified are displayed
6202 with a preceding asterisk (\fB*\fP).
6204 .B mark\-symlinked\-directories (Off)
6205 If set to \fBOn\fP, completed names which are symbolic links to directories
6206 have a slash appended (subject to the value of
6207 \fBmark\-directories\fP).
6209 .B match\-hidden\-files (On)
6210 This variable, when set to \fBOn\fP, causes readline to match files whose
6211 names begin with a `.' (hidden files) when performing filename
6213 If set to \fBOff\fP, the leading `.' must be
6214 supplied by the user in the filename to be completed.
6216 .B menu\-complete\-display\-prefix (Off)
6217 If set to \fBOn\fP, menu completion displays the common prefix of the
6218 list of possible completions (which may be empty) before cycling through
6221 .B output\-meta (Off)
6222 If set to \fBOn\fP, readline will display characters with the
6223 eighth bit set directly rather than as a meta-prefixed escape
6225 The default is \fIOff\fP, but readline will set it to \fIOn\fP if the
6226 locale contains eight-bit characters.
6227 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
6228 may change if the locale is changed.
6230 .B page\-completions (On)
6231 If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager
6232 to display a screenful of possible completions at a time.
6234 .B print\-completions\-horizontally (Off)
6235 If set to \fBOn\fP, readline will display completions with matches
6236 sorted horizontally in alphabetical order, rather than down the screen.
6238 .B revert\-all\-at\-newline (Off)
6239 If set to \fBOn\fP, readline will undo all changes to history lines
6240 before returning when \fBaccept\-line\fP is executed. By default,
6241 history lines may be modified and retain individual undo lists across
6242 calls to \fBreadline\fP.
6244 .B show\-all\-if\-ambiguous (Off)
6245 This alters the default behavior of the completion functions. If
6248 words which have more than one possible completion cause the
6249 matches to be listed immediately instead of ringing the bell.
6251 .B show\-all\-if\-unmodified (Off)
6252 This alters the default behavior of the completion functions in
6253 a fashion similar to \fBshow\-all\-if\-ambiguous\fP.
6256 words which have more than one possible completion without any
6257 possible partial completion (the possible completions don't share
6258 a common prefix) cause the matches to be listed immediately instead
6259 of ringing the bell.
6261 .B show\-mode\-in\-prompt (Off)
6262 If set to \fBOn\fP, add a string to the beginning of the prompt
6263 indicating the editing mode: emacs, vi command, or vi insertion.
6264 The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP).
6266 .B skip\-completed\-text (Off)
6267 If set to \fBOn\fP, this alters the default completion behavior when
6268 inserting a single match into the line. It's only active when
6269 performing completion in the middle of a word. If enabled, readline
6270 does not insert characters from the completion that match characters
6271 after point in the word being completed, so portions of the word
6272 following the cursor are not duplicated.
6274 .B vi\-cmd\-mode\-string ((cmd))
6275 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
6276 this string is displayed immediately before the last line of the primary
6277 prompt when vi editing mode is active and in command mode.
6278 The value is expanded like a
6279 key binding, so the standard set of meta- and control prefixes and
6280 backslash escape sequences is available.
6281 Use the \e1 and \e2 escapes to begin and end sequences of
6282 non-printing characters, which can be used to embed a terminal control
6283 sequence into the mode string.
6285 .B vi\-ins\-mode\-string ((ins))
6286 If the \fIshow\-mode\-in\-prompt\fP variable is enabled,
6287 this string is displayed immediately before the last line of the primary
6288 prompt when vi editing mode is active and in insertion mode.
6289 The value is expanded like a
6290 key binding, so the standard set of meta- and control prefixes and
6291 backslash escape sequences is available.
6292 Use the \e1 and \e2 escapes to begin and end sequences of
6293 non-printing characters, which can be used to embed a terminal control
6294 sequence into the mode string.
6296 .B visible\-stats (Off)
6297 If set to \fBOn\fP, a character denoting a file's type as reported
6298 by \fIstat\fP(2) is appended to the filename when listing possible
6301 .SS "Readline Conditional Constructs"
6302 Readline implements a facility similar in spirit to the conditional
6303 compilation features of the C preprocessor which allows key
6304 bindings and variable settings to be performed as the result
6305 of tests. There are four parser directives used.
6309 construct allows bindings to be made based on the
6310 editing mode, the terminal being used, or the application using
6311 readline. The text of the test, after any comparison operator,
6312 extends to the end of the line;
6313 unless otherwise noted, no characters are required to isolate it.
6316 The \fBmode=\fP form of the \fB$if\fP directive is used to test
6317 whether readline is in emacs or vi mode.
6318 This may be used in conjunction
6319 with the \fBset keymap\fP command, for instance, to set bindings in
6320 the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if
6321 readline is starting out in emacs mode.
6323 The \fBterm=\fP form may be used to include terminal-specific
6324 key bindings, perhaps to bind the key sequences output by the
6325 terminal's function keys. The word on the right side of the
6327 is tested against both the full name of the terminal and the portion
6328 of the terminal name before the first \fB\-\fP. This allows
6336 The \fBversion\fP test may be used to perform comparisons against
6337 specific readline versions.
6338 The \fBversion\fP expands to the current readline version.
6339 The set of comparison operators includes
6349 The version number supplied on the right side of the operator consists
6350 of a major version number, an optional decimal point, and an optional
6351 minor version (e.g., \fB7.1\fP). If the minor version is omitted, it
6352 is assumed to be \fB0\fP.
6353 The operator may be separated from the string \fBversion\fP
6354 and from the version number argument by whitespace.
6355 .IP \fBapplication\fP
6356 The \fBapplication\fP construct is used to include
6357 application-specific settings. Each program using the readline
6358 library sets the \fIapplication name\fP, and an initialization
6359 file can test for a particular value.
6360 This could be used to bind key sequences to functions useful for
6361 a specific program. For instance, the following command adds a
6362 key sequence that quotes the current or previous word in \fBbash\fP:
6367 # Quote the current or previous word
6368 "\eC\-xq": "\eeb\e"\eef\e""
6373 The \fIvariable\fP construct provides simple equality tests for readline
6374 variables and values.
6375 The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP.
6376 The variable name must be separated from the comparison operator by
6377 whitespace; the operator may be separated from the value on the right hand
6379 Both string and boolean variables may be tested. Boolean variables must be
6380 tested against the values \fIon\fP and \fIoff\fP.
6383 This command, as seen in the previous example, terminates an
6386 Commands in this branch of the \fB$if\fP directive are executed if
6389 This directive takes a single filename as an argument and reads commands
6390 and bindings from that file. For example, the following directive
6391 would read \fI/etc/inputrc\fP:
6395 \fB$include\fP \^ \fI/etc/inputrc\fP
6399 Readline provides commands for searching through the command history
6403 below) for lines containing a specified string.
6404 There are two search modes:
6407 .IR non-incremental .
6409 Incremental searches begin before the user has finished typing the
6411 As each character of the search string is typed, readline displays
6412 the next entry from the history matching the string typed so far.
6413 An incremental search requires only as many characters as needed to
6414 find the desired history entry.
6415 The characters present in the value of the \fBisearch-terminators\fP
6416 variable are used to terminate an incremental search.
6417 If that variable has not been assigned a value the Escape and
6418 Control-J characters will terminate an incremental search.
6419 Control-G will abort an incremental search and restore the original
6421 When the search is terminated, the history entry containing the
6422 search string becomes the current line.
6424 To find other matching entries in the history list, type Control-S or
6425 Control-R as appropriate.
6426 This will search backward or forward in the history for the next
6427 entry matching the search string typed so far.
6428 Any other key sequence bound to a readline command will terminate
6429 the search and execute that command.
6430 For instance, a \fInewline\fP will terminate the search and accept
6431 the line, thereby executing the command from the history list.
6433 Readline remembers the last incremental search string. If two
6434 Control-Rs are typed without any intervening characters defining a
6435 new search string, any remembered search string is used.
6437 Non-incremental searches read the entire search string before starting
6438 to search for matching history lines. The search string may be
6439 typed by the user or be part of the contents of the current line.
6440 .SS "Readline Command Names"
6441 The following is a list of the names of the commands and the default
6442 key sequences to which they are bound.
6443 Command names without an accompanying key sequence are unbound by default.
6444 In the following descriptions, \fIpoint\fP refers to the current cursor
6445 position, and \fImark\fP refers to a cursor position saved by the
6446 \fBset\-mark\fP command.
6447 The text between the point and mark is referred to as the \fIregion\fP.
6448 .SS Commands for Moving
6451 .B beginning\-of\-line (C\-a)
6452 Move to the start of the current line.
6454 .B end\-of\-line (C\-e)
6455 Move to the end of the line.
6457 .B forward\-char (C\-f)
6458 Move forward a character.
6460 .B backward\-char (C\-b)
6461 Move back a character.
6463 .B forward\-word (M\-f)
6464 Move forward to the end of the next word. Words are composed of
6465 alphanumeric characters (letters and digits).
6467 .B backward\-word (M\-b)
6468 Move back to the start of the current or previous word.
6469 Words are composed of alphanumeric characters (letters and digits).
6471 .B shell\-forward\-word
6472 Move forward to the end of the next word.
6473 Words are delimited by non-quoted shell metacharacters.
6475 .B shell\-backward\-word
6476 Move back to the start of the current or previous word.
6477 Words are delimited by non-quoted shell metacharacters.
6479 .B previous\-screen\-line
6480 Attempt to move point to the same physical screen column on the previous
6481 physical screen line. This will not have the desired effect if the current
6482 readline line does not take up more than one physical line or if point is not
6483 greater than the length of the prompt plus the screen width.
6485 .B next\-screen\-line
6486 Attempt to move point to the same physical screen column on the next
6487 physical screen line. This will not have the desired effect if the current
6488 readline line does not take up more than one physical line or if the length
6489 of the current readline line is not greater than the length of the prompt
6490 plus the screen width.
6492 .B clear\-display (M\-C\-l)
6493 Clear the screen and, if possible, the terminal's scrollback buffer,
6494 then redraw the current line,
6495 leaving the current line at the top of the screen.
6497 .B clear\-screen (C\-l)
6499 then redraw the current line,
6500 leaving the current line at the top of the screen.
6501 With an argument, refresh the current line without clearing the
6504 .B redraw\-current\-line
6505 Refresh the current line.
6507 .SS Commands for Manipulating the History
6510 .B accept\-line (Newline, Return)
6511 Accept the line regardless of where the cursor is. If this line is
6512 non-empty, add it to the history list according to the state of the
6515 variable. If the line is a modified history
6516 line, then restore the history line to its original state.
6518 .B previous\-history (C\-p)
6519 Fetch the previous command from the history list, moving back in
6522 .B next\-history (C\-n)
6523 Fetch the next command from the history list, moving forward in the
6526 .B beginning\-of\-history (M\-<)
6527 Move to the first line in the history.
6529 .B end\-of\-history (M\->)
6530 Move to the end of the input history, i.e., the line currently being
6533 .B operate\-and\-get\-next (C\-o)
6534 Accept the current line for execution and fetch the next line
6535 relative to the current line from the history for editing.
6536 A numeric argument, if supplied, specifies the history entry to use instead
6537 of the current line.
6541 With a numeric argument, fetch that entry from the history list
6542 and make it the current line.
6543 Without an argument, move back to the first entry in the history list.
6545 .B reverse\-search\-history (C\-r)
6546 Search backward starting at the current line and moving `up' through
6547 the history as necessary. This is an incremental search.
6549 .B forward\-search\-history (C\-s)
6550 Search forward starting at the current line and moving `down' through
6551 the history as necessary. This is an incremental search.
6553 .B non\-incremental\-reverse\-search\-history (M\-p)
6554 Search backward through the history starting at the current line
6555 using a non-incremental search for a string supplied by the user.
6557 .B non\-incremental\-forward\-search\-history (M\-n)
6558 Search forward through the history using a non-incremental search for
6559 a string supplied by the user.
6561 .B history\-search\-forward
6562 Search forward through the history for the string of characters
6563 between the start of the current line and the point.
6564 This is a non-incremental search.
6566 .B history\-search\-backward
6567 Search backward through the history for the string of characters
6568 between the start of the current line and the point.
6569 This is a non-incremental search.
6571 .B history\-substring\-search\-backward
6572 Search backward through the history for the string of characters
6573 between the start of the current line and the current cursor
6574 position (the \fIpoint\fP).
6575 The search string may match anywhere in a history line.
6576 This is a non-incremental search.
6578 .B history\-substring\-search\-forward
6579 Search forward through the history for the string of characters
6580 between the start of the current line and the point.
6581 The search string may match anywhere in a history line.
6582 This is a non-incremental search.
6584 .B yank\-nth\-arg (M\-C\-y)
6585 Insert the first argument to the previous command (usually
6586 the second word on the previous line) at point.
6589 insert the \fIn\fPth word from the previous command (the words
6590 in the previous command begin with word 0). A negative argument
6591 inserts the \fIn\fPth word from the end of the previous command.
6592 Once the argument \fIn\fP is computed, the argument is extracted
6593 as if the "!\fIn\fP" history expansion had been specified.
6596 yank\-last\-arg (M\-.\^, M\-_\^)
6597 Insert the last argument to the previous command (the last word of
6598 the previous history entry).
6599 With a numeric argument, behave exactly like \fByank\-nth\-arg\fP.
6600 Successive calls to \fByank\-last\-arg\fP move back through the history
6601 list, inserting the last word (or the word specified by the argument to
6602 the first call) of each line in turn.
6603 Any numeric argument supplied to these successive calls determines
6604 the direction to move through the history. A negative argument switches
6605 the direction through the history (back or forward).
6606 The history expansion facilities are used to extract the last word,
6607 as if the "!$" history expansion had been specified.
6609 .B shell\-expand\-line (M\-C\-e)
6610 Expand the line as the shell does. This
6611 performs alias and history expansion as well as all of the shell
6612 word expansions. See
6614 .B HISTORY EXPANSION
6615 below for a description of history expansion.
6617 .B history\-expand\-line (M\-^)
6618 Perform history expansion on the current line.
6621 .B HISTORY EXPANSION
6622 below for a description of history expansion.
6625 Perform history expansion on the current line and insert a space.
6628 .B HISTORY EXPANSION
6629 below for a description of history expansion.
6631 .B alias\-expand\-line
6632 Perform alias expansion on the current line.
6636 above for a description of alias expansion.
6638 .B history\-and\-alias\-expand\-line
6639 Perform history and alias expansion on the current line.
6641 .B insert\-last\-argument (M\-.\^, M\-_\^)
6642 A synonym for \fByank\-last\-arg\fP.
6644 .B edit\-and\-execute\-command (C\-x C\-e)
6645 Invoke an editor on the current command line, and execute the result as shell
6647 \fBBash\fP attempts to invoke
6652 and \fIemacs\fP as the editor, in that order.
6654 .SS Commands for Changing Text
6657 .B \fIend\-of\-file\fP (usually C\-d)
6658 The character indicating end-of-file as set, for example, by
6661 If this character is read when there are no characters
6662 on the line, and point is at the beginning of the line, readline
6663 interprets it as the end of input and returns
6667 .B delete\-char (C\-d)
6668 Delete the character at point.
6669 If this function is bound to the
6670 same character as the tty \fBEOF\fP character, as \fBC\-d\fP
6671 commonly is, see above for the effects.
6673 .B backward\-delete\-char (Rubout)
6674 Delete the character behind the cursor. When given a numeric argument,
6675 save the deleted text on the kill ring.
6677 .B forward\-backward\-delete\-char
6678 Delete the character under the cursor, unless the cursor is at the
6679 end of the line, in which case the character behind the cursor is
6682 .B quoted\-insert (C\-q, C\-v)
6683 Add the next character typed to the line verbatim. This is
6684 how to insert characters like \fBC\-q\fP, for example.
6686 .B tab\-insert (C\-v TAB)
6687 Insert a tab character.
6689 .B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
6690 Insert the character typed.
6692 .B transpose\-chars (C\-t)
6693 Drag the character before point forward over the character at point,
6694 moving point forward as well.
6695 If point is at the end of the line, then this transposes
6696 the two characters before point.
6697 Negative arguments have no effect.
6699 .B transpose\-words (M\-t)
6700 Drag the word before point past the word after point,
6701 moving point over that word as well.
6702 If point is at the end of the line, this transposes
6703 the last two words on the line.
6705 .B upcase\-word (M\-u)
6706 Uppercase the current (or following) word. With a negative argument,
6707 uppercase the previous word, but do not move point.
6709 .B downcase\-word (M\-l)
6710 Lowercase the current (or following) word. With a negative argument,
6711 lowercase the previous word, but do not move point.
6713 .B capitalize\-word (M\-c)
6714 Capitalize the current (or following) word. With a negative argument,
6715 capitalize the previous word, but do not move point.
6718 Toggle overwrite mode. With an explicit positive numeric argument,
6719 switches to overwrite mode. With an explicit non-positive numeric
6720 argument, switches to insert mode. This command affects only
6721 \fBemacs\fP mode; \fBvi\fP mode does overwrite differently.
6722 Each call to \fIreadline()\fP starts in insert mode.
6723 In overwrite mode, characters bound to \fBself\-insert\fP replace
6724 the text at point rather than pushing the text to the right.
6725 Characters bound to \fBbackward\-delete\-char\fP replace the character
6726 before point with a space. By default, this command is unbound.
6728 .SS Killing and Yanking
6731 .B kill\-line (C\-k)
6732 Kill the text from point to the end of the line.
6734 .B backward\-kill\-line (C\-x Rubout)
6735 Kill backward to the beginning of the line.
6737 .B unix\-line\-discard (C\-u)
6738 Kill backward from point to the beginning of the line.
6739 The killed text is saved on the kill-ring.
6740 .\" There is no real difference between this and backward-kill-line
6742 .B kill\-whole\-line
6743 Kill all characters on the current line, no matter where point is.
6745 .B kill\-word (M\-d)
6746 Kill from point to the end of the current word, or if between
6747 words, to the end of the next word.
6748 Word boundaries are the same as those used by \fBforward\-word\fP.
6750 .B backward\-kill\-word (M\-Rubout)
6751 Kill the word behind point.
6752 Word boundaries are the same as those used by \fBbackward\-word\fP.
6754 .B shell\-kill\-word
6755 Kill from point to the end of the current word, or if between
6756 words, to the end of the next word.
6757 Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
6759 .B shell\-backward\-kill\-word
6760 Kill the word behind point.
6761 Word boundaries are the same as those used by \fBshell\-backward\-word\fP.
6763 .B unix\-word\-rubout (C\-w)
6764 Kill the word behind point, using white space as a word boundary.
6765 The killed text is saved on the kill-ring.
6767 .B unix\-filename\-rubout
6768 Kill the word behind point, using white space and the slash character
6769 as the word boundaries.
6770 The killed text is saved on the kill-ring.
6772 .B delete\-horizontal\-space (M\-\e)
6773 Delete all spaces and tabs around point.
6776 Kill the text in the current region.
6778 .B copy\-region\-as\-kill
6779 Copy the text in the region to the kill buffer.
6781 .B copy\-backward\-word
6782 Copy the word before point to the kill buffer.
6783 The word boundaries are the same as \fBbackward\-word\fP.
6785 .B copy\-forward\-word
6786 Copy the word following point to the kill buffer.
6787 The word boundaries are the same as \fBforward\-word\fP.
6790 Yank the top of the kill ring into the buffer at point.
6793 Rotate the kill ring, and yank the new top. Only works following
6798 .SS Numeric Arguments
6801 .B digit\-argument (M\-0, M\-1, ..., M\-\-)
6802 Add this digit to the argument already accumulating, or start a new
6803 argument. M\-\- starts a negative argument.
6805 .B universal\-argument
6806 This is another way to specify an argument.
6807 If this command is followed by one or more digits, optionally with a
6808 leading minus sign, those digits define the argument.
6809 If the command is followed by digits, executing
6810 .B universal\-argument
6811 again ends the numeric argument, but is otherwise ignored.
6812 As a special case, if this command is immediately followed by a
6813 character that is neither a digit nor minus sign, the argument count
6814 for the next command is multiplied by four.
6815 The argument count is initially one, so executing this function the
6816 first time makes the argument count four, a second time makes the
6817 argument count sixteen, and so on.
6823 Attempt to perform completion on the text before point.
6825 attempts completion treating the text as a variable (if the
6826 text begins with \fB$\fP), username (if the text begins with
6827 \fB~\fP), hostname (if the text begins with \fB@\fP), or
6828 command (including aliases and functions) in turn. If none
6829 of these produces a match, filename completion is attempted.
6831 .B possible\-completions (M\-?)
6832 List the possible completions of the text before point.
6834 .B insert\-completions (M\-*)
6835 Insert all completions of the text before point
6836 that would have been generated by
6837 \fBpossible\-completions\fP.
6840 Similar to \fBcomplete\fP, but replaces the word to be completed
6841 with a single match from the list of possible completions.
6842 Repeated execution of \fBmenu\-complete\fP steps through the list
6843 of possible completions, inserting each match in turn.
6844 At the end of the list of completions, the bell is rung
6845 (subject to the setting of \fBbell\-style\fP)
6846 and the original text is restored.
6847 An argument of \fIn\fP moves \fIn\fP positions forward in the list
6848 of matches; a negative argument may be used to move backward
6850 This command is intended to be bound to \fBTAB\fP, but is unbound
6853 .B menu\-complete\-backward
6854 Identical to \fBmenu\-complete\fP, but moves backward through the list
6855 of possible completions, as if \fBmenu\-complete\fP had been given a
6856 negative argument. This command is unbound by default.
6858 .B delete\-char\-or\-list
6859 Deletes the character under the cursor if not at the beginning or
6860 end of the line (like \fBdelete\-char\fP).
6861 If at the end of the line, behaves identically to
6862 \fBpossible\-completions\fP.
6863 This command is unbound by default.
6865 .B complete\-filename (M\-/)
6866 Attempt filename completion on the text before point.
6868 .B possible\-filename\-completions (C\-x /)
6869 List the possible completions of the text before point,
6870 treating it as a filename.
6872 .B complete\-username (M\-~)
6873 Attempt completion on the text before point, treating
6876 .B possible\-username\-completions (C\-x ~)
6877 List the possible completions of the text before point,
6878 treating it as a username.
6880 .B complete\-variable (M\-$)
6881 Attempt completion on the text before point, treating
6882 it as a shell variable.
6884 .B possible\-variable\-completions (C\-x $)
6885 List the possible completions of the text before point,
6886 treating it as a shell variable.
6888 .B complete\-hostname (M\-@)
6889 Attempt completion on the text before point, treating
6892 .B possible\-hostname\-completions (C\-x @)
6893 List the possible completions of the text before point,
6894 treating it as a hostname.
6896 .B complete\-command (M\-!)
6897 Attempt completion on the text before point, treating
6898 it as a command name. Command completion attempts to
6899 match the text against aliases, reserved words, shell
6900 functions, shell builtins, and finally executable filenames,
6903 .B possible\-command\-completions (C\-x !)
6904 List the possible completions of the text before point,
6905 treating it as a command name.
6907 .B dynamic\-complete\-history (M\-TAB)
6908 Attempt completion on the text before point, comparing
6909 the text against lines from the history list for possible
6913 Attempt menu completion on the text before point, comparing
6914 the text against lines from the history list for possible
6917 .B complete\-into\-braces (M\-{)
6918 Perform filename completion and insert the list of possible completions
6919 enclosed within braces so the list is available to the shell (see
6926 .B start\-kbd\-macro (C\-x (\^)
6927 Begin saving the characters typed into the current keyboard macro.
6929 .B end\-kbd\-macro (C\-x )\^)
6930 Stop saving the characters typed into the current keyboard macro
6931 and store the definition.
6933 .B call\-last\-kbd\-macro (C\-x e)
6934 Re-execute the last keyboard macro defined, by making the characters
6935 in the macro appear as if typed at the keyboard.
6937 .B print\-last\-kbd\-macro ()
6938 Print the last keyboard macro defined in a format suitable for the
6944 .B re\-read\-init\-file (C\-x C\-r)
6945 Read in the contents of the \fIinputrc\fP file, and incorporate
6946 any bindings or variable assignments found there.
6949 Abort the current editing command and
6950 ring the terminal's bell (subject to the setting of
6953 .B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...)
6954 If the metafied character \fIx\fP is uppercase, run the command
6955 that is bound to the corresponding metafied lowercase character.
6956 The behavior is undefined if \fIx\fP is already lowercase.
6958 .B prefix\-meta (ESC)
6959 Metafy the next character typed.
6966 .B undo (C\-_, C\-x C\-u)
6967 Incremental undo, separately remembered for each line.
6969 .B revert\-line (M\-r)
6970 Undo all changes made to this line. This is like executing the
6972 command enough times to return the line to its initial state.
6974 .B tilde\-expand (M\-&)
6975 Perform tilde expansion on the current word.
6977 .B set\-mark (C\-@, M\-<space>)
6978 Set the mark to the point. If a
6979 numeric argument is supplied, the mark is set to that position.
6981 .B exchange\-point\-and\-mark (C\-x C\-x)
6982 Swap the point with the mark. The current cursor position is set to
6983 the saved position, and the old cursor position is saved as the mark.
6985 .B character\-search (C\-])
6986 A character is read and point is moved to the next occurrence of that
6987 character. A negative argument searches for previous occurrences.
6989 .B character\-search\-backward (M\-C\-])
6990 A character is read and point is moved to the previous occurrence of that
6991 character. A negative argument searches for subsequent occurrences.
6993 .B skip\-csi\-sequence
6994 Read enough characters to consume a multi-key sequence such as those
6995 defined for keys like Home and End. Such sequences begin with a
6996 Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is
6997 bound to "\e[", keys producing such sequences will have no effect
6998 unless explicitly bound to a readline command, instead of inserting
6999 stray characters into the editing buffer. This is unbound by default,
7000 but usually bound to ESC\-[.
7002 .B insert\-comment (M\-#)
7003 Without a numeric argument, the value of the readline
7005 variable is inserted at the beginning of the current line.
7006 If a numeric argument is supplied, this command acts as a toggle: if
7007 the characters at the beginning of the line do not match the value
7008 of \fBcomment\-begin\fP, the value is inserted, otherwise
7009 the characters in \fBcomment\-begin\fP are deleted from the beginning of
7011 In either case, the line is accepted as if a newline had been typed.
7012 The default value of
7013 \fBcomment\-begin\fP causes this command to make the current line
7015 If a numeric argument causes the comment character to be removed, the line
7016 will be executed by the shell.
7018 .B spell\-correct\-word (C\-x s)
7019 Perform spelling correction on the current word, treating it as a directory
7020 or filename, in the same way as the \fBcdspell\fP shell option.
7021 Word boundaries are the same as those used by \fBshell\-forward\-word\fP.
7023 .B glob\-complete\-word (M\-g)
7024 The word before point is treated as a pattern for pathname expansion,
7025 with an asterisk implicitly appended. This pattern is used to
7026 generate a list of matching filenames for possible completions.
7028 .B glob\-expand\-word (C\-x *)
7029 The word before point is treated as a pattern for pathname expansion,
7030 and the list of matching filenames is inserted, replacing the word.
7031 If a numeric argument is supplied, an asterisk is appended before
7034 .B glob\-list\-expansions (C\-x g)
7035 The list of expansions that would have been generated by
7036 .B glob\-expand\-word
7037 is displayed, and the line is redrawn.
7038 If a numeric argument is supplied, an asterisk is appended before
7042 Print all of the functions and their key bindings to the
7043 readline output stream. If a numeric argument is supplied,
7044 the output is formatted in such a way that it can be made part
7045 of an \fIinputrc\fP file.
7048 Print all of the settable readline variables and their values to the
7049 readline output stream. If a numeric argument is supplied,
7050 the output is formatted in such a way that it can be made part
7051 of an \fIinputrc\fP file.
7054 Print all of the readline key sequences bound to macros and the
7055 strings they output. If a numeric argument is supplied,
7056 the output is formatted in such a way that it can be made part
7057 of an \fIinputrc\fP file.
7059 .B display\-shell\-version (C\-x C\-v)
7060 Display version information about the current instance of
7063 .SS Programmable Completion
7064 When word completion is attempted for an argument to a command for
7065 which a completion specification (a \fIcompspec\fP) has been defined
7066 using the \fBcomplete\fP builtin (see
7068 .B "SHELL BUILTIN COMMANDS"
7069 below), the programmable completion facilities are invoked.
7071 First, the command name is identified.
7072 If the command word is the empty string (completion attempted at the
7073 beginning of an empty line), any compspec defined with
7074 the \fB\-E\fP option to \fBcomplete\fP is used.
7075 If a compspec has been defined for that command, the
7076 compspec is used to generate the list of possible completions for the word.
7077 If the command word is a full pathname, a compspec for the full
7078 pathname is searched for first.
7079 If no compspec is found for the full pathname, an attempt is made to
7080 find a compspec for the portion following the final slash.
7081 If those searches do not result in a compspec, any compspec defined with
7082 the \fB\-D\fP option to \fBcomplete\fP is used as the default.
7083 If there is no default compspec, \fBbash\fP attempts alias expansion
7084 on the command word as a final resort, and attempts to find a compspec
7085 for the command word from any successful expansion.
7087 Once a compspec has been found, it is used to generate the list of
7089 If a compspec is not found, the default \fBbash\fP completion as
7090 described above under \fBCompleting\fP is performed.
7092 First, the actions specified by the compspec are used.
7093 Only matches which are prefixed by the word being completed are
7099 option is used for filename or directory name completion, the shell
7103 is used to filter the matches.
7105 Any completions specified by a pathname expansion pattern to the
7106 \fB\-G\fP option are generated next.
7107 The words generated by the pattern need not match the word
7112 shell variable is not used to filter the matches, but the
7117 Next, the string specified as the argument to the \fB\-W\fP option
7119 The string is first split using the characters in the
7122 special variable as delimiters.
7123 Shell quoting is honored.
7124 Each word is then expanded using
7125 brace expansion, tilde expansion, parameter and variable expansion,
7126 command substitution, and arithmetic expansion,
7127 as described above under
7130 The results are split using the rules described above under
7131 \fBWord Splitting\fP.
7132 The results of the expansion are prefix-matched against the word being
7133 completed, and the matching words become the possible completions.
7135 After these matches have been generated, any shell function or command
7136 specified with the \fB\-F\fP and \fB\-C\fP options is invoked.
7137 When the command or function is invoked, the
7147 variables are assigned values as described above under
7148 \fBShell Variables\fP.
7149 If a shell function is being invoked, the
7155 variables are also set.
7156 When the function or command is invoked,
7157 the first argument (\fB$1\fP) is the name of the command whose arguments are
7159 the second argument (\fB$2\fP) is the word being completed,
7160 and the third argument (\fB$3\fP) is the word preceding the word being
7161 completed on the current command line.
7162 No filtering of the generated completions against the word being completed
7163 is performed; the function or command has complete freedom in generating
7166 Any function specified with \fB\-F\fP is invoked first.
7167 The function may use any of the shell facilities, including the
7168 \fBcompgen\fP builtin described below, to generate the matches.
7169 It must put the possible completions in the
7172 array variable, one per array element.
7174 Next, any command specified with the \fB\-C\fP option is invoked
7175 in an environment equivalent to command substitution.
7176 It should print a list of completions, one per line, to the
7178 Backslash may be used to escape a newline, if necessary.
7180 After all of the possible completions are generated, any filter
7181 specified with the \fB\-X\fP option is applied to the list.
7182 The filter is a pattern as used for pathname expansion; a \fB&\fP
7183 in the pattern is replaced with the text of the word being completed.
7184 A literal \fB&\fP may be escaped with a backslash; the backslash
7185 is removed before attempting a match.
7186 Any completion that matches the pattern will be removed from the list.
7187 A leading \fB!\fP negates the pattern; in this case any completion
7188 not matching the pattern will be removed.
7191 shell option is enabled, the match is performed without regard to the case
7192 of alphabetic characters.
7194 Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP
7195 options are added to each member of the completion list, and the result is
7196 returned to the readline completion code as the list of possible
7199 If the previously-applied actions do not generate any matches, and the
7200 \fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the
7201 compspec was defined, directory name completion is attempted.
7203 If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the
7204 compspec was defined, directory name completion is attempted and any
7205 matches are added to the results of the other actions.
7207 By default, if a compspec is found, whatever it generates is returned
7208 to the completion code as the full set of possible completions.
7209 The default \fBbash\fP completions are not attempted, and the readline
7210 default of filename completion is disabled.
7211 If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when
7212 the compspec was defined, the \fBbash\fP default completions are attempted
7213 if the compspec generates no matches.
7214 If the \fB\-o default\fP option was supplied to \fBcomplete\fP when the
7215 compspec was defined, readline's default completion will be performed
7216 if the compspec (and, if attempted, the default \fBbash\fP completions)
7217 generate no matches.
7219 When a compspec indicates that directory name completion is desired,
7220 the programmable completion functions force readline to append a slash
7221 to completed names which are symbolic links to directories, subject to
7222 the value of the \fBmark\-directories\fP readline variable, regardless
7223 of the setting of the \fBmark-symlinked\-directories\fP readline variable.
7225 There is some support for dynamically modifying completions. This is
7226 most useful when used in combination with a default completion specified
7227 with \fBcomplete \-D\fP.
7228 It's possible for shell functions executed as completion
7229 handlers to indicate that completion should be retried by returning an
7230 exit status of 124. If a shell function returns 124, and changes
7231 the compspec associated with the command on which completion is being
7232 attempted (supplied as the first argument when the function is executed),
7233 programmable completion restarts from the beginning, with an
7234 attempt to find a new compspec for that command. This allows a set of
7235 completions to be built dynamically as completion is attempted, rather than
7236 being loaded all at once.
7238 For instance, assuming that there is a library of compspecs, each kept in a
7239 file corresponding to the name of the command, the following default
7240 completion function would load completions dynamically:
7242 \f(CW_completion_loader()
7246 . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
7250 complete -D -F _completion_loader -o bashdefault -o default
7258 builtin is enabled, the shell provides access to the
7259 \fIcommand history\fP,
7260 the list of commands previously typed.
7264 variable is used as the
7265 number of commands to save in a history list.
7266 The text of the last
7269 commands (default 500) is saved. The shell
7270 stores each command in the history list prior to parameter and
7271 variable expansion (see
7274 above) but after history expansion is performed, subject to the
7275 values of the shell variables
7282 On startup, the history is initialized from the file named by
7286 (default \fI~/.bash_history\fP).
7287 The file named by the value of
7290 is truncated, if necessary, to contain no more than
7291 the number of lines specified by the value of
7294 If \fBHISTFILESIZE\fP is unset, or set to null, a non-numeric value,
7295 or a numeric value less than zero, the history file is not truncated.
7296 When the history file is read,
7297 lines beginning with the history comment character followed immediately
7298 by a digit are interpreted as timestamps for the following history line.
7299 These timestamps are optionally displayed depending on the value of the
7303 When a shell with history enabled exits, the last
7306 lines are copied from the history list to
7311 shell option is enabled
7312 (see the description of
7316 .B "SHELL BUILTIN COMMANDS"
7317 below), the lines are appended to the history file,
7318 otherwise the history file is overwritten.
7322 is unset, or if the history file is unwritable, the history is
7327 variable is set, time stamps are written to the history file, marked
7328 with the history comment character, so
7329 they may be preserved across shell sessions.
7330 This uses the history comment character to distinguish timestamps from
7331 other history lines.
7332 After saving the history, the history file is truncated
7333 to contain no more than
7339 is unset, or set to null, a non-numeric value,
7340 or a numeric value less than zero, the history file is not truncated.
7346 .B SHELL BUILTIN COMMANDS
7347 below) may be used to list or edit and re-execute a portion of
7351 builtin may be used to display or modify the history list and
7352 manipulate the history file.
7353 When using command-line editing, search commands
7354 are available in each editing mode that provide access to the
7357 The shell allows control over which commands are saved on the history
7364 variables may be set to cause the shell to save only a subset of the
7368 shell option, if enabled, causes the shell to attempt to save each
7369 line of a multi-line command in the same history entry, adding
7370 semicolons where necessary to preserve syntactic correctness.
7373 shell option causes the shell to save the command with embedded newlines
7374 instead of semicolons. See the description of the
7378 .B "SHELL BUILTIN COMMANDS"
7379 for information on setting and unsetting shell options.
7380 .SH "HISTORY EXPANSION"
7381 The shell supports a history expansion feature that
7382 is similar to the history expansion in
7384 This section describes what syntax features are available. This
7385 feature is enabled by default for interactive shells, and can be
7390 builtin command (see
7392 .B SHELL BUILTIN COMMANDS
7393 below). Non-interactive shells do not perform history expansion
7396 History expansions introduce words from the history list into
7397 the input stream, making it easy to repeat commands, insert the
7398 arguments to a previous command into the current input line, or
7399 fix errors in previous commands quickly.
7401 History expansion is performed immediately after a complete line
7402 is read, before the shell breaks it into words, and is performed
7403 on each line individually without taking quoting on previous lines into
7405 It takes place in two parts.
7406 The first is to determine which line from the history list
7407 to use during substitution.
7408 The second is to select portions of that line for inclusion into
7410 The line selected from the history is the \fIevent\fP,
7411 and the portions of that line that are acted upon are \fIwords\fP.
7412 Various \fImodifiers\fP are available to manipulate the selected words.
7413 The line is broken into words in the same fashion as when reading input,
7414 so that several \fImetacharacter\fP-separated words surrounded by
7415 quotes are considered one word.
7416 History expansions are introduced by the appearance of the
7417 history expansion character, which is \^\fB!\fP\^ by default.
7418 Only backslash (\^\fB\e\fP\^) and single quotes can quote
7419 the history expansion character, but the history expansion character is
7420 also treated as quoted if it immediately precedes the closing double quote
7421 in a double-quoted string.
7423 Several characters inhibit history expansion if found immediately
7424 following the history expansion character, even if it is unquoted:
7425 space, tab, newline, carriage return, and \fB=\fP.
7426 If the \fBextglob\fP shell option is enabled, \fB(\fP will also
7429 Several shell options settable with the
7431 builtin may be used to tailor the behavior of history expansion.
7434 shell option is enabled (see the description of the
7438 is being used, history substitutions are not immediately passed to
7440 Instead, the expanded line is reloaded into the
7442 editing buffer for further modification.
7445 is being used, and the
7447 shell option is enabled, a failed history substitution will be reloaded
7450 editing buffer for correction.
7455 builtin command may be used to see what a history expansion will
7461 builtin may be used to add commands to the end of the history list
7462 without actually executing them, so that they are available for
7465 The shell allows control of the various characters used by the
7466 history expansion mechanism (see the description of
7469 .BR "Shell Variables" ).
7471 the history comment character to mark history timestamps when
7472 writing the history file.
7473 .SS Event Designators
7474 An event designator is a reference to a command line entry in the
7476 Unless the reference is absolute, events are relative to the current
7477 position in the history list.
7482 Start a history substitution, except when followed by a
7484 newline, carriage return, =
7485 or ( (when the \fBextglob\fP shell option is enabled using
7486 the \fBshopt\fP builtin).
7489 Refer to command line
7493 Refer to the current command minus
7497 Refer to the previous command. This is a synonym for `!\-1'.
7500 Refer to the most recent command preceding the current position in the
7501 history list starting with
7504 .B !?\fIstring\fR\fB[?]\fR
7505 Refer to the most recent command preceding the current position in the
7506 history list containing
7508 The trailing \fB?\fP may be omitted if
7510 is followed immediately by a newline.
7511 If \fIstring\fP is missing, the string from the most recent search is used;
7512 it is an error if there is no previous search string.
7514 .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
7515 Quick substitution. Repeat the previous command, replacing
7520 ``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u''
7521 (see \fBModifiers\fP below).
7524 The entire command line typed so far.
7526 .SS Word Designators
7527 Word designators are used to select desired words from the event.
7530 separates the event specification from the word designator.
7531 It may be omitted if the word designator begins with a
7538 Words are numbered from the beginning of the line,
7539 with the first word being denoted by 0 (zero).
7540 Words are inserted into the current line separated by single spaces.
7545 The zeroth word. For the shell, this is the command
7552 The first argument. That is, word 1.
7555 The last word. This is usually the last argument, but will expand to the
7556 zeroth word if there is only one word in the line.
7559 The first word matched by the most recent `?\fIstring\fR?' search,
7560 if the search string begins with a character that is part of a word.
7563 A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
7566 All of the words but the zeroth. This is a synonym
7567 for `\fI1\-$\fP'. It is not an error to use
7569 if there is just one
7570 word in the event; the empty string is returned in that case.
7573 Abbreviates \fIx\-$\fP.
7576 Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
7577 If \fBx\fP is missing, it defaults to 0.
7580 If a word designator is supplied without an event specification, the
7581 previous command is used as the event.
7583 After the optional word designator, there may appear a sequence of
7584 one or more of the following modifiers, each preceded by a `:'.
7585 These modify, or edit, the word or words selected from the history event.
7590 Remove a trailing filename component, leaving only the head.
7593 Remove all leading filename components, leaving the tail.
7596 Remove a trailing suffix of the form \fI.xxx\fP, leaving the
7600 Remove all but the trailing suffix.
7603 Print the new command but do not execute it.
7606 Quote the substituted words, escaping further substitutions.
7609 Quote the substituted words as with
7611 but break into words at
7614 The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one
7617 .B s/\fIold\fP/\fInew\fP/
7620 for the first occurrence of
7623 Any character may be used as the delimiter in place of /.
7624 The final delimiter is optional if it is the last character of the
7626 The delimiter may be quoted in
7630 with a single backslash. If & appears in
7634 A single backslash will quote the &.
7637 is null, it is set to the last
7639 substituted, or, if no previous history substitutions took place,
7643 .B !?\fIstring\fR\fB[?]\fR
7647 is null, each matching
7652 Repeat the previous substitution.
7655 Cause changes to be applied over the entire event line. This is
7656 used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
7657 or `\fB:&\fP'. If used with
7658 `\fB:s\fP', any delimiter can be used
7659 in place of /, and the final delimiter is optional
7660 if it is the last character of the event line.
7661 An \fBa\fP may be used as a synonym for \fBg\fP.
7664 Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word
7667 .SH "SHELL BUILTIN COMMANDS"
7668 .\" start of bash_builtins
7671 Unless otherwise noted, each builtin command documented in this
7672 section as accepting options preceded by
7676 to signify the end of the options.
7677 The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins
7678 do not accept options and do not treat \fB\-\-\fP specially.
7679 The \fBexit\fP, \fBlogout\fP, \fBreturn\fP,
7680 \fBbreak\fP, \fBcontinue\fP, \fBlet\fP,
7681 and \fBshift\fP builtins accept and process arguments beginning with
7682 \fB\-\fP without requiring \fB\-\-\fP.
7683 Other builtins that accept arguments but are not specified as accepting
7684 options interpret arguments beginning with \fB\-\fP as invalid options and
7685 require \fB\-\-\fP to prevent this interpretation.
7689 \fB:\fP [\fIarguments\fP]
7691 No effect; the command does nothing beyond expanding
7693 and performing any specified
7695 The return status is zero.
7697 \fB .\| \fP \fIfilename\fP [\fIarguments\fP]
7700 \fBsource\fP \fIfilename\fP [\fIarguments\fP]
7702 Read and execute commands from
7705 shell environment and return the exit status of the last command
7710 does not contain a slash, filenames in
7713 are used to find the directory containing
7715 but \fIfilename\fP does not need to be executable.
7716 The file searched for in
7719 need not be executable.
7720 When \fBbash\fP is not in \fIposix mode\fP, it searches
7721 the current directory if no file is found in
7728 builtin command is turned off, the
7732 If any \fIarguments\fP are supplied, they become the positional
7733 parameters when \fIfilename\fP is executed. Otherwise the positional
7734 parameters are unchanged.
7735 If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on
7736 \fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and
7737 restored around the call to \fB.\fP, and \fB.\fP unsets the
7738 \fBDEBUG\fP trap while it executes.
7739 If \fB\-T\fP is not set, and the sourced file changes
7740 the \fBDEBUG\fP trap, the new value is retained when \fB.\fP completes.
7741 The return status is the status of the last command exited within
7742 the script (0 if no commands are executed), and false if
7744 is not found or cannot be read.
7746 \fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
7747 \fBAlias\fP with no arguments or with the
7749 option prints the list of aliases in the form
7750 \fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
7751 When arguments are supplied, an alias is defined for
7752 each \fIname\fP whose \fIvalue\fP is given.
7753 A trailing space in \fIvalue\fP causes the next word to be
7754 checked for alias substitution when the alias is expanded.
7755 For each \fIname\fP in the argument list for which no \fIvalue\fP
7756 is supplied, the name and value of the alias is printed.
7757 \fBAlias\fP returns true unless a \fIname\fP is given for which
7758 no alias has been defined.
7760 \fBbg\fP [\fIjobspec\fP ...]
7761 Resume each suspended job \fIjobspec\fP in the background, as if it
7762 had been started with
7766 is not present, the shell's notion of the \fIcurrent job\fP is used.
7769 returns 0 unless run when job control is disabled or, when run with
7770 job control enabled, any specified \fIjobspec\fP was not found
7771 or was started without job control.
7773 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP]
7776 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
7778 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
7780 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP
7782 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
7784 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP
7786 \fBbind\fP \fIreadline-command-line\fP
7790 key and function bindings, bind a key sequence to a
7792 function or macro, or set a
7795 Each non-option argument is a command as it would appear in a
7797 initialization file such as
7799 but each binding or command must be passed as a separate argument;
7800 e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'.
7801 Options, if supplied, have the following meanings:
7808 as the keymap to be affected by the subsequent bindings.
7812 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
7813 vi\-move, vi\-command\fP, and
7815 \fIvi\fP is equivalent to \fIvi\-command\fP (\fIvi\-move\fP is also
7816 a synonym); \fIemacs\fP is
7817 equivalent to \fIemacs\-standard\fP.
7820 List the names of all \fBreadline\fP functions.
7823 Display \fBreadline\fP function names and bindings in such a way
7824 that they can be re-read.
7827 List current \fBreadline\fP function names and bindings.
7830 Display \fBreadline\fP key sequences bound to macros and the strings
7831 they output in such a way that they can be re-read.
7834 Display \fBreadline\fP key sequences bound to macros and the strings
7838 Display \fBreadline\fP variable names and values in such a way that they
7842 List current \fBreadline\fP variable names and values.
7844 .B \-f \fIfilename\fP
7845 Read key bindings from \fIfilename\fP.
7847 .B \-q \fIfunction\fP
7848 Query about which keys invoke the named \fIfunction\fP.
7850 .B \-u \fIfunction\fP
7851 Unbind all keys bound to the named \fIfunction\fP.
7854 Remove any current binding for \fIkeyseq\fP.
7856 .B \-x \fIkeyseq\fP:\fIshell\-command\fP
7857 Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is
7859 When \fIshell\-command\fP is executed, the shell sets the
7862 variable to the contents of the \fBreadline\fP line buffer and the
7868 variables to the current location of the insertion point and the saved
7869 insertion point (the mark), respectively.
7870 The shell assigns any numeric argument the user supplied to the
7872 .B READLINE_ARGUMENT
7874 If there was no argument, that variable is not set.
7875 If the executed command changes the value of any of
7879 .BR READLINE_POINT ,
7883 those new values will be reflected in the editing state.
7886 List all key sequences bound to shell commands and the associated commands
7887 in a format that can be reused as input.
7890 The return value is 0 unless an unrecognized option is given or an
7894 \fBbreak\fP [\fIn\fP]
7901 loop. If \fIn\fP is specified, break \fIn\fP levels.
7905 is greater than the number of enclosing loops, all enclosing loops
7907 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
7909 \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
7910 Execute the specified shell builtin, passing it
7912 and return its exit status.
7913 This is useful when defining a
7914 function whose name is the same as a shell builtin,
7915 retaining the functionality of the builtin within the function.
7916 The \fBcd\fP builtin is commonly redefined this way.
7917 The return status is false if
7919 is not a shell builtin command.
7921 \fBcaller\fP [\fIexpr\fP]
7922 Returns the context of any active subroutine call (a shell function or
7923 a script executed with the \fB.\fP or \fBsource\fP builtins).
7924 Without \fIexpr\fP, \fBcaller\fP displays the line number and source
7925 filename of the current subroutine call.
7926 If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP
7927 displays the line number, subroutine name, and source file corresponding
7928 to that position in the current execution call stack. This extra
7929 information may be used, for example, to print a stack trace. The
7930 current frame is frame 0.
7931 The return value is 0 unless the shell is not executing a subroutine
7932 call or \fIexpr\fP does not correspond to a valid position in the
7935 \fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP]
7936 Change the current directory to \fIdir\fP.
7937 if \fIdir\fP is not supplied, the value of the
7940 shell variable is the default.
7944 defines the search path for the directory containing
7946 each directory name in
7949 is searched for \fIdir\fP.
7950 Alternative directory names in
7953 are separated by a colon (:). A null directory name in
7956 is the same as the current directory, i.e., ``\fB.\fP''. If
7958 begins with a slash (/),
7964 option causes \fBcd\fP to use the physical directory structure
7965 by resolving symbolic links while traversing \fIdir\fP and
7966 before processing instances of \fI..\fP in \fIdir\fP (see also the
7970 builtin command); the
7972 option forces symbolic links to be followed by resolving the link
7973 after processing instances of \fI..\fP in \fIdir\fP.
7974 If \fI..\fP appears in \fIdir\fP, it is processed by removing the
7975 immediately previous pathname component from \fIdir\fP, back to a slash
7976 or the beginning of \fIdir\fP.
7979 option is supplied with
7981 and the current working directory cannot be successfully determined
7982 after a successful directory change, \fBcd\fP will return an unsuccessful
7984 On systems that support it, the \fB\-@\fP option presents the extended
7985 attributes associated with a file as a directory.
7991 before the directory change is attempted.
7992 If a non-empty directory name from
7996 \fB\-\fP is the first argument, and the directory change is
7997 successful, the absolute pathname of the new working directory is
7998 written to the standard output.
7999 If the directory change is successful, \fBcd\fP sets the value of the
8000 \fBPWD\fP environment variable to the new directory name, and sets the
8001 \fBOLDPWD\fP environment variable to the value of the current working
8002 directory before the change.
8003 The return value is true if the directory was successfully changed;
8006 \fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...]
8011 suppressing the normal shell function lookup.
8012 Only builtin commands or commands found in the
8015 are executed. If the
8017 option is given, the search for
8019 is performed using a default value for
8022 that is guaranteed to find all of the standard utilities.
8027 option is supplied, a description of
8031 option causes a single word indicating the command or filename
8034 to be displayed; the
8036 option produces a more verbose description.
8041 option is supplied, the exit status is 0 if
8043 was found, and 1 if not. If neither option is supplied and
8044 an error occurred or
8046 cannot be found, the exit status is 127. Otherwise, the exit status of the
8048 builtin is the exit status of
8051 \fBcompgen\fP [\fIoption\fP] [\fIword\fP]
8052 Generate possible completion matches for \fIword\fP according to
8053 the \fIoption\fPs, which may be any option accepted by the
8055 builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write
8056 the matches to the standard output.
8057 When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables
8058 set by the programmable completion facilities, while available, will not
8061 The matches will be generated in the same way as if the programmable
8062 completion code had generated them directly from a completion specification
8063 with the same flags.
8064 If \fIword\fP is specified, only those completions matching \fIword\fP
8067 The return value is true unless an invalid option is supplied, or no
8068 matches were generated.
8070 \fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP]
8072 [\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP]
8075 \fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...]
8077 Specify how arguments to each \fIname\fP should be completed.
8078 If the \fB\-p\fP option is supplied, or if no options are supplied,
8079 existing completion specifications are printed in a way that allows
8080 them to be reused as input.
8081 The \fB\-r\fP option removes a completion specification for
8082 each \fIname\fP, or, if no \fIname\fPs are supplied, all
8083 completion specifications.
8084 The \fB\-D\fP option indicates that other supplied options and actions should
8085 apply to the ``default'' command completion; that is, completion attempted
8086 on a command for which no completion has previously been defined.
8087 The \fB\-E\fP option indicates that other supplied options and actions should
8088 apply to ``empty'' command completion; that is, completion attempted on a
8090 The \fB\-I\fP option indicates that other supplied options and actions should
8091 apply to completion on the initial non-assignment word on the line, or after
8092 a command delimiter such as \fB;\fP or \fB|\fP, which is usually command
8094 If multiple options are supplied, the \fB\-D\fP option takes precedence
8095 over \fB\-E\fP, and both take precedence over \fB\-I\fP.
8096 If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other
8097 \fIname\fP arguments are ignored; these completions only apply to the case
8098 specified by the option.
8100 The process of applying these completion specifications when word completion
8101 is attempted is described
8102 .ie \n(zZ=1 in \fIbash(1)\fP.
8103 .el above under \fBProgrammable Completion\fP.
8105 Other options, if specified, have the following meanings.
8106 The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options
8107 (and, if necessary, the \fB\-P\fP and \fB\-S\fP options)
8108 should be quoted to protect them from expansion before the
8114 \fB\-o\fP \fIcomp-option\fP
8115 The \fIcomp-option\fP controls several aspects of the compspec's behavior
8116 beyond the simple generation of completions.
8117 \fIcomp-option\fP may be one of:
8121 Perform the rest of the default \fBbash\fP completions if the compspec
8122 generates no matches.
8125 Use readline's default filename completion if the compspec generates
8129 Perform directory name completion if the compspec generates no matches.
8132 Tell readline that the compspec generates filenames, so it can perform any
8133 filename\-specific processing (like adding a slash to directory names,
8134 quoting special characters, or suppressing trailing spaces).
8135 Intended to be used with shell functions.
8138 Tell readline not to quote the completed words if they are filenames
8139 (quoting filenames is the default).
8142 Tell readline not to sort the list of possible completions alphabetically.
8145 Tell readline not to append a space (the default) to words completed at
8146 the end of the line.
8149 After any matches defined by the compspec are generated,
8150 directory name completion is attempted and any
8151 matches are added to the results of the other actions.
8154 \fB\-A\fP \fIaction\fP
8155 The \fIaction\fP may be one of the following to generate a list of possible
8160 Alias names. May also be specified as \fB\-a\fP.
8163 Array variable names.
8166 \fBReadline\fP key binding names.
8169 Names of shell builtin commands. May also be specified as \fB\-b\fP.
8172 Command names. May also be specified as \fB\-c\fP.
8175 Directory names. May also be specified as \fB\-d\fP.
8178 Names of disabled shell builtins.
8181 Names of enabled shell builtins.
8184 Names of exported shell variables. May also be specified as \fB\-e\fP.
8187 File names. May also be specified as \fB\-f\fP.
8190 Names of shell functions.
8193 Group names. May also be specified as \fB\-g\fP.
8196 Help topics as accepted by the \fBhelp\fP builtin.
8199 Hostnames, as taken from the file specified by the
8205 Job names, if job control is active. May also be specified as \fB\-j\fP.
8208 Shell reserved words. May also be specified as \fB\-k\fP.
8211 Names of running jobs, if job control is active.
8214 Service names. May also be specified as \fB\-s\fP.
8217 Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin.
8220 Shell option names as accepted by the \fBshopt\fP builtin.
8226 Names of stopped jobs, if job control is active.
8229 User names. May also be specified as \fB\-u\fP.
8232 Names of all shell variables. May also be specified as \fB\-v\fP.
8235 \fB\-C\fP \fIcommand\fP
8236 \fIcommand\fP is executed in a subshell environment, and its output is
8237 used as the possible completions.
8238 Arguments are passed as with the \fB\-F\fP option.
8240 \fB\-F\fP \fIfunction\fP
8241 The shell function \fIfunction\fP is executed in the current shell
8243 When the function is executed,
8244 the first argument (\fB$1\fP) is the name of the command whose arguments are
8246 the second argument (\fB$2\fP) is the word being completed,
8247 and the third argument (\fB$3\fP) is the word preceding the word being
8248 completed on the current command line.
8249 When it finishes, the possible completions are retrieved from the value
8255 \fB\-G\fP \fIglobpat\fP
8256 The pathname expansion pattern \fIglobpat\fP is expanded to generate
8257 the possible completions.
8259 \fB\-P\fP \fIprefix\fP
8260 \fIprefix\fP is added at the beginning of each possible completion
8261 after all other options have been applied.
8263 \fB\-S\fP \fIsuffix\fP
8264 \fIsuffix\fP is appended to each possible completion
8265 after all other options have been applied.
8267 \fB\-W\fP \fIwordlist\fP
8268 The \fIwordlist\fP is split using the characters in the
8271 special variable as delimiters, and each resultant word is expanded.
8272 Shell quoting is honored within \fIwordlist\fP,
8273 in order to provide a
8274 mechanism for the words to contain shell metacharacters or characters
8278 The possible completions are the members of the resultant list which
8279 match the word being completed.
8281 \fB\-X\fP \fIfilterpat\fP
8282 \fIfilterpat\fP is a pattern as used for pathname expansion.
8283 It is applied to the list of possible completions generated by the
8284 preceding options and arguments, and each completion matching
8285 \fIfilterpat\fP is removed from the list.
8286 A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this
8287 case, any completion not matching \fIfilterpat\fP is removed.
8290 The return value is true unless an invalid option is supplied, an option
8291 other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP
8292 argument, an attempt is made to remove a completion specification for
8293 a \fIname\fP for which no specification exists, or
8294 an error occurs adding a completion specification.
8297 \fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP]
8298 Modify completion options for each \fIname\fP according to the
8299 \fIoption\fPs, or for the
8300 currently-executing completion if no \fIname\fPs are supplied.
8301 If no \fIoption\fPs are given, display the completion options for each
8302 \fIname\fP or the current completion.
8303 The possible values of \fIoption\fP are those valid for the \fBcomplete\fP
8304 builtin described above.
8305 The \fB\-D\fP option indicates that other supplied options should
8306 apply to the ``default'' command completion; that is, completion attempted
8307 on a command for which no completion has previously been defined.
8308 The \fB\-E\fP option indicates that other supplied options should
8309 apply to ``empty'' command completion; that is, completion attempted on a
8311 The \fB\-I\fP option indicates that other supplied options should
8312 apply to completion on the initial non-assignment word on the line,
8313 or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually
8314 command name completion.
8316 The return value is true unless an invalid option is supplied, an attempt
8317 is made to modify the options for a \fIname\fP for which no completion
8318 specification exists, or an output error occurs.
8320 \fBcontinue\fP [\fIn\fP]
8321 Resume the next iteration of the enclosing
8330 is specified, resume at the \fIn\fPth enclosing loop.
8334 is greater than the number of enclosing loops, the last enclosing loop
8335 (the ``top-level'' loop) is resumed.
8336 The return value is 0 unless \fIn\fP is not greater than or equal to 1.
8338 \fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
8341 \fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
8343 Declare variables and/or give them attributes.
8344 If no \fIname\fPs are given then display the values of variables.
8347 option will display the attributes and values of each
8351 is used with \fIname\fP arguments, additional options,
8352 other than \fB\-f\fP and \fB\-F\fP, are ignored.
8355 is supplied without \fIname\fP arguments, it will display the attributes
8356 and values of all variables having the attributes specified by the
8358 If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will display
8359 the attributes and values of all shell variables. The \fB\-f\fP option
8360 will restrict the display to shell functions.
8363 option inhibits the display of function definitions; only the
8364 function name and attributes are printed.
8365 If the \fBextdebug\fP shell option is enabled using \fBshopt\fP,
8366 the source file name and line number where each \fIname\fP
8367 is defined are displayed as well. The
8373 option forces variables to be created or modified at the global scope,
8374 even when \fBdeclare\fP is executed in a shell function.
8375 It is ignored in all other cases.
8378 option causes local variables to inherit the attributes
8379 (except the \fInameref\fP attribute)
8380 and value of any existing variable with the same
8381 \fIname\fP at a surrounding scope.
8382 If there is no existing variable, the local variable is initially unset.
8383 The following options can
8384 be used to restrict output to variables with the specified attribute or
8385 to give variables attributes:
8390 Each \fIname\fP is an indexed array variable (see
8392 .ie \n(zZ=1 in \fIbash(1)\fP).
8396 Each \fIname\fP is an associative array variable (see
8398 .ie \n(zZ=1 in \fIbash(1)\fP).
8402 Use function names only.
8405 The variable is treated as an integer; arithmetic evaluation (see
8407 .B "ARITHMETIC EVALUATION"
8408 .ie \n(zZ=1 in \fIbash(1)\fP)
8410 is performed when the variable is assigned a value.
8413 When the variable is assigned a value, all upper-case characters are
8414 converted to lower-case.
8415 The upper-case attribute is disabled.
8418 Give each \fIname\fP the \fInameref\fP attribute, making
8419 it a name reference to another variable.
8420 That other variable is defined by the value of \fIname\fP.
8421 All references, assignments, and attribute modifications
8422 to \fIname\fP, except those using or changing the
8423 \fB\-n\fP attribute itself, are performed on the variable referenced by
8425 The nameref attribute cannot be applied to array variables.
8428 Make \fIname\fPs readonly. These names cannot then be assigned values
8429 by subsequent assignment statements or unset.
8432 Give each \fIname\fP the \fItrace\fP attribute.
8433 Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from
8435 The trace attribute has no special meaning for variables.
8438 When the variable is assigned a value, all lower-case characters are
8439 converted to upper-case.
8440 The lower-case attribute is disabled.
8443 Mark \fIname\fPs for export to subsequent commands via the environment.
8446 Using `+' instead of `\-'
8447 turns off the attribute instead,
8448 with the exceptions that \fB+a\fP and \fB+A\fP
8449 may not be used to destroy array variables and \fB+r\fP will not
8450 remove the readonly attribute.
8451 When used in a function,
8456 \fIname\fP local, as with the
8459 unless the \fB\-g\fP option is supplied.
8460 If a variable name is followed by =\fIvalue\fP, the value of
8461 the variable is set to \fIvalue\fP.
8462 When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to
8463 create array variables, additional attributes do not take effect until
8464 subsequent assignments.
8465 The return value is 0 unless an invalid option is encountered,
8466 an attempt is made to define a function using
8467 .if n ``\-f foo=bar'',
8468 .if t \f(CW\-f foo=bar\fP,
8469 an attempt is made to assign a value to a readonly variable,
8470 an attempt is made to assign a value to an array variable without
8471 using the compound assignment syntax (see
8473 .ie \n(zZ=1 in \fIbash(1)\fP),
8475 one of the \fInames\fP is not a valid shell variable name,
8476 an attempt is made to turn off readonly status for a readonly variable,
8477 an attempt is made to turn off array status for an array variable,
8478 or an attempt is made to display a non-existent function with \fB\-f\fP.
8481 .B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
8482 Without options, displays the list of currently remembered directories.
8483 The default display is on a single line with directory names separated
8485 Directories are added to the list with the
8489 command removes entries from the list.
8490 The current directory is always the first directory in the stack.
8495 Clears the directory stack by deleting all of the entries.
8498 Produces a listing using full pathnames;
8499 the default listing format uses a tilde to denote the home directory.
8502 Print the directory stack with one entry per line.
8505 Print the directory stack with one entry per line,
8506 prefixing each entry with its index in the stack.
8509 Displays the \fIn\fPth entry counting from the left of the list
8512 when invoked without options, starting with zero.
8515 Displays the \fIn\fPth entry counting from the right of the list
8518 when invoked without options, starting with zero.
8521 The return value is 0 unless an
8522 invalid option is supplied or \fIn\fP indexes beyond the end
8523 of the directory stack.
8526 \fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ]
8527 Without options, remove each
8529 from the table of active jobs.
8532 is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option
8533 is supplied, the \fIcurrent job\fP is used.
8534 If the \fB\-h\fP option is given, each
8536 is not removed from the table, but is marked so that
8539 is not sent to the job if the shell receives a
8546 option means to remove or mark all jobs; the
8550 argument restricts operation to running jobs.
8551 The return value is 0 unless a
8553 does not specify a valid job.
8555 \fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...]
8556 Output the \fIarg\fPs, separated by spaces, followed by a newline.
8557 The return status is 0 unless a write error occurs.
8558 If \fB\-n\fP is specified, the trailing newline is
8559 suppressed. If the \fB\-e\fP option is given, interpretation of
8560 the following backslash-escaped characters is enabled. The
8562 option disables the interpretation of these escape characters,
8563 even on systems where they are interpreted by default.
8564 The \fBxpg_echo\fP shell option may be used to
8565 dynamically determine whether or not \fBecho\fP expands these
8566 escape characters by default.
8568 does not interpret \fB\-\-\fP to mean the end of options.
8570 interprets the following escape sequences:
8581 suppress further output
8607 the eight-bit character whose value is the octal value \fInnn\fP
8608 (zero to three octal digits)
8611 the eight-bit character whose value is the hexadecimal value \fIHH\fP
8612 (one or two hex digits)
8615 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
8616 \fIHHHH\fP (one to four hex digits)
8618 .B \eU\fIHHHHHHHH\fP
8619 the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
8620 \fIHHHHHHHH\fP (one to eight hex digits)
8624 \fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...]
8625 Enable and disable builtin shell commands.
8626 Disabling a builtin allows a disk command which has the same name
8627 as a shell builtin to be executed without specifying a full pathname,
8628 even though the shell normally searches for builtins before disk commands.
8629 If \fB\-n\fP is used, each \fIname\fP
8630 is disabled; otherwise,
8631 \fInames\fP are enabled. For example, to use the
8633 binary found via the
8636 instead of the shell builtin version, run
8637 .if t \f(CWenable -n test\fP.
8638 .if n ``enable -n test''.
8641 option means to load the new builtin command
8645 on systems that support dynamic loading.
8646 Bash will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a
8647 colon-separated list of directories in which to search for \fIfilename\fP.
8648 The default is system-dependent.
8651 option will delete a builtin previously loaded with
8653 If no \fIname\fP arguments are given, or if the
8655 option is supplied, a list of shell builtins is printed.
8656 With no other option arguments, the list consists of all enabled
8658 If \fB\-n\fP is supplied, only disabled builtins are printed.
8659 If \fB\-a\fP is supplied, the list printed includes all builtins, with an
8660 indication of whether or not each is enabled.
8661 If \fB\-s\fP is supplied, the output is restricted to the POSIX
8662 \fIspecial\fP builtins.
8663 If no options are supplied and a \fIname\fP is not a shell builtin,
8664 \fBenable\fP will attempt to load \fIname\fP from a shared object named
8665 \fIname\fP, as if the command were
8666 .if t \f(CWenable \-f\fP \fIname name\fP .
8667 .if n ``enable -f \fIname name\fP .
8668 The return value is 0 unless a
8670 is not a shell builtin or there is an error loading a new builtin
8671 from a shared object.
8673 \fBeval\fP [\fIarg\fP ...]
8674 The \fIarg\fPs are read and concatenated together into a single
8675 command. This command is then read and executed by the shell, and
8676 its exit status is returned as the value of
8680 or only null arguments,
8684 \fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]]
8687 is specified, it replaces the shell.
8688 No new process is created. The
8690 become the arguments to \fIcommand\fP.
8694 the shell places a dash at the beginning of the zeroth argument passed to
8702 to be executed with an empty environment. If
8704 is supplied, the shell passes
8706 as the zeroth argument to the executed command.
8709 cannot be executed for some reason, a non-interactive shell exits,
8713 is enabled. In that case, it returns failure.
8714 An interactive shell returns failure if the file cannot be executed.
8715 A subshell exits unconditionally if \fBexec\fP fails.
8718 is not specified, any redirections take effect in the current shell,
8719 and the return status is 0. If there is a redirection error, the
8722 \fBexit\fP [\fIn\fP]
8723 Cause the shell to exit
8724 with a status of \fIn\fP. If
8726 is omitted, the exit status
8727 is that of the last command executed.
8731 is executed before the shell terminates.
8733 \fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ...
8740 are marked for automatic export to the environment of
8741 subsequently executed commands. If the
8743 option is given, the
8748 are given, or if the
8750 option is supplied, a list
8751 of names of all exported variables is printed.
8754 option causes the export property to be removed from each
8756 If a variable name is followed by =\fIword\fP, the value of
8757 the variable is set to \fIword\fP.
8759 returns an exit status of 0 unless an invalid option is
8761 one of the \fInames\fP is not a valid shell variable name, or
8765 that is not a function.
8767 \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP]
8770 \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
8772 The first form selects a range of commands from
8776 from the history list and displays or edits and re-executes them.
8780 may be specified as a string (to locate the last command beginning
8781 with that string) or as a number (an index into the history list,
8782 where a negative number is used as an offset from the current
8784 When listing, a \fIfirst\fP or \fIlast\fP of
8785 0 is equivalent to \-1 and \-0 is equivalent to the current
8786 command (usually the \fBfc\fP command); otherwise 0 is equivalent to \-1
8790 is not specified, it is set to
8791 the current command for listing (so that
8792 .if n ``fc \-l \-10''
8793 .if t \f(CWfc \-l \-10\fP
8794 prints the last 10 commands) and to
8799 is not specified, it is set to the previous
8800 command for editing and \-16 for listing.
8805 the command numbers when listing. The
8807 option reverses the order of
8808 the commands. If the
8811 the commands are listed on
8812 standard output. Otherwise, the editor given by
8815 on a file containing those commands. If
8821 variable is used, and
8828 is not set. If neither variable is set,
8830 is used. When editing is complete, the edited commands are
8831 echoed and executed.
8833 In the second form, \fIcommand\fP is re-executed after each instance
8834 of \fIpat\fP is replaced by \fIrep\fP.
8835 \fICommand\fP is interpreted the same as \fIfirst\fP above.
8836 A useful alias to use with this is
8837 .if n ``r="fc -s"'',
8838 .if t \f(CWr='fc \-s'\fP,
8842 runs the last command beginning with
8848 re-executes the last command.
8850 If the first form is used, the return value is 0 unless an invalid
8851 option is encountered or
8855 specify history lines out of range.
8858 option is supplied, the return value is the value of the last
8859 command executed or failure if an error occurs with the temporary
8860 file of commands. If the second form is used, the return status
8861 is that of the command re-executed, unless
8863 does not specify a valid history line, in which case
8867 \fBfg\fP [\fIjobspec\fP]
8870 in the foreground, and make it the current job.
8873 is not present, the shell's notion of the \fIcurrent job\fP is used.
8874 The return value is that of the command placed into the foreground,
8875 or failure if run when job control is disabled or, when run with
8876 job control enabled, if
8878 does not specify a valid job or
8880 specifies a job that was started without job control.
8882 \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg ...\fP]
8884 is used by shell procedures to parse positional parameters.
8886 contains the option characters to be recognized; if a character
8887 is followed by a colon, the option is expected to have an
8888 argument, which should be separated from it by white space.
8889 The colon and question mark characters may not be used as
8891 Each time it is invoked,
8893 places the next option in the shell variable
8897 if it does not exist,
8898 and the index of the next argument to be processed into the
8904 is initialized to 1 each time the shell or a shell script
8905 is invoked. When an option requires an argument,
8907 places that argument into the variable
8910 The shell does not reset
8913 automatically; it must be manually reset between multiple
8916 within the same shell invocation if a new set of parameters
8919 When the end of options is encountered, \fBgetopts\fP exits with a
8920 return value greater than zero.
8923 is set to the index of the first non-option argument,
8924 and \fIname\fP is set to ?.
8927 normally parses the positional parameters, but if more arguments are
8932 parses those instead.
8935 can report errors in two ways. If the first character of
8939 error reporting is used. In normal operation, diagnostic messages
8940 are printed when invalid options or missing option arguments are
8945 is set to 0, no error messages will be displayed, even if the first
8950 If an invalid option is seen,
8955 prints an error message and unsets
8961 the option character found is placed in
8964 and no diagnostic message is printed.
8966 If a required argument is not found, and
8969 a question mark (\^\fB?\fP\^) is placed in
8973 is unset, and a diagnostic message is printed.
8976 is silent, then a colon (\^\fB:\fP\^) is placed in
8981 is set to the option character found.
8984 returns true if an option, specified or unspecified, is found.
8985 It returns false if the end of options is encountered or an
8988 \fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP]
8989 Each time \fBhash\fP is invoked,
8990 the full pathname of the command
8992 is determined by searching
8995 and remembered. Any previously-remembered pathname is discarded.
8998 option is supplied, no path search is performed, and
9000 is used as the full filename of the command.
9003 option causes the shell to forget all
9004 remembered locations.
9007 option causes the shell to forget the remembered location of each \fIname\fP.
9010 option is supplied, the full pathname to which each \fIname\fP corresponds
9011 is printed. If multiple \fIname\fP arguments are supplied with \fB\-t\fP,
9012 the \fIname\fP is printed before the hashed full pathname.
9015 option causes output to be displayed in a format that may be reused as input.
9016 If no arguments are given, or if only \fB\-l\fP is supplied,
9017 information about remembered commands is printed.
9018 The return status is true unless a
9020 is not found or an invalid option is supplied.
9022 \fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP]
9023 Display helpful information about builtin commands. If
9027 gives detailed help on all commands matching
9029 otherwise help for all the builtins and shell control structures
9035 Display a short description of each \fIpattern\fP
9038 Display the description of each \fIpattern\fP in a manpage-like format
9041 Display only a short usage synopsis for each \fIpattern\fP
9044 The return status is 0 unless no command matches
9048 \fBhistory [\fIn\fP]
9051 \fBhistory\fP \fB\-c\fP
9053 \fBhistory \-d\fP \fIoffset\fP
9055 \fBhistory \-d\fP \fIstart\fP\-\fIend\fP
9057 \fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
9059 \fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP]
9061 \fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP]
9063 With no options, display the command
9064 history list with line numbers. Lines listed
9067 have been modified. An argument of
9072 If the shell variable
9075 is set and not null,
9076 it is used as a format string for \fIstrftime\fP(3) to display
9077 the time stamp associated with each displayed history entry.
9078 No intervening blank is printed between the formatted time stamp
9079 and the history line.
9080 If \fIfilename\fP is supplied, it is used as the
9081 name of the history file; if not, the value of
9084 is used. Options, if supplied, have the following meanings:
9089 Clear the history list by deleting all the entries.
9091 \fB\-d\fP \fIoffset\fP
9092 Delete the history entry at position \fIoffset\fP.
9093 If \fIoffset\fP is negative, it is interpreted as relative to one greater
9094 than the last history position, so negative indices count back from the
9095 end of the history, and an index of \-1 refers to the current
9096 \fBhistory -d\fP command.
9098 \fB\-d\fP \fIstart\fP\-\fIend\fP
9099 Delete the range of history entries between positions \fIstart\fP and
9100 \fIend\fP, inclusive.
9101 Positive and negative values for \fIstart\fP and \fIend\fP
9102 are interpreted as described above.
9105 Append the ``new'' history lines to the history file.
9106 These are history lines entered since the beginning of the current
9107 \fBbash\fP session, but not already appended to the history file.
9110 Read the history lines not already read from the history
9111 file into the current history list. These are lines
9112 appended to the history file since the beginning of the
9113 current \fBbash\fP session.
9116 Read the contents of the history file
9117 and append them to the current history list.
9120 Write the current history list to the history file, overwriting the
9121 history file's contents.
9124 Perform history substitution on the following \fIargs\fP and display
9125 the result on the standard output.
9126 Does not store the results in the history list.
9127 Each \fIarg\fP must be quoted to disable normal history expansion.
9132 in the history list as a single entry. The last command in the
9133 history list is removed before the
9141 variable is set, the time stamp information
9142 associated with each history entry is written to the history file,
9143 marked with the history comment character.
9144 When the history file is read, lines beginning with the history
9145 comment character followed immediately by a digit are interpreted
9146 as timestamps for the following history entry.
9147 The return value is 0 unless an invalid option is encountered, an
9148 error occurs while reading or writing the history file, an invalid
9149 \fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the
9150 history expansion supplied as an argument to \fB\-p\fP fails.
9153 \fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ]
9156 \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ]
9158 The first form lists the active jobs. The options have the following
9165 in addition to the normal information.
9168 Display information only about jobs that have changed status since
9169 the user was last notified of their status.
9172 List only the process ID of the job's process group
9176 Display only running jobs.
9179 Display only stopped jobs.
9184 is given, output is restricted to information about that job.
9185 The return status is 0 unless an invalid option is encountered
9200 with the corresponding process group ID, and executes
9204 returning its exit status.
9207 \fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ...
9210 \fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP]
9212 Send the signal named by
9216 to the processes named by
9221 is either a case-insensitive signal name such as
9224 (with or without the
9227 prefix) or a signal number;
9232 is not present, then
9238 lists the signal names.
9239 If any arguments are supplied when
9241 is given, the names of the signals corresponding to the arguments are
9242 listed, and the return status is 0.
9243 The \fIexit_status\fP argument to
9245 is a number specifying either a signal number or the exit status of
9246 a process terminated by a signal.
9249 option is equivalent to \fB\-l\fP.
9251 returns true if at least one signal was successfully sent, or false
9252 if an error occurs or an invalid option is encountered.
9254 \fBlet\fP \fIarg\fP [\fIarg\fP ...]
9257 is an arithmetic expression to be evaluated (see
9259 .B "ARITHMETIC EVALUATION"
9260 .ie \n(zZ=1 in \fIbash(1)\fP).
9266 returns 1; 0 is returned otherwise.
9268 \fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ]
9269 For each argument, a local variable named
9271 is created, and assigned
9273 The \fIoption\fP can be any of the options accepted by \fBdeclare\fP.
9276 is used within a function, it causes the variable
9278 to have a visible scope restricted to that function and its children.
9279 If \fIname\fP is \-, the set of shell options is made local to the function
9280 in which \fBlocal\fP is invoked: shell options changed using the
9281 \fBset\fP builtin inside the function are restored to their original values
9282 when the function returns.
9283 The restore is effected as if a series of \fBset\fP commands were executed
9284 to restore the values that were in place before the function.
9287 writes a list of local variables to the standard output. It is
9290 when not within a function. The return status is 0 unless
9292 is used outside a function, an invalid
9295 \fIname\fP is a readonly variable.
9300 \fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
9303 \fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP]
9305 Read lines from the standard input into the indexed array variable
9307 or from file descriptor
9315 is the default \fIarray\fP.
9316 Options, if supplied, have the following meanings:
9321 The first character of \fIdelim\fP is used to terminate each input line,
9322 rather than newline.
9323 If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line
9324 when it reads a NUL character.
9329 lines. If \fIcount\fP is 0, all lines are copied.
9336 The default index is 0.
9339 Discard the first \fIcount\fP lines read.
9342 Remove a trailing \fIdelim\fP (default newline) from each line read.
9345 Read lines from file descriptor \fIfd\fP instead of the standard input.
9350 each time \fIquantum\fP lines are read. The \fB\-c\fP option specifies
9354 Specify the number of lines read between each call to
9360 is specified without
9362 the default quantum is 5000.
9363 When \fIcallback\fP is evaluated, it is supplied the index of the next
9364 array element to be assigned and the line to be assigned to that element
9365 as additional arguments.
9366 \fIcallback\fP is evaluated after the line is read but before the
9367 array element is assigned.
9369 If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP
9370 before assigning to it.
9372 \fBmapfile\fP returns successfully unless an invalid option or option
9373 argument is supplied, \fIarray\fP is invalid or unassignable, or if
9374 \fIarray\fP is not an indexed array.
9377 \fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
9378 Removes entries from the directory stack.
9379 The elements are numbered from 0 starting at the first directory
9380 listed by \fBdirs\fP.
9381 With no arguments, \fBpopd\fP
9382 removes the top directory from the stack, and
9383 changes to the new top directory.
9384 Arguments, if supplied, have the following meanings:
9389 Suppresses the normal change of directory when removing directories
9390 from the stack, so that only the stack is manipulated.
9393 Removes the \fIn\fPth entry counting from the left of the list
9396 starting with zero, from the stack.
9399 .if t \f(CWpopd +0\fP
9400 removes the first directory,
9402 .if t \f(CWpopd +1\fP
9406 Removes the \fIn\fPth entry counting from the right of the list
9409 starting with zero. For example:
9411 .if t \f(CWpopd -0\fP
9412 removes the last directory,
9414 .if t \f(CWpopd -1\fP
9418 If the top element of the directory stack is modified, and
9419 the \fI-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP
9420 builtin to change to the directory at the top of the stack.
9421 If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value.
9425 returns false if an invalid option is encountered, the directory stack
9426 is empty, or a non-existent directory stack entry is specified.
9430 command is successful,
9433 to show the final contents of the directory stack,
9434 and the return status is 0.
9437 \fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP]
9438 Write the formatted \fIarguments\fP to the standard output under the
9439 control of the \fIformat\fP.
9440 The \fB\-v\fP option causes the output to be assigned to the variable
9441 \fIvar\fP rather than being printed to the standard output.
9443 The \fIformat\fP is a character string which contains three types of objects:
9444 plain characters, which are simply copied to standard output, character
9445 escape sequences, which are converted and copied to the standard output, and
9446 format specifications, each of which causes printing of the next successive
9448 In addition to the standard \fIprintf\fP(1) format specifications,
9449 \fBprintf\fP interprets the following extensions:
9455 \fBprintf\fP to expand backslash escape sequences in the corresponding
9457 in the same way as \fBecho \-e\fP.
9460 causes \fBprintf\fP to output the corresponding
9461 \fIargument\fP in a format that can be reused as shell input.
9464 like \fB%q\fP, but applies any supplied precision to the \fIargument\fP
9467 .B %(\fIdatefmt\fP)T
9468 causes \fBprintf\fP to output the date-time string resulting from using
9469 \fIdatefmt\fP as a format string for \fIstrftime\fP(3).
9470 The corresponding \fIargument\fP is an integer representing the number of
9471 seconds since the epoch.
9472 Two special argument values may be used: \-1 represents the current
9473 time, and \-2 represents the time the shell was invoked.
9474 If no argument is specified, conversion behaves as if \-1 had been given.
9475 This is an exception to the usual \fBprintf\fP behavior.
9478 The %b, %q, and %T directives all use the field width and precision
9479 arguments from the format specification and write that many bytes from
9480 (or use that wide a field for) the expanded argument, which usually
9481 contains more characters than the original.
9483 Arguments to non-string format specifiers are treated as C constants,
9484 except that a leading plus or minus sign is allowed, and if the leading
9485 character is a single or double quote, the value is the ASCII value of
9486 the following character.
9488 The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP.
9489 If the \fIformat\fP requires more \fIarguments\fP than are supplied, the
9490 extra format specifications behave as if a zero value or null string, as
9491 appropriate, had been supplied.
9492 The return value is zero on success, non-zero on failure.
9495 \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
9498 \fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
9500 Adds a directory to the top of the directory stack, or rotates
9501 the stack, making the new top of the stack the current working
9503 With no arguments, \fBpushd\fP exchanges the top two elements of
9504 the directory stack.
9505 Arguments, if supplied, have the following meanings:
9510 Suppresses the normal change of directory when rotating or
9511 adding directories to the stack, so that only the stack is manipulated.
9514 Rotates the stack so that the \fIn\fPth directory
9515 (counting from the left of the list shown by
9521 Rotates the stack so that the \fIn\fPth directory
9522 (counting from the right of the list shown by
9524 starting with zero) is at the top.
9529 to the directory stack at the top
9532 After the stack has been modified, if the \fB\-n\fP option was not
9533 supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the
9534 directory at the top of the stack.
9535 If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value.
9537 Otherwise, if no arguments are supplied,
9539 returns 0 unless the directory stack is empty.
9540 When rotating the directory stack,
9542 returns 0 unless the directory stack is empty or
9543 a non-existent directory stack element is specified.
9547 command is successful,
9550 to show the final contents of the directory stack.
9553 \fBpwd\fP [\fB\-LP\fP]
9554 Print the absolute pathname of the current working directory.
9555 The pathname printed contains no symbolic links if the
9557 option is supplied or the
9561 builtin command is enabled.
9564 option is used, the pathname printed may contain symbolic links.
9565 The return status is 0 unless an error occurs while
9566 reading the name of the current directory or an
9567 invalid option is supplied.
9569 \fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...]
9570 One line is read from the standard input, or from the file descriptor
9571 \fIfd\fP supplied as an argument to the \fB\-u\fP option,
9572 split into words as described
9573 .ie \n(zZ=1 in \fIbash(1)\fP
9575 under \fBWord Splitting\fP,
9577 is assigned to the first
9579 the second word to the second
9582 If there are more words than names, the remaining words and their
9583 intervening delimiters are assigned to the last
9585 If there are fewer words read from the input stream than names,
9586 the remaining names are assigned empty values.
9590 are used to split the line into words using the same rules the shell
9591 uses for expansion (described
9592 .ie \n(zZ=1 in \fIbash(1)\fP
9594 under \fBWord Splitting\fP).
9595 The backslash character (\fB\e\fP) may be used to remove any special
9596 meaning for the next character read and for line continuation.
9597 Options, if supplied, have the following meanings:
9602 The words are assigned to sequential indices
9603 of the array variable
9607 is unset before any new values are assigned.
9608 Other \fIname\fP arguments are ignored.
9611 The first character of \fIdelim\fP is used to terminate the input line,
9612 rather than newline.
9613 If \fIdelim\fP is the empty string, \fBread\fP will terminate a line
9614 when it reads a NUL character.
9617 If the standard input
9618 is coming from a terminal,
9623 .ie \n(zZ=1 in \fIbash(1)\fP)
9625 is used to obtain the line.
9626 Readline uses the current (or default, if line editing was not previously
9627 active) editing settings, but uses readline's default filename completion.
9632 is being used to read the line, \fItext\fP is placed into the editing
9633 buffer before editing begins.
9636 \fBread\fP returns after reading \fInchars\fP characters rather than
9637 waiting for a complete line of input, but honors a delimiter if fewer
9638 than \fInchars\fP characters are read before the delimiter.
9641 \fBread\fP returns after reading exactly \fInchars\fP characters rather
9642 than waiting for a complete line of input, unless EOF is encountered or
9643 \fBread\fP times out.
9644 Delimiter characters encountered in the input are
9645 not treated specially and do not cause \fBread\fP to return until
9646 \fInchars\fP characters are read.
9647 The result is not split on the characters in \fBIFS\fP; the intent is
9648 that the variable is assigned exactly the characters read
9649 (with the exception of backslash; see the \fB\-r\fP option below).
9652 Display \fIprompt\fP on standard error, without a
9653 trailing newline, before attempting to read any input. The prompt
9654 is displayed only if input is coming from a terminal.
9657 Backslash does not act as an escape character.
9658 The backslash is considered to be part of the line.
9659 In particular, a backslash-newline pair may not then be used as a line
9663 Silent mode. If input is coming from a terminal, characters are
9666 .B \-t \fItimeout\fP
9667 Cause \fBread\fP to time out and return failure if a complete line of
9668 input (or a specified number of characters)
9669 is not read within \fItimeout\fP seconds.
9670 \fItimeout\fP may be a decimal number with a fractional portion following
9672 This option is only effective if \fBread\fP is reading input from a
9673 terminal, pipe, or other special file; it has no effect when reading
9675 If \fBread\fP times out, \fBread\fP saves any partial input read into
9676 the specified variable \fIname\fP.
9677 If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to
9679 The exit status is 0 if input is available on the specified file descriptor,
9680 or the read will return EOF,
9682 The exit status is greater than 128 if the timeout is exceeded.
9685 Read input from file descriptor \fIfd\fP.
9690 are supplied, the line read,
9691 without the ending delimiter but otherwise unmodified,
9692 is assigned to the variable
9695 The exit status is zero, unless end-of-file is encountered, \fBread\fP
9696 times out (in which case the status is greater than 128),
9697 a variable assignment error (such as assigning to a readonly variable) occurs,
9698 or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
9701 \fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...]
9704 \fInames\fP are marked readonly; the values of these
9706 may not be changed by subsequent assignment.
9709 option is supplied, the functions corresponding to the
9714 option restricts the variables to indexed arrays; the
9716 option restricts the variables to associative arrays.
9717 If both options are supplied,
9722 arguments are given, or if the
9724 option is supplied, a list of all readonly names is printed.
9725 The other options may be used to restrict the output to a subset of
9726 the set of readonly names.
9729 option causes output to be displayed in a format that
9730 may be reused as input.
9731 If a variable name is followed by =\fIword\fP, the value of
9732 the variable is set to \fIword\fP.
9733 The return status is 0 unless an invalid option is encountered,
9736 is not a valid shell variable name, or
9740 that is not a function.
9742 \fBreturn\fP [\fIn\fP]
9743 Causes a function to stop executing and return the value specified by
9748 is omitted, the return status is that of the last command
9749 executed in the function body.
9750 If \fBreturn\fP is executed by a trap handler, the last command used to
9751 determine the status is the last command executed before the trap handler.
9752 If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command
9753 used to determine the status is the last command executed by the trap
9754 handler before \fBreturn\fP was invoked.
9757 is used outside a function,
9758 but during execution of a script by the
9760 (\fBsource\fP) command, it causes the shell to stop executing
9761 that script and return either
9763 or the exit status of the last command executed within the
9764 script as the exit status of the script.
9765 If \fIn\fP is supplied, the return value is its least significant
9767 The return status is non-zero if
9769 is supplied a non-numeric argument, or
9771 function and not during execution of a script by \fB.\fP\^ or \fBsource\fP.
9772 Any command associated with the \fBRETURN\fP trap is executed
9773 before execution resumes after the function or script.
9775 \fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]
9778 \fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...]
9780 Without options, display the name and value of each shell variable
9781 in a format that can be reused as input
9782 for setting or resetting the currently-set variables.
9783 Read-only variables cannot be reset.
9784 In \fIposix mode\fP, only shell variables are listed.
9785 The output is sorted according to the current locale.
9786 When options are specified, they set or unset shell attributes.
9787 Any arguments remaining after option processing are treated
9788 as values for the positional parameters and are assigned, in order, to
9793 Options, if specified, have the following meanings:
9798 Each variable or function that is created or modified is given the
9799 export attribute and marked for export to the environment of
9800 subsequent commands.
9803 Report the status of terminated background jobs
9804 immediately, rather than before the next primary prompt. This is
9805 effective only when job control is enabled.
9808 Exit immediately if a
9809 \fIpipeline\fP (which may consist of a single \fIsimple command\fP),
9811 or a \fIcompound command\fP
9815 .ie \n(zZ=1 in \fIbash(1)\fP),
9817 exits with a non-zero status.
9818 The shell does not exit if the
9819 command that fails is part of the command list immediately following a
9824 part of the test following the
9828 reserved words, part of any command executed in a
9832 list except the command following the final \fB&&\fP or \fB||\fP,
9833 any command in a pipeline but the last,
9834 or if the command's return value is
9837 If a compound command other than a subshell
9838 returns a non-zero status because a command failed
9839 while \fB\-e\fP was being ignored, the shell does not exit.
9840 A trap on \fBERR\fP, if set, is executed before the shell exits.
9841 This option applies to the shell environment and each subshell environment
9844 .B "COMMAND EXECUTION ENVIRONMENT"
9845 .ie \n(zZ=1 in \fIbash(1)\fP),
9848 subshells to exit before executing all the commands in the subshell.
9851 If a compound command or shell function executes in a context
9852 where \fB\-e\fP is being ignored,
9853 none of the commands executed within the compound command or function body
9854 will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set
9855 and a command returns a failure status.
9856 If a compound command or shell function sets \fB\-e\fP while executing in
9857 a context where \fB\-e\fP is ignored, that setting will not have any
9858 effect until the compound command or the command containing the function
9862 Disable pathname expansion.
9865 Remember the location of commands as they are looked up for execution.
9866 This is enabled by default.
9869 All arguments in the form of assignment statements
9870 are placed in the environment for a command, not just
9871 those that precede the command name.
9874 Monitor mode. Job control is enabled. This option is on
9875 by default for interactive shells on systems that support
9879 .ie \n(zZ=1 in \fIbash(1)\fP).
9881 All processes run in a separate process group.
9882 When a background job completes, the shell prints a line
9883 containing its exit status.
9886 Read commands but do not execute them.
9887 This may be used to check a shell script for syntax errors.
9888 This is ignored by interactive shells.
9890 .B \-o \fIoption\-name\fP
9891 The \fIoption\-name\fP can be one of the following:
9903 Use an emacs-style command line editing interface. This is enabled
9904 by default when the shell is interactive, unless the shell is started
9908 This also affects the editing interface used for \fBread \-e\fP.
9931 Enable command history, as described
9932 .ie \n(zZ=1 in \fIbash(1)\fP
9937 This option is on by default in interactive shells.
9940 The effect is as if the shell command
9941 .if t \f(CWIGNOREEOF=10\fP
9942 .if n ``IGNOREEOF=10''
9946 .ie \n(zZ=1 in \fIbash(1)\fP).
9989 If set, the return value of a pipeline is the value of the last
9990 (rightmost) command to exit with a non-zero status, or zero if all
9991 commands in the pipeline exit successfully.
9992 This option is disabled by default.
9995 Change the behavior of
9997 where the default operation differs
9998 from the POSIX standard to match the standard (\fIposix mode\fP).
10002 .ie \n(zZ=1 in \fIbash(1)\fP
10004 for a reference to a document that details how posix mode affects
10016 Use a vi-style command line editing interface.
10017 This also affects the editing interface used for \fBread \-e\fP.
10026 is supplied with no \fIoption\-name\fP, the values of the current options are
10030 is supplied with no \fIoption\-name\fP, a series of
10032 commands to recreate the current option settings is displayed on
10033 the standard output.
10039 mode. In this mode, the
10045 files are not processed, shell functions are not inherited from the
10046 environment, and the
10056 variables, if they appear in the environment, are ignored.
10057 If the shell is started with the effective user (group) id not equal to the
10058 real user (group) id, and the \fB\-p\fP option is not supplied, these actions
10059 are taken and the effective user id is set to the real user id.
10060 If the \fB\-p\fP option is supplied at startup, the effective user id is
10062 Turning this option off causes the effective user
10063 and group ids to be set to the real user and group ids.
10066 Enable restricted shell mode.
10067 This option cannot be unset once it has been set.
10070 Exit after reading and executing one command.
10073 Treat unset variables and parameters other than the special
10074 parameters "@" and "*",
10075 or array variables subscripted with "@" or "*",
10076 as an error when performing
10077 parameter expansion. If expansion is attempted on an
10078 unset variable or parameter, the shell prints an error message, and,
10079 if not interactive, exits with a non-zero status.
10082 Print shell input lines as they are read.
10085 After expanding each \fIsimple command\fP,
10086 \fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or
10087 arithmetic \fBfor\fP command, display the expanded value of
10090 followed by the command and its expanded arguments
10091 or associated word list.
10094 The shell performs brace expansion (see
10096 .ie \n(zZ=1 in \fIbash(1)\fP).
10098 This is on by default.
10103 does not overwrite an existing file with the
10108 redirection operators. This may be overridden when
10109 creating output files by using the redirection operator
10115 If set, any trap on \fBERR\fP is inherited by shell functions, command
10116 substitutions, and commands executed in a subshell environment.
10117 The \fBERR\fP trap is normally not inherited in such cases.
10122 style history substitution. This option is on by
10123 default when the shell is interactive.
10126 If set, the shell does not resolve symbolic links when executing
10129 that change the current working directory. It uses the
10130 physical directory structure instead. By default,
10132 follows the logical chain of directories when performing commands
10133 which change the current directory.
10136 If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell
10137 functions, command substitutions, and commands executed in a
10138 subshell environment.
10139 The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited
10143 If no arguments follow this option, then the positional parameters are
10144 unset. Otherwise, the positional parameters are set to the
10145 \fIarg\fPs, even if some of them begin with a
10149 Signal the end of options, cause all remaining \fIarg\fPs to be
10150 assigned to the positional parameters. The
10154 options are turned off.
10155 If there are no \fIarg\fPs,
10156 the positional parameters remain unchanged.
10159 The options are off by default unless otherwise noted.
10160 Using + rather than \- causes these options to be turned off.
10161 The options can also be specified as arguments to an invocation of
10163 The current set of options may be found in
10165 The return status is always true unless an invalid option is encountered.
10168 \fBshift\fP [\fIn\fP]
10169 The positional parameters from \fIn\fP+1 ... are renamed to
10172 Parameters represented by the numbers \fB$#\fP
10173 down to \fB$#\fP\-\fIn\fP+1 are unset.
10175 must be a non-negative number less than or equal to \fB$#\fP.
10178 is 0, no parameters are changed.
10181 is not given, it is assumed to be 1.
10184 is greater than \fB$#\fP, the positional parameters are not changed.
10185 The return status is greater than zero if
10189 or less than zero; otherwise 0.
10191 \fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...]
10192 Toggle the values of settings controlling optional shell behavior.
10193 The settings can be either those listed below, or, if the
10195 option is used, those available with the
10197 option to the \fBset\fP builtin command.
10198 With no options, or with the
10200 option, a list of all settable options is displayed, with
10201 an indication of whether or not each is set;
10202 if \fIoptnames\fP are supplied, the output is restricted to those options.
10203 The \fB\-p\fP option causes output to be displayed in a form that
10204 may be reused as input.
10205 Other options have the following meanings:
10210 Enable (set) each \fIoptname\fP.
10213 Disable (unset) each \fIoptname\fP.
10216 Suppresses normal output (quiet mode); the return status indicates
10217 whether the \fIoptname\fP is set or unset.
10218 If multiple \fIoptname\fP arguments are given with
10220 the return status is zero if all \fIoptnames\fP are enabled; non-zero
10224 Restricts the values of \fIoptname\fP to be those defined for the
10235 is used with no \fIoptname\fP arguments,
10237 shows only those options which are set or unset, respectively.
10238 Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
10241 The return status when listing options is zero if all \fIoptnames\fP
10242 are enabled, non-zero otherwise. When setting or unsetting options,
10243 the return status is zero unless an \fIoptname\fP is not a valid shell
10246 The list of \fBshopt\fP options is:
10251 .B assoc_expand_once
10252 If set, the shell suppresses multiple evaluation of associative array
10253 subscripts during arithmetic expression evaluation, while executing
10254 builtins that can perform variable assignments,
10255 and while executing builtins that perform array dereferencing.
10258 If set, a command name that is the name of a directory is executed as if
10259 it were the argument to the \fBcd\fP command.
10260 This option is only used by interactive shells.
10263 If set, an argument to the
10265 builtin command that
10266 is not a directory is assumed to be the name of a variable whose
10267 value is the directory to change to.
10270 If set, minor errors in the spelling of a directory component in a
10272 command will be corrected.
10273 The errors checked for are transposed characters,
10274 a missing character, and one character too many.
10275 If a correction is found, the corrected filename is printed,
10276 and the command proceeds.
10277 This option is only used by interactive shells.
10280 If set, \fBbash\fP checks that a command found in the hash
10281 table exists before trying to execute it. If a hashed command no
10282 longer exists, a normal path search is performed.
10285 If set, \fBbash\fP lists the status of any stopped and running jobs before
10286 exiting an interactive shell. If any jobs are running, this causes
10287 the exit to be deferred until a second exit is attempted without an
10288 intervening command (see
10291 .ie \n(zZ=1 in \fIbash(1)\fP).
10293 The shell always postpones exiting if any jobs are stopped.
10296 If set, \fBbash\fP checks the window size after each external (non-builtin)
10297 command and, if necessary, updates the values of
10303 This option is enabled by default.
10308 attempts to save all lines of a multiple-line
10309 command in the same history entry. This allows
10310 easy re-editing of multi-line commands.
10311 This option is enabled by default, but only has an effect if command
10312 history is enabled, as described
10313 .ie \n(zZ=1 in \fIbash(1)\fP
10336 These control aspects of the shell's compatibility mode
10339 .B "SHELL COMPATIBILITY MODE"
10340 .ie \n(zZ=1 in \fIbash(1)\fP).
10343 .B complete_fullquote
10346 quotes all shell metacharacters in filenames and directory names when
10347 performing completion.
10350 removes metacharacters such as the dollar sign from the set of
10351 characters that will be quoted in completed filenames
10352 when these metacharacters appear in shell variable references in words to be
10354 This means that dollar signs in variable names that expand to directories
10355 will not be quoted;
10356 however, any dollar signs appearing in filenames will not be quoted, either.
10357 This is active only when bash is using backslashes to quote completed
10359 This variable is set by default, which is the default bash behavior in
10360 versions through 4.2.
10365 replaces directory names with the results of word expansion when performing
10366 filename completion. This changes the contents of the readline editing
10370 attempts to preserve what the user typed.
10375 attempts spelling correction on directory names during word completion
10376 if the directory name initially supplied does not exist.
10381 includes filenames beginning with a `.' in the results of pathname
10387 must always be matched explicitly, even if
10392 If set, a non-interactive shell will not exit if
10393 it cannot execute the file specified as an argument to the
10395 builtin command. An interactive shell does not exit if
10400 If set, aliases are expanded as described
10401 .ie \n(zZ=1 in \fIbash(1)\fP
10406 This option is enabled by default for interactive shells.
10409 If set at shell invocation,
10410 or in a shell startup file,
10411 arrange to execute the debugger profile
10412 before the shell starts, identical to the \fB\-\-debugger\fP option.
10413 If set after invocation, behavior intended for use by debuggers is enabled:
10417 The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source
10418 file name and line number corresponding to each function name supplied
10422 If the command run by the \fBDEBUG\fP trap returns a non-zero value, the
10423 next command is skipped and not executed.
10426 If the command run by the \fBDEBUG\fP trap returns a value of 2, and the
10427 shell is executing in a subroutine (a shell function or a shell script
10428 executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates
10429 a call to \fBreturn\fP.
10437 are updated as described in their descriptions
10438 .ie \n(zZ=1 in \fIbash(1)\fP).
10442 Function tracing is enabled: command substitution, shell functions, and
10443 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
10444 \fBDEBUG\fP and \fBRETURN\fP traps.
10447 Error tracing is enabled: command substitution, shell functions, and
10448 subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the
10453 If set, the extended pattern matching features described
10454 .ie \n(zZ=1 in \fIbash(1)\fP
10457 \fBPathname Expansion\fP are enabled.
10460 If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is
10461 performed within \fB${\fP\fIparameter\fP\fB}\fP expansions
10462 enclosed in double quotes. This option is enabled by default.
10465 If set, patterns which fail to match filenames during pathname expansion
10466 result in an expansion error.
10469 If set, the suffixes specified by the
10473 cause words to be ignored when performing word completion even if
10474 the ignored words are the only possible completions.
10477 \fBSHELL VARIABLES\fP
10478 .ie \n(zZ=1 in \fIbash(1)\fP
10480 for a description of
10483 This option is enabled by default.
10486 If set, range expressions used in pattern matching bracket expressions (see
10488 .B Pattern Matching
10489 .ie \n(zZ=1 in \fIbash(1)\fP)
10491 behave as if in the traditional C locale when performing
10492 comparisons. That is, the current locale's collating sequence
10493 is not taken into account, so
10495 will not collate between
10499 and upper-case and lower-case ASCII characters will collate together.
10502 If set, pathname expansion will never match the filenames
10506 even if the pattern begins with a
10508 This option is enabled by default.
10511 If set, the pattern \fB**\fP used in a pathname expansion context will
10512 match all files and zero or more directories and subdirectories.
10513 If the pattern is followed by a \fB/\fP, only directories and
10514 subdirectories match.
10517 If set, shell error messages are written in the standard GNU error
10521 If set, the history list is appended to the file named by the value
10525 variable when the shell exits, rather than overwriting the file.
10530 is being used, a user is given the opportunity to re-edit a
10531 failed history substitution.
10536 is being used, the results of history substitution are not immediately
10537 passed to the shell parser. Instead, the resulting line is loaded into
10538 the \fBreadline\fP editing buffer, allowing further modification.
10543 is being used, \fBbash\fP will attempt to perform hostname completion when a
10544 word containing a \fB@\fP is being completed (see
10549 .ie \n(zZ=1 in \fIbash(1)\fP).
10551 This is enabled by default.
10554 If set, \fBbash\fP will send
10557 to all jobs when an interactive login shell exits.
10560 If set, command substitution inherits the value of the \fBerrexit\fP option,
10561 instead of unsetting it in the subshell environment.
10562 This option is enabled when \fIposix mode\fP is enabled.
10564 .B interactive_comments
10565 If set, allow a word beginning with
10567 to cause that word and all remaining characters on that
10568 line to be ignored in an interactive shell (see
10571 .ie \n(zZ=1 in \fIbash(1)\fP).
10573 This option is enabled by default.
10576 If set, and job control is not active, the shell runs the last command of
10577 a pipeline not executed in the background in the current shell environment.
10582 option is enabled, multi-line commands are saved to the history with
10583 embedded newlines rather than using semicolon separators where possible.
10585 .B localvar_inherit
10586 If set, local variables inherit the value and attributes of a variable of
10587 the same name that exists at a previous scope before any new value is
10588 assigned. The nameref attribute is not inherited.
10591 If set, calling \fBunset\fP on local variables in previous function scopes
10592 marks them so subsequent lookups find them unset until that function
10593 returns. This is identical to the behavior of unsetting local variables
10594 at the current function scope.
10597 The shell sets this option if it is started as a login shell (see
10600 .ie \n(zZ=1 in \fIbash(1)\fP).
10602 The value may not be changed.
10605 If set, and a file that \fBbash\fP is checking for mail has been
10606 accessed since the last time it was checked, the message ``The mail in
10607 \fImailfile\fP has been read'' is displayed.
10609 .B no_empty_cmd_completion
10614 will not attempt to search the
10617 for possible completions when
10618 completion is attempted on an empty line.
10623 matches filenames in a case\-insensitive fashion when performing pathname
10625 .B Pathname Expansion
10626 .ie \n(zZ=1 in \fIbash(1)\fP).
10632 matches patterns in a case\-insensitive fashion when performing matching
10633 while executing \fBcase\fP or \fB[[\fP conditional commands,
10634 when performing pattern substitution word expansions,
10635 or when filtering possible completions as part of programmable completion.
10637 .B noexpand_translation
10640 encloses the translated results of $"..." quoting in single quotes
10641 instead of double quotes.
10642 If the string is not translated, this has no effect.
10647 allows patterns which match no
10649 .B Pathname Expansion
10650 .ie \n(zZ=1 in \fIbash(1)\fP)
10652 to expand to a null string, rather than themselves.
10654 .B patsub_replacement
10656 expands occurrences of \fB&\fP in the replacement string of pattern
10657 substitution to the text matched by the pattern, as described
10658 under \fBParameter Expansion\fP
10659 .ie \n(zZ=1 in \fIbash(1)\fP.
10661 This option is enabled by default.
10664 If set, the programmable completion facilities (see
10665 \fBProgrammable Completion\fP
10666 .ie \n(zZ=1 in \fIbash(1)\fP)
10669 This option is enabled by default.
10672 If set, and programmable completion is enabled, \fBbash\fP treats a command
10673 name that doesn't have any completions as a possible alias and attempts
10674 alias expansion. If it has an alias, \fBbash\fP attempts programmable
10675 completion using the command word resulting from the expanded alias.
10678 If set, prompt strings undergo
10679 parameter expansion, command substitution, arithmetic
10680 expansion, and quote removal after being expanded as described in
10683 .ie \n(zZ=1 in \fIbash(1)\fP.
10685 This option is enabled by default.
10687 .B restricted_shell
10688 The shell sets this option if it is started in restricted mode
10691 .B "RESTRICTED SHELL"
10692 .ie \n(zZ=1 in \fIbash(1)\fP).
10694 The value may not be changed.
10695 This is not reset when the startup files are executed, allowing
10696 the startup files to discover whether or not a shell is restricted.
10701 builtin prints an error message when the shift count exceeds the
10702 number of positional parameters.
10706 \fB.\fP (\fBsource\fP) builtin uses the value of
10709 to find the directory containing the file supplied as an argument.
10710 This option is enabled by default.
10713 If set, the shell automatically closes file descriptors assigned using the
10714 \fI{varname}\fP redirection syntax (see
10717 .ie \n(zZ=1 in \fIbash(1)\fP)
10719 instead of leaving them open when the command completes.
10722 If set, the \fBecho\fP builtin expands backslash-escape sequences
10727 \fBsuspend\fP [\fB\-f\fP]
10728 Suspend the execution of this shell until it receives a
10731 signal. A login shell,
10732 or a shell without job control enabled,
10733 cannot be suspended; the
10735 option can be used to override this and force the suspension.
10736 The return status is 0 unless the shell is a login shell
10737 or job control is not enabled
10742 \fBtest\fP \fIexpr\fP
10745 \fB[\fP \fIexpr\fP \fB]\fP
10746 Return a status of 0 (true) or 1 (false) depending on
10747 the evaluation of the conditional expression
10749 Each operator and operand must be a separate argument.
10750 Expressions are composed of the primaries described
10751 .ie \n(zZ=1 in \fIbash(1)\fP
10755 .BR "CONDITIONAL EXPRESSIONS" .
10756 \fBtest\fP does not accept any options, nor does it accept and ignore
10757 an argument of \fB\-\-\fP as signifying the end of options.
10760 Expressions may be combined using the following operators, listed
10761 in decreasing order of precedence.
10762 The evaluation depends on the number of arguments; see below.
10763 Operator precedence is used when there are five or more arguments.
10773 Returns the value of \fIexpr\fP.
10774 This may be used to override the normal precedence of operators.
10776 \fIexpr1\fP \-\fBa\fP \fIexpr2\fP
10783 \fIexpr1\fP \-\fBo\fP \fIexpr2\fP
10791 \fBtest\fP and \fB[\fP evaluate conditional
10792 expressions using a set of rules based on the number of arguments.
10798 The expression is false.
10801 The expression is true if and only if the argument is not null.
10804 If the first argument is \fB!\fP, the expression is true if and
10805 only if the second argument is null.
10806 If the first argument is one of the unary conditional operators listed
10807 .ie \n(zZ=1 in \fIbash(1)\fP
10811 .BR "CONDITIONAL EXPRESSIONS" ,
10812 the expression is true if the unary test is true.
10813 If the first argument is not a valid unary conditional operator, the expression
10817 The following conditions are applied in the order listed.
10818 If the second argument is one of the binary conditional operators listed
10819 .ie \n(zZ=1 in \fIbash(1)\fP
10823 .BR "CONDITIONAL EXPRESSIONS" ,
10824 the result of the expression is the result of the binary test using
10825 the first and third arguments as operands.
10826 The \fB\-a\fP and \fB\-o\fP operators are considered binary operators
10827 when there are three arguments.
10828 If the first argument is \fB!\fP, the value is the negation of
10829 the two-argument test using the second and third arguments.
10830 If the first argument is exactly \fB(\fP and the third argument is
10831 exactly \fB)\fP, the result is the one-argument test of the second
10833 Otherwise, the expression is false.
10836 The following conditions are applied in the order listed.
10837 If the first argument is \fB!\fP, the result is the negation of
10838 the three-argument expression composed of the remaining arguments.
10839 the two-argument test using the second and third arguments.
10840 If the first argument is exactly \fB(\fP and the fourth argument is
10841 exactly \fB)\fP, the result is the two-argument test of the second
10842 and third arguments.
10843 Otherwise, the expression is parsed and evaluated according to
10844 precedence using the rules listed above.
10846 5 or more arguments
10847 The expression is parsed and evaluated according to precedence
10848 using the rules listed above.
10852 When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators
10853 sort lexicographically using ASCII ordering.
10858 Print the accumulated user and system times for the shell and
10859 for processes run from the shell. The return status is 0.
10861 \fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...]
10864 is to be read and executed when the shell receives
10869 is absent (and there is a single \fIsigspec\fP) or
10871 each specified signal is
10872 reset to its original disposition (the value it had
10873 upon entrance to the shell).
10876 is the null string the signal specified by each
10878 is ignored by the shell and by the commands it invokes.
10883 has been supplied, then the trap commands associated with each
10886 If no arguments are supplied or if only
10890 prints the list of commands associated with each signal.
10893 option causes the shell to print a list of signal names and
10894 their corresponding numbers.
10898 a signal name defined in <\fIsignal.h\fP>, or a signal number.
10899 Signal names are case insensitive and the
10902 prefix is optional.
10912 is executed on exit from the shell.
10920 is executed before every \fIsimple command\fP, \fIfor\fP command,
10921 \fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP
10922 command, and before the first command executes in a shell function (see
10925 .ie \n(zZ=1 in \fIbash(1)\fP).
10927 Refer to the description of the \fBextdebug\fP option to the
10928 \fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap.
10936 is executed each time a shell function or a script executed with
10937 the \fB.\fP or \fBsource\fP builtins finishes executing.
10947 is executed whenever
10948 a pipeline (which may consist of a single simple
10949 command), a list, or a compound command returns a
10950 non\-zero exit status,
10951 subject to the following conditions.
10955 trap is not executed if the failed
10956 command is part of the command list immediately following a
10961 part of the test in an
10963 statement, part of a command executed in a
10967 list except the command following the final \fB&&\fP or \fB||\fP,
10968 any command in a pipeline but the last,
10969 or if the command's return value is
10970 being inverted using
10972 These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option.
10975 Signals ignored upon entry to the shell cannot be trapped or reset.
10976 Trapped signals that are not being ignored are reset to their original
10977 values in a subshell or subshell environment when one is created.
10978 The return status is false if any
10980 is invalid; otherwise
10984 \fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...]
10988 would be interpreted if used as a command name.
10993 prints a string which is one of
11002 is an alias, shell reserved word, function, builtin, or disk file,
11006 is not found, then nothing is printed, and an exit status of false
11012 either returns the name of the disk file
11013 that would be executed if
11015 were specified as a command name,
11017 .if t \f(CWtype -t name\fP
11018 .if n ``type -t name''
11026 search for each \fIname\fP, even if
11027 .if t \f(CWtype -t name\fP
11028 .if n ``type -t name''
11031 If a command is hashed,
11035 print the hashed value, which is not necessarily the file that appears
11043 prints all of the places that contain
11044 an executable named
11046 This includes aliases and functions,
11049 option is not also used.
11050 The table of hashed commands is not consulted
11055 option suppresses shell function lookup, as with the \fBcommand\fP builtin.
11057 returns true if all of the arguments are found, false if
11060 \fBulimit\fP [\fB\-HS\fP] \fB\-a\fP
11063 \fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]]
11065 Provides control over the resources available to the shell and to
11066 processes started by it, on systems that allow such control.
11067 The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is
11068 set for the given resource.
11069 A hard limit cannot be increased by a non-root user once it is set;
11070 a soft limit may be increased up to the value of the hard limit.
11071 If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard
11075 can be a number in the unit specified for the resource
11076 or one of the special values
11081 which stand for the current hard limit, the current soft limit, and
11082 no limit, respectively.
11085 is omitted, the current value of the soft limit of the resource is
11086 printed, unless the \fB\-H\fP option is given. When more than one
11087 resource is specified, the limit name and unit, if appropriate,
11088 are printed before the value.
11089 Other options are interpreted as follows:
11094 All current limits are reported; no limits are set
11097 The maximum socket buffer size
11100 The maximum size of core files created
11103 The maximum size of a process's data segment
11106 The maximum scheduling priority ("nice")
11109 The maximum size of files written by the shell and its children
11112 The maximum number of pending signals
11115 The maximum number of kqueues that may be allocated
11118 The maximum size that may be locked into memory
11121 The maximum resident set size (many systems do not honor this limit)
11124 The maximum number of open file descriptors (most systems do not
11125 allow this value to be set)
11128 The pipe size in 512-byte blocks (this may not be set)
11131 The maximum number of bytes in POSIX message queues
11134 The maximum real-time scheduling priority
11137 The maximum stack size
11140 The maximum amount of cpu time in seconds
11143 The maximum number of processes available to a single user
11146 The maximum amount of virtual memory available to the shell and, on
11147 some systems, to its children
11150 The maximum number of file locks
11153 The maximum number of pseudoterminals
11156 The maximum time a real-time process can run before blocking, in microseconds
11159 The maximum number of threads
11166 option is not used,
11167 \fIlimit\fP is the new value of the specified resource.
11168 If no option is given, then
11170 is assumed. Values are in 1024-byte increments, except for
11172 which is in seconds;
11174 which is in microseconds;
11176 which is in units of 512-byte blocks;
11184 which are unscaled values;
11185 and, when in posix mode,
11189 which are in 512-byte increments.
11190 The return status is 0 unless an invalid option or argument is supplied,
11191 or an error occurs while setting a new limit.
11194 \fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP]
11195 The user file-creation mask is set to
11199 begins with a digit, it
11200 is interpreted as an octal number; otherwise
11201 it is interpreted as a symbolic mode mask similar
11202 to that accepted by
11206 is omitted, the current value of the mask is printed.
11209 option causes the mask to be printed in symbolic form; the
11210 default output is an octal number.
11213 option is supplied, and
11215 is omitted, the output is in a form that may be reused as input.
11216 The return status is 0 if the mode was successfully changed or if
11217 no \fImode\fP argument was supplied, and false otherwise.
11219 \fBunalias\fP [\-\fBa\fP] [\fIname\fP ...]
11220 Remove each \fIname\fP from the list of defined aliases. If
11222 is supplied, all alias definitions are removed. The return
11223 value is true unless a supplied
11225 is not a defined alias.
11227 \fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...]
11230 remove the corresponding variable or function.
11233 option is given, each
11235 refers to a shell variable, and that variable is removed.
11236 Read-only variables may not be unset.
11241 refers to a shell function, and the function definition
11245 option is supplied, and \fIname\fP is a variable with the \fInameref\fP
11246 attribute, \fIname\fP will be unset rather than the variable it
11248 \fB\-n\fP has no effect if the \fB\-f\fP option is supplied.
11249 If no options are supplied, each \fIname\fP refers to a variable; if
11250 there is no variable by that name, a function with that name, if any, is
11252 Each unset variable or function is removed from the environment
11253 passed to subsequent commands.
11264 .BR BASH_SUBSHELL ,
11268 .BR COMP_WORDBREAKS ,
11272 .BR EPOCHREALTIME ,
11290 are unset, they lose their special properties, even if they are
11291 subsequently reset. The exit status is true unless a
11293 is readonly or may not be unset.
11295 \fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid ...\fP]
11296 Wait for each specified child process and return its termination status.
11300 ID or a job specification; if a job spec is given, all processes
11301 in that job's pipeline are waited for. If
11304 \fBwait\fP waits for all running background jobs and
11305 the last-executed process substitution, if its process id is the same as
11307 and the return status is zero.
11308 If the \fB\-n\fP option is supplied,
11309 \fBwait\fP waits for a single job
11310 from the list of \fIid\fPs or, if no \fIid\fPs are supplied, any job,
11311 to complete and returns its exit status.
11312 If none of the supplied arguments is a child of the shell, or if no arguments
11313 are supplied and the shell has no unwaited-for children, the exit status
11315 If the \fB\-p\fP option is supplied, the process or job identifier of the job
11316 for which the exit status is returned is assigned to the variable
11317 \fIvarname\fP named by the option argument.
11318 The variable will be unset initially, before any assignment.
11319 This is useful only when the \fB\-n\fP option is supplied.
11320 Supplying the \fB\-f\fP option, when job control is enabled,
11321 forces \fBwait\fP to wait for \fIid\fP to terminate before returning
11322 its status, instead of returning when it changes status.
11325 specifies a non-existent process or job, the return status is 127.
11326 If \fBwait\fP is interrupted by a signal, the return status will be greater
11327 than 128, as described under
11329 .ie \n(zZ=1 in \fIbash(1)\fP.
11331 Otherwise, the return status is the exit status of the last
11332 process or job waited for.
11333 .SH "SHELL COMPATIBILITY MODE"
11334 Bash-4.0 introduced the concept of a \fIshell compatibility level\fP,
11335 specified as a set of options to the shopt builtin (
11341 There is only one current
11342 compatibility level -- each option is mutually exclusive.
11343 The compatibility level is intended to allow users to select behavior
11344 from previous versions that is incompatible with newer versions
11345 while they migrate scripts to use current features and
11346 behavior. It's intended to be a temporary solution.
11348 This section does not mention behavior that is standard for a particular
11349 version (e.g., setting \fBcompat32\fP means that quoting the rhs of the regexp
11350 matching operator quotes special regexp characters in the word, which is
11351 default behavior in bash-3.2 and subsequent versions).
11353 If a user enables, say, \fBcompat32\fP, it may affect the behavior of other
11354 compatibility levels up to and including the current compatibility level.
11355 The idea is that each compatibility level controls behavior that changed
11356 in that version of \fBbash\fP,
11357 but that behavior may have been present in earlier versions.
11358 For instance, the change to use locale-based comparisons with the \fB[[\fP
11359 command came in bash-4.1, and earlier versions used ASCII-based comparisons,
11360 so enabling \fBcompat32\fP will enable ASCII-based comparisons as well.
11361 That granularity may not be sufficient for
11362 all uses, and as a result users should employ compatibility levels carefully.
11363 Read the documentation for a particular feature to find out the
11366 Bash-4.3 introduced a new shell variable:
11370 to this variable (a decimal version number like 4.2, or an integer
11371 corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the
11372 compatibility level.
11374 Starting with bash-4.4, Bash has begun deprecating older compatibility
11376 Eventually, the options will be removed in favor of
11380 Bash-5.0 is the final version for which there will be an individual shopt
11381 option for the previous version. Users should use
11384 on bash-5.0 and later versions.
11386 The following table describes the behavior changes controlled by each
11387 compatibility level setting.
11388 The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the
11389 compatibility level
11390 to \fINN\fP using one of the following mechanisms.
11391 For versions prior to bash-5.0, the compatibility level may be set using
11392 the corresponding \fBcompat\fP\fINN\fP shopt option.
11393 For bash-4.3 and later versions, the
11396 variable is preferred,
11397 and it is required for bash-5.1 and later versions.
11403 quoting the rhs of the \fB[[\fP command's regexp matching operator (=~)
11404 has no special effect
11412 interrupting a command list such as "a ; b ; c" causes the execution
11413 of the next command in the list (in bash-4.0 and later versions,
11414 the shell acts as if it received the interrupt, so
11415 interrupting one command in a list aborts the execution of the
11424 the \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not
11425 consider the current locale when comparing strings; they use ASCII
11427 Bash versions prior to bash-4.1 use ASCII collation and
11429 bash-4.1 and later use the current locale's collation sequence and
11438 in \fIposix\fP mode, \fBtime\fP may be followed by options and still be
11439 recognized as a reserved word (this is POSIX interpretation 267)
11441 in \fIposix\fP mode, the parser requires that an even number of single
11442 quotes occur in the \fIword\fP portion of a double-quoted
11443 parameter expansion and treats them specially, so that characters within
11444 the single quotes are considered quoted
11445 (this is POSIX interpretation 221)
11453 the replacement string in double-quoted pattern substitution does not
11454 undergo quote removal, as it does in versions after bash-4.2
11456 in posix mode, single quotes are considered special when expanding
11457 the \fIword\fP portion of a double-quoted parameter expansion
11458 and can be used to quote a closing brace or other special character
11459 (this is part of POSIX interpretation 221);
11460 in later versions, single quotes
11461 are not special within double-quoted word expansions
11469 the shell does not print a warning message if an attempt is made to
11470 use a quoted compound assignment as an argument to declare
11471 (e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage is
11474 word expansion errors are considered non-fatal errors that cause the
11475 current command to fail, even in posix mode
11476 (the default behavior is to make them fatal errors that cause the shell
11479 when executing a shell function, the loop state (while/until/etc.)
11480 is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break
11481 or continue loops in the calling context. Bash-4.4 and later reset
11482 the loop state to prevent this
11490 the shell sets up the values used by
11496 so they can expand to the shell's positional parameters even if extended
11497 debugging mode is not enabled
11499 a subshell inherits loops from its parent context, so \fBbreak\fP
11500 or \fBcontinue\fP will cause the subshell to exit.
11501 Bash-5.0 and later reset the loop state to prevent the exit
11503 variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP
11504 that set attributes continue to affect variables with the same
11505 name in the calling environment even if the shell is not in posix
11514 Bash-5.1 changed the way
11517 is generated to introduce slightly
11518 more randomness. If the shell compatibility level is set to 50 or
11519 lower, it reverts to the method from bash-5.0 and previous versions,
11520 so seeding the random number generator by assigning a value to
11523 will produce the same sequence as in bash-5.0
11525 If the command hash table is empty, bash versions prior to bash-5.1
11526 printed an informational message to that effect, even when producing
11527 output that can be reused as input. Bash-5.1 suppresses that message
11528 when the \fB\-l\fP option is supplied.
11536 The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP
11537 and \fB*\fP differently depending on whether the array is indexed or
11538 associative, and differently than in previous versions.
11543 .SH "RESTRICTED SHELL"
11549 is started with the name
11553 option is supplied at invocation,
11554 the shell becomes restricted.
11555 A restricted shell is used to
11556 set up an environment more controlled than the standard shell.
11557 It behaves identically to
11559 with the exception that the following are disallowed or not performed:
11561 changing directories with \fBcd\fP
11563 setting or unsetting the values of
11576 specifying command names containing
11579 specifying a filename containing a
11581 as an argument to the
11585 specifying a filename containing a slash as an argument to the
11589 specifying a filename containing a slash as an argument to the
11595 importing function definitions from the shell environment at startup
11597 parsing the value of
11600 from the shell environment at startup
11602 redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
11606 builtin command to replace the shell with another command
11608 adding or deleting builtin commands with the
11616 using the \fBenable\fP builtin command to enable disabled shell builtins
11624 turning off restricted mode with
11625 \fBset +r\fP or \fBshopt -u restricted_shell\fP.
11627 These restrictions are enforced after any startup files are read.
11629 .ie \n(zY=1 When a command that is found to be a shell script is executed,
11630 .el \{ When a command that is found to be a shell script is executed
11633 .B "COMMAND EXECUTION"
11637 turns off any restrictions in the shell spawned to execute the
11644 \fIBash Reference Manual\fP, Brian Fox and Chet Ramey
11646 \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
11648 \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
11650 \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE --
11651 http://pubs.opengroup.org/onlinepubs/9699919799/
11653 http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode
11655 \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
11657 \fIemacs\fP(1), \fIvi\fP(1)
11665 The \fBbash\fP executable
11668 The systemwide initialization file, executed for login shells
11670 .FN ~/.bash_profile
11671 The personal initialization file, executed for login shells
11674 The individual per-interactive-shell startup file
11677 The individual login shell cleanup file, executed when a login shell exits
11679 .FN ~/.bash_history
11680 The default value of \fBHISTFILE\fP, the file in which bash saves the
11684 Individual \fIreadline\fP initialization file
11687 Brian Fox, Free Software Foundation
11691 Chet Ramey, Case Western Reserve University
11693 chet.ramey@case.edu
11695 If you find a bug in
11697 you should report it. But first, you should
11698 make sure that it really is a bug, and that it appears in the latest
11701 The latest version is always available from
11702 \fIftp://ftp.gnu.org/pub/gnu/bash/\fP and
11703 \fIhttp://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz\fP.
11705 Once you have determined that a bug actually exists, use the
11707 command to submit a bug report.
11708 If you have a fix, you are encouraged to mail that as well!
11709 Suggestions and `philosophical' bug reports may be mailed
11710 to \fIbug-bash@gnu.org\fP or posted to the Usenet
11714 ALL bug reports should include:
11718 The version number of \fBbash\fR
11720 The hardware and operating system
11722 The compiler used to compile
11724 A description of the bug behaviour
11726 A short script or `recipe' which exercises the bug
11730 inserts the first three items automatically into the template
11731 it provides for filing a bug report.
11733 Comments and bug reports concerning
11734 this manual page should be directed to
11735 .IR chet.ramey@case.edu .
11737 It's too big and too slow.
11739 There are some subtle differences between
11741 and traditional versions of
11743 mostly because of the
11748 Aliases are confusing in some uses.
11750 Shell builtin commands and functions are not stoppable/restartable.
11752 Compound commands and command sequences of the form `a ; b ; c'
11753 are not handled gracefully when process suspension is attempted.
11754 When a process is stopped, the shell immediately executes the next
11755 command in the sequence.
11756 It suffices to place the sequence of commands between
11757 parentheses to force it into a subshell, which may be stopped as
11760 Array variables may not (yet) be exported.
11762 There may be only one active coprocess at a time.
projects / thirdparty / bash.git / blob