2 <TITLE>BASH(1) Manual Page</TITLE>
4 <BODY><TABLE WIDTH=100%>
6 <TH ALIGN=LEFT width=33%>BASH(1)<TH ALIGN=CENTER width=33%>2008 December 29<TH ALIGN=RIGHT width=33%>BASH(1)
9 <BR><A HREF="#index">Index</A>
30 <A NAME="lbAB"> </A>
33 bash - GNU Bourne-Again SHell
34 <A NAME="lbAC"> </A>
41 <A NAME="lbAD"> </A>
45 Bash is Copyright © 1989-2009 by the Free Software Foundation, Inc.
46 <A NAME="lbAE"> </A>
51 is an <B>sh</B>-compatible command language interpreter that
52 executes commands read from the standard input or from a file.
55 also incorporates useful features from the <I>Korn</I> and <I>C</I>
56 shells (<B>ksh</B> and <B>csh</B>).
61 is intended to be a conformant implementation of the
62 Shell and Utilities portion of the IEEE POSIX specification
63 (IEEE Standard 1003.1).
66 can be configured to be POSIX-conformant by default.
67 <A NAME="lbAF"> </A>
70 In addition to the single-character shell options documented in the
71 description of the <B>set</B> builtin command, <B>bash</B>
72 interprets the following options when it is invoked:
77 <DT><B>-c</B><I> string</I>
83 option is present, then commands are read from
86 If there are arguments after the
89 they are assigned to the positional parameters, starting with
98 option is present, the shell is
107 act as if it had been invoked as a login shell (see
108 <FONT SIZE=-1><B>INVOCATION</B>
118 option is present, the shell becomes
122 <FONT SIZE=-1><B>RESTRICTED SHELL</B>
132 option is present, or if no arguments remain after option
133 processing, then commands are read from the standard input.
134 This option allows the positional parameters to be set
135 when invoking an interactive shell.
139 A list of all double-quoted strings preceded by <B>$</B>
140 is printed on the standard output.
141 These are the strings that
142 are subject to language translation when the current locale
143 is not <B>C</B> or <B>POSIX</B>.
144 This implies the <B>-n</B> option; no commands will be executed.
145 <DT><B>[-+]O [</B><I>shopt_option</I>]
148 <I>shopt_option</I> is one of the shell options accepted by the
149 <B>shopt</B> builtin (see
150 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
154 If <I>shopt_option</I> is present, <B>-O</B> sets the value of that option;
156 If <I>shopt_option</I> is not supplied, the names and values of the shell
157 options accepted by <B>shopt</B> are printed on the standard output.
158 If the invocation option is <B>+O</B>, the output is displayed in a format
159 that may be reused as input.
166 signals the end of options and disables further option processing.
167 Any arguments after the
170 are treated as filenames and arguments. An argument of
173 is equivalent to <B>--</B>.
180 also interprets a number of multi-character options.
181 These options must appear on the command line before the
182 single-character options to be recognized.
187 <DT><B>--debugger</B>
190 Arrange for the debugger profile to be executed before the shell
192 Turns on extended debugging mode (see the description of the
199 and shell function tracing (see the description of the
200 <B>-o functrace</B> option to the
204 <DT><B>--dump-po-strings</B>
207 Equivalent to <B>-D</B>, but the output is in the GNU <I>gettext</I>
208 <B>po</B> (portable object) file format.
209 <DT><B>--dump-strings</B>
212 Equivalent to <B>-D</B>.
216 Display a usage message on standard output and exit successfully.
217 <DT><B>--init-file</B> <I>file</I><DD>
219 <DT><B>--rcfile</B> <I>file</I><DD>
221 Execute commands from
224 instead of the standard personal initialization file
225 <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>
227 if the shell is interactive (see
228 <FONT SIZE=-1><B>INVOCATION</B>
235 Equivalent to <B>-l</B>.
236 <DT><B>--noediting</B>
242 library to read command lines when the shell is interactive.
243 <DT><B>--noprofile</B>
246 Do not read either the system-wide startup file
248 <A HREF="file:/etc/profile"><I>/etc/profile</I></A>
250 or any of the personal initialization files
251 <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A>,
253 <A HREF="file:~/.bash_login"><I>~/.bash_login</I></A>,
256 <A HREF="file:~/.profile"><I>~/.profile</I></A>.
261 reads these files when it is invoked as a login shell (see
262 <FONT SIZE=-1><B>INVOCATION</B>
269 Do not read and execute the personal initialization file
270 <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>
272 if the shell is interactive.
273 This option is on by default if the shell is invoked as
279 Change the behavior of <B>bash</B> where the default operation differs
280 from the POSIX standard to match the standard (<I>posix mode</I>).
281 <DT><B>--restricted</B>
284 The shell becomes restricted (see
285 <FONT SIZE=-1><B>RESTRICTED SHELL</B>
292 Equivalent to <B>-v</B>.
296 Show version information for this instance of
299 on the standard output and exit successfully.
302 <A NAME="lbAG"> </A>
305 If arguments remain after option processing, and neither the
311 option has been supplied, the first argument is assumed to
312 be the name of a file containing shell commands.
316 is invoked in this fashion,
319 is set to the name of the file, and the positional parameters
320 are set to the remaining arguments.
323 reads and executes commands from this file, then exits.
324 <B>Bash</B>'s exit status is the exit status of the last command
325 executed in the script.
326 If no commands are executed, the exit status is 0.
327 An attempt is first made to open the file in the current directory, and,
328 if no file is found, then the shell searches the directories in
329 <FONT SIZE=-1><B>PATH</B>
333 <A NAME="lbAH"> </A>
336 A <I>login shell</I> is one whose first character of argument zero is a
339 or one started with the
345 An <I>interactive</I> shell is one started without non-option arguments
350 whose standard input and error are
351 both connected to terminals (as determined by
354 or one started with the
358 <FONT SIZE=-1><B>PS1</B>
371 allowing a shell script or a startup file to test this state.
374 The following paragraphs describe how
377 executes its startup files.
378 If any of the files exist but cannot be read,
382 Tildes are expanded in file names as described below under
383 <B>Tilde Expansion</B>
386 <FONT SIZE=-1><B>EXPANSION</B>
395 is invoked as an interactive login shell, or as a non-interactive shell
396 with the <B>--login</B> option, it first reads and
397 executes commands from the file <A HREF="file:/etc/profile"><I>/etc/profile</I></A>, if that
399 After reading that file, it looks for <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A>,
400 <A HREF="file:~/.bash_login"><I>~/.bash_login</I></A>, and <A HREF="file:~/.profile"><I>~/.profile</I></A>, in that order, and reads
401 and executes commands from the first one that exists and is readable.
405 option may be used when the shell is started to inhibit this behavior.
408 When a login shell exits,
411 reads and executes commands from the file <A HREF="file:~/.bash_logout"><I>~/.bash_logout</I></A>, if it
415 When an interactive shell that is not a login shell is started,
418 reads and executes commands from <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>, if that file exists.
419 This may be inhibited by using the
423 The <B>--rcfile</B> <I>file</I> option will force
426 to read and execute commands from <I>file</I> instead of <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>.
432 is started non-interactively, to run a shell script, for example, it
433 looks for the variable
434 <FONT SIZE=-1><B>BASH_ENV</B>
437 in the environment, expands its value if it appears there, and uses the
438 expanded value as the name of a file to read and execute.
441 behaves as if the following command were executed:
444 <TT>if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi</TT>
450 <FONT SIZE=-1><B>PATH</B>
453 variable is not used to search for the file name.
459 is invoked with the name
462 it tries to mimic the startup behavior of historical versions of
465 as closely as possible,
466 while conforming to the POSIX standard as well.
467 When invoked as an interactive login shell, or a non-interactive
468 shell with the <B>--login</B> option, it first attempts to
469 read and execute commands from
470 <A HREF="file:/etc/profile"><I>/etc/profile</I></A>
473 <A HREF="file:~/.profile"><I>~/.profile</I></A>,
479 option may be used to inhibit this behavior.
480 When invoked as an interactive shell with the name
485 looks for the variable
486 <FONT SIZE=-1><B>ENV</B>,
489 expands its value if it is defined, and uses the
490 expanded value as the name of a file to read and execute.
491 Since a shell invoked as
494 does not attempt to read and execute commands from any other startup
498 option has no effect.
499 A non-interactive shell invoked with the name
502 does not attempt to read any other startup files.
511 mode after the startup files are read.
523 command line option, it follows the POSIX standard for startup files.
524 In this mode, interactive shells expand the
525 <FONT SIZE=-1><B>ENV</B>
528 variable and commands are read and executed from the file
529 whose name is the expanded value.
530 No other startup files are read.
535 attempts to determine when it is being run with its standard input
536 connected to a a network connection, as if by the remote shell
537 daemon, usually <I>rshd</I>, or the secure shell daemon <I>sshd</I>.
541 determines it is being run in this fashion, it reads and executes
542 commands from <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>, if that file exists and is readable.
543 It will not do this if invoked as <B>sh</B>.
547 option may be used to inhibit this behavior, and the
550 option may be used to force another file to be read, but
551 <I>rshd</I> does not generally invoke the shell with those options
552 or allow them to be specified.
555 If the shell is started with the effective user (group) id not equal to the
556 real user (group) id, and the <B>-p</B> option is not supplied, no startup
557 files are read, shell functions are not inherited from the environment, the
558 <FONT SIZE=-1><B>SHELLOPTS</B>
561 variable, if it appears in the environment, is ignored,
562 and the effective user id is set to the real user id.
563 If the <B>-p</B> option is supplied at invocation, the startup behavior is
564 the same, but the effective user id is not reset.
565 <A NAME="lbAI"> </A>
570 The following definitions are used throughout the rest of this
581 A sequence of characters considered as a single unit by the shell.
591 consisting only of alphanumeric characters and underscores, and
592 beginning with an alphabetic character or an underscore. Also
596 <DT><B>metacharacter</B>
599 A character that, when unquoted, separates words. One of the following:
605 <B>| & ; ( ) < > space tab</B>
613 <DT><B>control operator</B>
616 A <I>token</I> that performs a control function. It is one of the following
621 <B>|| & && ; ;; ( ) | |& <newline></B>
627 <A NAME="lbAJ"> </A>
628 <H3>RESERVED WORDS</H3>
630 <I>Reserved words</I> are words that have a special meaning to the shell.
631 The following words are recognized as reserved when unquoted and either
632 the first word of a simple command (see
633 <FONT SIZE=-1><B>SHELL GRAMMAR</B>
636 below) or the third word of a
650 ! case do done elif else esac fi for function if in select then until while { } time [[ ]]
654 <A NAME="lbAK"> </A>
655 <H3>SHELL GRAMMAR</H3>
657 <A NAME="lbAL"> </A>
658 <H4>Simple Commands</H4>
662 A <I>simple command</I> is a sequence of optional variable assignments
663 followed by <B>blank</B>-separated words and redirections, and
664 terminated by a <I>control operator</I>. The first word
665 specifies the command to be executed, and is passed as argument zero.
666 The remaining words are passed as arguments to the invoked command.
669 The return value of a <I>simple command</I> is its exit status, or
670 128+<I>n</I> if the command is terminated by signal
673 <A NAME="lbAM"> </A>
678 A <I>pipeline</I> is a sequence of one or more commands separated by
679 one of the control operators
683 The format for a pipeline is:
687 [<B>time</B> [<B>-p</B>]] [ ! ] <I>command</I> [ [<B>|</B>|<B>|&</B>] <I>command2</I> ... ]
692 The standard output of
695 is connected via a pipe to the standard input of
698 This connection is performed before any redirections specified by the
700 <FONT SIZE=-1><B>REDIRECTION</B>
704 If <B>|&</B> is used, the standard error of <I>command</I> is connected to
705 <I>command2</I>'s standard input through the pipe; it is shorthand for
706 <B>2>&1 |</B>.
707 This implicit redirection of the standard error is performed after any
708 redirections specified by the command.
711 The return status of a pipeline is the exit status of the last
712 command, unless the <B>pipefail</B> option is enabled.
713 If <B>pipefail</B> is enabled, the pipeline's return status is the
714 value of the last (rightmost) command to exit with a non-zero status,
715 or zero if all commands exit successfully.
719 precedes a pipeline, the exit status of that pipeline is the logical
720 negation of the exit status as described above.
721 The shell waits for all commands in the pipeline to
722 terminate before returning a value.
728 reserved word precedes a pipeline, the elapsed as well as user and
729 system time consumed by its execution are reported when the pipeline
731 The <B>-p</B> option changes the output format to that specified by POSIX.
733 <FONT SIZE=-1><B>TIMEFORMAT</B>
736 variable may be set to a format string that specifies how the timing
737 information should be displayed; see the description of
738 <FONT SIZE=-1><B>TIMEFORMAT</B>
742 <B>Shell Variables</B>
747 Each command in a pipeline is executed as a separate process (i.e., in a
749 <A NAME="lbAN"> </A>
754 A <I>list</I> is a sequence of one or more pipelines separated by one
765 and optionally terminated by one of
771 <B><newline></B>.
775 Of these list operators,
781 have equal precedence, followed by
787 which have equal precedence.
790 A sequence of one or more newlines may appear in a <I>list</I> instead
791 of a semicolon to delimit commands.
794 If a command is terminated by the control operator
797 the shell executes the command in the <I>background</I>
798 in a subshell. The shell does not wait for the command to
799 finish, and the return status is 0. Commands separated by a
802 are executed sequentially; the shell waits for each
803 command to terminate in turn. The return status is the
804 exit status of the last command executed.
807 AND and OR lists are sequences of one of more pipelines separated by the
808 <B>&&</B> and <B>||</B> control operators, respectively.
809 AND and OR lists are executed with left associativity.
810 An AND list has the form
814 <I>command1</I> <B>&&</B> <I>command2</I>
821 is executed if, and only if,
824 returns an exit status of zero.
827 An OR list has the form
831 <I>command1</I> <B>||</B> <I>command2</I>
840 is executed if and only if
843 returns a non-zero exit status.
845 AND and OR lists is the exit status of the last command
846 executed in the list.
847 <A NAME="lbAO"> </A>
848 <H4>Compound Commands</H4>
852 A <I>compound command</I> is one of the following:
854 <DT>(<I>list</I>)<DD>
855 <I>list</I> is executed in a subshell environment (see
856 <FONT SIZE=-1><B>COMMAND EXECUTION ENVIRONMENT</B></FONT>
858 Variable assignments and builtin
859 commands that affect the shell's environment do not remain in effect
860 after the command completes. The return status is the exit status of
862 <DT>{ <I>list</I>; }<DD>
863 <I>list</I> is simply executed in the current shell environment.
864 <I>list</I> must be terminated with a newline or semicolon.
865 This is known as a <I>group command</I>.
866 The return status is the exit status of
868 Note that unlike the metacharacters <B>(</B> and <B>)</B>, <B>{</B> and
869 <B>}</B> are <I>reserved words</I> and must occur where a reserved
870 word is permitted to be recognized. Since they do not cause a word
871 break, they must be separated from <I>list</I> by whitespace or another
873 <DT>((<I>expression</I>))<DD>
874 The <I>expression</I> is evaluated according to the rules described
876 <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>.
879 If the value of the expression is non-zero, the return status is 0;
880 otherwise the return status is 1. This is exactly equivalent to
881 <B>let "</B><I>expression</I>".
882 <DT><B>[[</B> <I>expression</I> <B>]]</B><DD>
883 Return a status of 0 or 1 depending on the evaluation of
884 the conditional expression <I>expression</I>.
885 Expressions are composed of the primaries described below under
886 <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>.
889 Word splitting and pathname expansion are not performed on the words
890 between the <B>[[</B> and <B>]]</B>; tilde expansion, parameter and
891 variable expansion, arithmetic expansion, command substitution, process
892 substitution, and quote removal are performed.
893 Conditional operators such as <B>-f</B> must be unquoted to be recognized
898 When the <B>==</B> and <B>!=</B> operators are used, the string to the
899 right of the operator is considered a pattern and matched according
900 to the rules described below under <B>Pattern Matching</B>.
904 is enabled, the match is performed without regard to the case
905 of alphabetic characters.
906 The return value is 0 if the string matches (<B>==</B>) or does not match
907 (<B>!=</B>) the pattern, and 1 otherwise.
908 Any part of the pattern may be quoted to force it to be matched as a
913 An additional binary operator, <B>=~</B>, is available, with the same
914 precedence as <B>==</B> and <B>!=</B>.
915 When it is used, the string to the right of the operator is considered
916 an extended regular expression and matched accordingly (as in <I>regex</I>(3)).
917 The return value is 0 if the string matches
918 the pattern, and 1 otherwise.
919 If the regular expression is syntactically incorrect, the conditional
920 expression's return value is 2.
924 is enabled, the match is performed without regard to the case
925 of alphabetic characters.
926 Any part of the pattern may be quoted to force it to be matched as a
928 Substrings matched by parenthesized subexpressions within the regular
929 expression are saved in the array variable <B>BASH_REMATCH</B>.
930 The element of <B>BASH_REMATCH</B> with index 0 is the portion of the string
931 matching the entire regular expression.
932 The element of <B>BASH_REMATCH</B> with index <I>n</I> is the portion of the
933 string matching the <I>n</I>th parenthesized subexpression.
937 Expressions may be combined using the following operators, listed
938 in decreasing order of precedence:
945 <DT><B>( </B><I>expression</I> )
948 Returns the value of <I>expression</I>.
949 This may be used to override the normal precedence of operators.
950 <DT><B>! </B><I>expression</I>
957 <DT><I>expression1</I> <B>&&</B> <I>expression2</I><DD>
965 <DT><I>expression1</I> <B>||</B> <I>expression2</I>
979 The <B>&&</B> and
982 operators do not evaluate <I>expression2</I> if the value of
983 <I>expression1</I> is sufficient to determine the return value of
984 the entire conditional expression.
987 <DT><B>for</B> <I>name</I> [ <B>in</B> <I>word</I> ] ; <B>do</B> <I>list</I> ; <B>done</B><DD>
988 The list of words following <B>in</B> is expanded, generating a list
990 The variable <I>name</I> is set to each element of this list
991 in turn, and <I>list</I> is executed each time.
992 If the <B>in</B> <I>word</I> is omitted, the <B>for</B> command executes
993 <I>list</I> once for each positional parameter that is set (see
994 <FONT SIZE=-1><B>PARAMETERS</B>
998 The return status is the exit status of the last command that executes.
999 If the expansion of the items following <B>in</B> results in an empty
1000 list, no commands are executed, and the return status is 0.
1001 <DT><B>for</B> (( <I>expr1</I> ; <I>expr2</I> ; <I>expr3</I> )) ; <B>do</B> <I>list</I> ; <B>done</B><DD>
1002 First, the arithmetic expression <I>expr1</I> is evaluated according
1003 to the rules described below under
1004 <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>.
1007 The arithmetic expression <I>expr2</I> is then evaluated repeatedly
1008 until it evaluates to zero.
1009 Each time <I>expr2</I> evaluates to a non-zero value, <I>list</I> is
1010 executed and the arithmetic expression <I>expr3</I> is evaluated.
1011 If any expression is omitted, it behaves as if it evaluates to 1.
1012 The return value is the exit status of the last command in <I>list</I>
1013 that is executed, or false if any of the expressions is invalid.
1014 <DT><B>select</B> <I>name</I> [ <B>in</B> <I>word</I> ] ; <B>do</B> <I>list</I> ; <B>done</B><DD>
1015 The list of words following <B>in</B> is expanded, generating a list
1016 of items. The set of expanded words is printed on the standard
1017 error, each preceded by a number. If the <B>in</B>
1018 <I>word</I> is omitted, the positional parameters are printed (see
1019 <FONT SIZE=-1><B>PARAMETERS</B>
1025 prompt is then displayed and a line read from the standard input.
1026 If the line consists of a number corresponding to one of
1027 the displayed words, then the value of
1030 is set to that word. If the line is empty, the words and prompt
1031 are displayed again. If EOF is read, the command completes. Any
1032 other value read causes
1035 to be set to null. The line read is saved in the variable
1041 is executed after each selection until a
1044 command is executed.
1048 is the exit status of the last command executed in
1051 or zero if no commands were executed.
1052 <DT><B>case</B> <I>word</I> <B>in</B> [ [(] <I>pattern</I> [ <B>|</B> <I>pattern</I> ]
1054 A <B>case</B> command first expands <I>word</I>, and tries to match
1055 it against each <I>pattern</I> in turn, using the same matching rules
1056 as for pathname expansion (see
1057 <B>Pathname Expansion</B>
1060 The <I>word</I> is expanded using tilde
1061 expansion, parameter and variable expansion, arithmetic substitution,
1062 command substitution, process substitution and quote removal.
1063 Each <I>pattern</I> examined is expanded using tilde
1064 expansion, parameter and variable expansion, arithmetic substitution,
1065 command substitution, and process substitution.
1069 is enabled, the match is performed without regard to the case
1070 of alphabetic characters.
1071 When a match is found, the corresponding <I>list</I> is executed.
1072 If the <B>;;</B> operator is used, no subsequent matches are attempted after
1073 the first pattern match.
1074 Using <B>;&</B> in place of <B>;;</B> causes execution to continue with
1075 the <I>list</I> associated with the next set of patterns.
1076 Using <B>;;&</B> in place of <B>;;</B> causes the shell to test the next
1077 pattern list in the statement, if any, and execute any associated <I>list</I>
1078 on a successful match.
1079 The exit status is zero if no
1080 pattern matches. Otherwise, it is the exit status of the
1081 last command executed in <I>list</I>.
1082 <DT><B>if</B> <I>list</I>; <B>then</B> <I>list;</I> [ <B>elif</B> <I>list</I>; <B>then</B> <I>list</I>; ] ... [ <B>else</B> <I>list</I>; ] <B>fi</B><DD>
1088 is executed. If its exit status is zero, the
1089 <B>then</B> <I>list</I> is executed. Otherwise, each <B>elif</B>
1090 <I>list</I> is executed in turn, and if its exit status is zero,
1091 the corresponding <B>then</B> <I>list</I> is executed and the
1092 command completes. Otherwise, the <B>else</B> <I>list</I> is
1093 executed, if present. The exit status is the exit status of the
1094 last command executed, or zero if no condition tested true.
1095 <DT><B>while</B> <I>list</I>; <B>do</B> <I>list</I>; <B>done</B><DD>
1097 <DT><B>until</B> <I>list</I>; <B>do</B> <I>list</I>; <B>done</B><DD>
1099 The <B>while</B> command continuously executes the <B>do</B>
1100 <I>list</I> as long as the last command in <I>list</I> returns
1101 an exit status of zero. The <B>until</B> command is identical
1102 to the <B>while</B> command, except that the test is negated;
1108 is executed as long as the last command in
1111 returns a non-zero exit status.
1112 The exit status of the <B>while</B> and <B>until</B> commands
1114 of the last <B>do</B> <I>list</I> command executed, or zero if
1117 <A NAME="lbAP"> </A>
1118 <H4>Coprocesses</H4>
1122 A <I>coprocess</I> is a shell command preceded by the <B>coproc</B> reserved
1124 A coprocess is executed asynchronously in a subshell, as if the command
1125 had been terminated with the <B>&</B> control operator, with a two-way pipe
1126 established between the executing shell and the coprocess.
1129 The format for a coprocess is:
1130 <DL COMPACT><DT><DD>
1133 <B>coproc</B> [<I>NAME</I>] <I>command</I> [<I>redirections</I>]
1138 This creates a coprocess named <I>NAME</I>.
1139 If <I>NAME</I> is not supplied, the default name is <I>COPROC</I>.
1140 <I>NAME</I> must not be supplied if <I>command</I> is a <I>simple
1141 command</I> (see above); otherwise, it is interpreted as the first word
1142 of the simple command.
1143 When the coproc is executed, the shell creates an array variable (see
1146 below) named <I>NAME</I> in the context of the executing shell.
1147 The standard output of
1150 is connected via a pipe to a file descriptor in the executing shell,
1151 and that file descriptor is assigned to <I>NAME</I>[0].
1152 The standard input of
1155 is connected via a pipe to a file descriptor in the executing shell,
1156 and that file descriptor is assigned to <I>NAME</I>[1].
1157 This pipe is established before any redirections specified by the
1159 <FONT SIZE=-1><B>REDIRECTION</B>
1163 The file descriptors can be utilized as arguments to shell commands
1164 and redirections using standard word expansions.
1165 The process id of the shell spawned to execute the coprocess is
1166 available as the value of the variable <I>NAME</I>_PID.
1168 builtin command may be used to wait for the coprocess to terminate.
1171 The return status of a coprocess is the exit status of <I>command</I>.
1172 <A NAME="lbAQ"> </A>
1173 <H4>Shell Function Definitions</H4>
1177 A shell function is an object that is called like a simple command and
1178 executes a compound command with a new set of positional parameters.
1179 Shell functions are declared as follows:
1181 <DT>[ <B>function</B> ] <I>name</I> () <I>compound-command</I> [<I>redirection</I>]<DD>
1182 This defines a function named <I>name</I>.
1183 The reserved word <B>function</B> is optional.
1184 If the <B>function</B> reserved word is supplied, the parentheses are optional.
1185 The <I>body</I> of the function is the compound command
1186 <I>compound-command </I>
1188 (see <B>Compound Commands</B> above).
1189 That command is usually a <I>list</I> of commands between { and }, but
1190 may be any command listed under <B>Compound Commands</B> above.
1191 <I>compound-command</I> is executed whenever <I>name</I> is specified as the
1192 name of a simple command.
1193 Any redirections (see
1194 <FONT SIZE=-1><B>REDIRECTION</B>
1197 below) specified when a function is defined are performed
1198 when the function is executed.
1199 The exit status of a function definition is zero unless a syntax error
1200 occurs or a readonly function with the same name already exists.
1201 When executed, the exit status of a function is the exit status of the
1202 last command executed in the body. (See
1203 <FONT SIZE=-1><B>FUNCTIONS</B>
1208 <A NAME="lbAR"> </A>
1211 In a non-interactive shell, or an interactive shell in which the
1212 <B>interactive_comments</B>
1217 builtin is enabled (see
1218 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
1221 below), a word beginning with
1224 causes that word and all remaining characters on that line to
1225 be ignored. An interactive shell without the
1226 <B>interactive_comments</B>
1228 option enabled does not allow comments. The
1229 <B>interactive_comments</B>
1231 option is on by default in interactive shells.
1232 <A NAME="lbAS"> </A>
1235 <I>Quoting</I> is used to remove the special meaning of certain
1236 characters or words to the shell. Quoting can be used to
1237 disable special treatment for special characters, to prevent
1238 reserved words from being recognized as such, and to prevent
1239 parameter expansion.
1242 Each of the <I>metacharacters</I> listed above under
1243 <FONT SIZE=-1><B>DEFINITIONS</B>
1246 has special meaning to the shell and must be quoted if it is to
1250 When the command history expansion facilities are being used
1252 <FONT SIZE=-1><B>HISTORY EXPANSION</B>
1256 <I>history expansion</I> character, usually <B>!</B>, must be quoted
1257 to prevent history expansion.
1260 There are three quoting mechanisms: the
1261 <I>escape character</I>,
1263 single quotes, and double quotes.
1266 A non-quoted backslash (<B>\</B>) is the
1267 <I>escape character</I>.
1269 It preserves the literal value of the next character that follows,
1270 with the exception of <newline>. If a <B>\</B><newline> pair
1271 appears, and the backslash is not itself quoted, the <B>\</B><newline>
1272 is treated as a line continuation (that is, it is removed from the
1273 input stream and effectively ignored).
1276 Enclosing characters in single quotes preserves the literal value
1277 of each character within the quotes. A single quote may not occur
1278 between single quotes, even when preceded by a backslash.
1281 Enclosing characters in double quotes preserves the literal value
1282 of all characters within the quotes, with the exception of
1289 and, when history expansion is enabled,
1298 retain their special meaning within double quotes. The backslash
1299 retains its special meaning only when followed by one of the following
1309 <B><newline></B>.
1311 A double quote may be quoted within double quotes by preceding it with
1313 If enabled, history expansion will be performed unless an
1316 appearing in double quotes is escaped using a backslash.
1317 The backslash preceding the
1323 The special parameters
1329 have special meaning when in double
1331 <FONT SIZE=-1><B>PARAMETERS</B>
1337 Words of the form <B>$</B>aq<I>string</I>aq are treated specially. The
1338 word expands to <I>string</I>, with backslash-escaped characters replaced
1339 as specified by the ANSI C standard. Backslash escape sequences, if
1340 present, are decoded as follows:
1341 <DL COMPACT><DT><DD>
1384 <DT><B>\</B><I>nnn</I>
1387 the eight-bit character whose value is the octal value <I>nnn</I>
1388 (one to three digits)
1389 <DT><B>\x</B><I>HH</I>
1392 the eight-bit character whose value is the hexadecimal value <I>HH</I>
1393 (one or two hex digits)
1394 <DT><B>\c</B><I>x</I>
1397 a control-<I>x</I> character
1403 The expanded result is single-quoted, as if the dollar sign had
1407 A double-quoted string preceded by a dollar sign (<B>$</B>) will cause
1408 the string to be translated according to the current locale.
1409 If the current locale is <B>C</B> or <B>POSIX</B>, the dollar sign
1411 If the string is translated and replaced, the replacement is
1413 <A NAME="lbAT"> </A>
1419 is an entity that stores values.
1423 a number, or one of the special characters listed below under
1424 <B>Special Parameters</B>.
1429 is a parameter denoted by a
1432 A variable has a <I>value</I> and zero or more <I>attributes</I>.
1433 Attributes are assigned using the
1436 builtin command (see
1440 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>).
1445 A parameter is set if it has been assigned a value. The null string is
1446 a valid value. Once a variable is set, it may be unset only by using
1450 builtin command (see
1451 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
1460 may be assigned to by a statement of the form
1461 <DL COMPACT><DT><DD>
1464 <I>name</I>=[<I>value</I>]
1472 is not given, the variable is assigned the null string. All
1475 undergo tilde expansion, parameter and variable expansion,
1476 command substitution, arithmetic expansion, and quote
1478 <FONT SIZE=-1><B>EXPANSION</B>
1481 below). If the variable has its
1487 is evaluated as an arithmetic expression even if the $((...)) expansion is
1489 <B>Arithmetic Expansion</B>
1492 Word splitting is not performed, with the exception
1493 of <B>"$@"</B> as explained below under
1494 <B>Special Parameters</B>.
1496 Pathname expansion is not performed.
1497 Assignment statements may also appear as arguments to the
1514 In the context where an assignment statement is assigning a value
1515 to a shell variable or array index, the += operator can be used to
1516 append to or add to the variable's previous value.
1517 When += is applied to a variable for which the integer attribute has been
1518 set, <I>value</I> is evaluated as an arithmetic expression and added to the
1519 variable's current value, which is also evaluated.
1520 When += is applied to an array variable using compound assignment (see
1524 variable's value is not unset (as it is when using =), and new values are
1525 appended to the array beginning at one greater than the array's maximum index
1526 (for indexed arrays) or added as additional key-value pairs in an
1528 When applied to a string-valued variable, <I>value</I> is expanded and
1529 appended to the variable's value.
1530 <A NAME="lbAU"> </A>
1531 <H4>Positional Parameters</H4>
1536 <I>positional parameter</I>
1538 is a parameter denoted by one or more
1539 digits, other than the single digit 0. Positional parameters are
1540 assigned from the shell's arguments when it is invoked,
1541 and may be reassigned using the
1544 builtin command. Positional parameters may not be assigned to
1545 with assignment statements. The positional parameters are
1546 temporarily replaced when a shell function is executed (see
1547 <FONT SIZE=-1><B>FUNCTIONS</B>
1553 When a positional parameter consisting of more than a single
1554 digit is expanded, it must be enclosed in braces (see
1555 <FONT SIZE=-1><B>EXPANSION</B>
1559 <A NAME="lbAV"> </A>
1560 <H4>Special Parameters</H4>
1564 The shell treats several parameters specially. These parameters may
1565 only be referenced; assignment to them is not allowed.
1571 Expands to the positional parameters, starting from one. When the
1572 expansion occurs within double quotes, it expands to a single word
1573 with the value of each parameter separated by the first character
1575 <FONT SIZE=-1><B>IFS</B>
1578 special variable. That is, "<B>$*</B>" is equivalent
1579 to "<B>$1</B><I>c</I><B>$2</B><I>c</I><B>...</B>", where
1582 is the first character of the value of the
1583 <FONT SIZE=-1><B>IFS</B>
1587 <FONT SIZE=-1><B>IFS</B>
1590 is unset, the parameters are separated by spaces.
1592 <FONT SIZE=-1><B>IFS</B>
1595 is null, the parameters are joined without intervening separators.
1599 Expands to the positional parameters, starting from one. When the
1600 expansion occurs within double quotes, each parameter expands to a
1601 separate word. That is, "<B>$@</B>" is equivalent to
1602 "<B>$1</B>" "<B>$2</B>" ...
1603 If the double-quoted expansion occurs within a word, the expansion of
1604 the first parameter is joined with the beginning part of the original
1605 word, and the expansion of the last parameter is joined with the last
1606 part of the original word.
1607 When there are no positional parameters, "<B>$@</B>" and
1610 expand to nothing (i.e., they are removed).
1614 Expands to the number of positional parameters in decimal.
1618 Expands to the exit status of the most recently executed foreground
1623 Expands to the current option flags as specified upon invocation,
1627 builtin command, or those set by the shell itself
1635 Expands to the process ID of the shell. In a () subshell, it
1636 expands to the process ID of the current shell, not the
1641 Expands to the process ID of the most recently executed background
1642 (asynchronous) command.
1646 Expands to the name of the shell or shell script. This is set at
1647 shell initialization. If
1650 is invoked with a file of commands,
1653 is set to the name of that file. If
1662 is set to the first argument after the string to be
1663 executed, if one is present. Otherwise, it is set
1664 to the file name used to invoke
1667 as given by argument zero.
1671 At shell startup, set to the absolute pathname used to invoke the
1672 shell or shell script being executed as passed in the environment
1674 Subsequently, expands to the last argument to the previous command,
1676 Also set to the full pathname used to invoke each command executed
1677 and placed in the environment exported to that command.
1678 When checking mail, this parameter holds the name of the mail file
1679 currently being checked.
1682 <A NAME="lbAW"> </A>
1683 <H4>Shell Variables</H4>
1687 The following variables are set by the shell:
1695 Expands to the full file name used to invoke this instance of
1701 Expands to the process id of the current <B>bash</B> process.
1702 This differs from <B>$$</B> under certain circumstances, such as subshells
1703 that do not require <B>bash</B> to be re-initialized.
1704 <DT><B>BASH_ALIASES</B>
1707 An associative array variable whose members correspond to the internal
1708 list of aliases as maintained by the <B>alias</B> builtin
1709 Elements added to this array appear in the alias list; unsetting array
1710 elements cause aliases to be removed from the alias list.
1711 <DT><B>BASH_ARGC</B>
1714 An array variable whose values are the number of parameters in each
1715 frame of the current <B>bash</B> execution call stack.
1717 parameters to the current subroutine (shell function or script executed
1718 with <B>.</B> or <B>source</B>) is at the top of the stack.
1719 When a subroutine is executed, the number of parameters passed is pushed onto
1721 The shell sets <B>BASH_ARGC</B> only when in extended debugging mode
1722 (see the description of the
1729 <DT><B>BASH_ARGV</B>
1732 An array variable containing all of the parameters in the current <B>bash</B>
1733 execution call stack. The final parameter of the last subroutine call
1734 is at the top of the stack; the first parameter of the initial call is
1735 at the bottom. When a subroutine is executed, the parameters supplied
1736 are pushed onto <B>BASH_ARGV</B>.
1737 The shell sets <B>BASH_ARGV</B> only when in extended debugging mode
1738 (see the description of the
1745 <DT><B>BASH_CMDS</B>
1748 An associative array variable whose members correspond to the internal
1749 hash table of commands as maintained by the <B>hash</B> builtin.
1750 Elements added to this array appear in the hash table; unsetting array
1751 elements cause commands to be removed from the hash table.
1752 <DT><B>BASH_COMMAND</B>
1755 The command currently being executed or about to be executed, unless the
1756 shell is executing a command as the result of a trap,
1757 in which case it is the command executing at the time of the trap.
1758 <DT><B>BASH_EXECUTION_STRING</B>
1761 The command argument to the <B>-c</B> invocation option.
1762 <DT><B>BASH_LINENO</B>
1765 An array variable whose members are the line numbers in source files
1766 corresponding to each member of <B>FUNCNAME</B>.
1767 <B>${BASH_LINENO[</B><I>$i</I><B>]}</B> is the line number in the source
1768 file where <B>${FUNCNAME[</B><I>$i</I><B>]}</B> was called
1769 (or <B>${BASH_LINENO[</B><I>$i-1</I><B>]}</B> if referenced within another
1771 The corresponding source file name is <B>${BASH_SOURCE[</B><I>$i</I><B>]}.
1772 Use LINENO</B> to obtain the current line number.
1773 <DT><B>BASH_REMATCH</B>
1776 An array variable whose members are assigned by the <B>=~</B> binary
1777 operator to the <B>[[</B> conditional command.
1778 The element with index 0 is the portion of the string
1779 matching the entire regular expression.
1780 The element with index <I>n</I> is the portion of the
1781 string matching the <I>n</I>th parenthesized subexpression.
1782 This variable is read-only.
1783 <DT><B>BASH_SOURCE</B>
1786 An array variable whose members are the source filenames corresponding
1787 to the elements in the <B>FUNCNAME</B> array variable.
1788 <DT><B>BASH_SUBSHELL</B>
1791 Incremented by one each time a subshell or subshell environment is spawned.
1792 The initial value is 0.
1793 <DT><B>BASH_VERSINFO</B>
1796 A readonly array variable whose members hold version information for
1800 The values assigned to the array members are as follows:
1802 <DL COMPACT><DT><DD>
1805 <DT><B>BASH_VERSINFO[</B>0]
1808 The major version number (the <I>release</I>).
1809 <DT><B>BASH_VERSINFO[</B>1]
1812 The minor version number (the <I>version</I>).
1813 <DT><B>BASH_VERSINFO[</B>2]
1817 <DT><B>BASH_VERSINFO[</B>3]
1821 <DT><B>BASH_VERSINFO[</B>4]
1824 The release status (e.g., <I>beta1</I>).
1825 <DT><B>BASH_VERSINFO[</B>5]
1828 The value of <B>MACHTYPE</B>.
1832 <DT><B>BASH_VERSION</B>
1835 Expands to a string describing the version of this instance of
1838 <DT><B>COMP_CWORD</B>
1841 An index into <B>${COMP_WORDS}</B> of the word containing the current
1843 This variable is available only in shell functions invoked by the
1844 programmable completion facilities (see <B>Programmable Completion</B>
1849 The key (or final key of a key sequence) used to invoke the current
1850 completion function.
1851 <DT><B>COMP_LINE</B>
1854 The current command line.
1855 This variable is available only in shell functions and external
1856 commands invoked by the
1857 programmable completion facilities (see <B>Programmable Completion</B>
1859 <DT><B>COMP_POINT</B>
1862 The index of the current cursor position relative to the beginning of
1863 the current command.
1864 If the current cursor position is at the end of the current command,
1865 the value of this variable is equal to <B>${#COMP_LINE}</B>.
1866 This variable is available only in shell functions and external
1867 commands invoked by the
1868 programmable completion facilities (see <B>Programmable Completion</B>
1870 <DT><B>COMP_TYPE</B>
1873 Set to an integer value corresponding to the type of completion attempted
1874 that caused a completion function to be called:
1875 <I>TAB</I>, for normal completion,
1876 <I>?</I>, for listing completions after successive tabs,
1877 <I>!</I>, for listing alternatives on partial word completion,
1878 <I>@</I>, to list completions if the word is not unmodified,
1880 <I>%</I>, for menu completion.
1881 This variable is available only in shell functions and external
1882 commands invoked by the
1883 programmable completion facilities (see <B>Programmable Completion</B>
1885 <DT><B>COMP_WORDBREAKS</B>
1888 The set of characters that the Readline library treats as word
1889 separators when performing word completion.
1891 <FONT SIZE=-1><B>COMP_WORDBREAKS</B>
1894 is unset, it loses its special properties, even if it is
1896 <DT><B>COMP_WORDS</B>
1899 An array variable (see <B>Arrays</B> below) consisting of the individual
1900 words in the current command line.
1901 The words are split on shell metacharacters as the shell parser would
1903 This variable is available only in shell functions invoked by the
1904 programmable completion facilities (see <B>Programmable Completion</B>
1909 An array variable (see
1912 below) containing the current contents of the directory stack.
1913 Directories appear in the stack in the order they are displayed by the
1917 Assigning to members of this array variable may be used to modify
1918 directories already in the stack, but the
1924 builtins must be used to add and remove directories.
1925 Assignment to this variable will not change the current directory.
1927 <FONT SIZE=-1><B>DIRSTACK</B>
1930 is unset, it loses its special properties, even if it is
1935 Expands to the effective user ID of the current user, initialized at
1936 shell startup. This variable is readonly.
1940 An array variable containing the names of all shell functions
1941 currently in the execution call stack.
1942 The element with index 0 is the name of any currently-executing
1944 The bottom-most element is
1945 <TT>"main"</TT>.
1947 This variable exists only when a shell function is executing.
1949 <FONT SIZE=-1><B>FUNCNAME</B>
1952 have no effect and return an error status.
1954 <FONT SIZE=-1><B>FUNCNAME</B>
1957 is unset, it loses its special properties, even if it is
1962 An array variable containing the list of groups of which the current
1965 <FONT SIZE=-1><B>GROUPS</B>
1968 have no effect and return an error status.
1970 <FONT SIZE=-1><B>GROUPS</B>
1973 is unset, it loses its special properties, even if it is
1978 The history number, or index in the history list, of the current
1981 <FONT SIZE=-1><B>HISTCMD</B>
1984 is unset, it loses its special properties, even if it is
1989 Automatically set to the name of the current host.
1993 Automatically set to a string that uniquely
1994 describes the type of machine on which
1998 The default is system-dependent.
2002 Each time this parameter is referenced, the shell substitutes
2003 a decimal number representing the current sequential line number
2004 (starting with 1) within a script or function. When not in a
2005 script or function, the value substituted is not guaranteed to
2008 <FONT SIZE=-1><B>LINENO</B>
2011 is unset, it loses its special properties, even if it is
2016 Automatically set to a string that fully describes the system
2020 is executing, in the standard GNU <I>cpu-company-system</I> format.
2021 The default is system-dependent.
2025 The previous working directory as set by the
2032 The value of the last option argument processed by the
2035 builtin command (see
2036 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
2043 The index of the next argument to be processed by the
2046 builtin command (see
2047 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
2054 Automatically set to a string that
2055 describes the operating system on which
2059 The default is system-dependent.
2060 <DT><B>PIPESTATUS</B>
2063 An array variable (see
2066 below) containing a list of exit status values from the processes
2067 in the most-recently-executed foreground pipeline (which may
2068 contain only a single command).
2072 The process ID of the shell's parent. This variable is readonly.
2076 The current working directory as set by the
2083 Each time this parameter is referenced, a random integer between
2085 generated. The sequence of random numbers may be initialized by assigning
2087 <FONT SIZE=-1><B>RANDOM</B>.
2091 <FONT SIZE=-1><B>RANDOM</B>
2094 is unset, it loses its special properties, even if it is
2099 Set to the line of input read by the
2102 builtin command when no arguments are supplied.
2106 Each time this parameter is
2107 referenced, the number of seconds since shell invocation is returned. If a
2108 value is assigned to
2109 <FONT SIZE=-1><B>SECONDS</B>,
2112 the value returned upon subsequent
2114 the number of seconds since the assignment plus the value assigned.
2116 <FONT SIZE=-1><B>SECONDS</B>
2119 is unset, it loses its special properties, even if it is
2121 <DT><B>SHELLOPTS</B>
2124 A colon-separated list of enabled shell options. Each word in
2125 the list is a valid argument for the
2131 builtin command (see
2132 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
2135 below). The options appearing in
2136 <FONT SIZE=-1><B>SHELLOPTS</B>
2139 are those reported as
2143 If this variable is in the environment when
2146 starts up, each shell option in the list will be enabled before
2147 reading any startup files.
2148 This variable is read-only.
2152 Incremented by one each time an instance of
2159 Expands to the user ID of the current user, initialized at shell startup.
2160 This variable is readonly.
2165 The following variables are used by the shell. In some cases,
2168 assigns a default value to a variable; these cases are noted
2177 If this parameter is set when <B>bash</B> is executing a shell script,
2178 its value is interpreted as a filename containing commands to
2179 initialize the shell, as in
2180 <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>.
2183 <FONT SIZE=-1><B>BASH_ENV</B>
2186 is subjected to parameter expansion, command substitution, and arithmetic
2187 expansion before being interpreted as a file name.
2188 <FONT SIZE=-1><B>PATH</B>
2191 is not used to search for the resultant file name.
2195 The search path for the
2199 This is a colon-separated list of directories in which the shell looks
2200 for destination directories specified by the
2205 <TT>".:~:/usr"</TT>.
2210 Used by the <B>select</B> builtin command to determine the terminal width
2211 when printing selection lists. Automatically set upon receipt of a SIGWINCH.
2212 <DT><B>COMPREPLY</B>
2215 An array variable from which <B>bash</B> reads the possible completions
2216 generated by a shell function invoked by the programmable completion
2217 facility (see <B>Programmable Completion</B> below).
2221 If <B>bash</B> finds this variable in the environment when the shell starts
2225 it assumes that the shell is running in an emacs shell buffer and disables
2230 The default editor for the
2237 A colon-separated list of suffixes to ignore when performing
2238 filename completion (see
2239 <FONT SIZE=-1><B>READLINE</B>
2243 A filename whose suffix matches one of the entries in
2244 <FONT SIZE=-1><B>FIGNORE</B>
2247 is excluded from the list of matched filenames.
2249 <TT>".o:~"</TT>.
2251 <DT><B>GLOBIGNORE</B>
2254 A colon-separated list of patterns defining the set of filenames to
2255 be ignored by pathname expansion.
2256 If a filename matched by a pathname expansion pattern also matches one
2258 <FONT SIZE=-1><B>GLOBIGNORE</B>,
2261 it is removed from the list of matches.
2262 <DT><B>HISTCONTROL</B>
2265 A colon-separated list of values controlling how commands are saved on
2267 If the list of values includes
2270 lines which begin with a
2273 character are not saved in the history list.
2277 causes lines matching the previous history entry to not be saved.
2281 is shorthand for <I>ignorespace</I> and <I>ignoredups</I>.
2285 causes all previous lines matching the current line to be removed from
2286 the history list before that line is saved.
2287 Any value not in the above list is ignored.
2288 If <B>HISTCONTROL</B> is unset, or does not include a valid value,
2289 all lines read by the shell parser are saved on the history list,
2290 subject to the value of
2293 The second and subsequent lines of a multi-line compound command are
2294 not tested, and are added to the history regardless of the value of
2300 The name of the file in which command history is saved (see
2301 <FONT SIZE=-1><B>HISTORY</B>
2304 below). The default value is <A HREF="file:~/.bash_history"><I>~/.bash_history</I></A>. If unset, the
2305 command history is not saved when an interactive shell exits.
2306 <DT><B>HISTFILESIZE</B>
2309 The maximum number of lines contained in the history file. When this
2310 variable is assigned a value, the history file is truncated, if
2311 necessary, by removing the oldest entries,
2312 to contain no more than that number of lines. The default
2313 value is 500. The history file is also truncated to this size after
2314 writing it when an interactive shell exits.
2315 <DT><B>HISTIGNORE</B>
2318 A colon-separated list of patterns used to decide which command lines
2319 should be saved on the history list. Each pattern is anchored at the
2320 beginning of the line and must match the complete line (no implicit
2321 `<B>*</B>' is appended). Each pattern is tested against the line
2322 after the checks specified by
2326 In addition to the normal shell pattern matching characters, `<B>&</B>'
2327 matches the previous history line. `<B>&</B>' may be escaped using a
2328 backslash; the backslash is removed before attempting a match.
2329 The second and subsequent lines of a multi-line compound command are
2330 not tested, and are added to the history regardless of the value of
2336 The number of commands to remember in the command history (see
2337 <FONT SIZE=-1><B>HISTORY</B>
2340 below). The default value is 500.
2341 <DT><B>HISTTIMEFORMAT</B>
2344 If this variable is set and not null, its value is used as a format string
2345 for <I>strftime</I>(3) to print the time stamp associated with each history
2346 entry displayed by the <B>history</B> builtin.
2347 If this variable is set, time stamps are written to the history file so
2348 they may be preserved across shell sessions.
2349 This uses the history comment character to distinguish timestamps from
2350 other history lines.
2354 The home directory of the current user; the default argument for the
2355 <B>cd</B> builtin command.
2356 The value of this variable is also used when performing tilde expansion.
2360 Contains the name of a file in the same format as
2364 that should be read when the shell needs to complete a
2366 The list of possible hostname completions may be changed while the
2368 the next time hostname completion is attempted after the
2372 adds the contents of the new file to the existing list.
2374 <FONT SIZE=-1><B>HOSTFILE</B>
2377 is set, but has no value, <B>bash</B> attempts to read
2381 to obtain the list of possible hostname completions.
2383 <FONT SIZE=-1><B>HOSTFILE</B>
2386 is unset, the hostname list is cleared.
2391 <I>Internal Field Separator</I>
2394 for word splitting after expansion and to
2395 split lines into words with the
2398 builtin command. The default value is
2399 ``<space><tab><newline>''.
2400 <DT><B>IGNOREEOF</B>
2404 action of an interactive shell on receipt of an
2405 <FONT SIZE=-1><B>EOF</B>
2408 character as the sole input. If set, the value is the number of
2410 <FONT SIZE=-1><B>EOF</B>
2413 characters which must be
2414 typed as the first characters on an input line before
2417 exits. If the variable exists but does not have a numeric value, or
2418 has no value, the default value is 10. If it does not exist,
2419 <FONT SIZE=-1><B>EOF</B>
2422 signifies the end of input to the shell.
2426 The filename for the
2429 startup file, overriding the default of
2431 <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A>
2434 <FONT SIZE=-1><B>READLINE</B>
2441 Used to determine the locale category for any category not specifically
2442 selected with a variable starting with <B>LC_</B>.
2446 This variable overrides the value of <B>LANG</B> and any other
2447 <B>LC_</B> variable specifying a locale category.
2448 <DT><B>LC_COLLATE</B>
2451 This variable determines the collation order used when sorting the
2452 results of pathname expansion, and determines the behavior of range
2453 expressions, equivalence classes, and collating sequences within
2454 pathname expansion and pattern matching.
2458 This variable determines the interpretation of characters and the
2459 behavior of character classes within pathname expansion and pattern
2461 <DT><B>LC_MESSAGES</B>
2464 This variable determines the locale used to translate double-quoted
2465 strings preceded by a <B>$</B>.
2466 <DT><B>LC_NUMERIC</B>
2469 This variable determines the locale category used for number formatting.
2473 Used by the <B>select</B> builtin command to determine the column length
2474 for printing selection lists. Automatically set upon receipt of a SIGWINCH.
2478 If this parameter is set to a file name and the
2479 <FONT SIZE=-1><B>MAILPATH</B>
2482 variable is not set,
2485 informs the user of the arrival of mail in the specified file.
2486 <DT><B>MAILCHECK</B>
2493 checks for mail. The default is 60 seconds. When it is time to check
2494 for mail, the shell does so before displaying the primary prompt.
2495 If this variable is unset, or set to a value that is not a number
2496 greater than or equal to zero, the shell disables mail checking.
2500 A colon-separated list of file names to be checked for mail.
2501 The message to be printed when mail arrives in a particular file
2502 may be specified by separating the file name from the message with a `?'.
2503 When used in the text of the message, <B>$_</B> expands to the name of
2504 the current mailfile.
2506 <DL COMPACT><DT><DD>
2509 <B>MAILPATH</B>=aq/var/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"aq
2514 supplies a default value for this variable, but the location of the user
2515 mail files that it uses is system dependent (e.g., /var/mail/<B>$USER</B>).
2521 If set to the value 1,
2524 displays error messages generated by the
2527 builtin command (see
2528 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
2532 <FONT SIZE=-1><B>OPTERR</B>
2535 is initialized to 1 each time the shell is invoked or a shell
2540 The search path for commands. It
2541 is a colon-separated list of directories in which
2542 the shell looks for commands (see
2543 <FONT SIZE=-1><B>COMMAND EXECUTION</B>
2547 A zero-length (null) directory name in the value of <B>PATH</B> indicates the
2549 A null directory name may appear as two adjacent colons, or as an initial
2551 The default path is system-dependent,
2552 and is set by the administrator who installs
2556 <TT>/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin</TT>.
2558 <DT><B>POSIXLY_CORRECT</B>
2561 If this variable is in the environment when <B>bash</B> starts, the shell
2562 enters <I>posix mode</I> before reading the startup files, as if the
2565 invocation option had been supplied. If it is set while the shell is
2566 running, <B>bash</B> enables <I>posix mode</I>, as if the command
2567 <TT>set -o posix</TT>
2570 <DT><B>PROMPT_COMMAND</B>
2573 If set, the value is executed as a command prior to issuing each primary
2575 <DT><B>PROMPT_DIRTRIM</B>
2578 If set to a number greater than zero, the value is used as the number of
2579 trailing directory components to retain when expanding the <B>\w and
2580 \W</B> prompt string escapes (see
2581 <FONT SIZE=-1><B>PROMPTING</B>
2584 below). Characters removed are replaced with an ellipsis.
2588 The value of this parameter is expanded (see
2589 <FONT SIZE=-1><B>PROMPTING</B>
2592 below) and used as the primary prompt string. The default value is
2593 ``<B>\s-\v\$ </B>''.
2597 The value of this parameter is expanded as with
2600 and used as the secondary prompt string. The default is
2605 The value of this parameter is used as the prompt for the
2609 <FONT SIZE=-1><B>SHELL GRAMMAR</B>
2616 The value of this parameter is expanded as with
2619 and the value is printed before each command
2622 displays during an execution trace. The first character of
2623 <FONT SIZE=-1><B>PS4</B>
2626 is replicated multiple times, as necessary, to indicate multiple
2627 levels of indirection. The default is ``<B>+ </B>''.
2631 The full pathname to the shell is kept in this environment variable.
2632 If it is not set when the shell starts,
2635 assigns to it the full pathname of the current user's login shell.
2636 <DT><B>TIMEFORMAT</B>
2639 The value of this parameter is used as a format string specifying
2640 how the timing information for pipelines prefixed with the
2643 reserved word should be displayed.
2644 The <B>%</B> character introduces an escape sequence that is
2645 expanded to a time value or other information.
2646 The escape sequences and their meanings are as follows; the
2647 braces denote optional portions.
2649 <DL COMPACT><DT><DD>
2656 <DT><B>%[</B><I>p</I>][l]R
2659 The elapsed time in seconds.
2660 <DT><B>%[</B><I>p</I>][l]U
2663 The number of CPU seconds spent in user mode.
2664 <DT><B>%[</B><I>p</I>][l]S
2667 The number of CPU seconds spent in system mode.
2671 The CPU percentage, computed as (%U + %S) / %R.
2676 The optional <I>p</I> is a digit specifying the <I>precision</I>,
2677 the number of fractional digits after a decimal point.
2678 A value of 0 causes no decimal point or fraction to be output.
2679 At most three places after the decimal point may be specified;
2680 values of <I>p</I> greater than 3 are changed to 3.
2681 If <I>p</I> is not specified, the value 3 is used.
2683 The optional <B>l</B> specifies a longer format, including
2684 minutes, of the form <I>MM</I>m<I>SS</I>.<I>FF</I>s.
2685 The value of <I>p</I> determines whether or not the fraction is
2688 If this variable is not set, <B>bash</B> acts as if it had the
2689 value <B>$aq\nreal\t%3lR\nuser\t%3lU\nsys %3lSaq</B>.
2690 If the value is null, no timing information is displayed.
2691 A trailing newline is added when the format string is displayed.
2695 If set to a value greater than zero, <B>TMOUT</B> is treated as the
2696 default timeout for the <B>read</B> builtin.
2697 The <B>select</B> command terminates if input does not arrive
2698 after <B>TMOUT</B> seconds when input is coming from a terminal.
2699 In an interactive shell, the value is interpreted as the
2700 number of seconds to wait for input after issuing the primary prompt.
2703 terminates after waiting for that number of seconds if input does
2708 If set, <B>Bash</B> uses its value as the name of a directory in which
2709 <B>Bash</B> creates temporary files for the shell's use.
2710 <DT><B>auto_resume</B>
2713 This variable controls how the shell interacts with the user and
2714 job control. If this variable is set, single word simple
2715 commands without redirections are treated as candidates for resumption
2716 of an existing stopped job. There is no ambiguity allowed; if there is
2717 more than one job beginning with the string typed, the job most recently
2718 accessed is selected. The
2721 of a stopped job, in this context, is the command line used to
2726 the string supplied must match the name of a stopped job exactly;
2730 the string supplied needs to match a substring of the name of a
2734 value provides functionality analogous to the
2738 <FONT SIZE=-1><B>JOB CONTROL</B>
2741 below). If set to any other value, the supplied string must
2742 be a prefix of a stopped job's name; this provides functionality
2743 analogous to the <B>%</B><I>string</I> job identifier.
2744 <DT><B>histchars</B>
2747 The two or three characters which control history expansion
2748 and tokenization (see
2749 <FONT SIZE=-1><B>HISTORY EXPANSION</B>
2752 below). The first character is the <I>history expansion</I> character,
2753 the character which signals the start of a history
2754 expansion, normally `<B>!</B>'.
2755 The second character is the <I>quick substitution</I>
2756 character, which is used as shorthand for re-running the previous
2757 command entered, substituting one string for another in the command.
2758 The default is `<B>^</B>'.
2759 The optional third character is the character
2760 which indicates that the remainder of the line is a comment when found
2761 as the first character of a word, normally `<B>#</B>'. The history
2762 comment character causes history substitution to be skipped for the
2763 remaining words on the line. It does not necessarily cause the shell
2764 parser to treat the rest of the line as a comment.
2767 <A NAME="lbAX"> </A>
2772 provides one-dimensional indexed and associative array variables.
2773 Any variable may be used as an indexed array; the
2776 builtin will explicitly declare an array.
2778 limit on the size of an array, nor any requirement that members
2779 be indexed or assigned contiguously.
2780 Indexed arrays are referenced using integers (including arithmetic
2781 expressions) and are zero-based; associative arrays are referenced
2782 using arbitrary strings.
2785 An indexed array is created automatically if any variable is assigned to
2786 using the syntax <I>name</I>[<I>subscript</I>]=<I>value</I>. The
2789 is treated as an arithmetic expression that must evaluate to a number
2790 greater than or equal to zero. To explicitly declare an indexed array,
2792 <B>declare -a </B><I>name</I>
2795 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
2799 <B>declare -a </B><I>name</I>[<I>subscript</I>]
2801 is also accepted; the <I>subscript</I> is ignored.
2804 Associative arrays are created using
2805 <B>declare -A </B><I>name</I>.
2810 specified for an array variable using the
2816 builtins. Each attribute applies to all members of an array.
2819 Arrays are assigned to using compound assignments of the form
2820 <I>name</I>=<B>(</B>value<I>1</I> ... value<I>n</I><B>)</B>, where each
2821 <I>value</I> is of the form [<I>subscript</I>]=<I>string</I>.
2822 Indexed array assignments do not require the bracket and subscript.
2823 When assigning to indexed arrays, if the optional brackets and subscript
2824 are supplied, that index is assigned to;
2825 otherwise the index of the element assigned is the last index assigned
2826 to by the statement plus one. Indexing starts at zero.
2829 When assigning to an associative array, the subscript is required.
2832 This syntax is also accepted by the
2835 builtin. Individual array elements may be assigned to using the
2836 <I>name</I>[<I>subscript</I>]=<I>value</I> syntax introduced above.
2839 Any element of an array may be referenced using
2840 ${<I>name</I>[<I>subscript</I>]}. The braces are required to avoid
2841 conflicts with pathname expansion. If
2842 <I>subscript</I> is <B>@</B> or <B>*</B>, the word expands to
2843 all members of <I>name</I>. These subscripts differ only when the
2844 word appears within double quotes. If the word is double-quoted,
2845 ${<I>name</I>[*]} expands to a single
2846 word with the value of each array member separated by the first
2848 <FONT SIZE=-1><B>IFS</B>
2851 special variable, and ${<I>name</I>[@]} expands each element of
2852 <I>name</I> to a separate word. When there are no array members,
2853 ${<I>name</I>[@]} expands to nothing.
2854 If the double-quoted expansion occurs within a word, the expansion of
2855 the first parameter is joined with the beginning part of the original
2856 word, and the expansion of the last parameter is joined with the last
2857 part of the original word.
2858 This is analogous to the expansion
2859 of the special parameters <B>*</B> and <B>@</B> (see
2860 <B>Special Parameters</B>
2862 above). ${#<I>name</I>[<I>subscript</I>]} expands to the length of
2863 ${<I>name</I>[<I>subscript</I>]}. If <I>subscript</I> is <B>*</B> or
2864 <B>@</B>, the expansion is the number of elements in the array.
2865 Referencing an array variable without a subscript is equivalent to
2866 referencing the array with a subscript of 0.
2872 builtin is used to destroy arrays. <B>unset</B> <I>name</I>[<I>subscript</I>]
2873 destroys the array element at index <I>subscript</I>.
2874 Care must be taken to avoid unwanted side effects caused by filename
2876 <B>unset</B> <I>name</I>, where <I>name</I> is an array, or
2877 <B>unset</B> <I>name</I>[<I>subscript</I>], where
2878 <I>subscript</I> is <B>*</B> or <B>@</B>, removes the entire array.
2889 builtins each accept a
2892 option to specify an indexed array and a
2895 option to specify an associative array.
2902 option to assign a list of words read from the standard input
2909 builtins display array values in a way that allows them to be
2910 reused as assignments.
2911 <A NAME="lbAY"> </A>
2914 Expansion is performed on the command line after it has been split into
2915 words. There are seven kinds of expansion performed:
2916 <I>brace expansion</I>,
2918 <I>tilde expansion</I>,
2920 <I>parameter and variable expansion</I>,
2922 <I>command substitution</I>,
2924 <I>arithmetic expansion</I>,
2926 <I>word splitting</I>,
2929 <I>pathname expansion</I>.
2933 The order of expansions is: brace expansion, tilde expansion,
2934 parameter, variable and arithmetic expansion and
2935 command substitution
2936 (done in a left-to-right fashion), word splitting, and pathname
2940 On systems that can support it, there is an additional expansion
2941 available: <I>process substitution</I>.
2944 Only brace expansion, word splitting, and pathname expansion
2945 can change the number of words of the expansion; other expansions
2946 expand a single word to a single word.
2947 The only exceptions to this are the expansions of
2948 "<B>$@</B>" and "<B>${</B><I>name</I><B>[@]}</B>"
2949 as explained above (see
2950 <FONT SIZE=-1><B>PARAMETERS</B>).
2953 <A NAME="lbAZ"> </A>
2954 <H4>Brace Expansion</H4>
2958 <I>Brace expansion</I>
2960 is a mechanism by which arbitrary strings
2961 may be generated. This mechanism is similar to
2962 <I>pathname expansion</I>, but the filenames generated
2963 need not exist. Patterns to be brace expanded take
2964 the form of an optional
2967 followed by either a series of comma-separated strings or
2968 a sequence expression between a pair of braces, followed by
2972 The preamble is prefixed to each string contained
2973 within the braces, and the postscript is then appended
2974 to each resulting string, expanding left to right.
2977 Brace expansions may be nested. The results of each expanded
2978 string are not sorted; left to right order is preserved.
2979 For example, a<B>{</B>d,c,b<B>}</B>e expands into `ade ace abe'.
2982 A sequence expression takes the form
2983 <B>{</B><I>x</I><B>..</B><I>y</I><B>[..</B><I>incr</I><B>]}</B>,
2984 where <I>x</I> and <I>y</I> are either integers or single characters,
2985 and <I>incr</I>, an optional increment, is an integer.
2986 When integers are supplied, the expression expands to each number between
2987 <I>x</I> and <I>y</I>, inclusive.
2988 Supplied integers may be prefixed with <I>0</I> to force each term to have the
2989 same width. When either <I>x</I> or y begins with a zero, the shell
2990 attempts to force all generated terms to contain the same number of digits,
2991 zero-padding where necessary.
2992 When characters are supplied, the expression expands to each character
2993 lexicographically between <I>x</I> and <I>y</I>, inclusive. Note that
2994 both <I>x</I> and <I>y</I> must be of the same type.
2995 When the increment is supplied, it is used as the difference between
2996 each term. The default increment is 1 or -1 as appropriate.
2999 Brace expansion is performed before any other expansions,
3000 and any characters special to other expansions are preserved
3001 in the result. It is strictly textual.
3004 does not apply any syntactic interpretation to the context of the
3005 expansion or the text between the braces.
3008 A correctly-formed brace expansion must contain unquoted opening
3009 and closing braces, and at least one unquoted comma or a valid
3010 sequence expression.
3011 Any incorrectly formed brace expansion is left unchanged.
3012 A <B>{</B> or <B>,</B> may be quoted with a backslash to prevent its
3013 being considered part of a brace expression.
3014 To avoid conflicts with parameter expansion, the string <B>${</B>
3015 is not considered eligible for brace expansion.
3018 This construct is typically used as shorthand when the common
3019 prefix of the strings to be generated is longer than in the
3021 <DL COMPACT><DT><DD>
3024 mkdir /usr/local/src/bash/{old,new,dist,bugs}
3028 <DL COMPACT><DT><DD>
3029 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
3034 Brace expansion introduces a slight incompatibility with
3035 historical versions of
3040 does not treat opening or closing braces specially when they
3041 appear as part of a word, and preserves them in the output.
3044 removes braces from words as a consequence of brace
3045 expansion. For example, a word entered to
3049 appears identically in the output. The same word is
3056 If strict compatibility with
3065 option or disable brace expansion with the
3072 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
3076 <A NAME="lbBA"> </A>
3077 <H4>Tilde Expansion</H4>
3081 If a word begins with an unquoted tilde character (`<B>~</B>'), all of
3082 the characters preceding the first unquoted slash (or all characters,
3083 if there is no unquoted slash) are considered a <I>tilde-prefix</I>.
3084 If none of the characters in the tilde-prefix are quoted, the
3085 characters in the tilde-prefix following the tilde are treated as a
3086 possible <I>login name</I>.
3087 If this login name is the null string, the tilde is replaced with the
3088 value of the shell parameter
3089 <FONT SIZE=-1><B>HOME</B>.
3093 <FONT SIZE=-1><B>HOME</B>
3096 is unset, the home directory of the user executing the shell is
3097 substituted instead.
3098 Otherwise, the tilde-prefix is replaced with the home directory
3099 associated with the specified login name.
3102 If the tilde-prefix is a `~+', the value of the shell variable
3103 <FONT SIZE=-1><B>PWD</B>
3106 replaces the tilde-prefix.
3107 If the tilde-prefix is a `~-', the value of the shell variable
3108 <FONT SIZE=-1><B>OLDPWD</B>,
3111 if it is set, is substituted.
3112 If the characters following the tilde in the tilde-prefix consist
3113 of a number <I>N</I>, optionally prefixed
3114 by a `+' or a `-', the tilde-prefix is replaced with the corresponding
3115 element from the directory stack, as it would be displayed by the
3118 builtin invoked with the tilde-prefix as an argument.
3119 If the characters following the tilde in the tilde-prefix consist of a
3120 number without a leading `+' or `-', `+' is assumed.
3123 If the login name is invalid, or the tilde expansion fails, the word
3127 Each variable assignment is checked for unquoted tilde-prefixes immediately
3134 In these cases, tilde expansion is also performed.
3135 Consequently, one may use file names with tildes in assignments to
3136 <FONT SIZE=-1><B>PATH</B>,
3139 <FONT SIZE=-1><B>MAILPATH</B>,
3143 <FONT SIZE=-1><B>CDPATH</B>,
3146 and the shell assigns the expanded value.
3147 <A NAME="lbBB"> </A>
3148 <H4>Parameter Expansion</H4>
3152 The `<B>$</B>' character introduces parameter expansion,
3153 command substitution, or arithmetic expansion. The parameter name
3154 or symbol to be expanded may be enclosed in braces, which
3155 are optional but serve to protect the variable to be expanded from
3156 characters immediately following it which could be
3157 interpreted as part of the name.
3160 When braces are used, the matching ending brace is the first `<B>}</B>'
3161 not escaped by a backslash or within a quoted string, and not within an
3162 embedded arithmetic expansion, command substitution, or parameter
3168 <DT>${<I>parameter</I>}<DD>
3169 The value of <I>parameter</I> is substituted. The braces are required
3173 is a positional parameter with more than one digit,
3177 is followed by a character which is not to be
3178 interpreted as part of its name.
3183 If the first character of <I>parameter</I> is an exclamation point,
3184 a level of variable indirection is introduced.
3185 <B>Bash</B> uses the value of the variable formed from the rest of
3186 <I>parameter</I> as the name of the variable; this variable is then
3187 expanded and that value is used in the rest of the substitution, rather
3188 than the value of <I>parameter</I> itself.
3189 This is known as <I>indirect expansion</I>.
3190 The exceptions to this are the expansions of ${!<I>prefix</I>*} and
3191 ${<B>!</B><I>name</I>[<I>@</I>]} described below.
3192 The exclamation point must immediately follow the left brace in order to
3193 introduce indirection.
3196 In each of the cases below, <I>word</I> is subject to tilde expansion,
3197 parameter expansion, command substitution, and arithmetic expansion.
3200 When not performing substring expansion, using the forms documented below,
3201 <B>bash</B> tests for a parameter that is unset or null. Omitting the colon
3202 results in a test only for a parameter that is unset.
3207 <DT>${<I>parameter</I><B>:-</B><I>word</I>}<DD>
3208 <B>Use Default Values</B>. If
3211 is unset or null, the expansion of
3214 is substituted. Otherwise, the value of
3218 <DT>${<I>parameter</I><B>:=</B><I>word</I>}<DD>
3219 <B>Assign Default Values</B>.
3223 is unset or null, the expansion of
3232 is then substituted. Positional parameters and special parameters may
3233 not be assigned to in this way.
3234 <DT>${<I>parameter</I><B>:?</B><I>word</I>}<DD>
3235 <B>Display Error if Null or Unset</B>.
3239 is null or unset, the expansion of <I>word</I> (or a message to that effect
3243 is not present) is written to the standard error and the shell, if it
3244 is not interactive, exits. Otherwise, the value of <I>parameter</I> is
3246 <DT>${<I>parameter</I><B>:+</B><I>word</I>}<DD>
3247 <B>Use Alternate Value</B>.
3251 is null or unset, nothing is substituted, otherwise the expansion of
3255 <DT>${<I>parameter</I><B>:</B><I>offset</I>}<DD>
3257 <DT>${<I>parameter</I><B>:</B><I>offset</I><B>:</B><I>length</I>}<DD>
3259 <B>Substring Expansion.</B>
3260 Expands to up to <I>length</I> characters of <I>parameter</I>
3261 starting at the character specified by <I>offset</I>.
3262 If <I>length</I> is omitted, expands to the substring of
3263 <I>parameter</I> starting at the character specified by <I>offset</I>.
3264 <I>length</I> and <I>offset</I> are arithmetic expressions (see
3265 <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>
3269 <I>length</I> must evaluate to a number greater than or equal to zero.
3270 If <I>offset</I> evaluates to a number less than zero, the value
3271 is used as an offset from the end of the value of <I>parameter</I>.
3272 If <I>parameter</I> is <B>@</B>, the result is <I>length</I> positional
3273 parameters beginning at <I>offset</I>.
3274 If <I>parameter</I> is an indexed array name subscripted by @ or *,
3275 the result is the <I>length</I>
3276 members of the array beginning with ${<I>parameter</I>[<I>offset</I>]}.
3277 A negative <I>offset</I> is taken relative to one greater than the maximum
3278 index of the specified array.
3279 Substring expansion applied to an associative array produces undefined
3281 Note that a negative offset must be separated from the colon by at least
3282 one space to avoid being confused with the :- expansion.
3283 Substring indexing is zero-based unless the positional parameters
3284 are used, in which case the indexing starts at 1 by default.
3285 If <I>offset</I> is 0, and the positional parameters are used, <B>$0</B> is
3286 prefixed to the list.
3287 <DT>${<B>!</B><I>prefix</I><B>*</B>}<DD>
3289 <DT>${<B>!</B><I>prefix</I><B>@</B>}<DD>
3291 <B>Names matching prefix.</B>
3292 Expands to the names of variables whose names begin with <I>prefix</I>,
3293 separated by the first character of the
3294 <FONT SIZE=-1><B>IFS</B>
3298 When <I>@</I> is used and the expansion appears within double quotes, each
3299 variable name expands to a separate word.
3300 <DT>${<B>!</B><I>name</I>[<I>@</I>]}<DD>
3302 <DT>${<B>!</B><I>name</I>[<I>*</I>]}<DD>
3304 <B>List of array keys.</B>
3305 If <I>name</I> is an array variable, expands to the list of array indices
3306 (keys) assigned in <I>name</I>.
3307 If <I>name</I> is not an array, expands to 0 if <I>name</I> is set and null
3309 When <I>@</I> is used and the expansion appears within double quotes, each
3310 key expands to a separate word.
3311 <DT>${<B>#</B><I>parameter</I>}<DD>
3312 <B>Parameter length.</B>
3313 The length in characters of the value of <I>parameter</I> is substituted.
3323 the value substituted is the number of positional parameters.
3327 is an array name subscripted by
3333 the value substituted is the number of elements in the array.
3334 <DT>${<I>parameter</I><B>#</B><I>word</I>}<DD>
3336 <DT>${<I>parameter</I><B>##</B><I>word</I>}<DD>
3338 <B>Remove matching prefix pattern.</B>
3342 is expanded to produce a pattern just as in pathname
3343 expansion. If the pattern matches the beginning of
3347 then the result of the expansion is the expanded value of
3350 with the shortest matching pattern (the ``<B>#</B>'' case) or the
3351 longest matching pattern (the ``<B>##</B>'' case) deleted.
3361 the pattern removal operation is applied to each positional
3362 parameter in turn, and the expansion is the resultant list.
3366 is an array variable subscripted with
3372 the pattern removal operation is applied to each member of the
3373 array in turn, and the expansion is the resultant list.
3374 <DT>${<I>parameter</I><B>%</B><I>word</I>}<DD>
3376 <DT>${<I>parameter</I><B>%%</B><I>word</I>}<DD>
3378 <B>Remove matching suffix pattern.</B>
3379 The <I>word</I> is expanded to produce a pattern just as in
3381 If the pattern matches a trailing portion of the expanded value of
3384 then the result of the expansion is the expanded value of
3387 with the shortest matching pattern (the ``<B>%</B>'' case) or the
3388 longest matching pattern (the ``<B>%%</B>'' case) deleted.
3398 the pattern removal operation is applied to each positional
3399 parameter in turn, and the expansion is the resultant list.
3403 is an array variable subscripted with
3409 the pattern removal operation is applied to each member of the
3410 array in turn, and the expansion is the resultant list.
3411 <DT>${<I>parameter</I><B>/</B><I>pattern</I><B>/</B><I>string</I>}<DD>
3412 <B>Pattern substitution.</B>
3413 The <I>pattern</I> is expanded to produce a pattern just as in
3415 <I>Parameter</I> is expanded and the longest match of <I>pattern</I>
3416 against its value is replaced with <I>string</I>.
3417 If <I>pattern</I> begins with <B>/</B>, all matches of <I>pattern</I> are
3418 replaced with <I>string</I>. Normally only the first match is replaced.
3419 If <I>pattern</I> begins with <B>#</B>, it must match at the beginning
3420 of the expanded value of <I>parameter</I>.
3421 If <I>pattern</I> begins with <B>%</B>, it must match at the end
3422 of the expanded value of <I>parameter</I>.
3423 If <I>string</I> is null, matches of <I>pattern</I> are deleted
3424 and the <B>/</B> following <I>pattern</I> may be omitted.
3434 the substitution operation is applied to each positional
3435 parameter in turn, and the expansion is the resultant list.
3439 is an array variable subscripted with
3445 the substitution operation is applied to each member of the
3446 array in turn, and the expansion is the resultant list.
3447 <DT>${<I>parameter</I><B>^</B><I>pattern</I>}<DD>
3449 <DT>${<I>parameter</I><B>^^</B><I>pattern</I>}<DD>
3450 <DT>${<I>parameter</I><B>,</B><I>pattern</I>}<DD>
3451 <DT>${<I>parameter</I><B>,,</B><I>pattern</I>}<DD>
3453 <B>Case modification.</B>
3454 This expansion modifies the case of alphabetic characters in <I>parameter</I>.
3455 The <I>pattern</I> is expanded to produce a pattern just as in
3457 The <B>^</B> operator converts lowercase letters matching <I>pattern</I>
3458 to uppercase; the <B>,</B> operator converts matching uppercase letters
3460 The <B>^^</B> and <B>,,</B> expansions convert each matched character in the
3461 expanded value; the <B>^</B> and <B>,</B> expansions match and convert only
3462 the first character in the expanded value..
3463 If <I>pattern</I> is omitted, it is treated like a <B>?</B>, which matches
3474 the case modification operation is applied to each positional
3475 parameter in turn, and the expansion is the resultant list.
3479 is an array variable subscripted with
3485 the case modification operation is applied to each member of the
3486 array in turn, and the expansion is the resultant list.
3488 <A NAME="lbBC"> </A>
3489 <H4>Command Substitution</H4>
3493 <I>Command substitution</I> allows the output of a command to replace
3494 the command name. There are two forms:
3497 <DL COMPACT><DT><DD>
3500 <B>$(</B><I>command</I><B>)</B>
3504 <DL COMPACT><DT><DD>
3505 <B>`</B><I>command</I><B>`</B>
3512 performs the expansion by executing <I>command</I> and
3513 replacing the command substitution with the standard output of the
3514 command, with any trailing newlines deleted.
3515 Embedded newlines are not deleted, but they may be removed during
3517 The command substitution <B>$(cat </B><I>file</I>) can be replaced by
3518 the equivalent but faster <B>$(< </B><I>file</I>).
3521 When the old-style backquote form of substitution is used,
3522 backslash retains its literal meaning except when followed by
3530 The first backquote not preceded by a backslash terminates the
3531 command substitution.
3532 When using the $(<I>command</I>) form, all characters between the
3533 parentheses make up the command; none are treated specially.
3536 Command substitutions may be nested. To nest when using the backquoted form,
3537 escape the inner backquotes with backslashes.
3540 If the substitution appears within double quotes, word splitting and
3541 pathname expansion are not performed on the results.
3542 <A NAME="lbBD"> </A>
3543 <H4>Arithmetic Expansion</H4>
3547 Arithmetic expansion allows the evaluation of an arithmetic expression
3548 and the substitution of the result. The format for arithmetic expansion is:
3549 <DL COMPACT><DT><DD>
3552 <B>$((</B><I>expression</I><B>))</B>
3560 is treated as if it were within double quotes, but a double quote
3561 inside the parentheses is not treated specially.
3562 All tokens in the expression undergo parameter expansion, string
3563 expansion, command substitution, and quote removal.
3564 Arithmetic expansions may be nested.
3567 The evaluation is performed according to the rules listed below under
3568 <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>.
3577 prints a message indicating failure and no substitution occurs.
3578 <A NAME="lbBE"> </A>
3579 <H4>Process Substitution</H4>
3583 <I>Process substitution</I> is supported on systems that support named
3584 pipes (<I>FIFOs</I>) or the <B>/dev/fd</B> method of naming open files.
3585 It takes the form of
3586 <B><(</B><I>list</I><B>)</B>
3588 <B>>(</B><I>list</I><B>)</B>.
3589 The process <I>list</I> is run with its input or output connected to a
3590 <I>FIFO</I> or some file in <B>/dev/fd</B>. The name of this file is
3591 passed as an argument to the current command as the result of the
3592 expansion. If the <B>>(</B><I>list</I><B>)</B> form is used, writing to
3593 the file will provide input for <I>list</I>. If the
3594 <B><(</B><I>list</I><B>)</B> form is used, the file passed as an
3595 argument should be read to obtain the output of <I>list</I>.
3598 When available, process substitution is performed
3599 simultaneously with parameter and variable expansion,
3600 command substitution,
3601 and arithmetic expansion.
3602 <A NAME="lbBF"> </A>
3603 <H4>Word Splitting</H4>
3607 The shell scans the results of
3608 parameter expansion,
3609 command substitution,
3611 arithmetic expansion
3612 that did not occur within double quotes for
3613 <I>word splitting</I>.
3617 The shell treats each character of
3618 <FONT SIZE=-1><B>IFS</B>
3621 as a delimiter, and splits the results of the other
3622 expansions into words on these characters. If
3623 <FONT SIZE=-1><B>IFS</B>
3628 <B><space><tab><newline></B>,
3632 <B><space></B>,
3637 <B><newline></B>
3639 at the beginning and end of the results of the previous
3640 expansions are ignored, and
3642 <FONT SIZE=-1><B>IFS</B>
3645 characters not at the beginning or end serves to delimit words.
3647 <FONT SIZE=-1><B>IFS</B>
3650 has a value other than the default, then sequences of
3651 the whitespace characters
3657 are ignored at the beginning and end of the
3658 word, as long as the whitespace character is in the
3660 <FONT SIZE=-1><B>IFS</B>
3664 <FONT SIZE=-1><B>IFS</B>
3667 whitespace character).
3669 <FONT SIZE=-1><B>IFS</B>
3673 <FONT SIZE=-1><B>IFS</B>
3676 whitespace, along with any adjacent
3677 <FONT SIZE=-1><B>IFS</B>
3680 whitespace characters, delimits a field.
3682 <FONT SIZE=-1><B>IFS</B>
3685 whitespace characters is also treated as a delimiter.
3687 <FONT SIZE=-1><B>IFS</B>
3690 is null, no word splitting occurs.
3693 Explicit null arguments (<B>""</B> or <B>aqaq</B>) are retained.
3694 Unquoted implicit null arguments, resulting from the expansion of
3695 parameters that have no values, are removed.
3696 If a parameter with no value is expanded within double quotes, a
3697 null argument results and is retained.
3700 Note that if no expansion occurs, no splitting
3702 <A NAME="lbBG"> </A>
3703 <H4>Pathname Expansion</H4>
3707 After word splitting,
3711 option has been set,
3714 scans each word for the characters
3722 If one of these characters appears, then the word is
3726 and replaced with an alphabetically sorted list of
3727 file names matching the pattern.
3728 If no matching file names are found,
3729 and the shell option
3732 is not enabled, the word is left unchanged.
3736 option is set, and no matches are found,
3737 the word is removed.
3741 shell option is set, and no matches are found, an error message
3742 is printed and the command is not executed.
3746 is enabled, the match is performed without regard to the case
3747 of alphabetic characters.
3748 When a pattern is used for pathname expansion,
3752 at the start of a name or immediately following a slash
3753 must be matched explicitly, unless the shell option
3757 When matching a pathname, the slash character must always be
3762 character is not treated specially.
3763 See the description of
3767 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
3770 for a description of the
3784 <FONT SIZE=-1><B>GLOBIGNORE</B>
3787 shell variable may be used to restrict the set of file names matching a
3791 <FONT SIZE=-1><B>GLOBIGNORE</B>
3794 is set, each matching file name that also matches one of the patterns in
3795 <FONT SIZE=-1><B>GLOBIGNORE</B>
3798 is removed from the list of matches.
3805 are always ignored when
3806 <FONT SIZE=-1><B>GLOBIGNORE</B>
3809 is set and not null. However, setting
3810 <FONT SIZE=-1><B>GLOBIGNORE</B>
3813 to a non-null value has the effect of enabling the
3816 shell option, so all other file names beginning with a
3820 To get the old behavior of ignoring file names beginning with a
3826 one of the patterns in
3827 <FONT SIZE=-1><B>GLOBIGNORE</B>.
3833 option is disabled when
3834 <FONT SIZE=-1><B>GLOBIGNORE</B>
3840 <B>Pattern Matching</B>
3843 Any character that appears in a pattern, other than the special pattern
3844 characters described below, matches itself. The NUL character may not
3845 occur in a pattern. A backslash escapes the following character; the
3846 escaping backslash is discarded when matching.
3847 The special pattern characters must be quoted if
3848 they are to be matched literally.
3851 The special pattern characters have the following meanings:
3859 Matches any string, including the null string.
3860 When the <B>globstar</B> shell option is enabled, and <B>*</B> is used in
3861 a filename expansion context, two adjacent <B>*</B>s used as a single
3862 pattern will match all files and zero or more directories and
3864 If followed by a <B>/</B>, two adjacent <B>*</B>s will match only directories
3869 Matches any single character.
3873 Matches any one of the enclosed characters. A pair of characters
3874 separated by a hyphen denotes a
3875 <I>range expression</I>;
3876 any character that sorts between those two characters, inclusive,
3877 using the current locale's collating sequence and character set,
3878 is matched. If the first character following the
3887 then any character not enclosed is matched.
3888 The sorting order of characters in range expressions is determined by
3889 the current locale and the value of the <B>LC_COLLATE</B> shell variable,
3894 may be matched by including it as the first or last character
3899 may be matched by including it as the first character
3912 <I>character classes</I> can be specified using the syntax
3913 <B>[:</B><I>class</I><B>:]</B>, where <I>class</I> is one of the
3914 following classes defined in the POSIX standard:
3918 <DL COMPACT><DT><DD>
3922 alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit
3925 A character class matches any character belonging to that class.
3926 The <B>word</B> character class matches letters, digits, and the character _.
3938 an <I>equivalence class</I> can be specified using the syntax
3939 <B>[=</B><I>c</I><B>=]</B>, which matches all characters with the
3940 same collation weight (as defined by the current locale) as
3941 the character <I>c</I>.
3953 the syntax <B>[.</B><I>symbol</I><B>.]</B> matches the collating symbol
3960 If the <B>extglob</B> shell option is enabled using the <B>shopt</B>
3961 builtin, several extended pattern matching operators are recognized.
3962 In the following description, a <I>pattern-list</I> is a list of one
3963 or more patterns separated by a <B>|</B>.
3964 Composite patterns may be formed using one or more of the following
3968 <DL COMPACT><DT><DD>
3970 <DT><B>?(</B><I>pattern-list</I><B>)</B><DD>
3971 Matches zero or one occurrence of the given patterns
3972 <DT><B>*(</B><I>pattern-list</I><B>)</B><DD>
3973 Matches zero or more occurrences of the given patterns
3974 <DT><B>+(</B><I>pattern-list</I><B>)</B><DD>
3975 Matches one or more occurrences of the given patterns
3976 <DT><B>@(</B><I>pattern-list</I><B>)</B><DD>
3977 Matches one of the given patterns
3978 <DT><B>!(</B><I>pattern-list</I><B>)</B><DD>
3979 Matches anything except one of the given patterns
3983 <A NAME="lbBH"> </A>
3984 <H4>Quote Removal</H4>
3988 After the preceding expansions, all unquoted occurrences of the
3994 and <B>"</B> that did not result from one of the above
3995 expansions are removed.
3996 <A NAME="lbBI"> </A>
3997 <H3>REDIRECTION</H3>
3999 Before a command is executed, its input and output
4003 using a special notation interpreted by the shell.
4004 Redirection may also be used to open and close files for the
4005 current shell execution environment. The following redirection
4006 operators may precede or appear anywhere within a
4007 <I>simple command</I>
4012 Redirections are processed in the order they appear, from
4016 In the following descriptions, if the file descriptor number is
4017 omitted, and the first character of the redirection operator is
4020 the redirection refers to the standard input (file descriptor
4021 0). If the first character of the redirection operator is
4024 the redirection refers to the standard output (file descriptor
4028 The word following the redirection operator in the following
4029 descriptions, unless otherwise noted, is subjected to brace expansion,
4030 tilde expansion, parameter expansion, command substitution, arithmetic
4031 expansion, quote removal, pathname expansion, and word splitting.
4032 If it expands to more than one word,
4038 Note that the order of redirections is significant. For example,
4040 <DL COMPACT><DT><DD>
4043 ls <B>></B> dirlist 2<B>>&</B>1
4048 directs both standard output and standard error to the file
4052 <DL COMPACT><DT><DD>
4055 ls 2<B>>&</B>1 <B>></B> dirlist
4060 directs only the standard output to file
4063 because the standard error was duplicated as standard output
4064 before the standard output was redirected to
4069 <B>Bash</B> handles several filenames specially when they are used in
4070 redirections, as described in the following table:
4071 <DL COMPACT><DT><DD>
4076 <DT><B>/dev/fd/</B><I>fd</I>
4079 If <I>fd</I> is a valid integer, file descriptor <I>fd</I> is duplicated.
4080 <DT><B>/dev/stdin</B>
4083 File descriptor 0 is duplicated.
4084 <DT><B>/dev/stdout</B>
4087 File descriptor 1 is duplicated.
4088 <DT><B>/dev/stderr</B>
4091 File descriptor 2 is duplicated.
4092 <DT><B>/dev/tcp/</B><I>host</I>/<I>port</I>
4095 If <I>host</I> is a valid hostname or Internet address, and <I>port</I>
4096 is an integer port number or service name, <B>bash</B> attempts to open
4097 a TCP connection to the corresponding socket.
4098 <DT><B>/dev/udp/</B><I>host</I>/<I>port</I>
4101 If <I>host</I> is a valid hostname or Internet address, and <I>port</I>
4102 is an integer port number or service name, <B>bash</B> attempts to open
4103 a UDP connection to the corresponding socket.
4109 A failure to open or create a file causes the redirection to fail.
4112 Redirections using file descriptors greater than 9 should be used with
4113 care, as they may conflict with file descriptors the shell uses
4115 <A NAME="lbBJ"> </A>
4116 <H4>Redirecting Input</H4>
4120 Redirection of input causes the file whose name results from
4124 to be opened for reading on file descriptor
4127 or the standard input (file descriptor 0) if
4133 The general format for redirecting input is:
4134 <DL COMPACT><DT><DD>
4137 [<I>n</I>]<B><</B><I>word</I>
4140 <A NAME="lbBK"> </A>
4141 <H4>Redirecting Output</H4>
4145 Redirection of output causes the file whose name results from
4149 to be opened for writing on file descriptor
4152 or the standard output (file descriptor 1) if
4155 is not specified. If the file does not exist it is created;
4156 if it does exist it is truncated to zero size.
4159 The general format for redirecting output is:
4160 <DL COMPACT><DT><DD>
4163 [<I>n</I>]<B>></B><I>word</I>
4168 If the redirection operator is
4177 builtin has been enabled, the redirection will fail if the file
4178 whose name results from the expansion of <I>word</I> exists and is
4180 If the redirection operator is
4183 or the redirection operator is
4192 builtin command is not enabled, the redirection is attempted even
4193 if the file named by <I>word</I> exists.
4194 <A NAME="lbBL"> </A>
4195 <H4>Appending Redirected Output</H4>
4199 Redirection of output in this fashion
4200 causes the file whose name results from
4204 to be opened for appending on file descriptor
4207 or the standard output (file descriptor 1) if
4210 is not specified. If the file does not exist it is created.
4213 The general format for appending output is:
4214 <DL COMPACT><DT><DD>
4217 [<I>n</I>]<B>>></B><I>word</I>
4222 <A NAME="lbBM"> </A>
4223 <H4>Redirecting Standard Output and Standard Error</H4>
4227 This construct allows both the
4228 standard output (file descriptor 1) and
4229 the standard error output (file descriptor 2)
4230 to be redirected to the file whose name is the
4236 There are two formats for redirecting standard output and
4238 <DL COMPACT><DT><DD>
4241 <B>&></B><I>word</I>
4245 <DL COMPACT><DT><DD>
4246 <B>>&</B><I>word</I>
4251 Of the two forms, the first is preferred.
4252 This is semantically equivalent to
4253 <DL COMPACT><DT><DD>
4256 <B>></B><I>word</I> 2<B>>&</B>1
4261 <A NAME="lbBN"> </A>
4262 <H4>Appending Standard Output and Standard Error</H4>
4266 This construct allows both the
4267 standard output (file descriptor 1) and
4268 the standard error output (file descriptor 2)
4269 to be appended to the file whose name is the
4275 The format for appending standard output and standard error is:
4276 <DL COMPACT><DT><DD>
4279 <B>&>></B><I>word</I>
4284 This is semantically equivalent to
4285 <DL COMPACT><DT><DD>
4288 <B>>></B><I>word</I> 2<B>>&</B>1
4291 <A NAME="lbBO"> </A>
4292 <H4>Here Documents</H4>
4296 This type of redirection instructs the shell to read input from the
4297 current source until a line containing only
4300 (with no trailing blanks)
4302 the lines read up to that point are then used as the standard
4303 input for a command.
4306 The format of here-documents is:
4307 <DL COMPACT><DT><DD>
4311 <B><<</B>[<B>-</B>]<I>word</I>
4312 <I>here-document</I>
4320 No parameter expansion, command substitution, arithmetic expansion,
4321 or pathname expansion is performed on
4324 If any characters in
4330 is the result of quote removal on
4333 and the lines in the here-document are not expanded.
4334 If <I>word</I> is unquoted,
4335 all lines of the here-document are subjected to parameter expansion,
4336 command substitution, and arithmetic expansion. In the latter
4337 case, the character sequence
4338 <B>\<newline></B>
4343 must be used to quote the characters
4353 If the redirection operator is
4356 then all leading tab characters are stripped from input lines and the
4361 here-documents within shell scripts to be indented in a
4363 <A NAME="lbBP"> </A>
4364 <H4>Here Strings</H4>
4366 A variant of here documents, the format is:
4367 <DL COMPACT><DT><DD>
4371 <B><<<</B><I>word</I>
4378 The <I>word</I> is expanded and supplied to the command on its standard
4380 <A NAME="lbBQ"> </A>
4381 <H4>Duplicating File Descriptors</H4>
4385 The redirection operator
4386 <DL COMPACT><DT><DD>
4389 [<I>n</I>]<B><&</B><I>word</I>
4394 is used to duplicate input file descriptors.
4398 expands to one or more digits, the file descriptor denoted by
4401 is made to be a copy of that file descriptor.
4405 do not specify a file descriptor open for input, a redirection error occurs.
4418 is not specified, the standard input (file descriptor 0) is used.
4422 <DL COMPACT><DT><DD>
4425 [<I>n</I>]<B>>&</B><I>word</I>
4430 is used similarly to duplicate output file descriptors. If
4433 is not specified, the standard output (file descriptor 1) is used.
4437 do not specify a file descriptor open for output, a redirection error occurs.
4438 As a special case, if <I>n</I> is omitted, and <I>word</I> does not
4439 expand to one or more digits, the standard output and standard
4440 error are redirected as described previously.
4441 <A NAME="lbBR"> </A>
4442 <H4>Moving File Descriptors</H4>
4446 The redirection operator
4447 <DL COMPACT><DT><DD>
4450 [<I>n</I>]<B><&</B><I>digit</I><B>-</B>
4455 moves the file descriptor <I>digit</I> to file descriptor
4458 or the standard input (file descriptor 0) if <I>n</I> is not specified.
4459 <I>digit</I> is closed after being duplicated to <I>n</I>.
4462 Similarly, the redirection operator
4463 <DL COMPACT><DT><DD>
4466 [<I>n</I>]<B>>&</B><I>digit</I><B>-</B>
4471 moves the file descriptor <I>digit</I> to file descriptor
4474 or the standard output (file descriptor 1) if <I>n</I> is not specified.
4475 <A NAME="lbBS"> </A>
4476 <H4>Opening File Descriptors for Reading and Writing</H4>
4480 The redirection operator
4481 <DL COMPACT><DT><DD>
4484 [<I>n</I>]<B><></B><I>word</I>
4489 causes the file whose name is the expansion of
4492 to be opened for both reading and writing on file descriptor
4495 or on file descriptor 0 if
4498 is not specified. If the file does not exist, it is created.
4499 <A NAME="lbBT"> </A>
4502 <I>Aliases</I> allow a string to be substituted for a word when it is used
4503 as the first word of a simple command.
4504 The shell maintains a list of aliases that may be set and unset with the
4510 builtin commands (see
4511 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
4515 The first word of each simple command, if unquoted,
4516 is checked to see if it has an
4517 alias. If so, that word is replaced by the text of the alias.
4518 The characters <B>/</B>, <B>$</B>, <B>`</B>, and <B>=</B> and
4519 any of the shell <I>metacharacters</I> or quoting characters
4520 listed above may not appear in an alias name.
4521 The replacement text may contain any valid shell input,
4522 including shell metacharacters.
4523 The first word of the replacement text is tested
4524 for aliases, but a word that is identical to an alias being expanded
4525 is not expanded a second time.
4526 This means that one may alias
4535 does not try to recursively expand the replacement text.
4536 If the last character of the alias value is a
4539 then the next command
4540 word following the alias is also checked for alias expansion.
4543 Aliases are created and listed with the
4546 command, and removed with the
4552 There is no mechanism for using arguments in the replacement text.
4553 If arguments are needed, a shell function should be used (see
4554 <FONT SIZE=-1><B>FUNCTIONS</B>
4560 Aliases are not expanded when the shell is not interactive, unless
4562 <B>expand_aliases</B>
4564 shell option is set using
4567 (see the description of
4571 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B></FONT>
4575 The rules concerning the definition and use of aliases are
4579 always reads at least one complete line
4580 of input before executing any
4581 of the commands on that line. Aliases are expanded when a
4582 command is read, not when it is executed. Therefore, an
4583 alias definition appearing on the same line as another
4584 command does not take effect until the next line of input is read.
4585 The commands following the alias definition
4586 on that line are not affected by the new alias.
4587 This behavior is also an issue when functions are executed.
4588 Aliases are expanded when a function definition is read,
4589 not when the function is executed, because a function definition
4590 is itself a compound command. As a consequence, aliases
4591 defined in a function are not available until after that
4592 function is executed. To be safe, always put
4593 alias definitions on a separate line, and do not use
4596 in compound commands.
4599 For almost every purpose, aliases are superseded by
4601 <A NAME="lbBU"> </A>
4604 A shell function, defined as described above under
4605 <FONT SIZE=-1><B>SHELL GRAMMAR</B>,
4608 stores a series of commands for later execution.
4609 When the name of a shell function is used as a simple command name,
4610 the list of commands associated with that function name is executed.
4611 Functions are executed in the context of the
4612 current shell; no new process is created to interpret
4613 them (contrast this with the execution of a shell script).
4614 When a function is executed, the arguments to the
4615 function become the positional parameters
4616 during its execution.
4617 The special parameter
4620 is updated to reflect the change. Special parameter 0
4622 The first element of the
4623 <FONT SIZE=-1><B>FUNCNAME</B>
4626 variable is set to the name of the function while the function
4628 All other aspects of the shell execution
4629 environment are identical between a function and its caller
4630 with the exception that the
4631 <FONT SIZE=-1><B>DEBUG</B>
4637 traps (see the description of the
4641 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
4644 below) are not inherited unless the function has been given the
4645 <B>trace</B> attribute (see the description of the
4646 <FONT SIZE=-1><B>declare</B>
4649 builtin below) or the
4650 <B>-o functrace</B> shell option has been enabled with
4651 the <B>set</B> builtin
4652 (in which case all functions inherit the <B>DEBUG</B> and <B>RETURN</B> traps).
4655 Variables local to the function may be declared with the
4658 builtin command. Ordinarily, variables and their values
4659 are shared between the function and its caller.
4662 If the builtin command
4665 is executed in a function, the function completes and
4666 execution resumes with the next command after the function
4668 Any command associated with the <B>RETURN</B> trap is executed
4669 before execution resumes.
4670 When a function completes, the values of the
4671 positional parameters and the special parameter
4674 are restored to the values they had prior to the function's
4678 Function names and definitions may be listed with the
4687 builtin commands. The
4696 will list the function names only
4697 (and optionally the source file and line number, if the <B>extdebug</B>
4698 shell option is enabled).
4699 Functions may be exported so that subshells
4700 automatically have them defined with the
4707 A function definition may be deleted using the <B>-f</B> option to
4712 Note that shell functions and variables with the same name may result
4713 in multiple identically-named entries in the environment passed to the
4715 Care should be taken in cases where this may cause a problem.
4718 Functions may be recursive. No limit is imposed on the number
4720 <A NAME="lbBV"> </A>
4721 <H3>ARITHMETIC EVALUATION</H3>
4723 The shell allows arithmetic expressions to be evaluated, under
4724 certain circumstances (see the <B>let</B> and <B>declare</B> builtin
4725 commands and <B>Arithmetic Expansion</B>).
4726 Evaluation is done in fixed-width integers with no check for overflow,
4727 though division by 0 is trapped and flagged as an error.
4728 The operators and their precedence, associativity, and values
4729 are the same as in the C language.
4730 The following list of operators is grouped into levels of
4731 equal-precedence operators.
4732 The levels are listed in order of decreasing precedence.
4737 <DT><B></B><I>id</I>++ <I>id</I>--
4740 variable post-increment and post-decrement
4741 <DT><B>++</B><I>id</I> --<I>id</I>
4744 variable pre-increment and pre-decrement
4748 unary minus and plus
4752 logical and bitwise negation
4760 multiplication, division, remainder
4764 addition, subtraction
4765 <DT><B><< >></B>
4768 left and right bitwise shifts
4769 <DT><B><= >= < ></B>
4776 equality and inequality
4784 bitwise exclusive OR
4789 <DT><B>&&</B>
4797 <DT><B></B><I>expr</I>?<I>expr</I>:<I>expr</I>
4800 conditional operator
4801 <DT><B>= *= /= %= += -= <<= >>= &= ^= |=</B>
4805 <DT><B></B><I>expr1</I> , <I>expr2</I>
4813 Shell variables are allowed as operands; parameter expansion is
4814 performed before the expression is evaluated.
4815 Within an expression, shell variables may also be referenced by name
4816 without using the parameter expansion syntax.
4817 A shell variable that is null or unset evaluates to 0 when referenced
4818 by name without using the parameter expansion syntax.
4819 The value of a variable is evaluated as an arithmetic expression
4820 when it is referenced, or when a variable which has been given the
4821 <I>integer</I> attribute using <B>declare -i</B> is assigned a value.
4822 A null value evaluates to 0.
4823 A shell variable need not have its integer attribute
4824 turned on to be used in an expression.
4827 Constants with a leading 0 are interpreted as octal numbers.
4828 A leading 0x or 0X denotes hexadecimal.
4829 Otherwise, numbers take the form [<I>base#</I>]n, where <I>base</I>
4830 is a decimal number between 2 and 64 representing the arithmetic
4831 base, and <I>n</I> is a number in that base.
4832 If <I>base#</I> is omitted, then base 10 is used.
4833 The digits greater than 9 are represented by the lowercase letters,
4834 the uppercase letters, @, and _, in that order.
4835 If <I>base</I> is less than or equal to 36, lowercase and uppercase
4836 letters may be used interchangeably to represent numbers between 10
4840 Operators are evaluated in order of precedence. Sub-expressions in
4841 parentheses are evaluated first and may override the precedence
4843 <A NAME="lbBW"> </A>
4844 <H3>CONDITIONAL EXPRESSIONS</H3>
4846 Conditional expressions are used by the <B>[[</B> compound command and
4847 the <B>test</B> and <B>[</B> builtin commands to test file attributes
4848 and perform string and arithmetic comparisons.
4849 Expressions are formed from the following unary or binary primaries.
4850 If any <I>file</I> argument to one of the primaries is of the form
4851 <I>/dev/fd/n</I>, then file descriptor <I>n</I> is checked.
4852 If the <I>file</I> argument to one of the primaries is one of
4853 <I>/dev/stdin</I>, <I>/dev/stdout</I>, or <I>/dev/stderr</I>, file
4854 descriptor 0, 1, or 2, respectively, is checked.
4857 Unless otherwise specified, primaries that operate on files follow symbolic
4858 links and operate on the target of the link, rather than the link itself.
4862 <DT><B>-a </B><I>file</I>
4865 True if <I>file</I> exists.
4866 <DT><B>-b </B><I>file</I>
4869 True if <I>file</I> exists and is a block special file.
4870 <DT><B>-c </B><I>file</I>
4873 True if <I>file</I> exists and is a character special file.
4874 <DT><B>-d </B><I>file</I>
4877 True if <I>file</I> exists and is a directory.
4878 <DT><B>-e </B><I>file</I>
4881 True if <I>file</I> exists.
4882 <DT><B>-f </B><I>file</I>
4885 True if <I>file</I> exists and is a regular file.
4886 <DT><B>-g </B><I>file</I>
4889 True if <I>file</I> exists and is set-group-id.
4890 <DT><B>-h </B><I>file</I>
4893 True if <I>file</I> exists and is a symbolic link.
4894 <DT><B>-k </B><I>file</I>
4897 True if <I>file</I> exists and its ``sticky'' bit is set.
4898 <DT><B>-p </B><I>file</I>
4901 True if <I>file</I> exists and is a named pipe (FIFO).
4902 <DT><B>-r </B><I>file</I>
4905 True if <I>file</I> exists and is readable.
4906 <DT><B>-s </B><I>file</I>
4909 True if <I>file</I> exists and has a size greater than zero.
4910 <DT><B>-t </B><I>fd</I>
4913 True if file descriptor
4916 is open and refers to a terminal.
4917 <DT><B>-u </B><I>file</I>
4920 True if <I>file</I> exists and its set-user-id bit is set.
4921 <DT><B>-w </B><I>file</I>
4924 True if <I>file</I> exists and is writable.
4925 <DT><B>-x </B><I>file</I>
4928 True if <I>file</I> exists and is executable.
4929 <DT><B>-O </B><I>file</I>
4932 True if <I>file</I> exists and is owned by the effective user id.
4933 <DT><B>-G </B><I>file</I>
4936 True if <I>file</I> exists and is owned by the effective group id.
4937 <DT><B>-L </B><I>file</I>
4940 True if <I>file</I> exists and is a symbolic link.
4941 <DT><B>-S </B><I>file</I>
4944 True if <I>file</I> exists and is a socket.
4945 <DT><B>-N </B><I>file</I>
4948 True if <I>file</I> exists and has been modified since it was last read.
4949 <DT><I>file1</I> -<B>nt</B> <I>file2</I><DD>
4950 True if <I>file1</I> is newer (according to modification date) than <I>file2</I>,
4951 or if <I>file1</I> exists and file2 does not.
4952 <DT><I>file1</I> -<B>ot</B> <I>file2</I><DD>
4953 True if <I>file1</I> is older than <I>file2</I>, or if <I>file2</I> exists
4954 and <I>file1</I> does not.
4955 <DT><I>file1</I> <B>-ef</B> <I>file2</I><DD>
4956 True if <I>file1</I> and <I>file2</I> refer to the same device and
4958 <DT><B>-o </B><I>optname</I>
4961 True if shell option
4965 See the list of options under the description of the
4972 <DT><B>-z </B><I>string</I>
4975 True if the length of <I>string</I> is zero.
4976 <DT><I>string</I><DD>
4978 <DT><B>-n </B><I>string</I>
4982 True if the length of
4986 <DT><I>string1</I> <B>==</B> <I>string2</I><DD>
4987 True if the strings are equal. <B>=</B> may be used in place of
4988 <B>==</B> for strict POSIX compliance.
4989 <DT><I>string1</I> <B>!=</B> <I>string2</I><DD>
4990 True if the strings are not equal.
4991 <DT><I>string1</I> <B><</B> <I>string2</I><DD>
4992 True if <I>string1</I> sorts before <I>string2</I> lexicographically
4993 in the current locale.
4994 <DT><I>string1</I> <B>></B> <I>string2</I><DD>
4995 True if <I>string1</I> sorts after <I>string2</I> lexicographically
4996 in the current locale.
4997 <DT><I>arg1</I> <B>OP</B> <I>arg2</I>
5000 <FONT SIZE=-1><B>OP</B>
5017 These arithmetic binary operators return true if <I>arg1</I>
5018 is equal to, not equal to, less than, less than or equal to,
5019 greater than, or greater than or equal to <I>arg2</I>, respectively.
5025 may be positive or negative integers.
5028 <A NAME="lbBX"> </A>
5029 <H3>SIMPLE COMMAND EXPANSION</H3>
5031 When a simple command is executed, the shell performs the following
5032 expansions, assignments, and redirections, from left to right.
5035 The words that the parser has marked as variable assignments (those
5036 preceding the command name) and redirections are saved for later
5039 The words that are not variable assignments or redirections are
5040 expanded. If any words remain after expansion, the first word
5041 is taken to be the name of the command and the remaining words are
5044 Redirections are performed as described above under
5045 <FONT SIZE=-1><B>REDIRECTION</B>.
5049 The text after the <B>=</B> in each variable assignment undergoes tilde
5050 expansion, parameter expansion, command substitution, arithmetic expansion,
5051 and quote removal before being assigned to the variable.
5055 If no command name results, the variable assignments affect the current
5056 shell environment. Otherwise, the variables are added to the environment
5057 of the executed command and do not affect the current shell environment.
5058 If any of the assignments attempts to assign a value to a readonly variable,
5059 an error occurs, and the command exits with a non-zero status.
5062 If no command name results, redirections are performed, but do not
5063 affect the current shell environment. A redirection error causes the
5064 command to exit with a non-zero status.
5067 If there is a command name left after expansion, execution proceeds as
5068 described below. Otherwise, the command exits. If one of the expansions
5069 contained a command substitution, the exit status of the command is
5070 the exit status of the last command substitution performed. If there
5071 were no command substitutions, the command exits with a status of zero.
5072 <A NAME="lbBY"> </A>
5073 <H3>COMMAND EXECUTION</H3>
5075 After a command has been split into words, if it results in a
5076 simple command and an optional list of arguments, the following
5080 If the command name contains no slashes, the shell attempts to
5081 locate it. If there exists a shell function by that name, that
5082 function is invoked as described above in
5083 <FONT SIZE=-1><B>FUNCTIONS</B>.
5086 If the name does not match a function, the shell searches for
5087 it in the list of shell builtins. If a match is found, that
5091 If the name is neither a shell function nor a builtin,
5092 and contains no slashes,
5095 searches each element of the
5096 <FONT SIZE=-1><B>PATH</B>
5099 for a directory containing an executable file by that name.
5102 uses a hash table to remember the full pathnames of executable
5107 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
5111 A full search of the directories in
5112 <FONT SIZE=-1><B>PATH</B>
5115 is performed only if the command is not found in the hash table.
5116 If the search is unsuccessful, the shell searches for a defined shell
5117 function named <B>command_not_found_handle</B>.
5118 If that function exists, it is invoked with the original command and
5119 the original command's arguments as its arguments, and the function's
5120 exit status becomes the exit status of the shell.
5121 If that function is not defined, the shell prints an error
5122 message and returns an exit status of 127.
5125 If the search is successful, or if the command name contains
5126 one or more slashes, the shell executes the named program in a
5127 separate execution environment.
5128 Argument 0 is set to the name given, and the remaining arguments
5129 to the command are set to the arguments given, if any.
5132 If this execution fails because the file is not in executable
5133 format, and the file is not a directory, it is assumed to be
5134 a <I>shell script</I>, a file
5135 containing shell commands. A subshell is spawned to execute
5136 it. This subshell reinitializes itself, so
5137 that the effect is as if a new shell had been invoked
5138 to handle the script, with the exception that the locations of
5139 commands remembered by the parent (see
5143 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>)</FONT>
5144 are retained by the child.
5147 If the program is a file beginning with
5150 the remainder of the first line specifies an interpreter
5151 for the program. The shell executes the
5152 specified interpreter on operating systems that do not
5153 handle this executable format themselves. The arguments to the
5154 interpreter consist of a single optional argument following the
5155 interpreter name on the first line of the program, followed
5156 by the name of the program, followed by the command
5158 <A NAME="lbBZ"> </A>
5159 <H3>COMMAND EXECUTION ENVIRONMENT</H3>
5161 The shell has an <I>execution environment</I>, which consists of the
5166 open files inherited by the shell at invocation, as modified by
5167 redirections supplied to the <B>exec</B> builtin
5169 the current working directory as set by <B>cd</B>, <B>pushd</B>, or
5170 <B>popd</B>, or inherited by the shell at invocation
5172 the file creation mode mask as set by <B>umask</B> or inherited from
5175 current traps set by <B>trap</B>
5177 shell parameters that are set by variable assignment or with <B>set</B>
5178 or inherited from the shell's parent in the environment
5180 shell functions defined during execution or inherited from the shell's
5181 parent in the environment
5183 options enabled at invocation (either by default or with command-line
5184 arguments) or by <B>set</B>
5186 options enabled by <B>shopt</B>
5188 shell aliases defined with <B>alias</B>
5190 various process IDs, including those of background jobs, the value
5191 of <B>$$</B>, and the value of <B>$PPID</B>
5195 When a simple command other than a builtin or shell function
5196 is to be executed, it
5197 is invoked in a separate execution environment that consists of
5198 the following. Unless otherwise noted, the values are inherited
5203 the shell's open files, plus any modifications and additions specified
5204 by redirections to the command
5206 the current working directory
5208 the file creation mode mask
5210 shell variables and functions marked for export, along with variables
5211 exported for the command, passed in the environment
5213 traps caught by the shell are reset to the values inherited from the
5214 shell's parent, and traps ignored by the shell are ignored
5218 A command invoked in this separate environment cannot affect the
5219 shell's execution environment.
5222 Command substitution, commands grouped with parentheses,
5223 and asynchronous commands are invoked in a
5224 subshell environment that is a duplicate of the shell environment,
5225 except that traps caught by the shell are reset to the values
5226 that the shell inherited from its parent at invocation. Builtin
5227 commands that are invoked as part of a pipeline are also executed in a
5228 subshell environment. Changes made to the subshell environment
5229 cannot affect the shell's execution environment.
5232 Subshells spawned to execute command substitutions inherit the value of
5233 the <B>-e</B> option from the parent shell. When not in posix mode,
5234 Bash clears the <B>-e</B> option in such subshells.
5237 If a command is followed by a <B>&</B> and job control is not active, the
5238 default standard input for the command is the empty file <I>/dev/null</I>.
5239 Otherwise, the invoked command inherits the file descriptors of the calling
5240 shell as modified by redirections.
5241 <A NAME="lbCA"> </A>
5242 <H3>ENVIRONMENT</H3>
5244 When a program is invoked it is given an array of strings
5249 <I>name</I>-<I>value</I> pairs, of the form
5254 The shell provides several ways to manipulate the environment.
5255 On invocation, the shell scans its own environment and
5256 creates a parameter for each name found, automatically marking
5260 to child processes. Executed commands inherit the environment.
5267 commands allow parameters and functions to be added to and
5268 deleted from the environment. If the value of a parameter
5269 in the environment is modified, the new value becomes part
5270 of the environment, replacing the old. The environment
5271 inherited by any executed command consists of the shell's
5272 initial environment, whose values may be modified in the shell,
5273 less any pairs removed by the
5276 command, plus any additions via the
5285 The environment for any
5286 <I>simple command</I>
5288 or function may be augmented temporarily by prefixing it with
5289 parameter assignments, as described above in
5290 <FONT SIZE=-1><B>PARAMETERS</B>.
5293 These assignment statements affect only the environment seen
5300 option is set (see the
5303 builtin command below), then
5306 parameter assignments are placed in the environment for a command,
5307 not just those that precede the command name.
5313 invokes an external command, the variable
5316 is set to the full file name of the command and passed to that
5317 command in its environment.
5318 <A NAME="lbCB"> </A>
5319 <H3>EXIT STATUS</H3>
5323 The exit status of an executed command is the value returned by the
5324 <I>waitpid</I> system call or equivalent function. Exit statuses
5325 fall between 0 and 255, though, as explained below, the shell may
5326 use values above 125 specially. Exit statuses from shell builtins and
5327 compound commands are also limited to this range. Under certain
5328 circumstances, the shell will use special values to indicate specific
5332 For the shell's purposes, a command which exits with a
5333 zero exit status has succeeded. An exit status of zero
5334 indicates success. A non-zero exit status indicates failure.
5335 When a command terminates on a fatal signal <I>N</I>, <B>bash</B> uses
5336 the value of 128+<I>N</I> as the exit status.
5339 If a command is not found, the child process created to
5340 execute it returns a status of 127. If a command is found
5341 but is not executable, the return status is 126.
5344 If a command fails because of an error during expansion or redirection,
5345 the exit status is greater than zero.
5348 Shell builtin commands return a status of 0 (<I>true</I>) if
5349 successful, and non-zero (<I>false</I>) if an error occurs
5351 All builtins return an exit status of 2 to indicate incorrect usage.
5354 <B>Bash</B> itself returns the exit status of the last command
5355 executed, unless a syntax error occurs, in which case it exits
5356 with a non-zero value. See also the <B>exit</B> builtin
5358 <A NAME="lbCC"> </A>
5361 When <B>bash</B> is interactive, in the absence of any traps, it ignores
5362 <FONT SIZE=-1><B>SIGTERM</B>
5365 (so that <B>kill 0</B> does not kill an interactive shell),
5367 <FONT SIZE=-1><B>SIGINT</B>
5370 is caught and handled (so that the <B>wait</B> builtin is interruptible).
5371 In all cases, <B>bash</B> ignores
5372 <FONT SIZE=-1><B>SIGQUIT</B>.
5375 If job control is in effect,
5379 <FONT SIZE=-1><B>SIGTTIN</B>,
5382 <FONT SIZE=-1><B>SIGTTOU</B>,
5386 <FONT SIZE=-1><B>SIGTSTP</B>.
5391 Non-builtin commands run by <B>bash</B> have signal handlers
5392 set to the values inherited by the shell from its parent.
5393 When job control is not in effect, asynchronous commands
5395 <FONT SIZE=-1><B>SIGINT</B>
5399 <FONT SIZE=-1><B>SIGQUIT</B>
5402 in addition to these inherited handlers.
5403 Commands run as a result of command substitution ignore the
5404 keyboard-generated job control signals
5405 <FONT SIZE=-1><B>SIGTTIN</B>,
5408 <FONT SIZE=-1><B>SIGTTOU</B>,
5412 <FONT SIZE=-1><B>SIGTSTP</B>.
5417 The shell exits by default upon receipt of a
5418 <FONT SIZE=-1><B>SIGHUP</B>.
5421 Before exiting, an interactive shell resends the
5422 <FONT SIZE=-1><B>SIGHUP</B>
5425 to all jobs, running or stopped.
5426 Stopped jobs are sent
5427 <FONT SIZE=-1><B>SIGCONT</B>
5430 to ensure that they receive the
5431 <FONT SIZE=-1><B>SIGHUP</B>.
5434 To prevent the shell from
5435 sending the signal to a particular job, it should be removed from the
5440 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
5445 <FONT SIZE=-1><B>SIGHUP</B>
5456 shell option has been set with
5462 <FONT SIZE=-1><B>SIGHUP</B>
5465 to all jobs when an interactive login shell exits.
5468 If <B>bash</B> is waiting for a command to complete and receives a signal
5469 for which a trap has been set, the trap will not be executed until
5470 the command completes.
5471 When <B>bash</B> is waiting for an asynchronous command via the <B>wait</B>
5472 builtin, the reception of a signal for which a trap has been set will
5473 cause the <B>wait</B> builtin to return immediately with an exit status
5474 greater than 128, immediately after which the trap is executed.
5475 <A NAME="lbCD"> </A>
5476 <H3>JOB CONTROL</H3>
5480 refers to the ability to selectively stop (<I>suspend</I>)
5481 the execution of processes and continue (<I>resume</I>)
5482 their execution at a later point. A user typically employs
5483 this facility via an interactive interface supplied jointly
5484 by the system's terminal driver and
5489 The shell associates a
5492 with each pipeline. It keeps a table of currently executing
5493 jobs, which may be listed with the
5499 starts a job asynchronously (in the
5502 it prints a line that looks like:
5503 <DL COMPACT><DT><DD>
5511 indicating that this job is job number 1 and that the process ID
5512 of the last process in the pipeline associated with this job is 25647.
5513 All of the processes in a single pipeline are members of the same job.
5519 abstraction as the basis for job control.
5522 To facilitate the implementation of the user interface to job
5523 control, the operating system maintains the notion of a <I>current terminal
5524 process group ID</I>. Members of this process group (processes whose
5525 process group ID is equal to the current terminal process group ID)
5526 receive keyboard-generated signals such as
5527 <FONT SIZE=-1><B>SIGINT</B>.
5530 These processes are said to be in the
5535 processes are those whose process group ID differs from the terminal's;
5536 such processes are immune to keyboard-generated signals.
5537 Only foreground processes are allowed to read from or write to the
5538 terminal. Background processes which attempt to read from (write to) the
5540 <FONT SIZE=-1><B>SIGTTIN (SIGTTOU)</B>
5543 signal by the terminal driver,
5544 which, unless caught, suspends the process.
5547 If the operating system on which
5554 contains facilities to use it.
5558 character (typically
5561 Control-Z) while a process is running
5562 causes that process to be stopped and returns control to
5566 <I>delayed suspend</I>
5568 character (typically
5571 Control-Y) causes the process to be stopped when it
5572 attempts to read input from the terminal, and control to
5576 The user may then manipulate the state of this job, using the
5579 command to continue it in the background, the
5582 command to continue it in the foreground, or
5586 command to kill it. A <B>^Z</B> takes effect immediately,
5587 and has the additional side effect of causing pending output
5588 and typeahead to be discarded.
5591 There are a number of ways to refer to a job in the shell.
5595 introduces a job specification (<I>jobspec</I>). Job number
5598 may be referred to as
5601 A job may also be referred to using a prefix of the name used to
5602 start it, or using a substring that appears in its command line.
5609 job. If a prefix matches more than one job,
5612 reports an error. Using
5615 on the other hand, refers to any job containing the string
5618 in its command line. If the substring matches more than one job,
5621 reports an error. The symbols
5627 refer to the shell's notion of the
5630 which is the last job stopped while it was in
5631 the foreground or started in the background.
5635 may be referenced using
5638 If there is only a single job, <B>%+</B> and <B>%-</B> can both be used
5639 to refer to that job.
5640 In output pertaining to jobs (e.g., the output of the
5643 command), the current job is always flagged with a
5646 and the previous job with a
5649 A single % (with no accompanying job specification) also refers to the
5653 Simply naming a job can be used to bring it into the
5659 bringing job 1 from the background into the foreground.
5663 resumes job 1 in the background, equivalent to
5667 The shell learns immediately whenever a job changes state.
5671 waits until it is about to print a prompt before reporting
5672 changes in a job's status so as to not interrupt
5673 any other output. If the
5683 reports such changes immediately.
5685 <FONT SIZE=-1><B>SIGCHLD</B>
5688 is executed for each child that exits.
5691 If an attempt to exit
5694 is made while jobs are stopped (or, if the <B>checkjobs</B> shell option has
5695 been enabled using the <B>shopt</B> builtin, running), the shell prints a
5696 warning message, and, if the <B>checkjobs</B> option is enabled, lists the
5697 jobs and their statuses.
5701 command may then be used to inspect their status.
5702 If a second attempt to exit is made without an intervening command,
5703 the shell does not print another warning, and any stopped
5704 jobs are terminated.
5705 <A NAME="lbCE"> </A>
5708 When executing interactively,
5711 displays the primary prompt
5712 <FONT SIZE=-1><B>PS1</B>
5715 when it is ready to read a command, and the secondary prompt
5716 <FONT SIZE=-1><B>PS2</B>
5719 when it needs more input to complete a command.
5722 allows these prompt strings to be customized by inserting a number of
5723 backslash-escaped special characters that are decoded as follows:
5724 <DL COMPACT><DT><DD>
5730 an ASCII bell character (07)
5734 the date in "Weekday Month Date" format (e.g., "Tue May 26")
5735 <DT><B>\D{</B><I>format</I>}
5738 the <I>format</I> is passed to <I>strftime</I>(3) and the result is inserted
5739 into the prompt string; an empty <I>format</I> results in a locale-specific
5740 time representation. The braces are required
5744 an ASCII escape character (033)
5748 the hostname up to the first `.'
5756 the number of jobs currently managed by the shell
5760 the basename of the shell's terminal device name
5772 the name of the shell, the basename of
5775 (the portion following the final slash)
5779 the current time in 24-hour HH:MM:SS format
5783 the current time in 12-hour HH:MM:SS format
5787 the current time in 12-hour am/pm format
5791 the current time in 24-hour HH:MM format
5795 the username of the current user
5799 the version of <B>bash</B> (e.g., 2.00)
5803 the release of <B>bash</B>, version + patch level (e.g., 2.00.0)
5807 the current working directory, with <B>$HOME</B> abbreviated with a tilde
5808 (uses the <B>$PROMPT_DIRTRIM</B> variable)
5812 the basename of the current working directory, with <B>$HOME</B>
5813 abbreviated with a tilde
5817 the history number of this command
5821 the command number of this command
5825 if the effective UID is 0, a
5831 <DT><B>\</B><I>nnn</I>
5834 the character corresponding to the octal number <I>nnn</I>
5842 begin a sequence of non-printing characters, which could be used to
5843 embed a terminal control sequence into the prompt
5847 end a sequence of non-printing characters
5853 The command number and the history number are usually different:
5854 the history number of a command is its position in the history
5855 list, which may include commands restored from the history file
5857 <FONT SIZE=-1><B>HISTORY</B>
5860 below), while the command number is the position in the sequence
5861 of commands executed during the current shell session.
5862 After the string is decoded, it is expanded via
5863 parameter expansion, command substitution, arithmetic
5864 expansion, and quote removal, subject to the value of the
5867 shell option (see the description of the
5871 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
5875 <A NAME="lbCF"> </A>
5878 This is the library that handles reading input when using an interactive
5882 option is given at shell invocation.
5883 Line editing is also used when using the <B>-e</B> option to the
5884 <B>read</B> builtin.
5885 By default, the line editing commands are similar to those of emacs.
5886 A vi-style line editing interface is also available.
5887 Line editing can be enabled at any time using the
5897 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
5901 To turn off line editing after the shell is running, use the
5911 <A NAME="lbCG"> </A>
5912 <H4>Readline Notation</H4>
5916 In this section, the emacs-style notation is used to denote
5917 keystrokes. Control keys are denoted by C-<I>key</I>, e.g., C-n
5918 means Control-N. Similarly,
5921 keys are denoted by M-<I>key</I>, so M-x means Meta-X. (On keyboards
5925 key, M-<I>x</I> means ESC <I>x</I>, i.e., press the Escape key
5929 key. This makes ESC the <I>meta prefix</I>.
5930 The combination M-C-<I>x</I> means ESC-Control-<I>x</I>,
5931 or press the Escape key
5932 then hold the Control key while pressing the
5938 Readline commands may be given numeric
5941 which normally act as a repeat count.
5942 Sometimes, however, it is the sign of the argument that is significant.
5943 Passing a negative argument to a command that acts in the forward
5944 direction (e.g., <B>kill-line</B>) causes that command to act in a
5946 Commands whose behavior with arguments deviates from this are noted
5950 When a command is described as <I>killing</I> text, the text
5951 deleted is saved for possible future retrieval
5952 (<I>yanking</I>). The killed text is saved in a
5953 <I>kill ring</I>. Consecutive kills cause the text to be
5954 accumulated into one unit, which can be yanked all at once.
5955 Commands which do not kill text separate the chunks of text
5957 <A NAME="lbCH"> </A>
5958 <H4>Readline Initialization</H4>
5962 Readline is customized by putting commands in an initialization
5963 file (the <I>inputrc</I> file).
5964 The name of this file is taken from the value of the
5965 <FONT SIZE=-1><B>INPUTRC</B>
5968 variable. If that variable is unset, the default is
5969 <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A>.
5971 When a program which uses the readline library starts up, the
5972 initialization file is read, and the key bindings and variables
5974 There are only a few basic constructs allowed in the
5975 readline initialization file.
5976 Blank lines are ignored.
5977 Lines beginning with a <B>#</B> are comments.
5978 Lines beginning with a <B>$</B> indicate conditional constructs.
5979 Other lines denote key bindings and variable settings.
5982 The default key-bindings may be changed with an
5986 Other programs that use this library may add their own commands
5990 For example, placing
5991 <DL COMPACT><DT><DD>
5994 M-Control-u: universal-argument
5998 <DL COMPACT><DT><DD>
5999 C-Meta-u: universal-argument
6005 would make M-C-u execute the readline command
6006 <I>universal-argument</I>.
6010 The following symbolic character names are recognized:
6034 In addition to command names, readline allows keys to be bound
6035 to a string that is inserted when the key is pressed (a <I>macro</I>).
6036 <A NAME="lbCI"> </A>
6037 <H4>Readline Key Bindings</H4>
6041 The syntax for controlling key bindings in the
6044 file is simple. All that is required is the name of the
6045 command or the text of a macro and a key sequence to which
6046 it should be bound. The name may be specified in one of two ways:
6047 as a symbolic key name, possibly with <I>Meta-</I> or <I>Control-</I>
6048 prefixes, or as a key sequence.
6051 When using the form <B>keyname</B>:<I>function-name</I> or <I>macro</I>,
6054 is the name of a key spelled out in English. For example:
6056 <DL COMPACT><DT><DD>
6057 Control-u: universal-argument
6060 Meta-Rubout: backward-kill-word
6063 Control-o: "> output"
6068 In the above example,
6071 is bound to the function
6072 <B>universal-argument</B>,
6076 is bound to the function
6077 <B>backward-kill-word</B>,
6082 is bound to run the macro
6083 expressed on the right hand side (that is, to insert the text
6084 <TT>> output</TT>
6089 In the second form, <B>"keyseq"</B>:<I>function-name</I> or <I>macro</I>,
6095 above in that strings denoting
6096 an entire key sequence may be specified by placing the sequence
6097 within double quotes. Some GNU Emacs style key escapes can be
6098 used, as in the following example, but the symbolic character names
6101 <DL COMPACT><DT><DD>
6102 "\C-u": universal-argument
6105 "\C-x\C-r": re-read-init-file
6108 "\e[11~": "Function Key 1"
6116 is again bound to the function
6117 <B>universal-argument</B>.
6121 is bound to the function
6122 <B>re-read-init-file</B>,
6127 is bound to insert the text
6128 <TT>Function Key 1</TT>.
6132 The full set of GNU Emacs style escape sequences is
6133 <DL COMPACT><DT><DD>
6165 In addition to the GNU Emacs style escape sequences, a second
6166 set of backslash escapes is available:
6167 <DL COMPACT><DT><DD>
6202 <DT><B>\</B><I>nnn</I>
6205 the eight-bit character whose value is the octal value <I>nnn</I>
6206 (one to three digits)
6207 <DT><B>\x</B><I>HH</I>
6210 the eight-bit character whose value is the hexadecimal value <I>HH</I>
6211 (one or two hex digits)
6217 When entering the text of a macro, single or double quotes must
6218 be used to indicate a macro definition.
6219 Unquoted text is assumed to be a function name.
6220 In the macro body, the backslash escapes described above are expanded.
6221 Backslash will quote any other character in the macro text,
6222 including " and aq.
6227 allows the current readline key bindings to be displayed or modified
6231 builtin command. The editing mode may be switched during interactive
6238 builtin command (see
6239 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
6243 <A NAME="lbCJ"> </A>
6244 <H4>Readline Variables</H4>
6248 Readline has variables that can be used to further customize its
6249 behavior. A variable may be set in the
6252 file with a statement of the form
6253 <DL COMPACT><DT><DD>
6256 <B>set</B> <I>variable-name</I> <I>value</I>
6261 Except where noted, readline variables can take the values
6267 (without regard to case).
6268 Unrecognized variable names are ignored.
6269 When a variable value is read, empty or null values, "on" (case-insensitive),
6270 and "1" are equivalent to <B>On</B>. All other values are equivalent to
6272 The variables and their default values are:
6277 <DT><B>bell-style (audible)</B>
6280 Controls what happens when readline wants to ring the terminal bell.
6281 If set to <B>none</B>, readline never rings the bell. If set to
6282 <B>visible</B>, readline uses a visible bell if one is available.
6283 If set to <B>audible</B>, readline attempts to ring the terminal's bell.
6284 <DT><B>bind-tty-special-chars (On)</B>
6287 If set to <B>On</B>, readline attempts to bind the control characters
6288 treated specially by the kernel's terminal driver to their readline
6290 <DT><B>comment-begin (``#'')</B>
6293 The string that is inserted when the readline
6294 <B>insert-comment</B>
6296 command is executed.
6297 This command is bound to
6300 in emacs mode and to
6304 <DT><B>completion-ignore-case (Off)</B>
6307 If set to <B>On</B>, readline performs filename matching and completion
6308 in a case-insensitive fashion.
6309 <DT><B>completion-prefix-display-length (0)</B>
6312 The length in characters of the common prefix of a list of possible
6313 completions that is displayed without modification. When set to a
6314 value greater than zero, common prefixes longer than this value are
6315 replaced with an ellipsis when displaying possible completions.
6316 <DT><B>completion-query-items (100)</B>
6319 This determines when the user is queried about viewing
6320 the number of possible completions
6321 generated by the <B>possible-completions</B> command.
6322 It may be set to any integer value greater than or equal to
6323 zero. If the number of possible completions is greater than
6324 or equal to the value of this variable, the user is asked whether
6325 or not he wishes to view them; otherwise they are simply listed
6327 <DT><B>convert-meta (On)</B>
6330 If set to <B>On</B>, readline will convert characters with the
6331 eighth bit set to an ASCII key sequence
6332 by stripping the eighth bit and prefixing an
6333 escape character (in effect, using escape as the <I>meta prefix</I>).
6334 <DT><B>disable-completion (Off)</B>
6337 If set to <B>On</B>, readline will inhibit word completion. Completion
6338 characters will be inserted into the line as if they had been
6339 mapped to <B>self-insert</B>.
6340 <DT><B>editing-mode (emacs)</B>
6343 Controls whether readline begins with a set of key bindings similar
6344 to <I>emacs</I> or <I>vi</I>.
6347 can be set to either
6353 <DT><B>enable-keypad (Off)</B>
6356 When set to <B>On</B>, readline will try to enable the application
6357 keypad when it is called. Some systems need this to enable the
6359 <DT><B>expand-tilde (Off)</B>
6362 If set to <B>on</B>, tilde expansion is performed when readline
6363 attempts word completion.
6364 <DT><B>history-preserve-point (Off)</B>
6367 If set to <B>on</B>, the history code attempts to place point at the
6368 same location on each history line retrieved with <B>previous-history</B>
6369 or <B>next-history</B>.
6370 <DT><B>history-size (0)</B>
6373 Set the maximum number of history entries saved in the history list. If
6374 set to zero, the number of entries in the history list is not limited.
6375 <DT><B>horizontal-scroll-mode (Off)</B>
6378 When set to <B>On</B>, makes readline use a single line for display,
6379 scrolling the input horizontally on a single screen line when it
6380 becomes longer than the screen width rather than wrapping to a new line.
6381 <DT><B>input-meta (Off)</B>
6384 If set to <B>On</B>, readline will enable eight-bit input (that is,
6385 it will not strip the high bit from the characters it reads),
6386 regardless of what the terminal claims it can support. The name
6389 is a synonym for this variable.
6390 <DT><B>isearch-terminators (``C-[C-J'')</B>
6393 The string of characters that should terminate an incremental
6394 search without subsequently executing the character as a command.
6395 If this variable has not been given a value, the characters
6396 <I>ESC</I> and <I>C-J</I> will terminate an incremental search.
6397 <DT><B>keymap (emacs)</B>
6400 Set the current readline keymap. The set of valid keymap names is
6401 <I>emacs, emacs-standard, emacs-meta, emacs-ctlx, vi,
6405 <I>vi</I> is equivalent to <I>vi-command</I>; <I>emacs</I> is
6406 equivalent to <I>emacs-standard</I>. The default value is
6412 also affects the default keymap.
6413 <DT><B>mark-directories (On)</B>
6416 If set to <B>On</B>, completed directory names have a slash
6418 <DT><B>mark-modified-lines (Off)</B>
6421 If set to <B>On</B>, history lines that have been modified are displayed
6422 with a preceding asterisk (<B>*</B>).
6423 <DT><B>mark-symlinked-directories (Off)</B>
6426 If set to <B>On</B>, completed names which are symbolic links to directories
6427 have a slash appended (subject to the value of
6428 <B>mark-directories</B>).
6429 <DT><B>match-hidden-files (On)</B>
6432 This variable, when set to <B>On</B>, causes readline to match files whose
6433 names begin with a `.' (hidden files) when performing filename
6434 completion, unless the leading `.' is
6435 supplied by the user in the filename to be completed.
6436 <DT><B>output-meta (Off)</B>
6439 If set to <B>On</B>, readline will display characters with the
6440 eighth bit set directly rather than as a meta-prefixed escape
6442 <DT><B>page-completions (On)</B>
6445 If set to <B>On</B>, readline uses an internal <I>more</I>-like pager
6446 to display a screenful of possible completions at a time.
6447 <DT><B>print-completions-horizontally (Off)</B>
6450 If set to <B>On</B>, readline will display completions with matches
6451 sorted horizontally in alphabetical order, rather than down the screen.
6452 <DT><B>revert-all-at-newline (Off)</B>
6455 If set to <B>on</B>, readline will undo all changes to history lines
6456 before returning when <B>accept-line</B> is executed. By default,
6457 history lines may be modified and retain individual undo lists across
6458 calls to <B>readline</B>.
6459 <DT><B>show-all-if-ambiguous (Off)</B>
6462 This alters the default behavior of the completion functions. If
6466 words which have more than one possible completion cause the
6467 matches to be listed immediately instead of ringing the bell.
6468 <DT><B>show-all-if-unmodified (Off)</B>
6471 This alters the default behavior of the completion functions in
6472 a fashion similar to <B>show-all-if-ambiguous</B>.
6476 words which have more than one possible completion without any
6477 possible partial completion (the possible completions don't share
6478 a common prefix) cause the matches to be listed immediately instead
6479 of ringing the bell.
6480 <DT><B>visible-stats (Off)</B>
6483 If set to <B>On</B>, a character denoting a file's type as reported
6484 by <I>stat</I>(2) is appended to the filename when listing possible
6488 <A NAME="lbCK"> </A>
6489 <H4>Readline Conditional Constructs</H4>
6493 Readline implements a facility similar in spirit to the conditional
6494 compilation features of the C preprocessor which allows key
6495 bindings and variable settings to be performed as the result
6496 of tests. There are four parser directives used.
6502 construct allows bindings to be made based on the
6503 editing mode, the terminal being used, or the application using
6504 readline. The text of the test extends to the end of the line;
6505 no characters are required to isolate it.
6506 <DL COMPACT><DT><DD>
6509 The <B>mode=</B> form of the <B>$if</B> directive is used to test
6510 whether readline is in emacs or vi mode.
6511 This may be used in conjunction
6512 with the <B>set keymap</B> command, for instance, to set bindings in
6513 the <I>emacs-standard</I> and <I>emacs-ctlx</I> keymaps only if
6514 readline is starting out in emacs mode.
6516 The <B>term=</B> form may be used to include terminal-specific
6517 key bindings, perhaps to bind the key sequences output by the
6518 terminal's function keys. The word on the right side of the
6521 is tested against the both full name of the terminal and the portion
6522 of the terminal name before the first <B>-</B>. This allows
6532 <DT><B>application</B><DD>
6533 The <B>application</B> construct is used to include
6534 application-specific settings. Each program using the readline
6535 library sets the <I>application name</I>, and an initialization
6536 file can test for a particular value.
6537 This could be used to bind key sequences to functions useful for
6538 a specific program. For instance, the following command adds a
6539 key sequence that quotes the current or previous word in Bash:
6541 <DL COMPACT><DT><DD>
6544 # Quote the current or previous word
6545 "\C-xq": "\eb\"\ef\""
6553 <DT><B>$endif</B><DD>
6554 This command, as seen in the previous example, terminates an
6556 <DT><B>$else</B><DD>
6557 Commands in this branch of the <B>$if</B> directive are executed if
6559 <DT><B>$include</B><DD>
6560 This directive takes a single filename as an argument and reads commands
6561 and bindings from that file. For example, the following directive
6562 would read <A HREF="file:/etc/inputrc"><I>/etc/inputrc</I></A>:
6564 <DL COMPACT><DT><DD>
6566 <B>$include</B> <A HREF="file:/etc/inputrc"><I>/etc/inputrc</I></A>
6572 <A NAME="lbCL"> </A>
6577 Readline provides commands for searching through the command history
6579 <FONT SIZE=-1><B>HISTORY</B>
6582 below) for lines containing a specified string.
6583 There are two search modes:
6587 <I>non-incremental</I>.
6591 Incremental searches begin before the user has finished typing the
6593 As each character of the search string is typed, readline displays
6594 the next entry from the history matching the string typed so far.
6595 An incremental search requires only as many characters as needed to
6596 find the desired history entry.
6597 The characters present in the value of the <B>isearch-terminators</B>
6598 variable are used to terminate an incremental search.
6599 If that variable has not been assigned a value the Escape and
6600 Control-J characters will terminate an incremental search.
6601 Control-G will abort an incremental search and restore the original
6603 When the search is terminated, the history entry containing the
6604 search string becomes the current line.
6607 To find other matching entries in the history list, type Control-S or
6608 Control-R as appropriate.
6609 This will search backward or forward in the history for the next
6610 entry matching the search string typed so far.
6611 Any other key sequence bound to a readline command will terminate
6612 the search and execute that command.
6613 For instance, a <I>newline</I> will terminate the search and accept
6614 the line, thereby executing the command from the history list.
6617 Readline remembers the last incremental search string. If two
6618 Control-Rs are typed without any intervening characters defining a
6619 new search string, any remembered search string is used.
6622 Non-incremental searches read the entire search string before starting
6623 to search for matching history lines. The search string may be
6624 typed by the user or be part of the contents of the current line.
6625 <A NAME="lbCM"> </A>
6626 <H4>Readline Command Names</H4>
6630 The following is a list of the names of the commands and the default
6631 key sequences to which they are bound.
6632 Command names without an accompanying key sequence are unbound by default.
6633 In the following descriptions, <I>point</I> refers to the current cursor
6634 position, and <I>mark</I> refers to a cursor position saved by the
6635 <B>set-mark</B> command.
6636 The text between the point and mark is referred to as the <I>region</I>.
6637 <A NAME="lbCN"> </A>
6638 <H4>Commands for Moving</H4>
6644 <DT><B>beginning-of-line (C-a)</B>
6647 Move to the start of the current line.
6648 <DT><B>end-of-line (C-e)</B>
6651 Move to the end of the line.
6652 <DT><B>forward-char (C-f)</B>
6655 Move forward a character.
6656 <DT><B>backward-char (C-b)</B>
6659 Move back a character.
6660 <DT><B>forward-word (M-f)</B>
6663 Move forward to the end of the next word. Words are composed of
6664 alphanumeric characters (letters and digits).
6665 <DT><B>backward-word (M-b)</B>
6668 Move back to the start of the current or previous word.
6669 Words are composed of alphanumeric characters (letters and digits).
6670 <DT><B>shell-forward-word</B>
6673 Move forward to the end of the next word.
6674 Words are delimited by non-quoted shell metacharacters.
6675 <DT><B>shell-backward-word</B>
6678 Move back to the start of the current or previous word.
6679 Words are delimited by non-quoted shell metacharacters.
6680 <DT><B>clear-screen (C-l)</B>
6683 Clear the screen leaving the current line at the top of the screen.
6684 With an argument, refresh the current line without clearing the
6686 <DT><B>redraw-current-line</B>
6689 Refresh the current line.
6692 <A NAME="lbCO"> </A>
6693 <H4>Commands for Manipulating the History</H4>
6699 <DT><B>accept-line (Newline, Return)</B>
6702 Accept the line regardless of where the cursor is. If this line is
6703 non-empty, add it to the history list according to the state of the
6704 <FONT SIZE=-1><B>HISTCONTROL</B>
6707 variable. If the line is a modified history
6708 line, then restore the history line to its original state.
6709 <DT><B>previous-history (C-p)</B>
6712 Fetch the previous command from the history list, moving back in
6714 <DT><B>next-history (C-n)</B>
6717 Fetch the next command from the history list, moving forward in the
6719 <DT><B>beginning-of-history (M-<)</B>
6722 Move to the first line in the history.
6723 <DT><B>end-of-history (M->)</B>
6726 Move to the end of the input history, i.e., the line currently being
6728 <DT><B>reverse-search-history (C-r)</B>
6731 Search backward starting at the current line and moving `up' through
6732 the history as necessary. This is an incremental search.
6733 <DT><B>forward-search-history (C-s)</B>
6736 Search forward starting at the current line and moving `down' through
6737 the history as necessary. This is an incremental search.
6738 <DT><B>non-incremental-reverse-search-history (M-p)</B>
6741 Search backward through the history starting at the current line
6742 using a non-incremental search for a string supplied by the user.
6743 <DT><B>non-incremental-forward-search-history (M-n)</B>
6746 Search forward through the history using a non-incremental search for
6747 a string supplied by the user.
6748 <DT><B>history-search-forward</B>
6751 Search forward through the history for the string of characters
6752 between the start of the current line and the point.
6753 This is a non-incremental search.
6754 <DT><B>history-search-backward</B>
6757 Search backward through the history for the string of characters
6758 between the start of the current line and the point.
6759 This is a non-incremental search.
6760 <DT><B>yank-nth-arg (M-C-y)</B>
6763 Insert the first argument to the previous command (usually
6764 the second word on the previous line) at point.
6768 insert the <I>n</I>th word from the previous command (the words
6769 in the previous command begin with word 0). A negative argument
6770 inserts the <I>n</I>th word from the end of the previous command.
6771 Once the argument <I>n</I> is computed, the argument is extracted
6772 as if the "!<I>n</I>" history expansion had been specified.
6773 <DT><B>yank-last-arg (M-., M-_)</B>
6776 Insert the last argument to the previous command (the last word of
6777 the previous history entry). With an argument,
6778 behave exactly like <B>yank-nth-arg</B>.
6779 Successive calls to <B>yank-last-arg</B> move back through the history
6780 list, inserting the last argument of each line in turn.
6781 The history expansion facilities are used to extract the last argument,
6782 as if the "!$" history expansion had been specified.
6783 <DT><B>shell-expand-line (M-C-e)</B>
6786 Expand the line as the shell does. This
6787 performs alias and history expansion as well as all of the shell
6788 word expansions. See
6789 <FONT SIZE=-1><B>HISTORY EXPANSION</B>
6792 below for a description of history expansion.
6793 <DT><B>history-expand-line (M-^)</B>
6796 Perform history expansion on the current line.
6798 <FONT SIZE=-1><B>HISTORY EXPANSION</B>
6801 below for a description of history expansion.
6802 <DT><B>magic-space</B>
6805 Perform history expansion on the current line and insert a space.
6807 <FONT SIZE=-1><B>HISTORY EXPANSION</B>
6810 below for a description of history expansion.
6811 <DT><B>alias-expand-line</B>
6814 Perform alias expansion on the current line.
6816 <FONT SIZE=-1><B>ALIASES</B>
6819 above for a description of alias expansion.
6820 <DT><B>history-and-alias-expand-line</B>
6823 Perform history and alias expansion on the current line.
6824 <DT><B>insert-last-argument (M-., M-_)</B>
6827 A synonym for <B>yank-last-arg</B>.
6828 <DT><B>operate-and-get-next (C-o)</B>
6831 Accept the current line for execution and fetch the next line
6832 relative to the current line from the history for editing. Any
6833 argument is ignored.
6834 <DT><B>edit-and-execute-command (C-xC-e)</B>
6837 Invoke an editor on the current command line, and execute the result as shell
6839 <B>Bash</B> attempts to invoke
6840 <FONT SIZE=-1><B>$VISUAL</B>,
6843 <FONT SIZE=-1><B>$EDITOR</B>,
6846 and <I>emacs</I> as the editor, in that order.
6849 <A NAME="lbCP"> </A>
6850 <H4>Commands for Changing Text</H4>
6856 <DT><B>delete-char (C-d)</B>
6859 Delete the character at point. If point is at the
6860 beginning of the line, there are no characters in the line, and
6861 the last character typed was not bound to <B>delete-char</B>,
6863 <FONT SIZE=-1><B>EOF</B>.
6866 <DT><B>backward-delete-char (Rubout)</B>
6869 Delete the character behind the cursor. When given a numeric argument,
6870 save the deleted text on the kill ring.
6871 <DT><B>forward-backward-delete-char</B>
6874 Delete the character under the cursor, unless the cursor is at the
6875 end of the line, in which case the character behind the cursor is
6877 <DT><B>quoted-insert (C-q, C-v)</B>
6880 Add the next character typed to the line verbatim. This is
6881 how to insert characters like <B>C-q</B>, for example.
6882 <DT><B>tab-insert (C-v TAB)</B>
6885 Insert a tab character.
6886 <DT><B>self-insert (a, b, A, 1, !, ...)</B>
6889 Insert the character typed.
6890 <DT><B>transpose-chars (C-t)</B>
6893 Drag the character before point forward over the character at point,
6894 moving point forward as well.
6895 If point is at the end of the line, then this transposes
6896 the two characters before point.
6897 Negative arguments have no effect.
6898 <DT><B>transpose-words (M-t)</B>
6901 Drag the word before point past the word after point,
6902 moving point over that word as well.
6903 If point is at the end of the line, this transposes
6904 the last two words on the line.
6905 <DT><B>upcase-word (M-u)</B>
6908 Uppercase the current (or following) word. With a negative argument,
6909 uppercase the previous word, but do not move point.
6910 <DT><B>downcase-word (M-l)</B>
6913 Lowercase the current (or following) word. With a negative argument,
6914 lowercase the previous word, but do not move point.
6915 <DT><B>capitalize-word (M-c)</B>
6918 Capitalize the current (or following) word. With a negative argument,
6919 capitalize the previous word, but do not move point.
6920 <DT><B>overwrite-mode</B>
6923 Toggle overwrite mode. With an explicit positive numeric argument,
6924 switches to overwrite mode. With an explicit non-positive numeric
6925 argument, switches to insert mode. This command affects only
6926 <B>emacs</B> mode; <B>vi</B> mode does overwrite differently.
6927 Each call to <I>readline()</I> starts in insert mode.
6928 In overwrite mode, characters bound to <B>self-insert</B> replace
6929 the text at point rather than pushing the text to the right.
6930 Characters bound to <B>backward-delete-char</B> replace the character
6931 before point with a space. By default, this command is unbound.
6934 <A NAME="lbCQ"> </A>
6935 <H4>Killing and Yanking</H4>
6941 <DT><B>kill-line (C-k)</B>
6944 Kill the text from point to the end of the line.
6945 <DT><B>backward-kill-line (C-x Rubout)</B>
6948 Kill backward to the beginning of the line.
6949 <DT><B>unix-line-discard (C-u)</B>
6952 Kill backward from point to the beginning of the line.
6953 The killed text is saved on the kill-ring.
6955 <DT><B>kill-whole-line</B>
6958 Kill all characters on the current line, no matter where point is.
6959 <DT><B>kill-word (M-d)</B>
6962 Kill from point to the end of the current word, or if between
6963 words, to the end of the next word.
6964 Word boundaries are the same as those used by <B>forward-word</B>.
6965 <DT><B>backward-kill-word (M-Rubout)</B>
6968 Kill the word behind point.
6969 Word boundaries are the same as those used by <B>backward-word</B>.
6970 <DT><B>shell-kill-word (M-d)</B>
6973 Kill from point to the end of the current word, or if between
6974 words, to the end of the next word.
6975 Word boundaries are the same as those used by <B>shell-forward-word</B>.
6976 <DT><B>shell-backward-kill-word (M-Rubout)</B>
6979 Kill the word behind point.
6980 Word boundaries are the same as those used by <B>shell-backward-word</B>.
6981 <DT><B>unix-word-rubout (C-w)</B>
6984 Kill the word behind point, using white space as a word boundary.
6985 The killed text is saved on the kill-ring.
6986 <DT><B>unix-filename-rubout</B>
6989 Kill the word behind point, using white space and the slash character
6990 as the word boundaries.
6991 The killed text is saved on the kill-ring.
6992 <DT><B>delete-horizontal-space (M-\)</B>
6995 Delete all spaces and tabs around point.
6996 <DT><B>kill-region</B>
6999 Kill the text in the current region.
7000 <DT><B>copy-region-as-kill</B>
7003 Copy the text in the region to the kill buffer.
7004 <DT><B>copy-backward-word</B>
7007 Copy the word before point to the kill buffer.
7008 The word boundaries are the same as <B>backward-word</B>.
7009 <DT><B>copy-forward-word</B>
7012 Copy the word following point to the kill buffer.
7013 The word boundaries are the same as <B>forward-word</B>.
7014 <DT><B>yank (C-y)</B>
7017 Yank the top of the kill ring into the buffer at point.
7018 <DT><B>yank-pop (M-y)</B>
7021 Rotate the kill ring, and yank the new top. Only works following
7029 <A NAME="lbCR"> </A>
7030 <H4>Numeric Arguments</H4>
7036 <DT><B>digit-argument (M-0, M-1, ..., M--)</B>
7039 Add this digit to the argument already accumulating, or start a new
7040 argument. M-- starts a negative argument.
7041 <DT><B>universal-argument</B>
7044 This is another way to specify an argument.
7045 If this command is followed by one or more digits, optionally with a
7046 leading minus sign, those digits define the argument.
7047 If the command is followed by digits, executing
7048 <B>universal-argument</B>
7050 again ends the numeric argument, but is otherwise ignored.
7051 As a special case, if this command is immediately followed by a
7052 character that is neither a digit or minus sign, the argument count
7053 for the next command is multiplied by four.
7054 The argument count is initially one, so executing this function the
7055 first time makes the argument count four, a second time makes the
7056 argument count sixteen, and so on.
7059 <A NAME="lbCS"> </A>
7066 <DT><B>complete (TAB)</B>
7069 Attempt to perform completion on the text before point.
7072 attempts completion treating the text as a variable (if the
7073 text begins with <B>$</B>), username (if the text begins with
7074 <B>~</B>), hostname (if the text begins with <B>@</B>), or
7075 command (including aliases and functions) in turn. If none
7076 of these produces a match, filename completion is attempted.
7077 <DT><B>possible-completions (M-?)</B>
7080 List the possible completions of the text before point.
7081 <DT><B>insert-completions (M-*)</B>
7084 Insert all completions of the text before point
7085 that would have been generated by
7086 <B>possible-completions</B>.
7087 <DT><B>menu-complete</B>
7090 Similar to <B>complete</B>, but replaces the word to be completed
7091 with a single match from the list of possible completions.
7092 Repeated execution of <B>menu-complete</B> steps through the list
7093 of possible completions, inserting each match in turn.
7094 At the end of the list of completions, the bell is rung
7095 (subject to the setting of <B>bell-style</B>)
7096 and the original text is restored.
7097 An argument of <I>n</I> moves <I>n</I> positions forward in the list
7098 of matches; a negative argument may be used to move backward
7100 This command is intended to be bound to <B>TAB</B>, but is unbound
7102 <DT><B>delete-char-or-list</B>
7105 Deletes the character under the cursor if not at the beginning or
7106 end of the line (like <B>delete-char</B>).
7107 If at the end of the line, behaves identically to
7108 <B>possible-completions</B>.
7109 This command is unbound by default.
7110 <DT><B>complete-filename (M-/)</B>
7113 Attempt filename completion on the text before point.
7114 <DT><B>possible-filename-completions (C-x /)</B>
7117 List the possible completions of the text before point,
7118 treating it as a filename.
7119 <DT><B>complete-username (M-~)</B>
7122 Attempt completion on the text before point, treating
7124 <DT><B>possible-username-completions (C-x ~)</B>
7127 List the possible completions of the text before point,
7128 treating it as a username.
7129 <DT><B>complete-variable (M-$)</B>
7132 Attempt completion on the text before point, treating
7133 it as a shell variable.
7134 <DT><B>possible-variable-completions (C-x $)</B>
7137 List the possible completions of the text before point,
7138 treating it as a shell variable.
7139 <DT><B>complete-hostname (M-@)</B>
7142 Attempt completion on the text before point, treating
7144 <DT><B>possible-hostname-completions (C-x @)</B>
7147 List the possible completions of the text before point,
7148 treating it as a hostname.
7149 <DT><B>complete-command (M-!)</B>
7152 Attempt completion on the text before point, treating
7153 it as a command name. Command completion attempts to
7154 match the text against aliases, reserved words, shell
7155 functions, shell builtins, and finally executable filenames,
7157 <DT><B>possible-command-completions (C-x !)</B>
7160 List the possible completions of the text before point,
7161 treating it as a command name.
7162 <DT><B>dynamic-complete-history (M-TAB)</B>
7165 Attempt completion on the text before point, comparing
7166 the text against lines from the history list for possible
7168 <DT><B>dabbrev-expand</B>
7171 Attempt menu completion on the text before point, comparing
7172 the text against lines from the history list for possible
7174 <DT><B>complete-into-braces (M-{)</B>
7177 Perform filename completion and insert the list of possible completions
7178 enclosed within braces so the list is available to the shell (see
7179 <B>Brace Expansion</B>
7184 <A NAME="lbCT"> </A>
7185 <H4>Keyboard Macros</H4>
7191 <DT><B>start-kbd-macro (C-x ()</B>
7194 Begin saving the characters typed into the current keyboard macro.
7195 <DT><B>end-kbd-macro (C-x ))</B>
7198 Stop saving the characters typed into the current keyboard macro
7199 and store the definition.
7200 <DT><B>call-last-kbd-macro (C-x e)</B>
7203 Re-execute the last keyboard macro defined, by making the characters
7204 in the macro appear as if typed at the keyboard.
7207 <A NAME="lbCU"> </A>
7208 <H4>Miscellaneous</H4>
7214 <DT><B>re-read-init-file (C-x C-r)</B>
7217 Read in the contents of the <I>inputrc</I> file, and incorporate
7218 any bindings or variable assignments found there.
7219 <DT><B>abort (C-g)</B>
7222 Abort the current editing command and
7223 ring the terminal's bell (subject to the setting of
7226 <DT><B>do-uppercase-version (M-a, M-b, M-</B><I>x</I>, ...)
7229 If the metafied character <I>x</I> is lowercase, run the command
7230 that is bound to the corresponding uppercase character.
7231 <DT><B>prefix-meta (ESC)</B>
7234 Metafy the next character typed.
7235 <FONT SIZE=-1><B>ESC</B>
7243 <DT><B>undo (C-_, C-x C-u)</B>
7246 Incremental undo, separately remembered for each line.
7247 <DT><B>revert-line (M-r)</B>
7250 Undo all changes made to this line. This is like executing the
7253 command enough times to return the line to its initial state.
7254 <DT><B>tilde-expand (M-&)</B>
7257 Perform tilde expansion on the current word.
7258 <DT><B>set-mark (C-@, M-<space>)</B>
7261 Set the mark to the point. If a
7262 numeric argument is supplied, the mark is set to that position.
7263 <DT><B>exchange-point-and-mark (C-x C-x)</B>
7266 Swap the point with the mark. The current cursor position is set to
7267 the saved position, and the old cursor position is saved as the mark.
7268 <DT><B>character-search (C-])</B>
7271 A character is read and point is moved to the next occurrence of that
7272 character. A negative count searches for previous occurrences.
7273 <DT><B>character-search-backward (M-C-])</B>
7276 A character is read and point is moved to the previous occurrence of that
7277 character. A negative count searches for subsequent occurrences.
7278 <DT><B>insert-comment (M-#)</B>
7281 Without a numeric argument, the value of the readline
7282 <B>comment-begin</B>
7284 variable is inserted at the beginning of the current line.
7285 If a numeric argument is supplied, this command acts as a toggle: if
7286 the characters at the beginning of the line do not match the value
7287 of <B>comment-begin</B>, the value is inserted, otherwise
7288 the characters in <B>comment-begin</B> are deleted from the beginning of
7290 In either case, the line is accepted as if a newline had been typed.
7291 The default value of
7292 <B>comment-begin</B> causes this command to make the current line
7294 If a numeric argument causes the comment character to be removed, the line
7295 will be executed by the shell.
7296 <DT><B>glob-complete-word (M-g)</B>
7299 The word before point is treated as a pattern for pathname expansion,
7300 with an asterisk implicitly appended. This pattern is used to
7301 generate a list of matching file names for possible completions.
7302 <DT><B>glob-expand-word (C-x *)</B>
7305 The word before point is treated as a pattern for pathname expansion,
7306 and the list of matching file names is inserted, replacing the word.
7307 If a numeric argument is supplied, an asterisk is appended before
7309 <DT><B>glob-list-expansions (C-x g)</B>
7312 The list of expansions that would have been generated by
7313 <B>glob-expand-word</B>
7315 is displayed, and the line is redrawn.
7316 If a numeric argument is supplied, an asterisk is appended before
7318 <DT><B>dump-functions</B>
7321 Print all of the functions and their key bindings to the
7322 readline output stream. If a numeric argument is supplied,
7323 the output is formatted in such a way that it can be made part
7324 of an <I>inputrc</I> file.
7325 <DT><B>dump-variables</B>
7328 Print all of the settable readline variables and their values to the
7329 readline output stream. If a numeric argument is supplied,
7330 the output is formatted in such a way that it can be made part
7331 of an <I>inputrc</I> file.
7332 <DT><B>dump-macros</B>
7335 Print all of the readline key sequences bound to macros and the
7336 strings they output. If a numeric argument is supplied,
7337 the output is formatted in such a way that it can be made part
7338 of an <I>inputrc</I> file.
7339 <DT><B>display-shell-version (C-x C-v)</B>
7342 Display version information about the current instance of
7347 <A NAME="lbCV"> </A>
7348 <H4>Programmable Completion</H4>
7352 When word completion is attempted for an argument to a command for
7353 which a completion specification (a <I>compspec</I>) has been defined
7354 using the <B>complete</B> builtin (see
7355 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
7358 below), the programmable completion facilities are invoked.
7361 First, the command name is identified.
7362 If a compspec has been defined for that command, the
7363 compspec is used to generate the list of possible completions for the word.
7364 If the command word is a full pathname, a compspec for the full
7365 pathname is searched for first.
7366 If no compspec is found for the full pathname, an attempt is made to
7367 find a compspec for the portion following the final slash.
7370 Once a compspec has been found, it is used to generate the list of
7372 If a compspec is not found, the default <B>bash</B> completion as
7373 described above under <B>Completing</B> is performed.
7376 First, the actions specified by the compspec are used.
7377 Only matches which are prefixed by the word being completed are
7385 option is used for filename or directory name completion, the shell
7387 <FONT SIZE=-1><B>FIGNORE</B>
7390 is used to filter the matches.
7393 Any completions specified by a filename expansion pattern to the
7394 <B>-G</B> option are generated next.
7395 The words generated by the pattern need not match the word
7398 <FONT SIZE=-1><B>GLOBIGNORE</B>
7401 shell variable is not used to filter the matches, but the
7402 <FONT SIZE=-1><B>FIGNORE</B>
7408 Next, the string specified as the argument to the <B>-W</B> option
7410 The string is first split using the characters in the
7411 <FONT SIZE=-1><B>IFS</B>
7414 special variable as delimiters.
7415 Shell quoting is honored.
7416 Each word is then expanded using
7417 brace expansion, tilde expansion, parameter and variable expansion,
7418 command substitution, and arithmetic expansion,
7419 as described above under
7420 <FONT SIZE=-1><B>EXPANSION</B>.
7423 The results are split using the rules described above under
7424 <B>Word Splitting</B>.
7425 The results of the expansion are prefix-matched against the word being
7426 completed, and the matching words become the possible completions.
7429 After these matches have been generated, any shell function or command
7430 specified with the <B>-F</B> and <B>-C</B> options is invoked.
7431 When the command or function is invoked, the
7432 <FONT SIZE=-1><B>COMP_LINE</B>,
7435 <FONT SIZE=-1><B>COMP_POINT</B>,
7438 <FONT SIZE=-1><B>COMP_KEY</B>,
7442 <FONT SIZE=-1><B>COMP_TYPE</B>
7445 variables are assigned values as described above under
7446 <B>Shell Variables</B>.
7447 If a shell function is being invoked, the
7448 <FONT SIZE=-1><B>COMP_WORDS</B>
7452 <FONT SIZE=-1><B>COMP_CWORD</B>
7455 variables are also set.
7456 When the function or command is invoked, the first argument is the
7457 name of the command whose arguments are being completed, the
7458 second argument is the word being completed, and the third argument
7459 is the word preceding the word being completed on the current command line.
7460 No filtering of the generated completions against the word being completed
7461 is performed; the function or command has complete freedom in generating
7465 Any function specified with <B>-F</B> is invoked first.
7466 The function may use any of the shell facilities, including the
7467 <B>compgen</B> builtin described below, to generate the matches.
7468 It must put the possible completions in the
7469 <FONT SIZE=-1><B>COMPREPLY</B>
7475 Next, any command specified with the <B>-C</B> option is invoked
7476 in an environment equivalent to command substitution.
7477 It should print a list of completions, one per line, to the
7479 Backslash may be used to escape a newline, if necessary.
7482 After all of the possible completions are generated, any filter
7483 specified with the <B>-X</B> option is applied to the list.
7484 The filter is a pattern as used for pathname expansion; a <B>&</B>
7485 in the pattern is replaced with the text of the word being completed.
7486 A literal <B>&</B> may be escaped with a backslash; the backslash
7487 is removed before attempting a match.
7488 Any completion that matches the pattern will be removed from the list.
7489 A leading <B>!</B> negates the pattern; in this case any completion
7490 not matching the pattern will be removed.
7493 Finally, any prefix and suffix specified with the <B>-P</B> and <B>-S</B>
7494 options are added to each member of the completion list, and the result is
7495 returned to the readline completion code as the list of possible
7499 If the previously-applied actions do not generate any matches, and the
7500 <B>-o dirnames</B> option was supplied to <B>complete</B> when the
7501 compspec was defined, directory name completion is attempted.
7504 If the <B>-o plusdirs</B> option was supplied to <B>complete</B> when the
7505 compspec was defined, directory name completion is attempted and any
7506 matches are added to the results of the other actions.
7509 By default, if a compspec is found, whatever it generates is returned
7510 to the completion code as the full set of possible completions.
7511 The default <B>bash</B> completions are not attempted, and the readline
7512 default of filename completion is disabled.
7513 If the <B>-o bashdefault</B> option was supplied to <B>complete</B> when
7514 the compspec was defined, the <B>bash</B> default completions are attempted
7515 if the compspec generates no matches.
7516 If the <B>-o default</B> option was supplied to <B>complete</B> when the
7517 compspec was defined, readline's default completion will be performed
7518 if the compspec (and, if attempted, the default <B>bash</B> completions)
7519 generate no matches.
7522 When a compspec indicates that directory name completion is desired,
7523 the programmable completion functions force readline to append a slash
7524 to completed names which are symbolic links to directories, subject to
7525 the value of the <B>mark-directories</B> readline variable, regardless
7526 of the setting of the <B>mark-symlinked-directories</B> readline variable.
7527 <A NAME="lbCW"> </A>
7536 builtin is enabled, the shell provides access to the
7537 <I>command history</I>,
7538 the list of commands previously typed.
7539 The value of the <B>HISTSIZE</B> variable is used as the
7540 number of commands to save in a history list.
7541 The text of the last
7542 <FONT SIZE=-1><B>HISTSIZE</B>
7545 commands (default 500) is saved. The shell
7546 stores each command in the history list prior to parameter and
7547 variable expansion (see
7548 <FONT SIZE=-1><B>EXPANSION</B>
7551 above) but after history expansion is performed, subject to the
7552 values of the shell variables
7553 <FONT SIZE=-1><B>HISTIGNORE</B>
7557 <FONT SIZE=-1><B>HISTCONTROL</B>.
7562 On startup, the history is initialized from the file named by
7564 <FONT SIZE=-1><B>HISTFILE</B>
7567 (default <A HREF="file:~/.bash_history"><I>~/.bash_history</I></A>).
7568 The file named by the value of
7569 <FONT SIZE=-1><B>HISTFILE</B>
7572 is truncated, if necessary, to contain no more than
7573 the number of lines specified by the value of
7574 <FONT SIZE=-1><B>HISTFILESIZE</B>.
7577 When the history file is read,
7578 lines beginning with the history comment character followed immediately
7579 by a digit are interpreted as timestamps for the preceding history line.
7580 These timestamps are optionally displayed depending on the value of the
7581 <FONT SIZE=-1><B>HISTTIMEFORMAT</B>
7585 When an interactive shell exits, the last
7586 <FONT SIZE=-1><B>$HISTSIZE</B>
7589 lines are copied from the history list to
7590 <FONT SIZE=-1><B>$HISTFILE</B>.
7596 shell option is enabled
7597 (see the description of
7601 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
7604 below), the lines are appended to the history file,
7605 otherwise the history file is overwritten.
7607 <FONT SIZE=-1><B>HISTFILE</B>
7610 is unset, or if the history file is unwritable, the history is
7615 variable is set, time stamps are written to the history file, marked
7616 with the history comment character, so
7617 they may be preserved across shell sessions.
7618 This uses the history comment character to distinguish timestamps from
7619 other history lines.
7620 After saving the history, the history file is truncated
7621 to contain no more than
7622 <FONT SIZE=-1><B>HISTFILESIZE</B>
7626 <FONT SIZE=-1><B>HISTFILESIZE</B>
7629 is not set, no truncation is performed.
7636 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
7639 below) may be used to list or edit and re-execute a portion of
7644 builtin may be used to display or modify the history list and
7645 manipulate the history file.
7646 When using command-line editing, search commands
7647 are available in each editing mode that provide access to the
7651 The shell allows control over which commands are saved on the history
7653 <FONT SIZE=-1><B>HISTCONTROL</B>
7657 <FONT SIZE=-1><B>HISTIGNORE</B>
7660 variables may be set to cause the shell to save only a subset of the
7665 shell option, if enabled, causes the shell to attempt to save each
7666 line of a multi-line command in the same history entry, adding
7667 semicolons where necessary to preserve syntactic correctness.
7671 shell option causes the shell to save the command with embedded newlines
7672 instead of semicolons. See the description of the
7676 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
7679 for information on setting and unsetting shell options.
7680 <A NAME="lbCX"> </A>
7681 <H3>HISTORY EXPANSION</H3>
7685 The shell supports a history expansion feature that
7686 is similar to the history expansion in
7689 This section describes what syntax features are available. This
7690 feature is enabled by default for interactive shells, and can be
7697 builtin command (see
7698 <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
7701 below). Non-interactive shells do not perform history expansion
7705 History expansions introduce words from the history list into
7706 the input stream, making it easy to repeat commands, insert the
7707 arguments to a previous command into the current input line, or
7708 fix errors in previous commands quickly.
7711 History expansion is performed immediately after a complete line
7712 is read, before the shell breaks it into words.
7713 It takes place in two parts.
7714 The first is to determine which line from the history list
7715 to use during substitution.
7716 The second is to select portions of that line for inclusion into
7718 The line selected from the history is the <I>event</I>,
7719 and the portions of that line that are acted upon are <I>words</I>.
7720 Various <I>modifiers</I> are available to manipulate the selected words.
7721 The line is broken into words in the same fashion as when reading input,
7722 so that several <I>metacharacter</I>-separated words surrounded by
7723 quotes are considered one word.
7724 History expansions are introduced by the appearance of the
7725 history expansion character, which is <B>!</B> by default.
7726 Only backslash (<B>\</B>) and single quotes can quote
7727 the history expansion character.
7730 Several characters inhibit history expansion if found immediately
7731 following the history expansion character, even if it is unquoted:
7732 space, tab, newline, carriage return, and <B>=</B>.
7733 If the <B>extglob</B> shell option is enabled, <B>(</B> will also
7737 Several shell options settable with the
7740 builtin may be used to tailor the behavior of history expansion.
7744 shell option is enabled (see the description of the
7750 is being used, history substitutions are not immediately passed to
7752 Instead, the expanded line is reloaded into the
7755 editing buffer for further modification.
7759 is being used, and the
7762 shell option is enabled, a failed history substitution will be reloaded
7766 editing buffer for correction.
7773 builtin command may be used to see what a history expansion will
7781 builtin may be used to add commands to the end of the history list
7782 without actually executing them, so that they are available for
7786 The shell allows control of the various characters used by the
7787 history expansion mechanism (see the description of
7791 <B>Shell Variables</B>).
7794 the history comment character to mark history timestamps when
7795 writing the history file.
7796 <A NAME="lbCY"> </A>
7797 <H4>Event Designators</H4>
7801 An event designator is a reference to a command line entry in the
7810 Start a history substitution, except when followed by a
7813 newline, carriage return, =
7814 or ( (when the <B>extglob</B> shell option is enabled using
7815 the <B>shopt</B> builtin).
7816 <DT><B>!</B><I>n</I>
7819 Refer to command line
7822 <DT><B>!-</B><I>n</I>
7825 Refer to the current command line minus
7831 Refer to the previous command. This is a synonym for `!-1'.
7832 <DT><B>!</B><I>string</I>
7835 Refer to the most recent command starting with
7838 <DT><B>!?</B><I>string</I><B>[?]</B>
7841 Refer to the most recent command containing
7844 The trailing <B>?</B> may be omitted if
7847 is followed immediately by a newline.
7848 <DT><B></B><FONT SIZE=+2><B>^</B></FONT><B></B><I>string1</I><FONT SIZE=+2>^</FONT><I>string2</I><FONT SIZE=+2>^</FONT>
7851 Quick substitution. Repeat the last command, replacing
7858 ``!!:s/<I>string1</I>/<I>string2</I>/''
7859 (see <B>Modifiers</B> below).
7863 The entire command line typed so far.
7866 <A NAME="lbCZ"> </A>
7867 <H4>Word Designators</H4>
7871 Word designators are used to select desired words from the event.
7875 separates the event specification from the word designator.
7876 It may be omitted if the word designator begins with a
7888 Words are numbered from the beginning of the line,
7889 with the first word being denoted by 0 (zero).
7890 Words are inserted into the current line separated by single spaces.
7898 The zeroth word. For the shell, this is the command
7903 The <I>n</I>th word.
7907 The first argument. That is, word 1.
7915 The word matched by the most recent `?<I>string</I>?' search.
7916 <DT><I>x</I><B>-</B>y
7919 A range of words; `-<I>y</I>' abbreviates `0-<I>y</I>'.
7923 All of the words but the zeroth. This is a synonym
7924 for `<I>1-$</I>'. It is not an error to use
7927 if there is just one
7928 word in the event; the empty string is returned in that case.
7932 Abbreviates <I>x-$</I>.
7936 Abbreviates <I>x-$</I> like <B>x*</B>, but omits the last word.
7941 If a word designator is supplied without an event specification, the
7942 previous command is used as the event.
7943 <A NAME="lbDA"> </A>
7948 After the optional word designator, there may appear a sequence of
7949 one or more of the following modifiers, each preceded by a `:'.
7959 Remove a trailing file name component, leaving only the head.
7963 Remove all leading file name components, leaving the tail.
7967 Remove a trailing suffix of the form <I>.xxx</I>, leaving the
7972 Remove all but the trailing suffix.
7976 Print the new command but do not execute it.
7980 Quote the substituted words, escaping further substitutions.
7984 Quote the substituted words as with
7987 but break into words at
7991 <DT><B>s/</B><I>old</I>/<I>new</I>/
7997 for the first occurrence of
8000 in the event line. Any delimiter can be used in place of /. The
8001 final delimiter is optional if it is the last character of the
8002 event line. The delimiter may be quoted in
8008 with a single backslash. If & appears in
8014 A single backslash will quote the &. If
8017 is null, it is set to the last
8020 substituted, or, if no previous history substitutions took place,
8025 <B>!?</B><I>string</I><B>[?]</B>
8031 Repeat the previous substitution.
8035 Cause changes to be applied over the entire event line. This is
8036 used in conjunction with `<B>:s</B>' (e.g., `<B>:gs/</B><I>old</I>/<I>new</I>/')
8037 or `<B>:&</B>'. If used with
8038 `<B>:s</B>', any delimiter can be used
8039 in place of /, and the final delimiter is optional
8040 if it is the last character of the event line.
8041 An <B>a</B> may be used as a synonym for <B>g</B>.
8045 Apply the following `<B>s</B>' modifier once to each word in the event line.
8048 <A NAME="lbDB"> </A>
8049 <H3>SHELL BUILTIN COMMANDS</H3>
8055 Unless otherwise noted, each builtin command documented in this
8056 section as accepting options preceded by
8062 to signify the end of the options.
8063 For example, the <B>:</B>, <B>true</B>, <B>false</B>, and <B>test</B> builtins
8064 do not accept options.
8068 <DT><B>:</B> [<I>arguments</I>]<DD>
8070 No effect; the command does nothing beyond expanding
8073 and performing any specified
8074 redirections. A zero exit code is returned.
8075 <DT><B> . </B> <I>filename</I> [<I>arguments</I>]<DD>
8077 <DT><B>source</B> <I>filename</I> [<I>arguments</I>]<DD>
8079 Read and execute commands from
8083 shell environment and return the exit status of the last command
8090 does not contain a slash, file names in
8091 <FONT SIZE=-1><B>PATH</B>
8094 are used to find the directory containing
8097 The file searched for in
8098 <FONT SIZE=-1><B>PATH</B>
8101 need not be executable.
8102 When <B>bash</B> is not in <I>posix mode</I>, the current directory is
8103 searched if no file is found in
8104 <FONT SIZE=-1><B>PATH</B>.
8113 builtin command is turned off, the
8114 <FONT SIZE=-1><B>PATH</B>
8118 If any <I>arguments</I> are supplied, they become the positional
8119 parameters when <I>filename</I> is executed. Otherwise the positional
8120 parameters are unchanged.
8121 The return status is the status of the last command exited within
8122 the script (0 if no commands are executed), and false if
8125 is not found or cannot be read.
8126 <DT><B>alias</B> [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD>
8127 <B>Alias</B> with no arguments or with the
8130 option prints the list of aliases in the form
8131 <B>alias</B> <I>name</I>=<I>value</I> on standard output.
8132 When arguments are supplied, an alias is defined for
8133 each <I>name</I> whose <I>value</I> is given.
8134 A trailing space in <I>value</I> causes the next word to be
8135 checked for alias substitution when the alias is expanded.
8136 For each <I>name</I> in the argument list for which no <I>value</I>
8137 is supplied, the name and value of the alias is printed.
8138 <B>Alias</B> returns true unless a <I>name</I> is given for which
8139 no alias has been defined.
8140 <DT><B>bg</B> [<I>jobspec</I> ...]<DD>
8141 Resume each suspended job <I>jobspec</I> in the background, as if it
8142 had been started with
8148 is not present, the shell's notion of the <I>current job</I> is used.
8153 returns 0 unless run when job control is disabled or, when run with
8154 job control enabled, any specified <I>jobspec</I> was not found
8155 or was started without job control.
8156 <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] [<B>-lpsvPSV</B>]<DD>
8158 <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] [<B>-q</B> <I>function</I>] [<B>-u</B> <I>function</I>] [<B>-r</B> <I>keyseq</I>]<DD>
8159 <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <B>-f</B> <I>filename</I><DD>
8160 <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <B>-x</B> <I>keyseq</I>:<I>shell-command</I><DD>
8161 <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <I>keyseq</I>:<I>function-name</I><DD>
8162 <DT><B>bind</B> <I>readline-command</I><DD>
8167 key and function bindings, bind a key sequence to a
8170 function or macro, or set a
8174 Each non-option argument is a command as it would appear in
8177 but each binding or command must be passed as a separate argument;
8178 e.g., '"\C-x\C-r": re-read-init-file'.
8179 Options, if supplied, have the following meanings:
8180 <DL COMPACT><DT><DD>
8183 <DT><B>-m </B><I>keymap</I>
8189 as the keymap to be affected by the subsequent bindings.
8194 <I>emacs, emacs-standard, emacs-meta, emacs-ctlx, vi,
8195 vi-move, vi-command</I>, and
8198 <I>vi</I> is equivalent to <I>vi-command</I>; <I>emacs</I> is
8199 equivalent to <I>emacs-standard</I>.
8203 List the names of all <B>readline</B> functions.
8207 Display <B>readline</B> function names and bindings in such a way
8208 that they can be re-read.
8212 List current <B>readline</B> function names and bindings.
8216 Display <B>readline</B> key sequences bound to macros and the strings
8217 they output in such a way that they can be re-read.
8221 Display <B>readline</B> key sequences bound to macros and the strings
8226 Display <B>readline</B> variable names and values in such a way that they
8231 List current <B>readline</B> variable names and values.
8232 <DT><B>-f </B><I>filename</I>
8235 Read key bindings from <I>filename</I>.
8236 <DT><B>-q </B><I>function</I>
8239 Query about which keys invoke the named <I>function</I>.
8240 <DT><B>-u </B><I>function</I>
8243 Unbind all keys bound to the named <I>function</I>.
8244 <DT><B>-r </B><I>keyseq</I>
8247 Remove any current binding for <I>keyseq</I>.
8248 <DT><B>-x </B><I>keyseq</I>:<I>shell-command</I>
8251 Cause <I>shell-command</I> to be executed whenever <I>keyseq</I> is
8253 When <I>shell-command</I> is executed, the shell sets the
8254 <B>READLINE_LINE</B>
8256 variable to the contents of the <B>readline</B> line buffer and the
8257 <B>READLINE_POINT</B>
8259 variable to the current location of the insertion point.
8260 If the executed command changes the value of
8261 <B>READLINE_LINE</B>
8264 <B>READLINE_POINT</B>,
8266 those new values will be reflected in the editing state.
8271 The return value is 0 unless an unrecognized option is given or an
8275 <DT><B>break</B> [<I>n</I>]<DD>
8286 loop. If <I>n</I> is specified, break <I>n</I> levels.
8292 is greater than the number of enclosing loops, all enclosing loops
8294 The return value is 0 unless <I>n</I> is not greater than or equal to 1.
8295 <DT><B>builtin</B> <I>shell-builtin</I> [<I>arguments</I>]<DD>
8296 Execute the specified shell builtin, passing it
8299 and return its exit status.
8300 This is useful when defining a
8301 function whose name is the same as a shell builtin,
8302 retaining the functionality of the builtin within the function.
8303 The <B>cd</B> builtin is commonly redefined this way.
8304 The return status is false if
8305 <I>shell-builtin</I>
8307 is not a shell builtin command.
8308 <DT><B>caller</B> [<I>expr</I>]<DD>
8309 Returns the context of any active subroutine call (a shell function or
8310 a script executed with the <B>.</B> or <B>source</B> builtins.
8311 Without <I>expr</I>, <B>caller</B> displays the line number and source
8312 filename of the current subroutine call.
8313 If a non-negative integer is supplied as <I>expr</I>, <B>caller</B>
8314 displays the line number, subroutine name, and source file corresponding
8315 to that position in the current execution call stack. This extra
8316 information may be used, for example, to print a stack trace. The
8317 current frame is frame 0.
8318 The return value is 0 unless the shell is not executing a subroutine
8319 call or <I>expr</I> does not correspond to a valid position in the
8321 <DT><B>cd</B> [<B>-L|-P</B>] [<I>dir</I>]<DD>
8322 Change the current directory to <I>dir</I>. The variable
8323 <FONT SIZE=-1><B>HOME</B>
8331 <FONT SIZE=-1><B>CDPATH</B>
8334 defines the search path for the directory containing
8337 Alternative directory names in
8338 <FONT SIZE=-1><B>CDPATH</B>
8341 are separated by a colon (:). A null directory name in
8342 <FONT SIZE=-1><B>CDPATH</B>
8345 is the same as the current directory, i.e., ``<B>.</B>''. If
8348 begins with a slash (/),
8350 <FONT SIZE=-1><B>CDPATH</B>
8356 option says to use the physical directory structure instead of
8357 following symbolic links (see also the
8363 builtin command); the
8366 option forces symbolic links to be followed. An argument of
8370 <FONT SIZE=-1><B>$OLDPWD</B>.
8373 If a non-empty directory name from <B>CDPATH</B> is used, or if
8374 <B>-</B> is the first argument, and the directory change is
8375 successful, the absolute pathname of the new working directory is
8376 written to the standard output.
8377 The return value is true if the directory was successfully changed;
8379 <DT><B>command</B> [<B>-pVv</B>] <I>command</I> [<I>arg</I> ...]<DD>
8386 suppressing the normal shell function lookup. Only builtin
8387 commands or commands found in the
8388 <FONT SIZE=-1><B>PATH</B>
8391 are executed. If the
8394 option is given, the search for
8397 is performed using a default value for
8400 that is guaranteed to find all of the standard utilities.
8407 option is supplied, a description of
8413 option causes a single word indicating the command or file name
8417 to be displayed; the
8420 option produces a more verbose description.
8427 option is supplied, the exit status is 0 if
8430 was found, and 1 if not. If neither option is supplied and
8431 an error occurred or
8434 cannot be found, the exit status is 127. Otherwise, the exit status of the
8437 builtin is the exit status of
8440 <DT><B>compgen</B> [<I>option</I>] [<I>word</I>]<DD>
8441 Generate possible completion matches for <I>word</I> according to
8442 the <I>option</I>s, which may be any option accepted by the
8445 builtin with the exception of <B>-p</B> and <B>-r</B>, and write
8446 the matches to the standard output.
8447 When using the <B>-F</B> or <B>-C</B> options, the various shell variables
8448 set by the programmable completion facilities, while available, will not
8451 The matches will be generated in the same way as if the programmable
8452 completion code had generated them directly from a completion specification
8453 with the same flags.
8454 If <I>word</I> is specified, only those completions matching <I>word</I>
8457 The return value is true unless an invalid option is supplied, or no
8458 matches were generated.
8459 <DT><B>complete</B> [<B>-abcdefgjksuv</B>] [<B>-o</B> <I>comp-option</I>] [<B>-E</B>] [<B>-A</B> <I>action</I>] [<B>-G</B> <I>globpat</I>] [<B>-W</B> <I>wordlist</I>] [<B>-F</B> <I>function</I>] [<B>-C</B> <I>command</I>]<DD>
8462 [<B>-X</B> <I>filterpat</I>] [<B>-P</B> <I>prefix</I>] [<B>-S</B> <I>suffix</I>] <I>name</I> [<I>name ...</I>]
8464 <DT><B>complete</B> <B>-pr</B> [<B>-E</B>] [<I>name</I> ...]<DD>
8466 Specify how arguments to each <I>name</I> should be completed.
8467 If the <B>-p</B> option is supplied, or if no options are supplied,
8468 existing completion specifications are printed in a way that allows
8469 them to be reused as input.
8470 The <B>-r</B> option removes a completion specification for
8471 each <I>name</I>, or, if no <I>name</I>s are supplied, all
8472 completion specifications.
8473 The <B>-E</B> option indicates that the remaining options and actions should
8474 apply to ``empty'' command completion; that is, completion attempted on a
8477 The process of applying these completion specifications when word completion
8478 is attempted is described above under <B>Programmable Completion</B>.
8480 Other options, if specified, have the following meanings.
8481 The arguments to the <B>-G</B>, <B>-W</B>, and <B>-X</B> options
8482 (and, if necessary, the <B>-P</B> and <B>-S</B> options)
8483 should be quoted to protect them from expansion before the
8487 <DL COMPACT><DT><DD>
8490 <DT><B>-o</B> <I>comp-option</I><DD>
8491 The <I>comp-option</I> controls several aspects of the compspec's behavior
8492 beyond the simple generation of completions.
8493 <I>comp-option</I> may be one of:
8494 <DL COMPACT><DT><DD>
8496 <DT><B>bashdefault</B>
8499 Perform the rest of the default <B>bash</B> completions if the compspec
8500 generates no matches.
8504 Use readline's default filename completion if the compspec generates
8509 Perform directory name completion if the compspec generates no matches.
8510 <DT><B>filenames</B>
8513 Tell readline that the compspec generates filenames, so it can perform any
8514 filename-specific processing (like adding a slash to directory names,
8515 quoting special characters, or suppressing trailing spaces).
8516 Intended to be used with shell functions.
8520 Tell readline not to append a space (the default) to words completed at
8521 the end of the line.
8525 After any matches defined by the compspec are generated,
8526 directory name completion is attempted and any
8527 matches are added to the results of the other actions.
8530 <DT><B>-A</B> <I>action</I><DD>
8531 The <I>action</I> may be one of the following to generate a list of possible
8533 <DL COMPACT><DT><DD>
8538 Alias names. May also be specified as <B>-a</B>.
8542 Array variable names.
8546 <B>Readline</B> key binding names.
8550 Names of shell builtin commands. May also be specified as <B>-b</B>.
8554 Command names. May also be specified as <B>-c</B>.
8555 <DT><B>directory</B>
8558 Directory names. May also be specified as <B>-d</B>.
8562 Names of disabled shell builtins.
8566 Names of enabled shell builtins.
8570 Names of exported shell variables. May also be specified as <B>-e</B>.
8574 File names. May also be specified as <B>-f</B>.
8578 Names of shell functions.
8582 Group names. May also be specified as <B>-g</B>.
8583 <DT><B>helptopic</B>
8586 Help topics as accepted by the <B>help</B> builtin.
8590 Hostnames, as taken from the file specified by the
8591 <FONT SIZE=-1><B>HOSTFILE</B>
8598 Job names, if job control is active. May also be specified as <B>-j</B>.
8602 Shell reserved words. May also be specified as <B>-k</B>.
8606 Names of running jobs, if job control is active.
8610 Service names. May also be specified as <B>-s</B>.
8614 Valid arguments for the <B>-o</B> option to the <B>set</B> builtin.
8618 Shell option names as accepted by the <B>shopt</B> builtin.
8626 Names of stopped jobs, if job control is active.
8630 User names. May also be specified as <B>-u</B>.
8634 Names of all shell variables. May also be specified as <B>-v</B>.
8637 <DT><B>-G</B> <I>globpat</I><DD>
8638 The filename expansion pattern <I>globpat</I> is expanded to generate
8639 the possible completions.
8640 <DT><B>-W</B> <I>wordlist</I><DD>
8641 The <I>wordlist</I> is split using the characters in the
8642 <FONT SIZE=-1><B>IFS</B>
8645 special variable as delimiters, and each resultant word is expanded.
8646 The possible completions are the members of the resultant list which
8647 match the word being completed.
8648 <DT><B>-C</B> <I>command</I><DD>
8649 <I>command</I> is executed in a subshell environment, and its output is
8650 used as the possible completions.
8651 <DT><B>-F</B> <I>function</I><DD>
8652 The shell function <I>function</I> is executed in the current shell
8654 When it finishes, the possible completions are retrieved from the value
8656 <FONT SIZE=-1><B>COMPREPLY</B>
8660 <DT><B>-X</B> <I>filterpat</I><DD>
8661 <I>filterpat</I> is a pattern as used for filename expansion.
8662 It is applied to the list of possible completions generated by the
8663 preceding options and arguments, and each completion matching
8664 <I>filterpat</I> is removed from the list.
8665 A leading <B>!</B> in <I>filterpat</I> negates the pattern; in this
8666 case, any completion not matching <I>filterpat</I> is removed.
8667 <DT><B>-P</B> <I>prefix</I><DD>
8668 <I>prefix</I> is added at the beginning of each possible completion
8669 after all other options have been applied.
8670 <DT><B>-S</B> <I>suffix</I><DD>
8671 <I>suffix</I> is appended to each possible completion
8672 after all other options have been applied.
8677 The return value is true unless an invalid option is supplied, an option
8678 other than <B>-p</B> or <B>-r</B> is supplied without a <I>name</I>
8679 argument, an attempt is made to remove a completion specification for
8680 a <I>name</I> for which no specification exists, or
8681 an error occurs adding a completion specification.
8684 <DT><B>compopt</B> [<B>-o</B> <I>option</I>] [<B>+o</B> <I>option</I>] [<I>name</I>]<DD>
8685 Modify completion options for each <I>name</I> according to the
8686 <I>option</I>s, or for the
8687 currently-execution completion if no <I>name</I>s are supplied.
8688 If no <I>option</I>s are given, display the completion options for each
8689 <I>name</I> or the current completion.
8690 The possible values of <I>option</I> are those valid for the <B>complete</B>
8691 builtin described above.
8695 The return value is true unless an invalid option is supplied, an attempt
8696 is made to modify the options for a <I>name</I> for which no completion
8697 specification exists, or an output error occurs.
8699 <DT><B>continue</B> [<I>n</I>]<DD>
8700 Resume the next iteration of the enclosing
8714 is specified, resume at the <I>n</I>th enclosing loop.
8720 is greater than the number of enclosing loops, the last enclosing loop
8721 (the ``top-level'' loop) is resumed.
8722 The return value is 0 unless <I>n</I> is not greater than or equal to 1.
8723 <DT><B>declare</B> [<B>-aAfFilrtux</B>] [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD>
8725 <DT><B>typeset</B> [<B>-aAfFilrtux</B>] [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD>
8727 Declare variables and/or give them attributes.
8728 If no <I>name</I>s are given then display the values of variables.
8732 option will display the attributes and values of each
8738 is used with <I>name</I> arguments, additional options are ignored.
8742 is supplied without <I>name</I> arguments, it will display the attributes
8743 and values of all variables having the attributes specified by the
8745 If no other options are supplied with <B>-p</B>, <B>declare</B> will display
8746 the attributes and values of all shell variables. The <B>-f</B> option
8747 will restrict the display to shell functions.
8751 option inhibits the display of function definitions; only the
8752 function name and attributes are printed.
8753 If the <B>extdebug</B> shell option is enabled using <B>shopt</B>,
8754 the source file name and line number where the function is defined
8755 are displayed as well. The
8761 The following options can
8762 be used to restrict output to variables with the specified attribute or
8763 to give variables attributes:
8764 <DL COMPACT><DT><DD>
8770 Each <I>name</I> is an indexed array variable (see
8777 Each <I>name</I> is an associative array variable (see
8784 Use function names only.
8788 The variable is treated as an integer; arithmetic evaluation (see
8789 <FONT SIZE=-1><B>ARITHMETIC EVALUATION ) </B>
8792 is performed when the variable is assigned a value.
8796 When the variable is assigned a value, all upper-case characters are
8797 converted to lower-case.
8798 The upper-case attribute is disabled.
8802 Make <I>name</I>s readonly. These names cannot then be assigned values
8803 by subsequent assignment statements or unset.
8807 Give each <I>name</I> the <I>trace</I> attribute.
8808 Traced functions inherit the <B>DEBUG</B> and <B>RETURN</B> traps from
8810 The trace attribute has no special meaning for variables.
8814 When the variable is assigned a value, all lower-case characters are
8815 converted to upper-case.
8816 The lower-case attribute is disabled.
8820 Mark <I>name</I>s for export to subsequent commands via the environment.
8825 Using `+' instead of `-'
8826 turns off the attribute instead,
8827 with the exceptions that <B>+a</B>
8828 may not be used to destroy an array variable and <B>+r will not
8829 remove the readonly attribute.
8830 When used in a function,
8832 </B><I>name</I> local, as with the
8836 If a variable name is followed by =<I>value</I>, the value of
8837 the variable is set to <I>value</I>.
8838 The return value is 0 unless an invalid option is encountered,
8839 an attempt is made to define a function using
8841 <TT>-f foo=bar</TT>,
8842 an attempt is made to assign a value to a readonly variable,
8843 an attempt is made to assign a value to an array variable without
8844 using the compound assignment syntax (see
8847 above), one of the <I>names</I> is not a valid shell variable name,
8848 an attempt is made to turn off readonly status for a readonly variable,
8849 an attempt is made to turn off array status for an array variable,
8850 or an attempt is made to display a non-existent function with <B>-f</B>.
8853 <DT><B>dirs [+</B><I>n</I>] [-<I>n</I>] [<B>-cplv</B>]
8856 Without options, displays the list of currently remembered directories.
8857 The default display is on a single line with directory names separated
8859 Directories are added to the list with the
8865 command removes entries from the list.
8866 <DL COMPACT><DT><DD>
8869 <DT><B>+</B><I>n</I><DD>
8870 Displays the <I>n</I>th entry counting from the left of the list
8874 when invoked without options, starting with zero.
8875 <DT><B>-</B><I>n</I><DD>
8876 Displays the <I>n</I>th entry counting from the right of the list
8880 when invoked without options, starting with zero.
8884 Clears the directory stack by deleting all of the entries.
8888 Produces a longer listing; the default listing format uses a
8889 tilde to denote the home directory.
8893 Print the directory stack with one entry per line.
8897 Print the directory stack with one entry per line,
8898 prefixing each entry with its index in the stack.
8903 The return value is 0 unless an
8904 invalid option is supplied or <I>n</I> indexes beyond the end
8905 of the directory stack.
8908 <DT><B>disown</B> [<B>-ar</B>] [<B>-h</B>] [<I>jobspec</I> ...]<DD>
8909 Without options, each
8912 is removed from the table of active jobs.
8916 is not present, and neither <B>-a nor -r</B> is supplied,
8917 the shell's notion of the <I>current job</I> is used.
8918 If the <B>-h</B> option is given, each
8921 is not removed from the table, but is marked so that
8922 <FONT SIZE=-1><B>SIGHUP</B>
8925 is not sent to the job if the shell receives a
8926 <FONT SIZE=-1><B>SIGHUP</B>.
8932 is present, and neither the
8938 option is supplied, the <I>current job</I> is used.
8945 option means to remove or mark all jobs; the
8951 argument restricts operation to running jobs.
8952 The return value is 0 unless a
8955 does not specify a valid job.
8956 <DT><B>echo</B> [<B>-neE</B>] [<I>arg</I> ...]<DD>
8957 Output the <I>arg</I>s, separated by spaces, followed by a newline.
8958 The return status is always 0.
8959 If <B>-n</B> is specified, the trailing newline is
8960 suppressed. If the <B>-e</B> option is given, interpretation of
8961 the following backslash-escaped characters is enabled. The
8964 option disables the interpretation of these escape characters,
8965 even on systems where they are interpreted by default.
8966 The <B>xpg_echo</B> shell option may be used to
8967 dynamically determine whether or not <B>echo</B> expands these
8968 escape characters by default.
8971 does not interpret <B>--</B> to mean the end of options.
8974 interprets the following escape sequences:
8975 <DL COMPACT><DT><DD>
8989 suppress further output
9018 <DT><B>\0</B><I>nnn</I>
9021 the eight-bit character whose value is the octal value <I>nnn</I>
9022 (zero to three octal digits)
9023 <DT><B>\x</B><I>HH</I>
9026 the eight-bit character whose value is the hexadecimal value <I>HH</I>
9027 (one or two hex digits)
9031 <DT><B>enable</B> [<B>-a</B>] [<B>-dnps</B>] [<B>-f</B> <I>filename</I>] [<I>name</I> ...]<DD>
9032 Enable and disable builtin shell commands.
9033 Disabling a builtin allows a disk command which has the same name
9034 as a shell builtin to be executed without specifying a full pathname,
9035 even though the shell normally searches for builtins before disk commands.
9036 If <B>-n</B> is used, each <I>name</I>
9037 is disabled; otherwise,
9038 <I>names</I> are enabled. For example, to use the
9041 binary found via the
9042 <FONT SIZE=-1><B>PATH</B>
9045 instead of the shell builtin version, run
9046 <TT>enable -n test</TT>.
9051 option means to load the new builtin command
9057 on systems that support dynamic loading. The
9060 option will delete a builtin previously loaded with
9063 If no <I>name</I> arguments are given, or if the
9066 option is supplied, a list of shell builtins is printed.
9067 With no other option arguments, the list consists of all enabled
9069 If <B>-n</B> is supplied, only disabled builtins are printed.
9070 If <B>-a</B> is supplied, the list printed includes all builtins, with an
9071 indication of whether or not each is enabled.
9072 If <B>-s</B> is supplied, the output is restricted to the POSIX
9073 <I>special</I> builtins.
9074 The return value is 0 unless a
9077 is not a shell builtin or there is an error loading a new builtin
9078 from a shared object.
9079 <DT><B>eval</B> [<I>arg</I> ...]<DD>
9080 The <I>arg</I>s are read and concatenated together into a single
9081 command. This command is then read and executed by the shell, and
9082 its exit status is returned as the value of
9088 or only null arguments,
9092 <DT><B>exec</B> [<B>-cl</B>] [<B>-a</B> <I>name</I>] [<I>command</I> [<I>arguments</I>]]<DD>
9096 is specified, it replaces the shell.
9097 No new process is created. The
9100 become the arguments to <I>command</I>.
9105 the shell places a dash at the beginning of the zeroth argument passed to
9117 to be executed with an empty environment. If
9120 is supplied, the shell passes
9123 as the zeroth argument to the executed command. If
9126 cannot be executed for some reason, a non-interactive shell exits,
9127 unless the shell option
9130 is enabled, in which case it returns failure.
9131 An interactive shell returns failure if the file cannot be executed.
9135 is not specified, any redirections take effect in the current shell,
9136 and the return status is 0. If there is a redirection error, the
9138 <DT><B>exit</B> [<I>n</I>]<DD>
9139 Cause the shell to exit
9140 with a status of <I>n</I>. If
9143 is omitted, the exit status
9144 is that of the last command executed.
9146 <FONT SIZE=-1><B>EXIT</B>
9149 is executed before the shell terminates.
9150 <DT><B>export</B> [<B>-fn</B>] [<I>name</I>[=<I>word</I>]] ...<DD>
9152 <DT><B>export -p</B>
9159 are marked for automatic export to the environment of
9160 subsequently executed commands. If the
9171 are given, or if the
9174 option is supplied, a list
9175 of all names that are exported in this shell is printed.
9179 option causes the export property to be removed from each
9181 If a variable name is followed by =<I>word</I>, the value of
9182 the variable is set to <I>word</I>.
9185 returns an exit status of 0 unless an invalid option is
9187 one of the <I>names</I> is not a valid shell variable name, or
9193 that is not a function.
9194 <DT><B>fc</B> [<B>-e</B> <I>ename</I>] [<B>-lnr</B>] [<I>first</I>] [<I>last</I>]<DD>
9196 <DT><B>fc</B> <B>-s</B> [<I>pat</I>=<I>rep</I>] [<I>cmd</I>]<DD>
9198 Fix Command. In the first form, a range of commands from
9204 is selected from the history list.
9210 may be specified as a string (to locate the last command beginning
9211 with that string) or as a number (an index into the history list,
9212 where a negative number is used as an offset from the current
9216 is not specified it is set to
9217 the current command for listing (so that
9220 prints the last 10 commands) and to
9227 is not specified it is set to the previous
9228 command for editing and -16 for listing.
9234 the command numbers when listing. The
9237 option reverses the order of
9238 the commands. If the
9242 the commands are listed on
9243 standard output. Otherwise, the editor given by
9247 on a file containing those commands. If
9252 <FONT SIZE=-1><B>FCEDIT</B>
9255 variable is used, and
9257 <FONT SIZE=-1><B>EDITOR</B>
9261 <FONT SIZE=-1><B>FCEDIT</B>
9264 is not set. If neither variable is set,
9268 is used. When editing is complete, the edited commands are
9269 echoed and executed.
9271 In the second form, <I>command</I> is re-executed after each instance
9272 of <I>pat</I> is replaced by <I>rep</I>.
9273 A useful alias to use with this is
9279 runs the last command beginning with
9285 re-executes the last command.
9287 If the first form is used, the return value is 0 unless an invalid
9288 option is encountered or
9294 specify history lines out of range.
9298 option is supplied, the return value is the value of the last
9299 command executed or failure if an error occurs with the temporary
9300 file of commands. If the second form is used, the return status
9301 is that of the command re-executed, unless
9304 does not specify a valid history line, in which case
9308 <DT><B>fg</B> [<I>jobspec</I>]<DD>
9312 in the foreground, and make it the current job.
9316 is not present, the shell's notion of the <I>current job</I> is used.
9317 The return value is that of the command placed into the foreground,
9318 or failure if run when job control is disabled or, when run with
9319 job control enabled, if
9322 does not specify a valid job or
9325 specifies a job that was started without job control.
9326 <DT><B>getopts</B> <I>optstring</I> <I>name</I> [<I>args</I>]<DD>
9329 is used by shell procedures to parse positional parameters.
9332 contains the option characters to be recognized; if a character
9333 is followed by a colon, the option is expected to have an
9334 argument, which should be separated from it by white space.
9335 The colon and question mark characters may not be used as
9337 Each time it is invoked,
9340 places the next option in the shell variable
9346 if it does not exist,
9347 and the index of the next argument to be processed into the
9349 <FONT SIZE=-1><B>OPTIND</B>.
9352 <FONT SIZE=-1><B>OPTIND</B>
9355 is initialized to 1 each time the shell or a shell script
9356 is invoked. When an option requires an argument,
9359 places that argument into the variable
9360 <FONT SIZE=-1><B>OPTARG</B>.
9363 The shell does not reset
9364 <FONT SIZE=-1><B>OPTIND</B>
9367 automatically; it must be manually reset between multiple
9371 within the same shell invocation if a new set of parameters
9374 When the end of options is encountered, <B>getopts</B> exits with a
9375 return value greater than zero.
9376 <B>OPTIND</B> is set to the index of the first non-option argument,
9377 and <B>name</B> is set to ?.
9381 normally parses the positional parameters, but if more arguments are
9387 parses those instead.
9391 can report errors in two ways. If the first character of
9397 error reporting is used. In normal operation diagnostic messages
9398 are printed when invalid options or missing option arguments are
9401 <FONT SIZE=-1><B>OPTERR</B>
9404 is set to 0, no error messages will be displayed, even if the first
9410 If an invalid option is seen,
9417 prints an error message and unsets
9418 <FONT SIZE=-1><B>OPTARG</B>.
9425 the option character found is placed in
9426 <FONT SIZE=-1><B>OPTARG</B>
9429 and no diagnostic message is printed.
9431 If a required argument is not found, and
9435 a question mark (<B>?</B>) is placed in
9438 <FONT SIZE=-1><B>OPTARG</B>
9441 is unset, and a diagnostic message is printed.
9445 is silent, then a colon (<B>:</B>) is placed in
9449 <FONT SIZE=-1><B>OPTARG</B>
9452 is set to the option character found.
9456 returns true if an option, specified or unspecified, is found.
9457 It returns false if the end of options is encountered or an
9459 <DT><B>hash</B> [<B>-lr</B>] [<B>-p</B> <I>filename</I>] [<B>-dt</B>] [<I>name</I>]<DD>
9463 the full file name of the command is determined by searching
9471 option is supplied, no path search is performed, and
9474 is used as the full file name of the command.
9478 option causes the shell to forget all
9479 remembered locations.
9483 option causes the shell to forget the remembered location of each <I>name</I>.
9487 option is supplied, the full pathname to which each <I>name</I> corresponds
9488 is printed. If multiple <I>name</I> arguments are supplied with <B>-t</B>,
9489 the <I>name</I> is printed before the hashed full pathname.
9493 option causes output to be displayed in a format that may be reused as input.
9494 If no arguments are given, or if only <B>-l</B> is supplied,
9495 information about remembered commands is printed.
9496 The return status is true unless a
9499 is not found or an invalid option is supplied.
9500 <DT><B>help</B> [<B>-dms</B>] [<I>pattern</I>]<DD>
9501 Display helpful information about builtin commands. If
9507 gives detailed help on all commands matching
9510 otherwise help for all the builtins and shell control structures
9512 <DL COMPACT><DT><DD>
9518 Display a short description of each <I>pattern</I>
9522 Display the description of each <I>pattern</I> in a manpage-like format
9526 Display only a short usage synopsis for each <I>pattern</I>
9530 The return status is 0 unless no command matches
9533 <DT><B>history [</B><I>n</I>]<DD>
9535 <DT><B>history</B> <B>-c</B><DD>
9536 <DT><B>history -d</B> <I>offset</I><DD>
9537 <DT><B>history</B> <B>-anrw</B> [<I>filename</I>]<DD>
9538 <DT><B>history</B> <B>-p</B> <I>arg</I> [<I>arg ...</I>]<DD>
9539 <DT><B>history</B> <B>-s</B> <I>arg</I> [<I>arg ...</I>]<DD>
9541 With no options, display the command
9542 history list with line numbers. Lines listed
9546 have been modified. An argument of
9553 If the shell variable <B>HISTTIMEFORMAT</B> is set and not null,
9554 it is used as a format string for <I>strftime</I>(3) to display
9555 the time stamp associated with each displayed history entry.
9556 No intervening blank is printed between the formatted time stamp
9557 and the history line.
9558 If <I>filename</I> is supplied, it is used as the
9559 name of the history file; if not, the value of
9560 <FONT SIZE=-1><B>HISTFILE</B>
9563 is used. Options, if supplied, have the following meanings:
9564 <DL COMPACT><DT><DD>
9570 Clear the history list by deleting all the entries.
9571 <DT><B>-d</B> <I>offset</I><DD>
9572 Delete the history entry at position <I>offset</I>.
9576 Append the ``new'' history lines (history lines entered since the
9577 beginning of the current <B>bash</B> session) to the history file.
9581 Read the history lines not already read from the history
9582 file into the current history list. These are lines
9583 appended to the history file since the beginning of the
9584 current <B>bash</B> session.
9588 Read the contents of the history file
9589 and use them as the current history.
9593 Write the current history to the history file, overwriting the
9594 history file's contents.
9598 Perform history substitution on the following <I>args</I> and display
9599 the result on the standard output.
9600 Does not store the results in the history list.
9601 Each <I>arg</I> must be quoted to disable normal history expansion.
9608 in the history list as a single entry. The last command in the
9609 history list is removed before the
9617 If the <B>HISTTIMEFORMAT</B> is set, the time stamp information
9618 associated with each history entry is written to the history file,
9619 marked with the history comment character.
9620 When the history file is read, lines beginning with the history
9621 comment character followed immediately by a digit are interpreted
9622 as timestamps for the previous history line.
9623 The return value is 0 unless an invalid option is encountered, an
9624 error occurs while reading or writing the history file, an invalid
9625 <I>offset</I> is supplied as an argument to <B>-d</B>, or the
9626 history expansion supplied as an argument to <B>-p</B> fails.
9629 <DT><B>jobs</B> [<B>-lnprs</B>] [ <I>jobspec</I> ... ]<DD>
9631 <DT><B>jobs</B> <B>-x</B> <I>command</I> [ <I>args</I> ... ]<DD>
9633 The first form lists the active jobs. The options have the following
9635 <DL COMPACT><DT><DD>
9642 in addition to the normal information.
9646 List only the process ID of the job's process group
9651 Display information only about jobs that have changed status since
9652 the user was last notified of their status.
9656 Restrict output to running jobs.
9660 Restrict output to stopped jobs.
9668 is given, output is restricted to information about that job.
9669 The return status is 0 unless an invalid option is encountered
9691 with the corresponding process group ID, and executes
9697 returning its exit status.
9700 <DT><B>kill</B> [<B>-s</B> <I>sigspec</I> | <B>-n</B> <I>signum</I> | <B>-</B><I>sigspec</I>] [<I>pid</I> | <I>jobspec</I>] ...<DD>
9702 <DT><B>kill</B> <B>-l</B> [<I>sigspec</I> | <I>exit_status</I>]<DD>
9704 Send the signal named by
9710 to the processes named by
9718 is either a case-insensitive signal name such as
9719 <FONT SIZE=-1><B>SIGKILL</B>
9722 (with or without the
9723 <FONT SIZE=-1><B>SIG</B>
9726 prefix) or a signal number;
9733 is not present, then
9734 <FONT SIZE=-1><B>SIGTERM</B>
9741 lists the signal names.
9742 If any arguments are supplied when
9745 is given, the names of the signals corresponding to the arguments are
9746 listed, and the return status is 0.
9747 The <I>exit_status</I> argument to
9750 is a number specifying either a signal number or the exit status of
9751 a process terminated by a signal.
9754 returns true if at least one signal was successfully sent, or false
9755 if an error occurs or an invalid option is encountered.
9756 <DT><B>let</B> <I>arg</I> [<I>arg</I> ...]<DD>
9760 is an arithmetic expression to be evaluated (see
9761 <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>).
9770 returns 1; 0 is returned otherwise.
9771 <DT><B>local</B> [<I>option</I>] [<I>name</I>[=<I>value</I>] ...]<DD>
9772 For each argument, a local variable named
9775 is created, and assigned
9778 The <I>option</I> can be any of the options accepted by <B>declare</B>.
9782 is used within a function, it causes the variable
9785 to have a visible scope restricted to that function and its children.
9789 writes a list of local variables to the standard output. It is
9793 when not within a function. The return status is 0 unless
9796 is used outside a function, an invalid
9800 <I>name</I> is a readonly variable.
9805 <DT><B>mapfile</B> [<B>-n</B> <I>count</I>] [<B>-O</B> <I>origin</I>] [<B>-s</B> <I>count</I>] [<B>-t</B>] [<B>-u</B> <I>fd</I>] [<B>-C</B> <I>callback</I>] [<B>-c</B> <I>quantum</I>] [<I>array</I>]<DD>
9807 <DT><B>readarray</B> [<B>-n</B> <I>count</I>] [<B>-O</B> <I>origin</I>] [<B>-s</B> <I>count</I>] [<B>-t</B>] [<B>-u</B> <I>fd</I>] [<B>-C</B> <I>callback</I>] [<B>-c</B> <I>quantum</I>] [<I>array</I>]<DD>
9809 Read lines from the standard input into array variable
9812 or from file descriptor
9819 The variable <B>MAPFILE</B> is the default <I>array</I>.
9820 Options, if supplied, have the following meanings:
9821 <DL COMPACT><DT><DD>
9830 lines. If <I>count</I> is 0, all lines are copied.
9840 The default index is 0.
9844 Discard the first <I>count</I> lines read.
9848 Remove a trailing line from each line read.
9852 Read lines from file descriptor <I>fd</I> instead of the standard input.
9859 each time <I>quantum</I> lines are read. The <B>-c</B> option specifies
9865 Specify the number of lines read between each call to
9875 is specified without
9878 the default quantum is 5000.
9879 When <I>callback</I> is evaluated, it is supplied the index of the next
9880 array element to be assigned as an additional argument.
9881 <I>callback</I> is evaluated after the line is read but before the
9882 array element is assigned.
9885 If not supplied with an explicit origin, <B>mapfile</B> will clear <I>array</I>
9886 before assigning to it.
9889 <B>mapfile</B> returns successfully unless an invalid option or option
9890 argument is supplied, or <I>array</I> is invalid or unassignable.
9893 <DT><B>popd</B> [-<B>n</B>] [+<I>n</I>] [-<I>n</I>]<DD>
9894 Removes entries from the directory stack. With no arguments,
9895 removes the top directory from the stack, and performs a
9898 to the new top directory.
9899 Arguments, if supplied, have the following meanings:
9900 <DL COMPACT><DT><DD>
9906 Suppresses the normal change of directory when removing directories
9907 from the stack, so that only the stack is manipulated.
9908 <DT><B>+</B><I>n</I><DD>
9909 Removes the <I>n</I>th entry counting from the left of the list
9913 starting with zero. For example:
9916 removes the first directory,
9920 <DT><B>-</B><I>n</I><DD>
9921 Removes the <I>n</I>th entry counting from the right of the list
9925 starting with zero. For example:
9928 removes the last directory,
9939 command is successful, a
9942 is performed as well, and the return status is 0.
9945 returns false if an invalid option is encountered, the directory stack
9946 is empty, a non-existent directory stack entry is specified, or the
9947 directory change fails.
9950 <DT><B>printf</B> [<B>-v</B> <I>var</I>] <I>format</I> [<I>arguments</I>]<DD>
9951 Write the formatted <I>arguments</I> to the standard output under the
9952 control of the <I>format</I>.
9953 The <I>format</I> is a character string which contains three types of objects:
9954 plain characters, which are simply copied to standard output, character
9955 escape sequences, which are converted and copied to the standard output, and
9956 format specifications, each of which causes printing of the next successive
9958 In addition to the standard <I>printf</I>(1) formats, <B>%b</B> causes
9959 <B>printf</B> to expand backslash escape sequences in the corresponding
9960 <I>argument</I> (except that <B>\c</B> terminates output, backslashes in
9961 <B>\aq</B>, <B>\"</B>, and <B>\?</B> are not removed, and octal escapes
9962 beginning with <B>\0</B> may contain up to four digits),
9963 and <B>%q</B> causes <B>printf</B> to output the corresponding
9964 <I>argument</I> in a format that can be reused as shell input.
9966 The <B>-v</B> option causes the output to be assigned to the variable
9967 <I>var</I> rather than being printed to the standard output.
9969 The <I>format</I> is reused as necessary to consume all of the <I>arguments</I>.
9970 If the <I>format</I> requires more <I>arguments</I> than are supplied, the
9971 extra format specifications behave as if a zero value or null string, as
9972 appropriate, had been supplied. The return value is zero on success,
9973 non-zero on failure.
9974 <DT><B>pushd</B> [<B>-n</B>] [+<I>n</I>] [-<I>n</I>]<DD>
9976 <DT><B>pushd</B> [<B>-n</B>] [<I>dir</I>]<DD>
9978 Adds a directory to the top of the directory stack, or rotates
9979 the stack, making the new top of the stack the current working
9980 directory. With no arguments, exchanges the top two directories
9981 and returns 0, unless the directory stack is empty.
9982 Arguments, if supplied, have the following meanings:
9983 <DL COMPACT><DT><DD>
9989 Suppresses the normal change of directory when adding directories
9990 to the stack, so that only the stack is manipulated.
9991 <DT><B>+</B><I>n</I><DD>
9992 Rotates the stack so that the <I>n</I>th directory
9993 (counting from the left of the list shown by
9998 <DT><B>-</B><I>n</I><DD>
9999 Rotates the stack so that the <I>n</I>th directory
10000 (counting from the right of the list shown by
10003 starting with zero) is at the top.
10010 to the directory stack at the top, making it the
10011 new current working directory.
10019 command is successful, a
10022 is performed as well.
10023 If the first form is used,
10026 returns 0 unless the cd to
10029 fails. With the second form,
10032 returns 0 unless the directory stack is empty,
10033 a non-existent directory stack element is specified,
10034 or the directory change to the specified new current directory
10038 <DT><B>pwd</B> [<B>-LP</B>]<DD>
10039 Print the absolute pathname of the current working directory.
10040 The pathname printed contains no symbolic links if the
10043 option is supplied or the
10049 builtin command is enabled.
10053 option is used, the pathname printed may contain symbolic links.
10054 The return status is 0 unless an error occurs while
10055 reading the name of the current directory or an
10056 invalid option is supplied.
10057 <DT><B>read</B> [<B>-ers</B>] [<B>-a</B> <I>aname</I>] [<B>-d</B> <I>delim</I>] [<B>-</B> <I>text</I>] [<B>-n</B> <I>nchars</I>] [<B>-p</B> <I>prompt</I>] [<B>-t</B> <I>timeout</I>] [<B>-u</B> <I>fd</I>] [<I>name</I> ...]<DD>
10058 One line is read from the standard input, or from the file descriptor
10059 <I>fd</I> supplied as an argument to the <B>-u</B> option, and the first word
10060 is assigned to the first
10063 the second word to the second
10066 and so on, with leftover words and their intervening separators assigned
10070 If there are fewer words read from the input stream than names,
10071 the remaining names are assigned empty values.
10073 <FONT SIZE=-1><B>IFS</B>
10076 are used to split the line into words.
10077 The backslash character (<B>\</B>) may be used to remove any special
10078 meaning for the next character read and for line continuation.
10079 Options, if supplied, have the following meanings:
10080 <DL COMPACT><DT><DD>
10083 <DT><B>-a </B><I>aname</I>
10086 The words are assigned to sequential indices
10087 of the array variable
10093 is unset before any new values are assigned.
10094 Other <I>name</I> arguments are ignored.
10095 <DT><B>-d </B><I>delim</I>
10098 The first character of <I>delim</I> is used to terminate the input line,
10099 rather than newline.
10103 If the standard input
10104 is coming from a terminal,
10108 <FONT SIZE=-1><B>READLINE</B>
10111 above) is used to obtain the line.
10112 Readline uses the current (or default, if line editing was not previously
10113 active) editing settings.
10114 <DT><B>-i </B><I>text</I>
10120 is being used to read the line, <I>text</I> is placed into the editing
10121 buffer before editing begins.
10122 <DT><B>-n </B><I>nchars</I>
10125 <B>read</B> returns after reading <I>nchars</I> characters rather than
10126 waiting for a complete line of input.
10127 <DT><B>-p </B><I>prompt</I>
10130 Display <I>prompt</I> on standard error, without a
10131 trailing newline, before attempting to read any input. The prompt
10132 is displayed only if input is coming from a terminal.
10136 Backslash does not act as an escape character.
10137 The backslash is considered to be part of the line.
10138 In particular, a backslash-newline pair may not be used as a line
10143 Silent mode. If input is coming from a terminal, characters are
10145 <DT><B>-t </B><I>timeout</I>
10148 Cause <B>read</B> to time out and return failure if a complete line of
10149 input is not read within <I>timeout</I> seconds.
10150 <I>timeout</I> may be a decimal number with a fractional portion following
10152 This option is only effective if <B>read</B> is reading input from a
10153 terminal, pipe, or other special file; it has no effect when reading
10154 from regular files.
10155 If <I>timeout</I> is 0, <B>read</B> returns success if input is available on
10156 the specified file descriptor, failure otherwise.
10157 The exit status is greater than 128 if the timeout is exceeded.
10158 <DT><B>-u </B><I>fd</I>
10161 Read input from file descriptor <I>fd</I>.
10169 are supplied, the line read is assigned to the variable
10170 <FONT SIZE=-1><B>REPLY</B>.
10173 The return code is zero, unless end-of-file is encountered, <B>read</B>
10174 times out (in which case the return code is greater than 128), or an
10175 invalid file descriptor is supplied as the argument to <B>-u</B>.
10178 <DT><B>readonly</B> [<B>-aApf</B>] [<I>name</I>[=<I>word</I>] ...]<DD>
10181 <I>names</I> are marked readonly; the values of these
10184 may not be changed by subsequent assignment.
10188 option is supplied, the functions corresponding to the
10189 <I>names</I> are so
10194 option restricts the variables to indexed arrays; the
10197 option restricts the variables to associative arrays.
10201 arguments are given, or if the
10204 option is supplied, a list of all readonly names is printed.
10208 option causes output to be displayed in a format that
10209 may be reused as input.
10210 If a variable name is followed by =<I>word</I>, the value of
10211 the variable is set to <I>word</I>.
10212 The return status is 0 unless an invalid option is encountered,
10216 is not a valid shell variable name, or
10222 that is not a function.
10223 <DT><B>return</B> [<I>n</I>]<DD>
10224 Causes a function to exit with the return value specified by
10230 is omitted, the return status is that of the last command
10231 executed in the function body. If used outside a function,
10232 but during execution of a script by the
10235 (<B>source</B>) command, it causes the shell to stop executing
10236 that script and return either
10239 or the exit status of the last command executed within the
10240 script as the exit status of the script. If used outside a
10241 function and not during execution of a script by <B>.</B>,
10242 the return status is false.
10243 Any command associated with the <B>RETURN</B> trap is executed
10244 before execution resumes after the function or script.
10245 <DT><B>set</B> [<B>--abefhkmnptuvxBCEHPT</B>] [<B>-o</B> <I>option</I>] [<I>arg</I> ...]<DD>
10247 <DT><B>set</B> [<B>+abefhkmnptuvxBCEHPT</B>] [<B>+o</B> <I>option</I>] [<I>arg</I> ...]<DD>
10249 Without options, the name and value of each shell variable are displayed
10250 in a format that can be reused as input
10251 for setting or resetting the currently-set variables.
10252 Read-only variables cannot be reset.
10253 In <I>posix mode</I>, only shell variables are listed.
10254 The output is sorted according to the current locale.
10255 When options are specified, they set or unset shell attributes.
10256 Any arguments remaining after option processing are treated
10257 as values for the positional parameters and are assigned, in order, to
10266 Options, if specified, have the following meanings:
10267 <DL COMPACT><DT><DD>
10273 Automatically mark variables and functions which are modified or
10274 created for export to the environment of subsequent commands.
10278 Report the status of terminated background jobs
10279 immediately, rather than before the next primary prompt. This is
10280 effective only when job control is enabled.
10284 Exit immediately if a <I>simple command</I> (see
10285 <FONT SIZE=-1><B>SHELL GRAMMAR</B>
10288 above) exits with a non-zero status.
10289 The shell does not exit if the
10290 command that fails is part of the command list immediately following a
10297 part of the test in an
10300 statement, part of a command executed in a
10307 any command in a pipeline but the last,
10308 or if the command's return value is
10312 Failing simple commands that are part of shell functions or command lists
10313 enclosed in braces or parentheses satisfying the above conditions do not
10314 cause the shell to exit.
10315 A trap on <B>ERR</B>, if set, is executed before the shell exits.
10319 Disable pathname expansion.
10323 Remember the location of commands as they are looked up for execution.
10324 This is enabled by default.
10328 All arguments in the form of assignment statements
10329 are placed in the environment for a command, not just
10330 those that precede the command name.
10334 Monitor mode. Job control is enabled. This option is on
10335 by default for interactive shells on systems that support
10337 <FONT SIZE=-1><B>JOB CONTROL</B>
10340 above). Background processes run in a separate process
10341 group and a line containing their exit status is printed
10342 upon their completion.
10346 Read commands but do not execute them. This may be used to
10347 check a shell script for syntax errors. This is ignored by
10348 interactive shells.
10349 <DT><B>-o </B><I>option-name</I>
10352 The <I>option-name</I> can be one of the following:
10353 <DL COMPACT><DT><DD>
10355 <DT><B>allexport</B>
10361 <DT><B>braceexpand</B>
10370 Use an emacs-style command line editing interface. This is enabled
10371 by default when the shell is interactive, unless the shell is started
10376 This also affects the editing interface used for <B>read -e</B>.
10377 <DT><B>errtrace</B>
10383 <DT><B>functrace</B>
10401 <DT><B>histexpand</B>
10410 Enable command history, as described above under
10411 <FONT SIZE=-1><B>HISTORY</B>.
10414 This option is on by default in interactive shells.
10415 <DT><B>ignoreeof</B>
10418 The effect is as if the shell command
10419 <TT>IGNOREEOF=10</TT>
10423 <B>Shell Variables</B>
10438 <DT><B>noclobber</B>
10478 <DT><B>physical</B>
10484 <DT><B>pipefail</B>
10487 If set, the return value of a pipeline is the value of the last
10488 (rightmost) command to exit with a non-zero status, or zero if all
10489 commands in the pipeline exit successfully.
10490 This option is disabled by default.
10494 Change the behavior of
10497 where the default operation differs
10498 from the POSIX standard to match the standard (<I>posix mode</I>).
10499 <DT><B>privileged</B>
10514 Use a vi-style command line editing interface.
10515 This also affects the editing interface used for <B>read -e</B>.
10529 is supplied with no <I>option-name</I>, the values of the current options are
10534 is supplied with no <I>option-name</I>, a series of
10537 commands to recreate the current option settings is displayed on
10538 the standard output.
10547 mode. In this mode, the
10548 <FONT SIZE=-1><B>$ENV</B>
10552 <FONT SIZE=-1><B>$BASH_ENV</B>
10555 files are not processed, shell functions are not inherited from the
10556 environment, and the
10557 <FONT SIZE=-1><B>SHELLOPTS</B>,
10565 variables, if they appear in the environment, are ignored.
10566 If the shell is started with the effective user (group) id not equal to the
10567 real user (group) id, and the <B>-p</B> option is not supplied, these actions
10568 are taken and the effective user id is set to the real user id.
10569 If the <B>-p</B> option is supplied at startup, the effective user id is
10571 Turning this option off causes the effective user
10572 and group ids to be set to the real user and group ids.
10576 Exit after reading and executing one command.
10580 Treat unset variables as an error when performing
10581 parameter expansion. If expansion is attempted on an
10582 unset variable, the shell prints an error message, and,
10583 if not interactive, exits with a non-zero status.
10587 Print shell input lines as they are read.
10591 After expanding each <I>simple command</I>,
10592 <B>for</B> command, <B>case</B> command, <B>select</B> command, or
10593 arithmetic <B>for</B> command, display the expanded value of
10594 <FONT SIZE=-1><B>PS4</B>,
10597 followed by the command and its expanded arguments
10598 or associated word list.
10602 The shell performs brace expansion (see
10603 <B>Brace Expansion</B>
10605 above). This is on by default.
10612 does not overwrite an existing file with the
10620 redirection operators. This may be overridden when
10621 creating output files by using the redirection operator
10630 If set, any trap on <B>ERR</B> is inherited by shell functions, command
10631 substitutions, and commands executed in a subshell environment.
10632 The <B>ERR</B> trap is normally not inherited in such cases.
10639 style history substitution. This option is on by
10640 default when the shell is interactive.
10644 If set, the shell does not follow symbolic links when executing
10648 that change the current working directory. It uses the
10649 physical directory structure instead. By default,
10652 follows the logical chain of directories when performing commands
10653 which change the current directory.
10657 If set, any traps on <B>DEBUG</B> and <B>RETURN</B> are inherited by shell
10658 functions, command substitutions, and commands executed in a
10659 subshell environment.
10660 The <B>DEBUG</B> and <B>RETURN</B> traps are normally not inherited
10665 If no arguments follow this option, then the positional parameters are
10666 unset. Otherwise, the positional parameters are set to the
10667 <I>arg</I>s, even if some of them begin with a
10673 Signal the end of options, cause all remaining <I>arg</I>s to be
10674 assigned to the positional parameters. The
10680 options are turned off.
10681 If there are no <I>arg</I>s,
10682 the positional parameters remain unchanged.
10687 The options are off by default unless otherwise noted.
10688 Using + rather than - causes these options to be turned off.
10689 The options can also be specified as arguments to an invocation of
10691 The current set of options may be found in
10694 The return status is always true unless an invalid option is encountered.
10697 <DT><B>shift</B> [<I>n</I>]<DD>
10698 The positional parameters from <I>n</I>+1 ... are renamed to
10703 Parameters represented by the numbers <B>$#</B>
10704 down to <B>$#</B>-<I>n</I>+1 are unset.
10707 must be a non-negative number less than or equal to <B>$#</B>.
10711 is 0, no parameters are changed.
10715 is not given, it is assumed to be 1.
10719 is greater than <B>$#</B>, the positional parameters are not changed.
10720 The return status is greater than zero if
10726 or less than zero; otherwise 0.
10727 <DT><B>shopt</B> [<B>-pqsu</B>] [<B>-o</B>] [<I>optname</I> ...]<DD>
10728 Toggle the values of variables controlling optional shell behavior.
10729 With no options, or with the
10732 option, a list of all settable options is displayed, with
10733 an indication of whether or not each is set.
10734 The <B>-p</B> option causes output to be displayed in a form that
10735 may be reused as input.
10736 Other options have the following meanings:
10737 <DL COMPACT><DT><DD>
10743 Enable (set) each <I>optname</I>.
10747 Disable (unset) each <I>optname</I>.
10751 Suppresses normal output (quiet mode); the return status indicates
10752 whether the <I>optname</I> is set or unset.
10753 If multiple <I>optname</I> arguments are given with
10756 the return status is zero if all <I>optnames</I> are enabled; non-zero
10761 Restricts the values of <I>optname</I> to be those defined for the
10778 is used with no <I>optname</I> arguments, the display is limited to
10779 those options which are set or unset, respectively.
10780 Unless otherwise noted, the <B>shopt</B> options are disabled (unset)
10784 The return status when listing options is zero if all <I>optnames</I>
10785 are enabled, non-zero otherwise. When setting or unsetting options,
10786 the return status is zero unless an <I>optname</I> is not a valid shell
10790 The list of <B>shopt</B> options is:
10799 If set, a command name that is the name of a directory is executed as if
10800 it were the argument to the <B>cd</B> command.
10801 This option is only used by interactive shells.
10802 <DT><B>cdable_vars</B>
10805 If set, an argument to the
10808 builtin command that
10809 is not a directory is assumed to be the name of a variable whose
10810 value is the directory to change to.
10814 If set, minor errors in the spelling of a directory component in a
10817 command will be corrected.
10818 The errors checked for are transposed characters,
10819 a missing character, and one character too many.
10820 If a correction is found, the corrected file name is printed,
10821 and the command proceeds.
10822 This option is only used by interactive shells.
10823 <DT><B>checkhash</B>
10826 If set, <B>bash</B> checks that a command found in the hash
10827 table exists before trying to execute it. If a hashed command no
10828 longer exists, a normal path search is performed.
10829 <DT><B>checkjobs</B>
10832 If set, <B>bash</B> lists the status of any stopped and running jobs before
10833 exiting an interactive shell. If any jobs are running, this causes
10834 the exit to be deferred until a second exit is attempted without an
10835 intervening command (see <B>JOB CONTROL</B> above). The shell always
10836 postpones exiting if any jobs are stopped.
10837 <DT><B>checkwinsize</B>
10840 If set, <B>bash</B> checks the window size after each command
10841 and, if necessary, updates the values of
10842 <FONT SIZE=-1><B>LINES</B>
10846 <FONT SIZE=-1><B>COLUMNS</B>.
10855 attempts to save all lines of a multiple-line
10856 command in the same history entry. This allows
10857 easy re-editing of multi-line commands.
10858 <DT><B>compat31</B>
10864 changes its behavior to that of version 3.1 with respect to quoted
10865 arguments to the conditional command's =~ operator.
10866 <DT><B>dirspell</B>
10872 attempts spelling correction on directory names during word completion
10873 if the directory name initially supplied does not exist.
10880 includes filenames beginning with a `.' in the results of pathname
10882 <DT><B>execfail</B>
10885 If set, a non-interactive shell will not exit if
10886 it cannot execute the file specified as an argument to the
10889 builtin command. An interactive shell does not exit if
10893 <DT><B>expand_aliases</B>
10896 If set, aliases are expanded as described above under
10897 <FONT SIZE=-1><B>ALIASES</B>.
10900 This option is enabled by default for interactive shells.
10901 <DT><B>extdebug</B>
10904 If set, behavior intended for use by debuggers is enabled:
10905 <DL COMPACT><DT><DD>
10910 The <B>-F</B> option to the <B>declare</B> builtin displays the source
10911 file name and line number corresponding to each function name supplied
10916 If the command run by the <B>DEBUG</B> trap returns a non-zero value, the
10917 next command is skipped and not executed.
10921 If the command run by the <B>DEBUG</B> trap returns a value of 2, and the
10922 shell is executing in a subroutine (a shell function or a shell script
10923 executed by the <B>.</B> or <B>source</B> builtins), a call to
10924 <B>return</B> is simulated.
10928 <B>BASH_ARGC</B> and <B>BASH_ARGV</B> are updated as described in their
10929 descriptions above.
10933 Function tracing is enabled: command substitution, shell functions, and
10934 subshells invoked with <B>(</B> <I>command</I> <B>)</B> inherit the
10935 <B>DEBUG</B> and <B>RETURN</B> traps.
10939 Error tracing is enabled: command substitution, shell functions, and
10940 subshells invoked with <B>(</B> <I>command</I> <B>)</B> inherit the
10947 If set, the extended pattern matching features described above under
10948 <B>Pathname Expansion</B> are enabled.
10949 <DT><B>extquote</B>
10952 If set, <B>$</B>aq<I>string</I>aq and <B>$</B>"<I>string</I>" quoting is
10953 performed within <B>${</B><I>parameter</I><B>}</B> expansions
10954 enclosed in double quotes. This option is enabled by default.
10955 <DT><B>failglob</B>
10958 If set, patterns which fail to match filenames during pathname expansion
10959 result in an expansion error.
10960 <DT><B>force_fignore</B>
10963 If set, the suffixes specified by the <B>FIGNORE</B> shell variable
10964 cause words to be ignored when performing word completion even if
10965 the ignored words are the only possible completions.
10967 <FONT SIZE=-1><B>SHELL VARIABLES</B></FONT>
10968 above for a description of <B>FIGNORE</B>.
10969 This option is enabled by default.
10970 <DT><B>globstar</B>
10973 If set, the pattern <B>**</B> used in a filename expansion context will
10974 match a files and zero or more directories and subdirectories.
10975 If the pattern is followed by a <B>/</B>, only directories and
10976 subdirectories match.
10977 <DT><B>gnu_errfmt</B>
10980 If set, shell error messages are written in the standard GNU error
10982 <DT><B>histappend</B>
10985 If set, the history list is appended to the file named by the value
10989 variable when the shell exits, rather than overwriting the file.
10990 <DT><B>histreedit</B>
10996 is being used, a user is given the opportunity to re-edit a
10997 failed history substitution.
10998 <DT><B>histverify</B>
11004 is being used, the results of history substitution are not immediately
11005 passed to the shell parser. Instead, the resulting line is loaded into
11006 the <B>readline</B> editing buffer, allowing further modification.
11007 <DT><B>hostcomplete</B>
11013 is being used, <B>bash</B> will attempt to perform hostname completion when a
11014 word containing a <B>@</B> is being completed (see
11018 <FONT SIZE=-1><B>READLINE</B>
11022 This is enabled by default.
11023 <DT><B>huponexit</B>
11026 If set, <B>bash</B> will send
11027 <FONT SIZE=-1><B>SIGHUP</B>
11030 to all jobs when an interactive login shell exits.
11031 <DT><B>interactive_comments</B>
11034 If set, allow a word beginning with
11037 to cause that word and all remaining characters on that
11038 line to be ignored in an interactive shell (see
11039 <FONT SIZE=-1><B>COMMENTS</B>
11042 above). This option is enabled by default.
11049 option is enabled, multi-line commands are saved to the history with
11050 embedded newlines rather than using semicolon separators where possible.
11051 <DT><B>login_shell</B>
11054 The shell sets this option if it is started as a login shell (see
11055 <FONT SIZE=-1><B>INVOCATION</B>
11059 The value may not be changed.
11060 <DT><B>mailwarn</B>
11063 If set, and a file that <B>bash</B> is checking for mail has been
11064 accessed since the last time it was checked, the message ``The mail in
11065 <I>mailfile</I> has been read'' is displayed.
11066 <DT><B>no_empty_cmd_completion</B>
11075 will not attempt to search the <B>PATH</B> for possible completions when
11076 completion is attempted on an empty line.
11077 <DT><B>nocaseglob</B>
11083 matches filenames in a case-insensitive fashion when performing pathname
11085 <B>Pathname Expansion</B>
11088 <DT><B>nocasematch</B>
11094 matches patterns in a case-insensitive fashion when performing matching
11095 while executing <B>case</B> or <B>[[</B> conditional commands.
11096 <DT><B>nullglob</B>
11102 allows patterns which match no
11104 <B>Pathname Expansion</B>
11107 to expand to a null string, rather than themselves.
11108 <DT><B>progcomp</B>
11111 If set, the programmable completion facilities (see
11112 <B>Programmable Completion</B> above) are enabled.
11113 This option is enabled by default.
11114 <DT><B>promptvars</B>
11117 If set, prompt strings undergo
11118 parameter expansion, command substitution, arithmetic
11119 expansion, and quote removal after being expanded as described in
11120 <FONT SIZE=-1><B>PROMPTING</B>
11123 above. This option is enabled by default.
11124 <DT><B>restricted_shell</B>
11127 The shell sets this option if it is started in restricted mode (see
11128 <FONT SIZE=-1><B>RESTRICTED SHELL</B>
11132 The value may not be changed.
11133 This is not reset when the startup files are executed, allowing
11134 the startup files to discover whether or not a shell is restricted.
11135 <DT><B>shift_verbose</B>
11141 builtin prints an error message when the shift count exceeds the
11142 number of positional parameters.
11143 <DT><B>sourcepath</B>
11147 <B>source</B> (<B>.</B>) builtin uses the value of
11148 <FONT SIZE=-1><B>PATH</B>
11151 to find the directory containing the file supplied as an argument.
11152 This option is enabled by default.
11153 <DT><B>xpg_echo</B>
11156 If set, the <B>echo</B> builtin expands backslash-escape sequences
11160 <DT><B>suspend</B> [<B>-f</B>]<DD>
11161 Suspend the execution of this shell until it receives a
11162 <FONT SIZE=-1><B>SIGCONT</B>
11165 signal. A login shell cannot be suspended; the
11168 option can be used to override this and force the suspension.
11169 The return status is 0 unless the shell is a login shell and
11172 is not supplied, or if job control is not enabled.
11173 <DT><B>test</B> <I>expr</I><DD>
11175 <DT><B>[</B> <I>expr</I> <B>]</B><DD>
11176 Return a status of 0 or 1 depending on
11177 the evaluation of the conditional expression
11180 Each operator and operand must be a separate argument.
11181 Expressions are composed of the primaries described above under
11182 <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>.
11185 <B>test</B> does not accept any options, nor does it accept and ignore
11186 an argument of <B>--</B> as signifying the end of options.
11190 Expressions may be combined using the following operators, listed
11191 in decreasing order of precedence.
11192 The evaluation depends on the number of arguments; see below.
11193 <DL COMPACT><DT><DD>
11196 <DT><B>! </B><I>expr</I>
11203 <DT><B>( </B><I>expr</I> )
11206 Returns the value of <I>expr</I>.
11207 This may be used to override the normal precedence of operators.
11208 <DT><I>expr1</I> -<B>a</B> <I>expr2</I><DD>
11216 <DT><I>expr1</I> -<B>o</B> <I>expr2</I><DD>
11228 <B>test</B> and <B>[</B> evaluate conditional
11229 expressions using a set of rules based on the number of arguments.
11235 <DT>0 arguments<DD>
11236 The expression is false.
11238 The expression is true if and only if the argument is not null.
11239 <DT>2 arguments<DD>
11240 If the first argument is <B>!</B>, the expression is true if and
11241 only if the second argument is null.
11242 If the first argument is one of the unary conditional operators listed above
11244 <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>,
11247 the expression is true if the unary test is true.
11248 If the first argument is not a valid unary conditional operator, the expression
11250 <DT>3 arguments<DD>
11251 If the second argument is one of the binary conditional operators listed above
11253 <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>,
11256 the result of the expression is the result of the binary test using
11257 the first and third arguments as operands.
11258 The <B>-a</B> and <B>-o</B> operators are considered binary operators
11259 when there are three arguments.
11260 If the first argument is <B>!</B>, the value is the negation of
11261 the two-argument test using the second and third arguments.
11262 If the first argument is exactly <B>(</B> and the third argument is
11263 exactly <B>)</B>, the result is the one-argument test of the second
11265 Otherwise, the expression is false.
11266 <DT>4 arguments<DD>
11267 If the first argument is <B>!</B>, the result is the negation of
11268 the three-argument expression composed of the remaining arguments.
11269 Otherwise, the expression is parsed and evaluated according to
11270 precedence using the rules listed above.
11271 <DT>5 or more arguments<DD>
11272 The expression is parsed and evaluated according to precedence
11273 using the rules listed above.
11280 Print the accumulated user and system times for the shell and
11281 for processes run from the shell. The return status is 0.
11282 <DT><B>trap</B> [<B>-lp</B>] [[<I>arg</I>] <I>sigspec</I> ...]<DD>
11286 is to be read and executed when the shell receives
11293 is absent (and there is a single <I>sigspec</I>) or
11296 each specified signal is
11297 reset to its original disposition (the value it had
11298 upon entrance to the shell).
11302 is the null string the signal specified by each
11305 is ignored by the shell and by the commands it invokes.
11312 has been supplied, then the trap commands associated with each
11316 If no arguments are supplied or if only
11322 prints the list of commands associated with each signal.
11326 option causes the shell to print a list of signal names and
11327 their corresponding numbers.
11332 a signal name defined in <<I>signal.h</I>>, or a signal number.
11333 Signal names are case insensitive and the SIG prefix is optional.
11338 <FONT SIZE=-1><B>EXIT</B>
11344 is executed on exit from the shell.
11349 <FONT SIZE=-1><B>DEBUG</B>,
11355 is executed before every <I>simple command</I>, <I>for</I> command,
11356 <I>case</I> command, <I>select</I> command, every arithmetic <I>for</I>
11357 command, and before the first command executes in a shell function (see
11358 <FONT SIZE=-1><B>SHELL GRAMMAR</B>
11362 Refer to the description of the <B>extdebug</B> option to the
11363 <B>shopt</B> builtin for details of its effect on the <B>DEBUG</B> trap.
11368 <FONT SIZE=-1><B>ERR</B>,
11374 is executed whenever a simple command has a non-zero exit status,
11375 subject to the following conditions.
11377 <FONT SIZE=-1><B>ERR</B>
11380 trap is not executed if the failed
11381 command is part of the command list immediately following a
11388 part of the test in an
11391 statement, part of a command executed in a
11397 list, or if the command's return value is
11401 These are the same conditions obeyed by the <B>errexit</B> option.
11406 <FONT SIZE=-1><B>RETURN</B>,
11412 is executed each time a shell function or a script executed with the
11413 <B>.</B> or <B>source</B> builtins finishes executing.
11414 Signals ignored upon entry to the shell cannot be trapped or reset.
11415 Trapped signals that are not being ignored are reset to their original
11416 values in a child process when it is created.
11417 The return status is false if any
11420 is invalid; otherwise
11424 <DT><B>type</B> [<B>-aftpP</B>] <I>name</I> [<I>name</I> ...]<DD>
11429 would be interpreted if used as a command name.
11436 prints a string which is one of
11451 is an alias, shell reserved word, function, builtin, or disk file,
11456 is not found, then nothing is printed, and an exit status of false
11464 either returns the name of the disk file
11465 that would be executed if
11468 were specified as a command name,
11470 <TT>type -t name</TT>
11479 <FONT SIZE=-1><B>PATH</B>
11482 search for each <I>name</I>, even if
11483 <TT>type -t name</TT>
11488 If a command is hashed,
11494 print the hashed value, not necessarily the file that appears
11496 <FONT SIZE=-1><B>PATH</B>.
11505 prints all of the places that contain
11506 an executable named
11509 This includes aliases and functions,
11513 option is not also used.
11514 The table of hashed commands is not consulted
11521 option suppresses shell function lookup, as with the <B>command</B> builtin.
11524 returns true if all of the arguments are found, false if
11526 <DT><B>ulimit</B> [<B>-HSTabcdefilmnpqrstuvx</B> [<I>limit</I>]]<DD>
11527 Provides control over the resources available to the shell and to
11528 processes started by it, on systems that allow such control.
11529 The <B>-H</B> and <B>-S</B> options specify that the hard or soft limit is
11530 set for the given resource.
11531 A hard limit cannot be increased by a non-root user once it is set;
11532 a soft limit may be increased up to the value of the hard limit.
11533 If neither <B>-H</B> nor <B>-S</B> is specified, both the soft and hard
11538 can be a number in the unit specified for the resource
11539 or one of the special values
11547 which stand for the current hard limit, the current soft limit, and
11548 no limit, respectively.
11552 is omitted, the current value of the soft limit of the resource is
11553 printed, unless the <B>-H</B> option is given. When more than one
11554 resource is specified, the limit name and unit are printed before the value.
11555 Other options are interpreted as follows:
11556 <DL COMPACT><DT><DD>
11562 All current limits are reported
11566 The maximum socket buffer size
11570 The maximum size of core files created
11574 The maximum size of a process's data segment
11578 The maximum scheduling priority ("nice")
11582 The maximum size of files written by the shell and its children
11586 The maximum number of pending signals
11590 The maximum size that may be locked into memory
11594 The maximum resident set size
11598 The maximum number of open file descriptors (most systems do not
11599 allow this value to be set)
11603 The pipe size in 512-byte blocks (this may not be set)
11607 The maximum number of bytes in POSIX message queues
11611 The maximum real-time scheduling priority
11615 The maximum stack size
11619 The maximum amount of cpu time in seconds
11623 The maximum number of processes available to a single user
11627 The maximum amount of virtual memory available to the shell
11631 The maximum number of file locks
11635 The maximum number of threads
11643 is given, it is the new value of the specified resource (the
11646 option is display only).
11647 If no option is given, then
11650 is assumed. Values are in 1024-byte increments, except for
11653 which is in seconds,
11656 which is in units of 512-byte blocks,
11667 which are unscaled values.
11668 The return status is 0 unless an invalid option or argument is supplied,
11669 or an error occurs while setting a new limit.
11672 <DT><B>umask</B> [<B>-p</B>] [<B>-S</B>] [<I>mode</I>]<DD>
11673 The user file-creation mask is set to
11679 begins with a digit, it
11680 is interpreted as an octal number; otherwise
11681 it is interpreted as a symbolic mode mask similar
11682 to that accepted by
11688 is omitted, the current value of the mask is printed.
11692 option causes the mask to be printed in symbolic form; the
11693 default output is an octal number.
11697 option is supplied, and
11700 is omitted, the output is in a form that may be reused as input.
11701 The return status is 0 if the mode was successfully changed or if
11702 no <I>mode</I> argument was supplied, and false otherwise.
11703 <DT><B>unalias</B> [-<B>a</B>] [<I>name</I> ...]<DD>
11704 Remove each <I>name</I> from the list of defined aliases. If
11707 is supplied, all alias definitions are removed. The return
11708 value is true unless a supplied
11711 is not a defined alias.
11712 <DT><B>unset</B> [-<B>fv</B>] [<I>name</I> ...]<DD>
11716 remove the corresponding variable or function.
11717 If no options are supplied, or the
11720 option is given, each
11723 refers to a shell variable.
11724 Read-only variables may not be unset.
11731 refers to a shell function, and the function definition
11733 Each unset variable or function is removed from the environment
11734 passed to subsequent commands.
11736 <FONT SIZE=-1><B>RANDOM</B>,
11739 <FONT SIZE=-1><B>SECONDS</B>,
11742 <FONT SIZE=-1><B>LINENO</B>,
11745 <FONT SIZE=-1><B>HISTCMD</B>,
11748 <FONT SIZE=-1><B>FUNCNAME</B>,
11751 <FONT SIZE=-1><B>GROUPS</B>,
11755 <FONT SIZE=-1><B>DIRSTACK</B>
11758 are unset, they lose their special properties, even if they are
11759 subsequently reset. The exit status is true unless a
11763 <DT><B>wait</B> [<I>n ...</I>]<DD>
11764 Wait for each specified process and return its termination status.
11769 ID or a job specification; if a job spec is given, all processes
11770 in that job's pipeline are waited for. If
11773 is not given, all currently active child processes
11774 are waited for, and the return status is zero. If
11777 specifies a non-existent process or job, the return status is
11778 127. Otherwise, the return status is the exit status of the last
11779 process or job waited for.
11783 <A NAME="lbDC"> </A>
11784 <H3>RESTRICTED SHELL</H3>
11793 is started with the name
11799 option is supplied at invocation,
11800 the shell becomes restricted.
11801 A restricted shell is used to
11802 set up an environment more controlled than the standard shell.
11803 It behaves identically to
11806 with the exception that the following are disallowed or not performed:
11809 changing directories with <B>cd</B>
11811 setting or unsetting the values of
11822 specifying command names containing
11826 specifying a file name containing a
11829 as an argument to the
11834 Specifying a filename containing a slash as an argument to the
11842 importing function definitions from the shell environment at startup
11844 parsing the value of <B>SHELLOPTS</B> from the shell environment at startup
11846 redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
11851 builtin command to replace the shell with another command
11853 adding or deleting builtin commands with the
11864 Using the <B>enable</B> builtin command to enable disabled shell builtins
11874 turning off restricted mode with
11875 <B>set +r</B> or <B>set +o restricted</B>.
11879 These restrictions are enforced after any startup files are read.
11883 When a command that is found to be a shell script is executed
11885 <FONT SIZE=-1><B>COMMAND EXECUTION</B>
11893 turns off any restrictions in the shell spawned to execute the
11897 <A NAME="lbDD"> </A>
11902 <DT><I>Bash Reference Manual</I>, Brian Fox and Chet Ramey<DD>
11903 <DT><I>The Gnu Readline Library</I>, Brian Fox and Chet Ramey<DD>
11904 <DT><I>The Gnu History Library</I>, Brian Fox and Chet Ramey<DD>
11905 <DT><I>Portable Operating System Interface (POSIX) Part 2: Shell and Utilities</I>, IEEE<DD>
11906 <DT><I>sh</I>(1), <I>ksh</I>(1), <I>csh</I>(1)<DD>
11907 <DT><I>emacs</I>(1), <I>vi</I>(1)<DD>
11908 <DT><I>readline</I>(3)<DD>
11911 <A NAME="lbDE"> </A>
11917 <A HREF="file:/bin/bash"><I>/bin/bash</I></A>
11920 The <B>bash</B> executable
11922 <A HREF="file:/etc/profile"><I>/etc/profile</I></A>
11925 The systemwide initialization file, executed for login shells
11927 <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A>
11930 The personal initialization file, executed for login shells
11932 <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>
11935 The individual per-interactive-shell startup file
11937 <A HREF="file:~/.bash_logout"><I>~/.bash_logout</I></A>
11940 The individual login shell cleanup file, executed when a login shell exits
11942 <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A>
11945 Individual <I>readline</I> initialization file
11948 <A NAME="lbDF"> </A>
11951 Brian Fox, Free Software Foundation
11954 <A HREF="mailto:bfox@gnu.org">bfox@gnu.org</A>
11957 Chet Ramey, Case Western Reserve University
11960 <A HREF="mailto:chet@po.cwru.edu">chet@po.cwru.edu</A>
11961 <A NAME="lbDG"> </A>
11962 <H3>BUG REPORTS</H3>
11964 If you find a bug in
11967 you should report it. But first, you should
11968 make sure that it really is a bug, and that it appears in the latest
11972 The latest version is always available from
11973 <I><A HREF="ftp://ftp.gnu.org/pub/bash/">ftp://ftp.gnu.org/pub/bash/</A></I>.
11976 Once you have determined that a bug actually exists, use the
11979 command to submit a bug report.
11980 If you have a fix, you are encouraged to mail that as well!
11981 Suggestions and `philosophical' bug reports may be mailed
11982 to <I><A HREF="mailto:bug-bash@gnu.org">bug-bash@gnu.org</A></I> or posted to the Usenet
11984 <A HREF="news:gnu.bash.bug">gnu.bash.bug</A>.
11988 ALL bug reports should include:
11993 <DT>The version number of <B>bash</B><DD>
11994 <DT>The hardware and operating system<DD>
11995 <DT>The compiler used to compile<DD>
11996 <DT>A description of the bug behaviour<DD>
11997 <DT>A short script or `recipe' which exercises the bug<DD>
12004 inserts the first three items automatically into the template
12005 it provides for filing a bug report.
12008 Comments and bug reports concerning
12009 this manual page should be directed to
12010 <I><A HREF="mailto:chet@po.cwru.edu">chet@po.cwru.edu</A></I>.
12012 <A NAME="lbDH"> </A>
12017 It's too big and too slow.
12020 There are some subtle differences between
12023 and traditional versions of
12026 mostly because of the
12027 <FONT SIZE=-1><B>POSIX</B>
12033 Aliases are confusing in some uses.
12036 Shell builtin commands and functions are not stoppable/restartable.
12039 Compound commands and command sequences of the form `a ; b ; c'
12040 are not handled gracefully when process suspension is attempted.
12041 When a process is stopped, the shell immediately executes the next
12042 command in the sequence.
12043 It suffices to place the sequence of commands between
12044 parentheses to force it into a subshell, which may be stopped as
12048 Array variables may not (yet) be exported.
12051 There may be only one active coprocess at a time.
12058 <TH ALIGN=LEFT width=33%>GNU Bash-4.0<TH ALIGN=CENTER width=33%>2008 December 29<TH ALIGN=RIGHT width=33%>BASH(1)
12062 <A NAME="index"> </A><H2>Index</H2>
12064 <DT><A HREF="#lbAB">NAME</A><DD>
12065 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
12066 <DT><A HREF="#lbAD">COPYRIGHT</A><DD>
12067 <DT><A HREF="#lbAE">DESCRIPTION</A><DD>
12068 <DT><A HREF="#lbAF">OPTIONS</A><DD>
12069 <DT><A HREF="#lbAG">ARGUMENTS</A><DD>
12070 <DT><A HREF="#lbAH">INVOCATION</A><DD>
12071 <DT><A HREF="#lbAI">DEFINITIONS</A><DD>
12072 <DT><A HREF="#lbAJ">RESERVED WORDS</A><DD>
12073 <DT><A HREF="#lbAK">SHELL GRAMMAR</A><DD>
12075 <DT><A HREF="#lbAL">Simple Commands</A><DD>
12076 <DT><A HREF="#lbAM">Pipelines</A><DD>
12077 <DT><A HREF="#lbAN">Lists</A><DD>
12078 <DT><A HREF="#lbAO">Compound Commands</A><DD>
12079 <DT><A HREF="#lbAP">Coprocesses</A><DD>
12080 <DT><A HREF="#lbAQ">Shell Function Definitions</A><DD>
12082 <DT><A HREF="#lbAR">COMMENTS</A><DD>
12083 <DT><A HREF="#lbAS">QUOTING</A><DD>
12084 <DT><A HREF="#lbAT">PARAMETERS</A><DD>
12086 <DT><A HREF="#lbAU">Positional Parameters</A><DD>
12087 <DT><A HREF="#lbAV">Special Parameters</A><DD>
12088 <DT><A HREF="#lbAW">Shell Variables</A><DD>
12089 <DT><A HREF="#lbAX">Arrays</A><DD>
12091 <DT><A HREF="#lbAY">EXPANSION</A><DD>
12093 <DT><A HREF="#lbAZ">Brace Expansion</A><DD>
12094 <DT><A HREF="#lbBA">Tilde Expansion</A><DD>
12095 <DT><A HREF="#lbBB">Parameter Expansion</A><DD>
12096 <DT><A HREF="#lbBC">Command Substitution</A><DD>
12097 <DT><A HREF="#lbBD">Arithmetic Expansion</A><DD>
12098 <DT><A HREF="#lbBE">Process Substitution</A><DD>
12099 <DT><A HREF="#lbBF">Word Splitting</A><DD>
12100 <DT><A HREF="#lbBG">Pathname Expansion</A><DD>
12101 <DT><A HREF="#lbBH">Quote Removal</A><DD>
12103 <DT><A HREF="#lbBI">REDIRECTION</A><DD>
12105 <DT><A HREF="#lbBJ">Redirecting Input</A><DD>
12106 <DT><A HREF="#lbBK">Redirecting Output</A><DD>
12107 <DT><A HREF="#lbBL">Appending Redirected Output</A><DD>
12108 <DT><A HREF="#lbBM">Redirecting Standard Output and Standard Error</A><DD>
12109 <DT><A HREF="#lbBN">Appending Standard Output and Standard Error</A><DD>
12110 <DT><A HREF="#lbBO">Here Documents</A><DD>
12111 <DT><A HREF="#lbBP">Here Strings</A><DD>
12112 <DT><A HREF="#lbBQ">Duplicating File Descriptors</A><DD>
12113 <DT><A HREF="#lbBR">Moving File Descriptors</A><DD>
12114 <DT><A HREF="#lbBS">Opening File Descriptors for Reading and Writing</A><DD>
12116 <DT><A HREF="#lbBT">ALIASES</A><DD>
12117 <DT><A HREF="#lbBU">FUNCTIONS</A><DD>
12118 <DT><A HREF="#lbBV">ARITHMETIC EVALUATION</A><DD>
12119 <DT><A HREF="#lbBW">CONDITIONAL EXPRESSIONS</A><DD>
12120 <DT><A HREF="#lbBX">SIMPLE COMMAND EXPANSION</A><DD>
12121 <DT><A HREF="#lbBY">COMMAND EXECUTION</A><DD>
12122 <DT><A HREF="#lbBZ">COMMAND EXECUTION ENVIRONMENT</A><DD>
12123 <DT><A HREF="#lbCA">ENVIRONMENT</A><DD>
12124 <DT><A HREF="#lbCB">EXIT STATUS</A><DD>
12125 <DT><A HREF="#lbCC">SIGNALS</A><DD>
12126 <DT><A HREF="#lbCD">JOB CONTROL</A><DD>
12127 <DT><A HREF="#lbCE">PROMPTING</A><DD>
12128 <DT><A HREF="#lbCF">READLINE</A><DD>
12130 <DT><A HREF="#lbCG">Readline Notation</A><DD>
12131 <DT><A HREF="#lbCH">Readline Initialization</A><DD>
12132 <DT><A HREF="#lbCI">Readline Key Bindings</A><DD>
12133 <DT><A HREF="#lbCJ">Readline Variables</A><DD>
12134 <DT><A HREF="#lbCK">Readline Conditional Constructs</A><DD>
12135 <DT><A HREF="#lbCL">Searching</A><DD>
12136 <DT><A HREF="#lbCM">Readline Command Names</A><DD>
12137 <DT><A HREF="#lbCN">Commands for Moving</A><DD>
12138 <DT><A HREF="#lbCO">Commands for Manipulating the History</A><DD>
12139 <DT><A HREF="#lbCP">Commands for Changing Text</A><DD>
12140 <DT><A HREF="#lbCQ">Killing and Yanking</A><DD>
12141 <DT><A HREF="#lbCR">Numeric Arguments</A><DD>
12142 <DT><A HREF="#lbCS">Completing</A><DD>
12143 <DT><A HREF="#lbCT">Keyboard Macros</A><DD>
12144 <DT><A HREF="#lbCU">Miscellaneous</A><DD>
12145 <DT><A HREF="#lbCV">Programmable Completion</A><DD>
12147 <DT><A HREF="#lbCW">HISTORY</A><DD>
12148 <DT><A HREF="#lbCX">HISTORY EXPANSION</A><DD>
12150 <DT><A HREF="#lbCY">Event Designators</A><DD>
12151 <DT><A HREF="#lbCZ">Word Designators</A><DD>
12152 <DT><A HREF="#lbDA">Modifiers</A><DD>
12154 <DT><A HREF="#lbDB">SHELL BUILTIN COMMANDS</A><DD>
12155 <DT><A HREF="#lbDC">RESTRICTED SHELL</A><DD>
12156 <DT><A HREF="#lbDD">SEE ALSO</A><DD>
12157 <DT><A HREF="#lbDE">FILES</A><DD>
12158 <DT><A HREF="#lbDF">AUTHORS</A><DD>
12159 <DT><A HREF="#lbDG">BUG REPORTS</A><DD>
12160 <DT><A HREF="#lbDH">BUGS</A><DD>
12163 This document was created by man2html from bash.1.<BR>
12164 Time: 05 February 2009 08:05:34 EST
projects / platform / upstream / bash.git / blob