2 .\" MAN PAGE COMMENTS to
5 .\" Information Network Services
6 .\" Case Western Reserve University
9 .\" Last Change: Mon May 19 12:45:24 EDT 1997
11 .\" bash_builtins, strip all but Built-Ins section
13 .TH BASH 1 "1997 May 19" GNU
15 .\" There's some problem with having a `@'
16 .\" in a tagged paragraph with the BSD man macros.
17 .\" It has to do with `@' appearing in the }1 macro.
18 .\" This is a problem on 4.3 BSD and Ultrix, but Sun
19 .\" appears to have fixed it.
20 .\" If you're seeing the characters
21 .\" `@u-3p' appearing before the lines reading
22 .\" `possible-hostname-completions
23 .\" and `complete-hostname' down in READLINE,
24 .\" then uncomment this redefinition.
29 .if !"\\$1"" .nr )I \\$1n
32 .in \\n()Ru+\\n(INu+\\n()Iu
34 .ie !\\n()Iu+\\n()Ru-\w
\a\\*(]X
\au-3p \{\\*(]X
36 .el \\*(]X\h
\a|\\n()Iu+\\n()Ru
\a\c
40 .\" File Name macro. This used to be `.PN', for Path Name,
41 .\" but Sun doesn't seem to like that very much.
47 bash \- GNU Bourne-Again SHell
53 .if n Bash is Copyright (C) 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc.
54 .if t Bash is Copyright \(co 1989, 1991, 1993, 1995, 1996 by the Free Software Foundation, Inc.
57 is an \fBsh\fR-compatible command language interpreter that
58 executes commands read from the standard input or from a file.
60 also incorporates useful features from the \fIKorn\fP and \fIC\fP
61 shells (\fBksh\fP and \fBcsh\fP).
64 is ultimately intended to be a conformant implementation of the IEEE
65 POSIX Shell and Tools specification (IEEE Working Group 1003\.2).
67 In addition to the single-character shell options documented in the
68 description of the \fBset\fR builtin command, \fBbash\fR
69 interprets the following flags when it is invoked:
76 flag is present, then commands are read from
78 If there are arguments after the
80 they are assigned to the positional parameters, starting with
86 flag is present, the shell becomes
96 flag is present, the shell is
102 flag is present, or if no arguments remain after option
103 processing, then commands are read from the standard input.
104 This option allows the positional parameters to be set
105 when invoking an interactive shell.
108 A list of all double-quoted strings preceded by \fB$\fP
109 is printed on the standard ouput.
110 These are the strings that
111 are subject to language translation when the current locale
113 This implies the \fB\-n\fP option; no commands will be executed.
118 signals the end of options and disables further option processing.
119 Any arguments after the
121 are treated as filenames and arguments. An argument of
123 is equivalent to \fB\-\-\fP.
127 also interprets a number of multi-character options.
128 These options must appear on the command line before the
129 single-character options in order for them to be recognized.
134 Equivalent to \fB\-D\fP.
137 Display a usage message on standard output and exit successfully.
142 act as if it had been invoked as a login shell (see
150 library to read command lines if interactive.
153 Do not read either the system-wide startup file
155 or any of the personal initialization files
156 .IR ~/.bash_profile ,
162 reads these files when it is invoked as a login shell (see
168 Do not read and execute the personal initialization file
170 if the shell is interactive.
171 This option is on by default if the shell is invoked as
175 Change the behavior of \fBbash\fP where the default operation differs
176 from the POSIX 1003.2 standard to match the standard.
178 \fB\-\-rcfile\fP \fIfile\fP
179 Execute commands from
181 instead of the standard personal initialization file
183 if the shell is interactive (see
189 The shell becomes restricted (see
191 .B "RESTRICTED SHELL"
195 Equivalent to \fB\-v\fP.
198 Show version information for this instance of
200 on the standard output and exit successfully.
203 If arguments remain after option processing, and neither the
207 option has been supplied, the first argument is assumed to
208 be the name of a file containing shell commands.
211 is invoked in this fashion,
213 is set to the name of the file, and the positional parameters
214 are set to the remaining arguments.
216 reads and executes commands from this file, then exits.
217 \fBBash\fP's exit status is the exit status of the last command
218 executed in the script.
219 If no commands are executed, the exit status is 0.
221 A \fIlogin shell\fP is one whose first character of argument zero is a
223 or one started with the
227 An \fIinteractive\fP shell is one whose standard input and output are
228 both connected to terminals (as determined by
230 or one started with the
242 allowing a shell script or a startup file to test this state.
244 The following paragraphs describe how
246 executes its startup files.
247 If any of the files exist but cannot be read,
250 Tildes are expanded in file names as described below under
259 is invoked as an interactive login shell, it first reads and
260 executes commands from the file \fI/etc/profile\fP, if that
262 After reading that file, it looks for \fI~/.bash_profile\fP,
263 \fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads
264 and executes commands from the first one that exists and is readable.
267 option may be used when the shell is started to inhibit this behavior.
269 When a login shell exits,
271 reads and executes commands from the file \fI~/.bash_logout\fP, if it
274 When an interactive shell that is not a login shell is started,
276 reads and executes commands from \fI~/.bashrc\fP, if that file exists.
277 This may be inhibited by using the
280 The \fB\-\-rcfile\fP \fIfile\fP option will force
282 to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP.
286 is started non-interactively, to run a shell script, for example, it
287 looks for the variable
290 in the environment, expands its value if it appears there, and uses the
291 expanded value as the name of a file to read and execute.
293 behaves as if the following command were executed:
296 \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP
302 variable is not used to search for the file name.
306 is invoked with the name
308 it tries to mimic the startup behavior of historical versions of
310 as closely as possible,
311 while conforming to the POSIX standard as well.
312 When invoked as a login shell, it first attempts to read and execute
320 option may be used to inhibit this behavior.
321 When invoked as an interactive shell with the name
324 looks for the variable
327 expands its value if it is defined, and uses the
328 expanded value as the name of a file to read and execute.
329 Since a shell invoked as
331 does not attempt to read and execute commands from any other startup
334 option has no effect.
335 A non-interactive shell invoked with the name
337 does not attempt to read any startup files.
343 mode after the startup files are read.
351 command line option, it follows the POSIX standard for startup files.
355 variable is expanded and commands are read and executed from the file
356 whose name is the expanded value.
357 No other startup files are read.
358 This is done by interactive shells only.
361 attempts to determine when it is being run by the remote shell
362 daemon, usually \fIrshd\fP.
365 determines it is being run by \fIrshd\fP, it reads and executes
366 commands from \fI~/.bashrc\fP, if that file exists and is readable.
367 It will not do this if invoked as \fBsh\fP.
370 option may be used to inhibit this behavior, and the
372 option may be used to force another file to be read, but
373 \fIrshd\fP does not generally invoke the shell with those options
374 or allow them to be specified.
377 The following definitions are used throughout the rest of this
385 A sequence of characters considered as a single unit by the shell.
392 consisting only of alphanumeric characters and underscores, and
393 beginning with an alphabetic character or an underscore. Also
398 A character that, when unquoted, separates words. One of the following:
402 .if t \fB| & ; ( ) < > space tab\fP
403 .if n \fB| & ; ( ) < > space tab\fP
408 A \fItoken\fP that performs a control function. It is one of the following
412 .if t \fB\(bv\(bv & && ; ;; ( ) | <newline>\fP
413 .if n \fB|| & && ; ;; ( ) | <newline>\fP
417 \fIReserved words\fP are words that have a special meaning to the shell.
418 The following words are recognized as reserved when unquoted and either
419 the first word of a simple command (see
422 below) or the third word of a
430 .if n ! case do done elif else esac fi for function if in select then until while { } time
431 .if t ! case do done elif else esac fi for function if in select then until while { } time
437 A \fIsimple command\fP is a sequence of optional variable assignments
438 followed by \fBblank\fP-separated words and redirections, and
439 terminated by a \fIcontrol operator\fP. The first word
440 specifies the command to be executed. The remaining words are
441 passed as arguments to the invoked command.
443 The return value of a \fIsimple command\fP is its exit status, or
444 128+\fIn\^\fP if the command is terminated by signal
448 A \fIpipeline\fP is a sequence of one or more commands separated by
451 The format for a pipeline is:
454 [\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand\fP [ \fB|\fP \fIcommand2\fP ... ]
457 The standard output of
459 is connected to the standard input of
461 This connection is performed before any redirections specified by the
469 precedes a pipeline, the exit status of that
470 pipeline is the logical NOT of the exit status of the last command.
471 Otherwise, the status of the pipeline is the exit status of the last
473 The shell waits for all commands in the pipeline to
474 terminate before returning a value.
478 reserved word precedes a pipeline, the elapsed as well as user and
479 system time consumed by its execution are reported when the pipeline
481 The \fB\-p\fP option changes the output format to that specified by POSIX.
485 variable may be set to a format string that specifies how the timing
486 information should be displayed; see the description of
493 Each command in a pipeline is executed as a separate process (i.e., in a
497 A \fIlist\fP is a sequence of one or more pipelines separated by one
504 and optionally terminated by one of
510 Of these list operators,
514 have equal precedence, followed by
518 which have equal precedence.
520 If a command is terminated by the control operator
522 the shell executes the command in the \fIbackground\fP
523 in a subshell. The shell does not wait for the command to
524 finish, and the return status is 0. Commands separated by a
526 are executed sequentially; the shell waits for each
527 command to terminate in turn. The return status is the
528 exit status of the last command executed.
530 The control operators
534 denote AND lists and OR lists, respectively.
535 An AND list has the form
538 \fIcommand\fP \fB&&\fP \fIcommand2\fP
542 is executed if, and only if,
544 returns an exit status of zero.
546 An OR list has the form
549 \fIcommand\fP \fB\(bv\(bv\fP \fIcommand2\fP
554 is executed if and only if
556 returns a non-zero exit status. The return status of
557 AND and OR lists is the exit status of the last command
558 executed in the list.
559 .SS Compound Commands
561 A \fIcompound command\fP is one of the following:
564 \fIlist\fP is executed in a subshell. Variable assignments and builtin
565 commands that affect the shell's environment do not remain in effect
566 after the command completes. The return status is the exit status of
570 \fIlist\fP is simply executed in the current shell environment.
571 \fIlist\fP must be terminated with a newline or semicolon.
572 This is known as a \fIgroup command\fP.
573 The return status is the exit status of
577 The \fIexpression\fP is evaluated according to the rules described
580 .BR "ARITHMETIC EVALUATION" .
581 If the value of the expression is non-zero, the return status is 0;
582 otherwise the return status is 1. This is exactly equivalent to
583 \fBlet "\fIexpression\fP"\fR.
585 \fBfor\fP \fIname\fP [ \fBin\fP \fIword\fP; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
586 The list of words following \fBin\fP is expanded, generating a list
587 of items. The variable \fIname\fP is set to each element of this list
588 in turn, and \fIlist\fP is executed each time. If the \fBin\fP
589 \fIword\fP is omitted, the \fBfor\fP command executes \fIlist\fP
590 once for each positional parameter that is set (see
595 \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
596 The list of words following \fBin\fP is expanded, generating a list
597 of items. The set of expanded words is printed on the standard
598 error, each preceded by a number. If the \fBin\fP
599 \fIword\fP is omitted, the positional parameters are printed (see
604 prompt is then displayed and a line read from the standard input.
605 If the line consists of a number corresponding to one of
606 the displayed words, then the value of
608 is set to that word. If the line is empty, the words and prompt
609 are displayed again. If EOF is read, the command completes. Any
610 other value read causes
612 to be set to null. The line read is saved in the variable
616 is executed after each selection until a
623 is the exit status of the last command executed in
625 or zero if no commands were executed.
627 \fBcase\fP \fIword\fP \fBin\fP [ ( \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
628 ... ) \fIlist\fP ;; ] ... \fBesac\fP
629 A \fBcase\fP command first expands \fIword\fP, and tries to match
630 it against each \fIpattern\fP in turn, using the same matching rules
631 as for pathname expansion (see
632 .B Pathname Expansion
633 below). When a match is found, the
634 corresponding \fIlist\fP is executed. After the first match, no
635 subsequent matches are attempted. The exit status is zero if no
636 pattern matches. Otherwise, it is the exit status of the
637 last command executed in \fIlist\fP.
639 \fBif\fP \fIlist\fP; \fBthen\fP \fIlist;\fP \
640 [ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
641 [ \fBelse\fP \fIlist\fP; ] \fBfi\fP
645 is executed. If its exit status is zero, the
646 \fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP
647 \fIlist\fP is executed in turn, and if its exit status is zero,
648 the corresponding \fBthen\fP \fIlist\fP is executed and the
649 command completes. Otherwise, the \fBelse\fP \fIlist\fP is
650 executed, if present. The exit status is the exit status of the
651 last command executed, or zero if no condition tested true.
654 \fBwhile\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
656 \fBuntil\fP \fIlist\fP; \fBdo\fP \fIlist\fP; \fBdone\fP
658 The \fBwhile\fP command continuously executes the \fBdo\fP
659 \fIlist\fP as long as the last command in \fIlist\fP returns
660 an exit status of zero. The \fBuntil\fP command is identical
661 to the \fBwhile\fP command, except that the test is negated;
665 is executed as long as the last command in
667 returns a non-zero exit status.
668 The exit status of the \fBwhile\fP and \fBuntil\fP commands
670 of the last \fBdo\fP \fIlist\fP command executed, or zero if
673 [ \fBfunction\fP ] \fIname\fP () { \fIlist\fP; }
674 This defines a function named \fIname\fP. The \fIbody\fP of the
677 of commands between { and }. This list
678 is executed whenever \fIname\fP is specified as the
679 name of a simple command. The exit status of a function is
680 the exit status of the last command executed in the body. (See
685 In a non-interactive shell, or an interactive shell in which the
686 .B interactive_comments
689 builtin is enabled (see
691 .B "SHELL BUILTIN COMMANDS"
692 below), a word beginning with
694 causes that word and all remaining characters on that line to
695 be ignored. An interactive shell without the
696 .B interactive_comments
698 option enabled does not allow comments. The
699 .B interactive_comments
700 option is on by default in interactive shells.
702 \fIQuoting\fP is used to remove the special meaning of certain
703 characters or words to the shell. Quoting can be used to
704 disable special treatment for special characters, to prevent
705 reserved words from being recognized as such, and to prevent
708 Each of the \fImetacharacters\fP listed above under
711 has special meaning to the shell and must be quoted if they are to
712 represent themselves. There are three quoting mechanisms: the
713 .IR "escape character" ,
714 single quotes, and double quotes.
716 A non-quoted backslash (\fB\e\fP) is the
717 .IR "escape character" .
718 It preserves the literal value of the next character that follows,
719 with the exception of <newline>. If a \fB\e\fP<newline> pair
720 appears, and the backslash is not quoted, the \fB\e\fP<newline>
721 is treated as a line continuation (that is, it is effectively ignored).
723 Enclosing characters in single quotes preserves the literal value
724 of each character within the quotes. A single quote may not occur
725 between single quotes, even when preceded by a backslash.
727 Enclosing characters in double quotes preserves the literal value
728 of all characters within the quotes, with the exception of
737 retain their special meaning within double quotes. The backslash
738 retains its special meaning only when followed by one of the following
746 A double quote may be quoted within double quotes by preceding it with
749 The special parameters
753 have special meaning when in double
759 Words of the form \fB$\fP'\fIstring\fP' are treated specially. The
760 word expands to \fIstring\fP, with backslash-escaped characters replaced
761 as specifed by the ANSI C standard. Backslash escape sequences, if
762 present, are decoded as follows:
794 the character whose ASCII code is \fInnn\fP (octal)
798 The translated result is single-quoted, as if the dollar sign had
801 A double-quoted string preceded by a dollar sign (\fB$\fP) will cause
802 the string to be translated according to the current locale.
803 If the current locale is \fBC\fP or \fBPOSIX\fP, the dollar sign
805 If the string is translated and replaced, the replacement is
810 is an entity that stores values.
813 a number, or one of the special characters listed below under
814 .BR "Special Parameters" .
815 For the shell's purposes, a
817 is a parameter denoted by a
820 A parameter is set if it has been assigned a value. The null string is
821 a valid value. Once a variable is set, it may be unset only by using
826 .B SHELL BUILTIN COMMANDS
831 may be assigned to by a statement of the form
834 \fIname\fP=[\fIvalue\fP]
839 is not given, the variable is assigned the null string. All
841 undergo tilde expansion, parameter and variable expansion, string
842 expansion, command substitution, arithmetic expansion, and quote
846 below). If the variable has its
852 .BR "SHELL BUILTIN COMMANDS" )
855 is subject to arithmetic expansion even if the $((...)) syntax does
857 .B "Arithmetic Expansion"
859 Word splitting is not performed, with the exception
860 of \fB"$@"\fP as explained below under
861 .BR "Special Parameters" .
862 Pathname expansion is not performed.
863 .SS Positional Parameters
866 .I positional parameter
867 is a parameter denoted by one or more
868 digits, other than the single digit 0. Positional parameters are
869 assigned from the shell's arguments when it is invoked,
870 and may be reassigned using the
872 builtin command. Positional parameters may not be assigned to
873 with assignment statements. The positional parameters are
874 temporarily replaced when a shell function is executed (see
879 When a positional parameter consisting of more than a single
880 digit is expanded, it must be enclosed in braces (see
884 .SS Special Parameters
886 The shell treats several parameters specially. These parameters may
887 only be referenced; assignment to them is not allowed.
891 Expands to the positional parameters, starting from one. When the
892 expansion occurs within double quotes, it expands to a single word
893 with the value of each parameter separated by the first character
897 special variable. That is, ``\fB$*\fP'' is equivalent
898 to ``\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP'', where
900 is the first character of the value of the
906 is unset, the parameters are separated by spaces.
910 is null, the parameters are joined without intervening separators.
913 Expands to the positional parameters, starting from one. When the
914 expansion occurs within double quotes, each parameter expands as a
915 separate word. That is, ``
918 ``\fB$1\fP'' ``\fB$2\fP'' ...
919 When there are no positional parameters, ``\fB$@\fP'' and
921 expand to nothing (i.e., they are removed).
924 Expands to the number of positional parameters in decimal.
927 Expands to the status of the most recently executed foreground
931 Expands to the current option flags as specified upon invocation,
934 builtin command, or those set by the shell itself
940 Expands to the process ID of the shell. In a () subshell, it
941 expands to the process ID of the current shell, not the
945 Expands to the process ID of the most recently executed background
946 (asynchronous) command.
949 Expands to the name of the shell or shell script. This is set at
950 shell initialization. If
952 is invoked with a file of commands,
954 is set to the name of that file. If
960 is set to the first argument after the string to be
961 executed, if one is present. Otherwise, it is set
962 to the file name used to invoke
964 as given by argument zero.
967 At shell startup, set to the absolute file name of the shell or shell
968 script being executed as passed in the argument list.
969 Subsequently, expands to the last argument to the previous command,
971 Also set to the full file name of each command executed and placed in
972 the environment exported to that command.
973 When checking mail, this parameter holds the name of the mail file
974 currently being checked.
978 The following variables are set by the shell:
983 The process ID of the shell's parent.
986 The current working directory as set by the
991 The previous working directory as set by the
996 Set to the line of input read by the
998 builtin command when no arguments are supplied.
1001 Expands to the user ID of the current user, initialized at shell startup.
1004 Expands to the effective user ID of the current user, initialized at
1008 An array variable containing the list of groups of which the current
1012 Expands to the full file name used to invoke this instance of
1016 Expands to a string describing the version of this instance of
1020 An array variable whose members hold version information for this
1023 The values assigned to the array members are as follows:
1028 .B BASH_VERSINFO[\fR0\fP]
1029 The major version number (the \fIrelease\fP).
1031 .B BASH_VERSINFO[\fR1\fP]
1032 The minor version number (the \fIversion\fP).
1034 .B BASH_VERSINFO[\fR2\fP]
1037 .B BASH_VERSINFO[\fR3\fP]
1040 .B BASH_VERSINFO[\fR4\fP]
1041 The release status (e.g., \fIbeta1\fP).
1043 .B BASH_VERSINFO[\fR5\fP]
1044 The value of \fBMACHTYPE\fP.
1049 Incremented by one each time an instance of
1054 Each time this parameter is referenced, a random integer between
1056 generated. The sequence of random numbers may be initialized by assigning
1063 is unset, it loses its special properties, even if it is
1067 Each time this parameter is
1068 referenced, the number of seconds since shell invocation is returned. If a
1069 value is assigned to
1072 the value returned upon subsequent
1074 the number of seconds since the assignment plus the value assigned.
1078 is unset, it loses its special properties, even if it is
1082 Each time this parameter is referenced, the shell substitutes
1083 a decimal number representing the current sequential line number
1084 (starting with 1) within a script or function. When not in a
1085 script or function, the value substituted is not guaranteed to
1090 is unset, it loses its special properties, even if it is
1094 The history number, or index in the history list, of the current
1099 is unset, it loses its special properties, even if it is
1103 An array variable (see
1105 below) containing the current contents of the directory stack.
1106 Directories appear in the stack in the order they are displayed by the
1109 Assigning to members of this array variable may be used to modify
1110 directories already in the stack, but the
1114 builtins must be used to add and remove directories.
1115 Assignment to this variable will not change the current directory.
1119 is unset, it loses its special properties, even if it is
1123 An array variable (see
1125 below) containing a list of exit status values from the processes
1126 in the most-recently-executed foreground pipeline (which may
1127 contain only a single command).
1130 The value of the last option argument processed by the
1132 builtin command (see
1134 .B SHELL BUILTIN COMMANDS
1138 The index of the next argument to be processed by the
1140 builtin command (see
1142 .B SHELL BUILTIN COMMANDS
1146 Automatically set to the name of the current host.
1149 Automatically set to a string that uniquely
1150 describes the type of machine on which
1153 The default is system-dependent.
1156 Automatically set to a string that
1157 describes the operating system on which
1160 The default is system-dependent.
1163 Automatically set to a string that fully describes the system
1166 is executing, in the standard GNU \fIcpu-company-system\fP format.
1167 The default is system-dependent.
1170 A colon-separated list of enabled shell options. Each word in
1171 the list is a valid argument for the
1175 builtin command (see
1177 .B "SHELL BUILTIN COMMANDS"
1178 below). The options appearing in
1181 are those reported as
1184 If this variable is in the environment when
1186 starts up, each shell option in the list will be enabled before
1187 reading any startup files.
1188 This variable is read-only.
1191 The following variables are used by the shell. In some cases,
1193 assigns a default value to a variable; these cases are noted
1200 .I Internal Field Separator
1202 for word splitting after expansion and to
1203 split lines into words with the
1205 builtin command. The default value is
1206 ``<space><tab><newline>''.
1209 The search path for commands. It
1210 is a colon-separated list of directories in which
1211 the shell looks for commands (see
1213 .B COMMAND EXECUTION
1214 below). The default path is system-dependent,
1215 and is set by the administrator who installs
1217 A common value is ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin:.''.
1220 The home directory of the current user; the default argument for the
1221 \fBcd\fP builtin command.
1224 The search path for the
1226 command. This is a colon-separated
1227 list of directories in which the shell looks for destination directories
1230 command. A sample value is
1234 If this parameter is set when \fBbash\fP is executing a shell script,
1235 its value is interpreted as a filename containing commands to
1236 initialize the shell, as in
1241 is subjected to parameter expansion, command substitution, and arithmetic
1242 expansion before being interpreted as a file name.
1245 is not used to search for the resultant file name.
1248 If this parameter is set to a file name and the
1251 variable is not set,
1253 informs the user of the arrival of mail in the specified file.
1259 checks for mail. The default is 60 seconds. When it is time to check
1260 for mail, the shell does so before displaying the primary prompt.
1261 If this variable is unset, the shell disables mail checking.
1264 A colon-separated list of file names to be checked for mail.
1265 The message to be printed may be specified by separating the file name from
1266 the message with a `?'. $_ stands for the name of the current mailfile.
1270 \fBMAILPATH\fP='/usr/spool/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"'
1273 supplies a default value for this variable, but the location of the user
1274 mail files that it uses is system dependent (e.g., /usr/spool/mail/\fB$USER\fP).
1278 The value of this parameter is expanded (see
1281 below) and used as the primary prompt string. The default value is
1282 ``\fB\es\-\ev\e$ \fP''.
1285 The value of this parameter is expanded as with
1287 and used as the secondary prompt string. The default is
1291 The value of this parameter is used as the prompt for the
1299 The value of this parameter is expanded as with
1301 and the value is printed before each command
1303 displays during an execution trace. The first character of
1306 is replicated multiple times, as necessary, to indicate multiple
1307 levels of indirection. The default is ``\fB+ \fP''.
1310 The value of this parameter is used as a format string specifying
1311 how the timing information for pipelines prefixed with the
1313 reserved word should be displayed.
1314 The \fB%\fP character introduces an escape sequence that is
1315 expanded to a time value or other information.
1316 The escape sequences and their meanings are as follows; the
1317 braces denote optional portions.
1326 The elapsed time in seconds.
1329 The number of CPU seconds spent in user mode.
1332 The number of CPU seconds spent in system mode.
1335 The CPU percentage, computed as (%U + %S) / %R.
1339 The optional \fIp\fP is a digit specifying the \fIprecision\fP,
1340 the number of fractional digits after a decimal point.
1341 A value of 0 causes no decimal point or fraction to be output.
1342 At most three places after the decimal point may be specified;
1343 values of \fIp\fP greater than 3 are changed to 3.
1344 If \fIp\fP is not specified, the value 3 is used.
1346 The optional \fBl\fP specifies a longer format, including
1347 minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs.
1348 The value of \fIp\fP determines whether or not the fraction is
1351 If this variable is not set, \fBbash\fP acts as if it had the
1352 value \fB$'\enreal\et%3lR\enuser\et%3lU\ensys\t%3lS'\fP.
1353 If the value is null, no timing information is displayed.
1354 A trailing newline is added when the format string is displayed.
1357 The number of commands to remember in the command history (see
1360 below). The default value is 500.
1363 The name of the file in which command history is saved (see
1366 below). The default value is \fI~/.bash_history\fP. If unset, the
1367 command history is not saved when an interactive shell exits.
1370 The maximum number of lines contained in the history file. When this
1371 variable is assigned a value, the history file is truncated, if
1372 necessary, to contain no more than that number of lines. The default
1373 value is 500. The history file is also truncated to this size after
1374 writing it when an interactive shell exits.
1377 If set to the value 1,
1379 displays error messages generated by the
1381 builtin command (see
1383 .B SHELL BUILTIN COMMANDS
1387 is initialized to 1 each time the shell is invoked or a shell
1391 Used to determine the locale category for any category not specifically
1392 selected with a variable starting with \fBLC_\fP.
1395 This variable overrides the value of \fBLANG\fP and any other
1396 \fBLC_\fP variable specifying a locale category.
1399 This variable determines the collation order used when sorting the
1400 results of pathname expansion.
1403 This variable determines the locale used to translate double-quoted
1404 strings preceded by a \fB$\fP.
1407 If set, the value is executed as a command prior to issuing each primary
1412 action of an interactive shell on receipt of an
1415 character as the sole input. If set, the value is the number of
1419 characters which must be
1420 typed as the first characters on an input line before
1422 exits. If the variable exists but does not have a numeric value, or
1423 has no value, the default value is 10. If it does not exist,
1426 signifies the end of input to the shell.
1429 If set to a value greater than zero, the value is interpreted as the
1430 number of seconds to wait for input after issuing the primary prompt.
1432 terminates after waiting for that number of seconds if input does
1436 The default editor for the
1441 A colon-separated list of suffixes to ignore when performing
1442 filename completion (see
1446 A filename whose suffix matches one of the entries in
1449 is excluded from the list of matched filenames.
1450 A sample value is ``.o:~''.
1453 A colon-separated list of patterns defining the set of filenames to
1454 be ignored by pathname expansion.
1455 If a filename matched by a pathname expansion pattern also matches one
1459 it is removed from the list of matches.
1462 The filename for the
1464 startup file, overriding the default of
1472 If set to a value of
1474 lines which begin with a
1476 character are not entered on the history list. If set to
1479 lines matching the last history line are not entered.
1482 combines the two options.
1483 If unset, or if set to any other value than those above,
1485 by the parser are saved on the history list, subject to the value
1488 This variable's function is superseded by
1492 A colon-separated list of patterns used to decide which command lines
1493 should be saved on the history list. Each pattern is anchored at the
1494 beginning of the line and must fully specify the line (no implicit
1495 `\fB*\fP' is appended). Each pattern is tested against the line
1496 after the checks specified by
1499 In addition to the normal shell pattern matching characters, `\fB&\fP'
1500 matches the previous history line. `\fB&\fP' may be escaped using a
1501 backslash. The backslash is removed before attempting a match.
1504 The two or three characters which control history expansion
1505 and tokenization (see
1507 .B HISTORY EXPANSION
1508 below). The first character is the
1509 .IR "history expansion character" ,
1510 that is, the character which signals the start of a history
1511 expansion, normally `\fB!\fP'.
1512 The second character is the
1513 .IR "quick substitution"
1514 character, which is used as shorthand for re-running the previous
1515 command entered, substituting one string for another in the command.
1516 The default is `\fB^\fP'.
1517 The optional third character is the character
1518 which signifies that the remainder of the line is a comment when found
1519 as the first character of a word, normally `\fB#\fP'. The history
1520 comment character causes history substitution to be skipped for the
1521 remaining words on the line. It does not necessarily cause the shell
1522 parser to treat the rest of the line as a comment.
1525 Contains the name of a file in the same format as
1527 that should be read when the shell needs to complete a
1528 hostname. The file may be changed interactively; the next
1529 time hostname completion is attempted
1531 adds the contents of the new file to the already existing database.
1534 This variable controls how the shell interacts with the user and
1535 job control. If this variable is set, single word simple
1536 commands without redirections are treated as candidates for resumption
1537 of an existing stopped job. There is no ambiguity allowed; if there is
1538 more than one job beginning with the string typed, the job most recently
1539 accessed is selected. The
1541 of a stopped job, in this context, is the command line used to
1545 the string supplied must match the name of a stopped job exactly;
1548 the string supplied needs to match a substring of the name of a
1551 value provides functionality analogous to the
1556 below). If set to any other value, the supplied string must
1557 be a prefix of a stopped job's name; this provides functionality
1564 provides one-dimensional array variables. Any variable may be used as
1567 builtin will explicitly declare an array. There is no maximum
1568 limit on the size of an array, nor any requirement that members
1569 be indexed or assigned contiguously. Arrays are indexed using
1570 integers and are zero-based.
1572 An array is created automatically if any variable is assigned to using
1573 the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP. The
1575 is treated as an arithmetic expression that must evaluate to a number
1576 greater than or equal to zero. To explicitly declare an array, use
1577 .B declare \-a \fIname\fP
1580 .B SHELL BUILTIN COMMANDS
1582 .B declare \-a \fIname\fP[\fIsubscript\fP]
1583 is also accepted; the \fIsubscript\fP is ignored. Attributes may be
1584 specified for an array variable using the
1588 builtins. Each attribute applies to all members of an array.
1590 Arrays are assigned to using compound assignments of the form
1591 \fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each
1592 \fIvalue\fP is of the form [\fIsubscript\fP]=\fIstring\fP. Only
1593 \fIstring\fP is required. If
1594 the optional brackets and subscript are supplied, that index is assigned to;
1595 otherwise the index of the element assigned is the last index assigned
1596 to by the statement plus one. Indexing starts at zero.
1597 This syntax is also accepted by the
1599 builtin. Individual array elements may be assigned to using the
1600 \fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above.
1602 Any element of an array may be referenced using
1603 ${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid
1604 conflicts with pathname expansion. If
1605 \fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to
1606 all members of \fIname\fP. These subscripts differ only when the
1607 word appears within double quotes. If the word is double-quoted,
1608 ${\fIname\fP[*]} expands to a single
1609 word with the value of each array member separated by the first
1613 special variable, and ${\fIname\fP[@]} expands each element of
1614 \fIname\fP to a separate word. When there are no array members,
1615 ${\fIname\fP[@]} expands to nothing. This is analogous to the expansion
1616 of the special parameters \fB*\fP and \fB@\fP (see
1617 .B Special Parameters
1618 above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of
1619 ${\fIname\fP[\fIsubscript\fP]}. If \fIsubscript\fP is \fB*\fP or
1620 \fB@\fP, the expansion is the number of elements in the array.
1621 Referencing an array variable without a subscript is equivalent to
1622 referencing element zero.
1626 builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP]
1627 destroys the array element at index \fIsubscript\fP.
1628 \fBunset\fP \fIname\fP, where \fIname\fP is an array, or
1629 \fBunset\fP \fIname\fP[\fIsubscript\fP], where
1630 \fIsubscript\fP is \fB*\fP or \fB@\fP, removes the entire array.
1637 builtins each accept a
1639 option to specify an array. The
1643 option to assign a list of words read from the standard input
1648 builtins display array values in a way that allows them to be
1649 reused as assignments.
1651 Expansion is performed on the command line after it has been split into
1652 words. There are seven kinds of expansion performed:
1653 .IR "brace expansion" ,
1654 .IR "tilde expansion" ,
1655 .IR "parameter and variable expansion" ,
1656 .IR "command substitution" ,
1657 .IR "arithmetic expansion" ,
1658 .IR "word splitting" ,
1660 .IR "pathname expansion" .
1662 The order of expansions is: brace expansion, tilde expansion,
1663 parameter, variable and arithmetic expansion and
1664 command substitution
1665 (done in a left-to-right fashion), word splitting, and pathname
1668 On systems that can support it, there is an additional expansion
1669 available: \fIprocess substitution\fP.
1671 Only brace expansion, word splitting, and pathname expansion
1672 can change the number of words of the expansion; other expansions
1673 expand a single word to a single word.
1674 The only exceptions to this are the expansions of
1675 ``\fB$@\fP'' and ``\fB${\fP\fIname\fP\fB[@]}\fP''
1676 as explained above (see
1681 .I "Brace expansion"
1682 is a mechanism by which arbitrary strings
1683 may be generated. This mechanism is similar to
1684 \fIpathname expansion\fP, but the filenames generated
1685 need not exist. Patterns to be brace expanded take
1686 the form of an optional
1688 followed by a series of comma-separated strings
1689 between a pair of braces, followed by an optional
1691 The preamble is prefixed to each string contained
1692 within the braces, and the postamble is then appended
1693 to each resulting string, expanding left to right.
1695 Brace expansions may be nested. The results of each expanded
1696 string are not sorted; left to right order is preserved.
1697 For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'.
1699 Brace expansion is performed before any other expansions,
1700 and any characters special to other expansions are preserved
1701 in the result. It is strictly textual.
1703 does not apply any syntactic interpretation to the context of the
1704 expansion or the text between the braces.
1706 A correctly-formed brace expansion must contain unquoted opening
1707 and closing braces, and at least one unquoted comma.
1708 Any incorrectly formed brace expansion is left unchanged.
1709 A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its
1710 being considered part of a brace expression.
1712 This construct is typically used as shorthand when the common
1713 prefix of the strings to be generated is longer than in the
1717 mkdir /usr/local/src/bash/{old,new,dist,bugs}
1721 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
1724 Brace expansion introduces a slight incompatibility with
1725 historical versions of
1728 does not treat opening or closing braces specially when they
1729 appear as part of a word, and preserves them in the output.
1731 removes braces from words as a consequence of brace
1732 expansion. For example, a word entered to
1735 appears identically in the output. The same word is
1740 If strict compatibility with
1746 option or disable brace expansion with the
1752 .B SHELL BUILTIN COMMANDS
1756 If a word begins with a tilde character (`\fB~\fP'), all of the characters
1757 preceding the first slash (or all characters, if there is no slash)
1758 are treated as a possible \fIlogin name\fP. If this \fIlogin name\fP
1759 is the null string, the tilde is replaced with the value of the
1766 is unset, the home directory of
1767 the user executing the shell is substituted instead.
1769 If a `+' follows the tilde, the value of
1772 replaces the tilde and `+'. If
1773 a `\-' follows, the value of
1777 If the value following the tilde is a valid \fIlogin name\fP,
1778 the tilde and \fIlogin name\fP are replaced with the home directory
1779 associated with that name. If the name is invalid, or the tilde
1780 expansion fails, the word is unchanged.
1782 Each variable assignment is checked for unquoted
1783 tildes immediately following a
1787 In these cases, tilde substitution is also performed. Consequently, one
1788 may use file names with tildes in assignments to
1796 and the shell assigns the expanded value.
1797 .SS Parameter Expansion
1799 The `\fB$\fP' character introduces parameter expansion,
1800 command substitution, or arithmetic expansion. The parameter name
1801 or symbol to be expanded may be enclosed in braces, which
1802 are optional but serve to protect the variable to be expanded from
1803 characters immediately following it which could be
1804 interpreted as part of the name.
1809 The value of \fIparameter\fP is substituted. The braces are required
1812 is a positional parameter with more than one digit,
1815 is followed by a character which is not to be
1816 interpreted as part of its name.
1819 If the first character of \fIparameter\fP is an exclamation point,
1820 a level of variable indirection is introduced.
1821 \fBBash\fP uses the value of the variable formed from the rest of
1822 \fIparameter\fP as the name of the variable; this variable is then
1823 expanded and that value used in the rest of the substitution, rather
1824 than the value of \fIparameter\fP itself.
1825 This is known as \fIindirect expansion\fP.
1827 In each of the cases below, \fIword\fP is subject to tilde expansion,
1828 parameter expansion, command substitution, and arithmetic expansion.
1829 When not performing substring expansion, \fBbash\fP tests for a parameter
1830 that is unset or null; omitting the colon results in a test only for a
1831 parameter that is unset.
1835 ${\fIparameter\fP\fB:\-\fP\fIword\fP}
1836 \fBUse Default Values\fP. If
1838 is unset or null, the expansion of
1840 is substituted. Otherwise, the value of
1844 ${\fIparameter\fP\fB:=\fP\fIword\fP}
1845 \fBAssign Default Values\fP.
1848 is unset or null, the expansion of
1854 is then substituted. Positional parameters and special parameters may
1855 not be assigned to in this way.
1857 ${\fIparameter\fP\fB:?\fP\fIword\fP}
1858 \fBDisplay Error if Null or Unset\fP.
1861 is null or unset, the expansion of \fIword\fP (or a message to that effect
1864 is not present) is written to the standard error and the shell, if it
1865 is not interactive, exits. Otherwise, the value of \fIparameter\fP is
1868 ${\fIparameter\fP\fB:+\fP\fIword\fP}
1869 \fBUse Alternate Value\fP.
1872 is null or unset, nothing is substituted, otherwise the expansion of
1877 ${\fIparameter\fP\fB:\fP\fIoffset\fP}
1879 ${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP}
1881 \fBSubstring Expansion.\fP
1882 Expands to up to \fIlength\fP characters of \fIparameter\fP,
1883 starting at \fIoffset\fP.
1884 If \fIlength\fP is omitted, expands to the substring of
1885 \fIparameter\fP, starting at the character specified by \fIoffset\fP.
1886 \fIlength\fP and \fIoffset\fP are arithmetic expressions (see
1889 ARITHMETIC EVALUATION
1891 \fIlength\fP must evaluate to a number greater than or equal to zero.
1892 If \fIoffset\fP evaluates to a number less than zero, the value
1893 is used as an offset from the end of the value of \fIparameter\fP.
1894 If \fIparameter\fP is \fB@\fP, the result is \fIlength\fP positional
1895 parameters beginning at \fIoffset\fP.
1896 If \fIparameter\fP is an array name indexed by @ or *,
1897 the result is the \fIlength\fP
1898 members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}.
1899 Substring indexing is zero-based unless the positional parameters are
1900 used, in which case the indexing starts at 1.
1902 ${\fB#\fP\fIparameter\fP}
1903 The length in characters of the value of \fIparameter\fP is substituted.
1910 the length substituted is the number of positional parameters.
1913 is an array name subscripted by
1917 the length substituted is the number of elements in the array.
1920 ${\fIparameter\fP\fB#\fP\fIword\fP}
1922 ${\fIparameter\fP\fB##\fP\fIword\fP}
1926 is expanded to produce a pattern just as in pathname
1927 expansion. If the pattern matches the beginning of
1930 then the expansion is the value of
1932 with the shortest matching pattern (the ``\fB#\fP'' case) or the
1933 longest matching pattern (the ``\fB##\fP'' case) deleted.
1940 the pattern removal operation is applied to each positional
1941 parameter in turn, and the expansion is the resultant list.
1944 is an array variable subscripted with
1948 the pattern removal operation is applied to each member of the
1949 array in turn, and the expansion is the resultant list.
1952 ${\fIparameter\fP\fB%\fP\fIword\fP}
1954 ${\fIparameter\fP\fB%%\fP\fIword\fP}
1956 The \fIword\fP is expanded to produce a pattern just as in
1958 If the pattern matches a trailing portion of the value of
1960 then the expansion is the value of
1962 with the shortest matching pattern (the ``\fB%\fP'' case) or the
1963 longest matching pattern (the ``\fB%%\fP'' case) deleted.
1970 the pattern removal operation is applied to each positional
1971 parameter in turn, and the expansion is the resultant list.
1974 is an array variable subscripted with
1978 the pattern removal operation is applied to each member of the
1979 array in turn, and the expansion is the resultant list.
1982 ${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP}
1984 ${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP}
1986 The \fIpattern\fP is expanded to produce a pattern just as in
1988 \fIParameter\fP is expanded and the longest match of \fIpattern\fP
1989 against its value is replaced with \fIstring\fP.
1990 In the first form, only the first match is replaced.
1991 The second form causes all matches of \fIpattern\fP to be
1992 replaced with \fIstring\fP.
1993 If \fIpattern\fP begins with \fB#\fP, it must match at the beginning
1995 If \fIpattern\fP begins with \fB%\fP, it must match at the end
1997 If \fIstring\fP is null, matches of \fIpattern\fP are deleted
1998 and the \fB/\fP following \fIpattern\fP may be omitted.
2005 the substitution operation is applied to each positional
2006 parameter in turn, and the expansion is the resultant list.
2009 is an array variable subscripted with
2013 the substitution operation is applied to each member of the
2014 array in turn, and the expansion is the resultant list.
2015 .SS Command Substitution
2017 \fICommand substitution\fP allows the output of a command to replace
2018 the command name. There are two forms:
2022 \fB$(\fP\fIcommand\fP\|\fB)\fP
2026 \fB`\fP\fIcommand\fP\fB`\fP
2030 performs the expansion by executing \fIcommand\fP and
2031 replacing the command substitution with the standard output of the
2032 command, with any trailing newlines deleted.
2034 When the old-style backquote form of substitution is used,
2035 backslash retains its literal meaning except when followed by
2040 When using the $(\^\fIcommand\fP\|) form, all characters between the
2041 parentheses make up the command; none are treated specially.
2043 Command substitutions may be nested. To nest when using the old form,
2044 escape the inner backquotes with backslashes.
2046 If the substitution appears within double quotes, word splitting and
2047 pathname expansion are not performed on the results.
2048 .SS Arithmetic Expansion
2050 Arithmetic expansion allows the evaluation of an arithmetic expression
2051 and the substitution of the result. The format for arithmetic expansion is:
2054 \fB$((\fP\fIexpression\fP\fB))\fP
2059 is treated as if it were within double quotes, but a double quote
2060 inside the parentheses is not treated specially.
2061 All tokens in the expression undergo parameter expansion, string
2062 expansion, command substitution, and quote removal.
2063 Arithmetic substitutions may be nested.
2065 The evaluation is performed according to the rules listed below under
2067 .BR "ARITHMETIC EVALUATION" .
2072 prints a message indicating failure and no substitution occurs.
2073 .SS Process Substitution
2075 \fIProcess substitution\fP is supported on systems that support named
2076 pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files.
2077 It takes the form of
2078 \fB<(\fP\fIlist\^\fP\fB)\fP
2080 \fB>(\fP\fIlist\^\fP\fB)\fP.
2081 The process \fIlist\fP is run with its input or output connected to a
2082 \fIFIFO\fP or some file in \fB/dev/fd\fP. The name of this file is
2083 passed as an argument to the current command as the result of the
2084 expansion. If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
2085 the file will provide input for \fIlist\fP. If the
2086 \fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an
2087 argument should be read to obtain the output of \fIlist\fP.
2089 On systems that support it, \fIprocess substitution\fP is performed
2090 simultaneously with parameter and variable expansion,
2091 command substitution,
2092 and arithmetic expansion.
2095 The shell scans the results of
2096 parameter expansion,
2097 command substitution,
2099 arithmetic expansion
2100 that did not occur within double quotes for
2101 .IR "word splitting" .
2103 The shell treats each character of
2106 as a delimiter, and splits the results of the other
2107 expansions into words on these characters. If
2112 .BR <space><tab><newline> ,
2117 characters serves to delimit words. If
2120 has a value other than the default, then sequences of
2121 the whitespace characters
2125 are ignored at the beginning and end of the
2126 word, as long as the whitespace character is in the
2133 whitespace character).
2140 whitespace, along with any adjacent
2143 whitespace characters, delimits a field.
2147 whitespace characters is also treated as a delimiter.
2151 is null, no word splitting occurs.
2153 Explicit null arguments (\^\f3"\^"\fP or \^\f3'\^'\fP\^) are retained.
2154 Unquoted implicit null arguments, resulting from the expansion of
2156 that have no values, are removed.
2157 If a parameter with no value is expanded within double quotes, a
2158 null argument results and is retained.
2160 Note that if no expansion occurs, no splitting
2162 .SS Pathname Expansion
2164 After word splitting,
2167 option has been set,
2169 scans each word for the characters
2174 If one of these characters appears, then the word is
2177 and replaced with an alphabetically sorted list of
2178 file names matching the pattern.
2179 If no matching file names are found,
2180 and the shell option
2182 is disabled, the word is left unchanged.
2183 If the option is set, and no matches are found,
2184 the word is removed.
2185 When a pattern is used for pathname expansion,
2188 at the start of a name or immediately following a slash
2189 must be matched explicitly, unless the shell option
2192 The slash character must always be matched explicitly.
2195 character is not treated specially.
2196 See the description of
2200 .B SHELL BUILTIN COMMANDS
2201 for a description of the
2210 shell variable may be used to restrict the set of file names matching a
2215 is set, each matching file name that also matches one of the patterns in
2218 is removed from the list of matches.
2223 are always ignored, even when
2226 is set. However, setting
2229 has the effect of enabling the
2231 shell option, so all other file names beginning with a
2234 To get the old behavior of ignoring file names beginning with a
2238 one of the patterns in
2243 option is disabled when
2248 The special pattern characters have the following meanings:
2253 Matches any string, including the null string.
2256 Matches any single character.
2259 Matches any one of the enclosed characters. A pair of characters
2260 separated by a minus sign denotes a
2262 any character lexically between those two characters, inclusive,
2263 is matched. If the first character following the
2269 then any character not enclosed is matched.
2272 may be matched by including it as the first or last character
2276 may be matched by including it as the first character
2281 After the preceding expansions, all unquoted occurrences of the
2285 and \^\f3"\fP\^ that did not result from one of the above
2286 expansions are removed.
2288 Before a command is executed, its input and output
2291 using a special notation interpreted by the shell.
2292 Redirection may also be used to open and close files for the
2293 current shell execution environment. The following redirection
2294 operators may precede or appear anywhere within a
2298 Redirections are processed in the order they appear, from
2301 In the following descriptions, if the file descriptor number is
2302 omitted, and the first character of the redirection operator is
2304 the redirection refers to the standard input (file descriptor
2305 0). If the first character of the redirection operator is
2307 the redirection refers to the standard output (file descriptor
2310 The word that follows the redirection operator in the following
2311 descriptions is subjected to brace expansion, tilde expansion,
2312 parameter expansion, command substitution, arithmetic expansion,
2313 quote removal, and pathname expansion. If it expands to more
2318 Note that the order of redirections is significant. For example,
2322 ls \fB>\fP dirlist 2\fB>&\fP1
2325 directs both standard output and standard error to the file
2330 ls 2\fB>&\fP1 \fB>\fP dirlist
2333 directs only the standard output to file
2335 because the standard error was duplicated as standard output
2336 before the standard output was redirected to
2338 .SS Redirecting Input
2340 Redirection of input causes the file whose name results from
2343 to be opened for reading on file descriptor
2345 or the standard input (file descriptor 0) if
2349 The general format for redirecting input is:
2352 [\fIn\fP]\fB<\fP\fIword\fP
2354 .SS Redirecting Output
2356 Redirection of output causes the file whose name results from
2359 to be opened for writing on file descriptor
2361 or the standard output (file descriptor 1) if
2363 is not specified. If the file does not exist it is created;
2364 if it does exist it is truncated to zero size.
2366 The general format for redirecting output is:
2369 [\fIn\fP]\fB>\fP\fIword\fP
2372 If the redirection operator is
2378 builtin has been enabled, the redirection will fail if the filename
2379 whose name results from the expansion of \fIword\fP exists.
2380 If the redirection operator is
2382 then the value of the
2386 builtin command is not tested, and the redirection is attempted even
2387 if the file named by \fIword\fP exists.
2388 .SS Appending Redirected Output
2390 Redirection of output in this fashion
2391 causes the file whose name results from
2394 to be opened for appending on file descriptor
2396 or the standard output (file descriptor 1) if
2398 is not specified. If the file does not exist it is created.
2400 The general format for appending output is:
2403 [\fIn\fP]\fB>>\fP\fIword\fP
2406 .SS Redirecting Standard Output and Standard Error
2410 standard output (file descriptor 1) and
2411 the standard error output (file descriptor 2)
2412 to be redirected to the file whose name is the
2415 with this construct.
2417 There are two formats for redirecting standard output and
2428 Of the two forms, the first is preferred.
2429 This is semantically equivalent to
2432 \fB>\fP\fIword\fP 2\fB>&\fP1
2436 This type of redirection instructs the shell to read input from the
2437 current source until a line containing only
2439 (with no trailing blanks)
2441 the lines read up to that point are then used as the standard
2442 input for a command.
2444 The format of here-documents is as follows:
2448 \fB<<\fP[\fB\-\fP]\fIword\fP
2449 \fIhere\-document\fP
2454 No parameter expansion, command substitution, pathname
2455 expansion, or arithmetic expansion is performed on
2457 If any characters in
2461 is the result of quote removal on
2463 and the lines in the here-document are not expanded. Otherwise,
2464 all lines of the here-document are subjected to parameter expansion,
2465 command substitution, and arithmetic expansion. In the latter
2470 must be used to quote the characters
2476 If the redirection operator is
2478 then all leading tab characters are stripped from input lines and the
2482 here-documents within shell scripts to be indented in a
2484 .SS "Duplicating File Descriptors"
2486 The redirection operator
2489 [\fIn\fP]\fB<&\fP\fIword\fP
2492 is used to duplicate input file descriptors.
2495 expands to one or more digits, the file descriptor denoted by
2497 is made to be a copy of that file descriptor. If
2505 is not specified, the standard input (file descriptor 0) is used.
2510 [\fIn\fP]\fB>&\fP\fIword\fP
2513 is used similarly to duplicate output file descriptors. If
2515 is not specified, the standard output (file descriptor 1) is used.
2516 As a special case, if \fIn\fP is omitted, and \fIword\fP does not
2517 expand to one or more digits, the standard output and standard
2518 error are redirected as described previously.
2519 .SS "Opening File Descriptors for Reading and Writing"
2521 The redirection operator
2524 [\fIn\fP]\fB<>\fP\fIword\fP
2527 causes the file whose name is the expansion of
2529 to be opened for both reading and writing on file descriptor
2531 or on file descriptor 0 if
2533 is not specified. If the file does not exist, it is created.
2535 The shell maintains a list of
2537 that may be set and unset with the
2541 builtin commands (see
2543 .B SHELL BUILTIN COMMANDS
2545 The first word of each command, if unquoted,
2546 is checked to see if it has an
2547 alias. If so, that word is replaced by the text of the alias.
2548 The alias name and the replacement text may contain any valid
2549 shell input, including the
2551 listed above, with the exception that the alias name may not
2552 contain \fI=\fP. The first word of the replacement text is tested
2553 for aliases, but a word that is identical to an alias being expanded
2554 is not expanded a second time. This means that one may alias
2560 does not try to recursively expand the replacement text.
2561 If the last character of the alias value is a
2563 then the next command
2564 word following the alias is also checked for alias expansion.
2566 Aliases are created and listed with the
2568 command, and removed with the
2572 There is no mechanism for using arguments in the replacement text.
2573 If arguments are needed, a shell function should be used.
2575 Aliases are not expanded when the shell is not interactive, unless
2578 shell option is set using
2580 (see the description of
2584 \fBSHELL BUILTIN COMMANDS\fP
2587 The rules concerning the definition and use of aliases are
2590 always reads at least one complete line
2591 of input before executing any
2592 of the commands on that line. Aliases are expanded when a
2593 command is read, not when it is executed. Therefore, an
2594 alias definition appearing on the same line as another
2595 command does not take effect until the next line of input is read.
2596 The commands following the alias definition
2597 on that line are not affected by the new alias.
2598 This behavior is also an issue when functions are executed.
2599 Aliases are expanded when the function definition is read,
2600 not when the function is executed, because a function definition
2601 is itself a compound command. As a consequence, aliases
2602 defined in a function are not available until after that
2603 function is executed. To be safe, always put
2604 alias definitions on a separate line, and do not use
2606 in compound commands.
2608 Note that for almost every purpose, aliases are superseded by
2611 A shell function, defined as described above under
2613 .BR "SHELL GRAMMAR" ,
2614 stores a series of commands for later execution.
2615 Functions are executed in the context of the
2616 current shell; no new process is created to interpret
2617 them (contrast this with the execution of a shell script).
2618 When a function is executed, the arguments to the
2619 function become the positional parameters
2620 during its execution. The special parameter
2622 is updated to reflect the change. Positional parameter 0
2623 is unchanged. All other aspects of the shell execution
2624 environment are identical between a function and its caller
2625 with the exception that the
2628 trap (see the description of the
2632 .B SHELL BUILTIN COMMANDS
2633 below) is not inherited.
2635 Variables local to the function may be declared with the
2637 builtin command. Ordinarily, variables and their values
2638 are shared between the function and its caller.
2640 If the builtin command
2642 is executed in a function, the function completes and
2643 execution resumes with the next command after the function
2644 call. When a function completes, the values of the
2645 positional parameters and the special parameter
2647 are restored to the values they had prior to function
2650 Function names and definitions may be listed with the
2656 builtin commands. The
2662 will list the function names only.
2663 Functions may be exported so that subshells
2664 automatically have them defined with the
2670 Functions may be recursive. No limit is imposed on the number
2672 .SH "COMMAND EXECUTION"
2673 After a command has been split into words, if it results in a
2674 simple command and an optional list of arguments, the following
2677 If the command name contains no slashes, the shell attempts to
2678 locate it. If there exists a shell function by that name, that
2679 function is invoked as described above in
2682 If the name does not match a function, the shell searches for
2683 it in the list of shell builtins. If a match is found, that
2686 If the name is neither a shell function nor a builtin,
2687 and contains no slashes,
2689 searches each element of the
2692 for a directory containing an executable file by that name.
2694 uses a hash table to remember the full file names of executable
2699 .B "SHELL BUILTIN COMMANDS"
2701 A full search of the directories in
2704 is performed only if the command is not found in the hash table.
2705 If the search is unsuccessful, the shell prints an error
2706 message and returns a non-zero exit status.
2708 If the search is successful, or if the command name contains
2709 one or more slashes, the shell executes the named program.
2710 Argument 0 is set to the name given, and the remaining arguments
2711 to the command are set to the arguments given, if any.
2713 If this execution fails because the file is not in executable
2714 format, and the file is not a directory, it is assumed to be
2715 a \fIshell script\fP, a file
2716 containing shell commands. A subshell is spawned to execute
2717 it. This subshell reinitializes itself, so
2718 that the effect is as if a new shell had been invoked
2719 to handle the script, with the exception that the locations of
2720 commands remembered by the parent (see
2724 \fBSHELL BUILTIN COMMANDS\fP)
2725 are retained by the child.
2727 If the program is a file beginning with
2729 the remainder of the first line specifies an interpreter
2730 for the program. The shell executes the
2731 specified interpreter on operating systems that do not
2732 handle this executable format themselves. The arguments to the
2733 interpreter consist of a single optional argument following the
2734 interpreter name on the first line of the program, followed
2735 by the name of the program, followed by the command
2738 When a program is invoked it is given an array of strings
2742 \fIname\fP\-\fIvalue\fP pairs, of the form
2743 .IR "name\fR=\fPvalue" .
2745 The shell allows you to manipulate the environment in several
2746 ways. On invocation, the shell scans its own environment and
2747 creates a parameter for each name found, automatically marking
2750 to child processes. Executed commands inherit the environment.
2755 commands allow parameters and functions to be added to and
2756 deleted from the environment. If the value of a parameter
2757 in the environment is modified, the new value becomes part
2758 of the environment, replacing the old. The environment
2759 inherited by any executed command consists of the shell's
2760 initial environment, whose values may be modified in the shell,
2761 less any pairs removed by the
2763 command, plus any additions via the
2769 The environment for any
2771 or function may be augmented temporarily by prefixing it with
2772 parameter assignments, as described above in
2775 These assignment statements affect only the environment seen
2780 flag is set (see the
2782 builtin command below), then
2784 parameter assignments are placed in the environment for a command,
2785 not just those that precede the command name.
2789 invokes an external command, the variable
2791 is set to the full file name of the command and passed to that
2792 command in its environment.
2794 For the purposes of the shell, a command which exits with a
2795 zero exit status has succeeded. An exit status of zero
2796 indicates success. A non-zero exit status indicates failure.
2797 When a command terminates on a fatal signal, \fBbash\fP uses
2798 the value of 128+\fBsignal\fP as the exit status.
2800 If a command is not found, the child process created to
2801 execute it returns a status of 127. If a command is found
2802 but is not executable, the return status is 126.
2804 Shell builtin commands return a status of 0 (\fItrue\fP) if
2805 successful, and non-zero (\fIfalse\fP) if an error occurs
2807 All builtins return an exit status of 2 to indicate incorrect usage.
2809 \fBBash\fP itself returns the exit status of the last command
2810 executed, unless a syntax error occurs, in which case it exits
2811 with a non-zero value. See also the \fBexit\fP builtin
2814 When \fBbash\fP is interactive, it ignores
2817 (so that \fBkill 0\fP does not kill an interactive shell),
2821 is caught and handled (so that the \fBwait\fP builtin is interruptible).
2822 In all cases, \fBbash\fP ignores
2825 If job control is in effect,
2836 Synchronous jobs started by \fBbash\fP have signals set to the
2837 values inherited by the shell from its parent. When job control
2838 is not in effect, background jobs (jobs started with
2846 Commands run as a result of command substitution ignore the
2847 keyboard-generated job control signals
2856 The shell exits by default upon receipt of a
2859 Before exiting, it resends the
2862 to all jobs, running or stopped. To prevent the shell from
2863 sending the signal to a particular job, remove it from the
2868 .B "SHELL BUILTIN COMMANDS"
2871 to mark it to not receive
2876 refers to the ability to selectively stop (\fIsuspend\fP)
2877 the execution of processes and continue (\fIresume\fP)
2878 their execution at a later point. A user typically employs
2879 this facility via an interactive interface supplied jointly
2880 by the system's terminal driver and
2883 The shell associates a
2885 with each pipeline. It keeps a table of currently executing
2886 jobs, which may be listed with the
2890 starts a job asynchronously (in the
2892 it prints a line that looks like:
2898 indicating that this job is job number 1 and that the process ID
2899 of the last process in the pipeline associated with this job is 25647.
2900 All of the processes in a single pipeline are members of the same job.
2904 abstraction as the basis for job control.
2906 To facilitate the implementation of the user interface to job
2907 control, the system maintains the notion of a \fIcurrent terminal
2908 process group ID\fP. Members of this process group (processes whose
2909 process group ID is equal to the current terminal process group ID)
2910 receive keyboard-generated signals such as
2913 These processes are said to be in the
2916 processes are those whose process group ID differs from the terminal's;
2917 such processes are immune to keyboard-generated signals.
2918 Only foreground processes are allowed to read from or write to the
2919 terminal. Background processes which attempt to read from (write to) the
2922 .B SIGTTIN (SIGTTOU)
2923 signal by the terminal driver,
2924 which, unless caught, suspends the process.
2926 If the operating system on which
2931 allows you to use it.
2934 character (typically
2936 Control-Z) while a process is running
2937 causes that process to be stopped and returns you to
2940 .I "delayed suspend"
2941 character (typically
2943 Control-Y) causes the process to be stopped when it
2944 attempts to read input from the terminal, and control to
2947 You may then manipulate the state of this job, using the
2949 command to continue it in the background, the
2951 command to continue it in the foreground, or
2954 command to kill it. A \fB^Z\fP takes effect immediately,
2955 and has the additional side effect of causing pending output
2956 and typeahead to be discarded.
2958 There are a number of ways to refer to a job in the shell.
2961 introduces a job name. Job number
2963 may be referred to as
2965 A job may also be referred to using a prefix of the name used to
2966 start it, or using a substring that appears in its command line.
2971 job. If a prefix matches more than one job,
2973 reports an error. Using
2975 on the other hand, refers to any job containing the string
2977 in its command line. If the substring matches more than one job,
2979 reports an error. The symbols
2983 refer to the shell's notion of the
2985 which is the last job stopped while it was in
2989 may be referenced using
2991 In output pertaining to jobs (e.g., the output of the
2993 command), the current job is always flagged with a
2995 and the previous job with a
2998 Simply naming a job can be used to bring it into the
3003 bringing job 1 from the background into the foreground.
3006 resumes job 1 in the background, equivalent to
3009 The shell learns immediately whenever a job changes state.
3012 waits until it is about to print a prompt before reporting
3013 changes in a job's status so as to not interrupt
3014 any other output. If the
3021 reports such changes immediately.
3023 If an attempt to exit
3025 is made while jobs are stopped, the shell prints a warning message. The
3027 command may then be used to inspect their status.
3028 If a second attempt to exit is made without an intervening command,
3029 the shell does not print another warning, and the stopped
3030 jobs are terminated.
3032 When executing interactively,
3034 displays the primary prompt
3037 when it is ready to read a command, and the secondary prompt
3040 when it needs more input to complete a command.
3042 allows these prompt strings to be customized by inserting a number of
3043 backslash-escaped special characters that are decoded as follows:
3048 an ASCII bell character (07)
3051 the date in "Weekday Month Date" format (e.g., "Tue May 26")
3054 an ASCII escape character (033)
3057 the hostname up to the first `.'
3066 the name of the shell, the basename of
3068 (the portion following the final slash)
3071 the current time in 24-hour HH:MM:SS format
3074 the current time in 12-hour HH:MM:SS format
3077 the current time in 12-hour am/pm format
3080 the username of the current user
3083 the version of \fBbash\fP (e.g., 2.00)
3086 the release of \fBbash\fP, version + patchlevel (e.g., 2.00.0)
3089 the current working directory
3092 the basename of the current working directory
3095 the history number of this command
3098 the command number of this command
3101 if the effective UID is 0, a
3107 the character corresponding to the octal number \fInnn\fP
3113 begin a sequence of non-printing characters, which could be used to
3114 embed a terminal control sequence into the prompt
3117 end a sequence of non-printing characters
3121 The command number and the history number are usually different:
3122 the history number of a command is its position in the history
3123 list, which may include commands restored from the history file
3127 below), while the command number is the position in the sequence
3128 of commands executed during the current shell session.
3129 After the string is decoded, it is expanded via
3130 parameter expansion, command substitution, arithmetic expansion,
3131 string expansion, and quote removal, subject to the value of the
3133 shell option (see the description of the
3137 .B "SHELL BUILTIN COMMANDS"
3140 This is the library that handles reading input when using an interactive
3143 option is given at shell invocation.
3144 By default, the line editing commands are similar to those of emacs.
3145 A vi-style line editing interface is also available.
3146 To turn off line editing after the shell is running, use the
3154 .B SHELL BUILTIN COMMANDS
3156 .SS "Readline Notation"
3158 In this section, the emacs-style notation is used to denote
3159 keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
3160 means Control\-N. Similarly,
3162 keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards
3165 key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
3168 key. This makes ESC the \fImeta prefix\fP.
3169 The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
3170 or press the Escape key
3171 then hold the Control key while pressing the
3175 Readline commands may be given numeric
3177 which normally act as a repeat count.
3178 Sometimes, however, it is the sign of the argument that is significant.
3179 Passing a negative argument to a command that acts in the forward
3180 direction (e.g., \fBkill\-line\fP) causes that command to act in a
3182 Commands whose behavior with arguments deviates from this are noted
3185 When a command is described as \fIkilling\fP text, the text
3186 deleted is saved for possible future retrieval
3187 (\fIyanking\fP). The killed text is saved in a
3188 \fIkill ring\fP. Consecutive kills cause the text to be
3189 accumulated into one unit, which can be yanked all at once.
3190 Commands which do not kill text separate the chunks of text
3192 .SS "Readline Initialization"
3194 Readline is customized by putting commands in an initialization
3195 file (the \fIinputrc\fP file).
3196 The name of this file is taken from the value of the
3199 variable. If that variable is unset, the default is
3201 When a program which uses the readline library starts up, the
3202 initialization file is read, and the key bindings and variables
3204 There are only a few basic constructs allowed in the
3205 readline initialization file.
3206 Blank lines are ignored.
3207 Lines beginning with a \fB#\fP are comments.
3208 Lines beginning with a \fB$\fP indicate conditional constructs.
3209 Other lines denote key bindings and variable settings.
3211 The default key-bindings may be changed with an
3214 Other programs that use this library may add their own commands
3217 For example, placing
3220 M\-Control\-u: universal\-argument
3224 C\-Meta\-u: universal\-argument
3228 would make M\-C\-u execute the readline command
3229 .IR universal\-argument .
3231 The following symbolic character names are recognized:
3243 In addition to command names, readline allows keys to be bound
3244 to a string that is inserted when the key is pressed (a \fImacro\fP).
3245 .SS "Readline Key Bindings"
3247 The syntax for controlling key bindings in the
3249 file is simple. All that is required is the name of the
3250 command or the text of a macro and a key sequence to which
3251 it should be bound. The name may be specified in one of two ways:
3252 as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
3253 prefixes, or as a key sequence.
3254 When using the form \fBkeyname\fP:\fIfunction\-name\fP or \fImacro\fP,
3256 is the name of a key spelled out in English. For example:
3259 Control-u: universal\-argument
3261 Meta-Rubout: backward-kill-word
3263 Control-o: "> output"
3266 In the above example,
3268 is bound to the function
3269 .BR universal\-argument ,
3271 is bound to the function
3272 .BR backward\-kill\-word ,
3275 is bound to run the macro
3276 expressed on the right hand side (that is, to insert the text
3280 In the second form, \fB"keyseq"\fP:\fIfunction\-name\fP or \fImacro\fP,
3284 above in that strings denoting
3285 an entire key sequence may be specified by placing the sequence
3286 within double quotes. Some GNU Emacs style key escapes can be
3287 used, as in the following example.
3290 "\eC\-u": universal\-argument
3292 "\eC\-x\eC\-r": re\-read\-init\-file
3294 "\ee[11~": "Function Key 1"
3299 is again bound to the function
3300 .BR universal\-argument .
3302 is bound to the function
3303 .BR re\-read\-init\-file ,
3306 is bound to insert the text
3307 .BR "Function Key 1" .
3308 The full set of escape sequences is
3330 When entering the text of a macro, single or double quotes should
3331 be used to indicate a macro definition. Unquoted text
3332 is assumed to be a function name. Backslash
3333 will quote any character in the macro text, including " and '.
3336 allows the current readline key bindings to be displayed or modified
3339 builtin command. The editing mode may be switched during interactive
3344 builtin command (see
3346 .B SHELL BUILTIN COMMANDS
3348 .SS "Readline Variables"
3350 Readline has variables that can be used to further customize its
3351 behavior. A variable may be set in the
3353 file with a statement of the form
3356 \fBset\fP \fIvariable\-name\fP \fIvalue\fP
3359 Except where noted, readline variables can take the values
3363 The variables and their default values are:
3367 .B bell\-style (audible)
3368 Controls what happens when readline wants to ring the terminal bell.
3369 If set to \fBnone\fP, readline never rings the bell. If set to
3370 \fBvisible\fP, readline uses a visible bell if one is available.
3371 If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
3373 .B comment\-begin (``#'')
3374 The string that is inserted when the
3377 command is executed.
3378 This command is bound to
3380 in emacs mode and to
3384 .B completion\-query\-items (100)
3385 This determines when the user is queried about viewing
3386 the number of possible completions
3387 generated by the \fBpossible\-completions\fP command.
3388 It may be set to any integer value greater than or equal to
3389 zero. If the number of possible completions is greater than
3390 or equal to the value of this variable, the user is asked whether
3391 or not he wishes to view them; otherwise they are simply listed
3394 .B convert\-meta (On)
3395 If set to \fBOn\fP, readline will convert characters with the
3396 eighth bit set to an ASCII key sequence
3397 by stripping the eighth bit and prepending an
3398 escape character (in effect, using escape as the \fImeta prefix\fP).
3400 .B disable\-completion (Off)
3401 If set to \fBOn\fP, readline will inhibit word completion. Completion
3402 characters will be inserted into the line as if they had been
3403 mapped to \fBself-insert\fP.
3405 .B editing\-mode (emacs)
3406 Controls whether readline begins with a set of key bindings similar
3407 to \fIemacs\fP or \fIvi\fP.
3409 can be set to either
3414 .B enable\-keypad (Off)
3415 When set to \fBOn\fP, readline will try to enable the application
3416 keypad when it is called. Some systems need this to enable the
3419 .B expand\-tilde (Off)
3420 If set to \fBon\fP, tilde expansion is performed when readline
3421 attempts word completion.
3423 .B horizontal\-scroll\-mode (Off)
3424 When set to \fBOn\fP, makes readline use a single line for display,
3425 scrolling the input horizontally on a single screen line when it
3426 becomes longer than the screen width rather than wrapping to a new line.
3428 .B input\-meta (Off)
3429 If set to \fBOn\fP, readline will enable eight-bit input (that is,
3430 it will not strip the high bit from the characters it reads),
3431 regardless of what the terminal claims it can support. The name
3433 is a synonym for this variable.
3436 Set the current readline keymap. The set of legal keymap names is
3437 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
3440 \fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is
3441 equivalent to \fIemacs\-standard\fP. The default value is
3445 also affects the default keymap.
3447 .B mark\-directories (On)
3448 If set to \fBOn\fP, completed directory names have a slash
3451 .B mark\-modified\-lines (Off)
3452 If set to \fBOn\fP, history lines that have been modified are displayed
3453 with a preceding asterisk (\fB*\fP).
3455 .B output\-meta (Off)
3456 If set to \fBOn\fP, readline will display characters with the
3457 eighth bit set directly rather than as a meta-prefixed escape
3460 .B show\-all\-if\-ambiguous (Off)
3461 This alters the default behavior of the completion functions. If
3464 words which have more than one possible completion cause the
3465 matches to be listed immediately instead of ringing the bell.
3467 .B visible\-stats (Off)
3468 If set to \fBOn\fP, a character denoting a file's type as reported
3469 by \fIstat\fP(2) is appended to the filename when listing possible
3472 .SS "Readline Conditional Constructs"
3474 Readline implements a facility similar in spirit to the conditional
3475 compilation features of the C preprocessor which allows key
3476 bindings and variable settings to be performed as the result
3477 of tests. There are three parser directives used.
3481 construct allows bindings to be made based on the
3482 editing mode, the terminal being used, or the application using
3483 readline. The text of the test extends to the end of the line;
3484 no characters are required to isolate it.
3487 The \fBmode=\fP form of the \fB$if\fP directive is used to test
3488 whether readline is in emacs or vi mode.
3489 This may be used in conjunction
3490 with the \fBset keymap\fP command, for instance, to set bindings in
3491 the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if
3492 readline is starting out in emacs mode.
3494 The \fBterm=\fP form may be used to include terminal-specific
3495 key bindings, perhaps to bind the key sequences output by the
3496 terminal's function keys. The word on the right side of the
3498 is tested against the full name of the terminal and the portion
3499 of the terminal name before the first \fB\-\fP. This allows
3506 .IP \fBapplication\fP
3507 The \fBapplication\fP construct is used to include
3508 application-specific settings. Each program using the readline
3509 library sets the \fIapplication name\fP, and an initialization
3510 file can test for a particular value.
3511 This could be used to bind key sequences to functions useful for
3512 a specific program. For instance, the following command adds a
3513 key sequence that quotes the current or previous word in Bash:
3517 # Quote the current or previous word
3518 "\eC\-xq": "\eeb\e"\eef\e""
3524 This command, as you saw in the previous example, terminates an
3527 Commands in this branch of the \fB$if\fP directive are executed if
3531 Readline provides commands for searching through the command history
3535 below) for lines containing a specified string.
3536 There are two search modes:
3539 .IR non-incremental .
3541 Incremental searches begin before the user has finished typing the
3543 As each character of the search string is typed, readline displays
3544 the next entry from the history matching the string typed so far.
3545 An incremental search requires only as many characters as needed to
3546 find the desired history entry.
3547 The Escape character is used to terminate an incremental search.
3548 Control-J will also terminate the search.
3549 Control-G will abort an incremental search and restore the original
3551 When the search is terminated, the history entry containing the
3552 search string becomes the current line.
3553 To find other matching entries in the history list, type Control-S or
3554 Control-R as appropriate.
3555 This will search backward or forward in the history for the next
3556 entry matching the search string typed so far.
3557 Any other key sequence bound to a readline command will terminate
3558 the search and execute that command.
3559 For instance, a \fInewline\fP will terminate the search and accept
3560 the line, thereby executing the command from the history list.
3562 Non-incremental searches read the entire search string before starting
3563 to search for matching history lines. The search string may be
3564 typed by the user or part of the contents of the current line.
3565 .SS "Readline Command Names"
3567 The following is a list of the names of the commands and the default
3568 key sequences to which they are bound.
3569 Command names without an accompanying key sequence are unbound by default.
3570 .SS Commands for Moving
3574 .B beginning\-of\-line (C\-a)
3575 Move to the start of the current line.
3577 .B end\-of\-line (C\-e)
3578 Move to the end of the line.
3580 .B forward\-char (C\-f)
3581 Move forward a character.
3583 .B backward\-char (C\-b)
3584 Move back a character.
3586 .B forward\-word (M\-f)
3587 Move forward to the end of the next word. Words are composed of
3588 alphanumeric characters (letters and digits).
3590 .B backward\-word (M\-b)
3591 Move back to the start of this, or the previous, word. Words are
3592 composed of alphanumeric characters (letters and digits).
3594 .B clear\-screen (C\-l)
3595 Clear the screen leaving the current line at the top of the screen.
3596 With an argument, refresh the current line without clearing the
3599 .B redraw\-current\-line
3600 Refresh the current line.
3602 .SS Commands for Manipulating the History
3606 .B accept\-line (Newline, Return)
3607 Accept the line regardless of where the cursor is. If this line is
3608 non-empty, add it to the history list according to the state of the
3611 variable. If the line is a modified history
3612 line, then restore the history line to its original state.
3614 .B previous\-history (C\-p)
3615 Fetch the previous command from the history list, moving back in
3618 .B next\-history (C\-n)
3619 Fetch the next command from the history list, moving forward in the
3622 .B beginning\-of\-history (M\-<)
3623 Move to the first line in the history.
3625 .B end\-of\-history (M\->)
3626 Move to the end of the input history, i.e., the line currently being
3629 .B reverse\-search\-history (C\-r)
3630 Search backward starting at the current line and moving `up' through
3631 the history as necessary. This is an incremental search.
3633 .B forward\-search\-history (C\-s)
3634 Search forward starting at the current line and moving `down' through
3635 the history as necessary. This is an incremental search.
3637 .B non\-incremental\-reverse\-search\-history (M\-p)
3638 Search backward through the history starting at the current line
3639 using a non-incremental search for a string supplied by the user.
3641 .B non\-incremental\-forward\-search\-history (M\-n)
3642 Search forward through the history using a non-incremental search for
3643 a string supplied by the user.
3645 .B history\-search\-forward
3646 Search forward through the history for the string of characters
3647 between the start of the current line and the current cursor
3648 position (the \fIpoint\fP).
3649 This is a non-incremental search.
3651 .B history\-search\-backward
3652 Search backward through the history for the string of characters
3653 between the start of the current line and the point.
3654 This is a non-incremental search.
3656 .B yank\-nth\-arg (M\-C\-y)
3657 Insert the first argument to the previous command (usually
3658 the second word on the previous line) at point (the current
3659 cursor position). With an argument
3661 insert the \fIn\fPth word from the previous command (the words
3662 in the previous command begin with word 0). A negative argument
3663 inserts the \fIn\fPth word from the end of the previous command.
3666 yank\-last\-arg (M\-.\^, M\-_\^)
3667 Insert the last argument to the previous command (the last word of
3668 the previous history entry). With an argument,
3669 behave exactly like \fByank\-nth\-arg\fP.
3671 .B shell\-expand\-line (M\-C\-e)
3672 Expand the line the way the shell does when it reads it. This
3673 performs alias and history expansion as well as all of the shell
3674 word expansions. See
3676 .B HISTORY EXPANSION
3677 below for a description of history expansion.
3679 .B history\-expand\-line (M\-^)
3680 Perform history expansion on the current line.
3683 .B HISTORY EXPANSION
3684 below for a description of history expansion.
3686 .B alias\-expand\-line
3687 Perform alias expansion on the current line.
3691 above for a description of alias expansion.
3693 .B history\-and\-alias\-expand\-line
3694 Perform history and alias expansion on the current line.
3696 .B insert\-last\-argument (M\-.\^, M\-_\^)
3697 A synonym for \fByank\-last\-arg\fP.
3699 .B operate\-and\-get\-next (C\-o)
3700 Accept the current line for execution and fetch the next line
3701 relative to the current line from the history for editing. Any
3702 argument is ignored.
3704 .SS Commands for Changing Text
3708 .B delete\-char (C\-d)
3709 Delete the character under the cursor. If point is at the
3710 beginning of the line, there are no characters in the line, and
3711 the last character typed was not
3717 .B backward\-delete\-char (Rubout)
3718 Delete the character behind the cursor. When given a numeric argument,
3719 save the deleted text on the kill ring.
3721 .B quoted\-insert (C\-q, C\-v)
3722 Add the next character that you type to the line verbatim. This is
3723 how to insert characters like \fBC\-q\fP, for example.
3725 .B tab\-insert (C\-v TAB)
3726 Insert a tab character.
3728 .B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
3729 Insert the character typed.
3731 .B transpose\-chars (C\-t)
3732 Drag the character before point forward over the character at point.
3733 Point moves forward as well. If point is at the end of the line, then
3734 transpose the two characters before point. Negative arguments don't work.
3736 .B transpose\-words (M\-t)
3737 Drag the word behind the cursor past the word in front of the cursor
3738 moving the cursor over that word as well.
3740 .B upcase\-word (M\-u)
3741 Uppercase the current (or following) word. With a negative argument,
3742 do the previous word, but do not move point.
3744 .B downcase\-word (M\-l)
3745 Lowercase the current (or following) word. With a negative argument,
3746 do the previous word, but do not move point.
3748 .B capitalize\-word (M\-c)
3749 Capitalize the current (or following) word. With a negative argument,
3750 do the previous word, but do not move point.
3752 .SS Killing and Yanking
3756 .B kill\-line (C\-k)
3757 Kill the text from the current cursor position to the end of the line.
3759 .B backward\-kill\-line (C\-x Rubout)
3760 Kill backward to the beginning of the line.
3762 .B unix\-line\-discard (C\-u)
3763 Kill backward from point to the beginning of the line.
3764 .\" There is no real difference between this and backward-kill-line
3766 .B kill\-whole\-line
3767 Kill all characters on the current line, no matter where the
3770 .B kill\-word (M\-d)
3771 Kill from the cursor to the end of the current word, or if between
3772 words, to the end of the next word. Word boundaries are the same as
3773 those used by \fBforward\-word\fP.
3775 .B backward\-kill\-word (M\-Rubout)
3776 Kill the word behind the cursor. Word boundaries are the same as
3777 those used by \fBbackward\-word\fP.
3779 .B unix\-word\-rubout (C\-w)
3780 Kill the word behind the cursor, using white space as a word boundary.
3781 The word boundaries are different from \fBbackward\-kill\-word\fP.
3783 .B delete\-horizontal\-space (M\-\e)
3784 Delete all spaces and tabs around point.
3787 Kill the text between the point and \fImark\fP (saved cursor position).
3788 This text is referred to as the \fIregion\fP.
3790 .B copy\-region\-as\-kill
3791 Copy the text in the region to the kill buffer.
3793 .B copy\-backward\-word
3794 Copy the word before point to the kill buffer.
3796 .B copy\-forward\-word
3797 Copy the word following point to the kill buffer.
3800 Yank the top of the kill ring into the buffer at the cursor.
3803 Rotate the kill ring, and yank the new top. Only works following
3808 .SS Numeric Arguments
3812 .B digit\-argument (M\-0, M\-1, ..., M\-\-)
3813 Add this digit to the argument already accumulating, or start a new
3814 argument. M\-\- starts a negative argument.
3816 .B universal\-argument
3817 This is another way to specify an argument.
3818 If this command is followed by one or more digits, optionally with a
3819 leading minus sign, those digits define the argument.
3820 If the command is followed by digits, executing
3821 .B universal\-argument
3822 again ends the numeric argument, but is otherwise ignored.
3823 As a special case, if this command is immediately followed by a
3824 character that is neither a digit or minus sign, the argument count
3825 for the next command is multiplied by four.
3826 The argument count is initially one, so executing this function the
3827 first time makes the argument count four, a second time makes the
3828 argument count sixteen, and so on.
3835 Attempt to perform completion on the text before point.
3837 attempts completion treating the text as a variable (if the
3838 text begins with \fB$\fP), username (if the text begins with
3839 \fB~\fP), hostname (if the text begins with \fB@\fP), or
3840 command (including aliases and functions) in turn. If none
3841 of these produces a match, filename completion is attempted.
3843 .B possible\-completions (M\-?)
3844 List the possible completions of the text before point.
3846 .B insert\-completions (M\-*)
3847 Insert all completions of the text before point
3848 that would have been generated by
3849 \fBpossible\-completions\fP.
3851 .B complete\-filename (M\-/)
3852 Attempt filename completion on the text before point.
3854 .B possible\-filename\-completions (C\-x /)
3855 List the possible completions of the text before point,
3856 treating it as a filename.
3858 .B complete\-username (M\-~)
3859 Attempt completion on the text before point, treating
3862 .B possible\-username\-completions (C\-x ~)
3863 List the possible completions of the text before point,
3864 treating it as a username.
3866 .B complete\-variable (M\-$)
3867 Attempt completion on the text before point, treating
3868 it as a shell variable.
3870 .B possible\-variable\-completions (C\-x $)
3871 List the possible completions of the text before point,
3872 treating it as a shell variable.
3874 .B complete\-hostname (M\-@)
3875 Attempt completion on the text before point, treating
3878 .B possible\-hostname\-completions (C\-x @)
3879 List the possible completions of the text before point,
3880 treating it as a hostname.
3882 .B complete\-command (M\-!)
3883 Attempt completion on the text before point, treating
3884 it as a command name. Command completion attempts to
3885 match the text against aliases, reserved words, shell
3886 functions, builtins, and finally executable filenames,
3889 .B possible\-command\-completions (C\-x !)
3890 List the possible completions of the text before point,
3891 treating it as a command name.
3893 .B dynamic\-complete\-history (M\-TAB)
3894 Attempt completion on the text before point, comparing
3895 the text against lines from the history list for possible
3898 .B complete\-into\-braces (M\-{)
3899 Perform filename completion and return the list of possible completions
3900 enclosed within braces so the list is available to the shell (see
3908 .B start\-kbd\-macro (C\-x (\^)
3909 Begin saving the characters typed into the current keyboard macro.
3911 .B end\-kbd\-macro (C\-x )\^)
3912 Stop saving the characters typed into the current keyboard macro
3913 and store the definition.
3915 .B call\-last\-kbd\-macro (C\-x e)
3916 Re-execute the last keyboard macro defined, by making the characters
3917 in the macro appear as if typed at the keyboard.
3923 .B re\-read\-init\-file (C\-x C\-r)
3924 Read in the contents of the \fIinputrc\fP file, and incorporate
3925 any bindings or variable assignments found there.
3928 Abort the current editing command and
3929 ring the terminal's bell (subject to the setting of
3932 .B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...)
3933 If the metafied character \fIx\fP is lowercase, run the command
3934 that is bound to the corresponding uppercase character.
3936 .B prefix\-meta (ESC)
3937 Metafy the next character typed.
3944 .B undo (C\-_, C\-x C\-u)
3945 Incremental undo, separately remembered for each line.
3947 .B revert\-line (M\-r)
3948 Undo all changes made to this line. This is like typing the
3950 command enough times to return the line to its initial state.
3952 .B tilde\-expand (M\-~)
3953 Perform tilde expansion on the current word.
3955 .B set\-mark (C\-@, M\-<space>)
3956 Set the mark to the current point. If a
3957 numeric argument is supplied, the mark is set to that position.
3959 .B exchange\-point\-and\-mark (C\-x C\-x)
3960 Swap the point with the mark. The current cursor position is set to
3961 the saved position, and the old cursor position is saved as the mark.
3963 .B character\-search (C\-])
3964 A character is read and point is moved to the next occurrence of that
3965 character. A negative count searches for previous occurrences.
3967 .B character\-search\-backward (M\-C\-])
3968 A character is read and point is moved to the previous occurrence of that
3969 character. A negative count searches for subsequent occurrences.
3971 .B insert\-comment (M\-#)
3975 variable is inserted at the beginning of the current line, and the line
3976 is accepted as if a newline had been typed. This makes the current line
3979 .B glob\-expand\-word (C\-x *)
3980 The word before point is treated as a pattern for pathname expansion,
3981 and the list of matching file names is inserted, replacing the word.
3983 .B glob\-list\-expansions (C\-x g)
3984 The list of expansions that would have been generated by
3985 .B glob\-expand\-word
3986 is displayed, and the line is redrawn.
3989 Print all of the functions and their key bindings to the
3990 readline output stream. If a numeric argument is supplied,
3991 the output is formatted in such a way that it can be made part
3992 of an \fIinputrc\fP file.
3995 Print all of the settable readline variables and their values to the
3996 readline output stream. If a numeric argument is supplied,
3997 the output is formatted in such a way that it can be made part
3998 of an \fIinputrc\fP file.
4001 Print all of the readline key sequences bound to macros and the
4002 strings they ouput. If a numeric argument is supplied,
4003 the output is formatted in such a way that it can be made part
4004 of an \fIinputrc\fP file.
4006 .B display\-shell\-version (C\-x C\-v)
4007 Display version information about the current instance of
4015 builtin is enabled, the shell provides access to the
4016 \fIcommand history\fP,
4017 the list of commands previously typed. The text of the last
4020 commands (default 500) is saved in a history list. The shell
4021 stores each command in the history list prior to parameter and
4022 variable expansion (see
4025 above) but after history expansion is performed, subject to the
4026 values of the shell variables
4032 On startup, the history is initialized from the file named by
4036 (default \fI~/.bash_history\fP).
4039 is truncated, if necessary, to contain no more than
4043 When an interactive shell exits, the last
4046 lines are copied from the history list to
4051 shell option is enabled
4052 (see the description of
4056 .B "SHELL BUILTIN COMMANDS"
4057 below), the lines are appended to the history file,
4058 otherwise the history file is overwritten.
4062 is unset, or if the history file is unwritable, the history is
4063 not saved. After saving the history, the history file is truncated
4064 to contain no more than
4070 is not set, no truncation is performed.
4076 .B SHELL BUILTIN COMMANDS
4077 below) may be used to list or edit and re-execute a portion of
4081 builtin can be used to display or modify the history list and
4082 manipulate the history file.
4083 When using the command-line editing, search commands
4084 are available in each editing mode that provide access to the
4087 The shell allows control over which commands are saved on the history
4094 variables may be set to cause the shell to save only a subset of the
4098 shell option, if enabled, causes the shell to attempt to save each
4099 line of a multi-line command in the same history entry, adding
4100 semicolons where necessary to preserve syntactic correctness.
4103 shell option causes the shell to save the command with embedded newlines
4104 instead of semicolons. See the description of the
4108 .B "SHELL BUILTIN COMMANDS"
4109 for information on setting and unsetting shell options.
4110 .SH "HISTORY EXPANSION"
4112 The shell supports a history expansion feature that
4113 is similar to the history expansion in
4115 This section describes what syntax features are available. This
4116 feature is enabled by default for interactive shells, and can be
4121 builtin command (see
4123 .B SHELL BUILTIN COMMANDS
4124 below). Non-interactive shells do not perform history expansion
4127 History expansions introduce words from the history list into
4128 the input stream, making it easy to repeat commands, insert the
4129 arguments to a previous command into the current input line, or
4130 fix errors in previous commands quickly.
4132 History expansion is performed immediately after a complete line
4133 is read, before the shell breaks it into words.
4134 It takes place in two parts.
4135 The first is to determine which line from the previous history
4136 to use during substitution.
4137 The second is to select portions of that line for inclusion into
4139 The line selected from the previous history is the \fIevent\fP,
4140 and the portions of that line that are acted upon are \fIwords\fP.
4141 Various \fImodifiers\fP are available to manipulate the selected words.
4142 The line is broken into words in the same fashion as when reading input,
4143 so that several \fImetacharacter\fP-separated words surrounded by
4144 quotes are considered as one word.
4145 History expansions are introduced by the appearance of the
4146 history expansion character, which is \^\fB!\fP\^ by default.
4147 Only backslash (\^\fB\e\fP\^) and single quotes can quote
4148 the history expansion character.
4150 Several shell options settable with the
4152 builtin may be used to tailor the behavior of history expansion.
4155 shell option is enabled (see the description of the
4159 is being used, history substitutions are not immediately passed to
4161 Instead, the expanded line is reloaded into the
4163 editing buffer for further modification.
4166 is being used, and the
4168 shell option is enabled, a failed history substitution will be reloaded
4171 editing buffer for correction.
4176 builtin command may be used to see what a history expansion will
4182 builtin may be used to add commands to the end of the history list
4183 without actually executing them, so that they are available for
4186 The shell allows control of the various characters used by the
4187 history expansion mechanism (see the description of
4190 .BR "Shell Variables" ).
4191 .SS Event Designators
4193 An event designator is a reference to a command line entry in the
4199 Start a history substitution, except when followed by a
4204 Refer to command line
4208 Refer to the current command line minus
4212 Refer to the previous command. This is a synonym for `!\-1'.
4215 Refer to the most recent command starting with
4218 .B !?\fIstring\fR\fB[?]\fR
4219 Refer to the most recent command containing
4221 The trailing \fB?\fP may be omitted if
4223 is followed immediately by a newline.
4225 .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
4226 Quick substitution. Repeat the last command, replacing
4231 ``!!:s/\fIstring1\fP/\fIstring2\fP/''
4232 (see \fBModifiers\fP below).
4235 The entire command line typed so far.
4237 .SS Word Designators
4239 Word designators are used to select desired words from the event.
4242 separates the event specification from the word designator.
4243 It can be omitted if the word designator begins with a
4250 Words are numbered from the beginning of the line,
4251 with the first word being denoted by 0 (zero).
4252 Words are inserted into the current line separated by single spaces.
4257 The zeroth word. For the shell, this is the command
4264 The first argument. That is, word 1.
4270 The word matched by the most recent `?\fIstring\fR?' search.
4273 A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
4276 All of the words but the zeroth. This is a synonym
4277 for `\fI1\-$\fP'. It is not an error to use
4279 if there is just one
4280 word in the event; the empty string is returned in that case.
4283 Abbreviates \fIx\-$\fP.
4286 Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
4289 If a word designator is supplied without an event specification, the
4290 previous command is used as the event.
4293 After the optional word designator, there may appear a sequence of
4294 one or more of the following modifiers, each preceded by a `:'.
4300 Remove a trailing file name component, leaving only the head.
4303 Remove all leading file name components, leaving the tail.
4306 Remove a trailing suffix of the form \fI.xxx\fP, leaving the
4310 Remove all but the trailing suffix.
4313 Print the new command but do not execute it.
4316 Quote the substituted words, escaping further substitutions.
4319 Quote the substituted words as with
4321 but break into words at
4325 .B s/\fIold\fP/\fInew\fP/
4328 for the first occurrence of
4330 in the event line. Any delimiter can be used in place of /. The
4331 final delimiter is optional if it is the last character of the
4332 event line. The delimiter may be quoted in
4336 with a single backslash. If & appears in
4340 A single backslash will quote the &. If
4342 is null, it is set to the last
4344 substituted, or, if no previous history substitutions took place,
4348 .B !?\fIstring\fR\fB[?]\fR
4352 Repeat the previous substitution.
4355 Cause changes to be applied over the entire event line. This is
4356 used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
4357 or `\fB:&\fP'. If used with
4358 `\fB:s\fP', any delimiter can be used
4359 in place of /, and the final delimiter is optional
4360 if it is the last character of the event line.
4362 .SH "ARITHMETIC EVALUATION"
4363 The shell allows arithmetic expressions to be evaluated, under
4364 certain circumstances (see the \fBlet\fP builtin command and
4365 \fBArithmetic Expansion\fP).
4367 is done in long integers with no check for overflow, though division
4368 by 0 is trapped and flagged as an error. The following list of
4369 operators is grouped into levels of equal-precedence operators.
4370 The levels are listed in order of decreasing precedence.
4375 unary minus and plus
4378 logical and bitwise negation
4381 multiplication, division, remainder
4384 addition, subtraction
4387 left and right bitwise shifts
4393 equality and inequality
4399 bitwise exclusive OR
4410 .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
4411 conditional evaluation
4413 .B = *= /= %= += \-= <<= >>= &= ^= |=
4417 Shell variables are allowed as operands; parameter expansion is
4418 performed before the expression is evaluated.
4419 The value of a parameter is coerced to a long integer within
4420 an expression. A shell variable need not have its integer attribute
4421 turned on to be used in an expression.
4423 Constants with a leading 0 are interpreted as octal numbers.
4424 A leading 0x or 0X denotes hexadecimal.
4425 Otherwise, numbers take the form [\fIbase#\fP]n, where \fIbase\fP
4426 is a decimal number between 2 and 64 representing the arithmetic
4427 base, and \fIn\fP is a number in that base.
4428 If \fIbase\fP is omitted, then base 10 is used.
4429 The digits greater than 9 are represented by the lowercase letters,
4430 the uppercase letters, _, and @, in that order.
4431 If \fIbase\fP is less than or equal to 36, lowercase and uppercase
4432 letters may be used interchangably to represent numbers between 10
4435 Operators are evaluated in order of precedence. Sub-expressions in
4436 parentheses are evaluated first and may override the precedence
4438 .SH "SHELL BUILTIN COMMANDS"
4439 .\" start of bash_builtins
4442 Unless otherwise noted, each builtin command documented in this
4443 section as accepting options preceded by
4447 to signify the end of the options.
4451 \fB:\fP [\fIarguments\fP]
4453 No effect; the command does nothing beyond expanding
4455 and performing any specified
4456 redirections. A zero exit code is returned.
4459 \fB .\| \fP \fIfilename\fP [\fIarguments\fP]
4461 \fBsource\fP \fIfilename\fP [\fIarguments\fP]
4463 Read and execute commands from
4466 shell environment and return the exit status of the last command
4471 does not contain a slash, file names in
4474 are used to find the directory containing
4476 The file searched for in
4479 need not be executable. The current directory is
4480 searched if no file is found in
4487 builtin command is turned off, the
4491 If any \fIarguments\fP are supplied, they become the positional
4492 parameters when \fIfilename\fP is executed. Otherwise the positional
4493 parameters are unchanged.
4494 The return status is the status of the last command exited within
4495 the script (0 if no commands are executed), and false if
4499 \fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...]
4500 \fBAlias\fP with no arguments or with the
4502 option prints the list of aliases in the form
4503 \fBalias\fP \fIname\fP=\fIvalue\fP on standard output.
4504 When arguments are supplied, an alias is defined for
4505 each \fIname\fP whose \fIvalue\fP is given.
4506 A trailing space in \fIvalue\fP causes the next word to be
4507 checked for alias substitution when the alias is expanded.
4508 For each \fIname\fP in the argument list for which no \fIvalue\fP
4509 is supplied, the name and value of the alias is printed.
4510 \fBAlias\fP returns true unless a \fIname\fP is given for which
4511 no alias has been defined.
4513 \fBbg\fP [\fIjobspec\fP]
4514 Place \fIjobspec\fP in the background, as if it had been started with
4516 If \fIjobspec\fP is not present, the shell's notion of the
4517 \fIcurrent job\fP is used.
4520 returns 0 unless run when job control is disabled or, when run with
4521 job control enabled, if \fIjobspec\fP was not found or started without
4525 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSV\fP] [\fB\-q\fP \fIname\fP] [\fB\-r\fP \fIkeyseq\fP]
4527 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP
4529 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP
4533 key and function bindings, or bind a key sequence to a
4535 function or macro. The binding syntax accepted is identical to that of
4537 but each binding must be passed as a separate argument;
4538 e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'. Options, if supplied, have the
4546 as the keymap to be affected by the subsequent bindings.
4550 \fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi,
4553 \fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is
4554 equivalent to \fIemacs\-standard\fP.
4557 List the names of all \fBreadline\fP functions.
4560 Display \fBreadline\fP function names and bindings in such a way
4561 that they can be re-read.
4564 List current \fBreadline\fP function names and bindings.
4567 Display \fBreadline\fP variable names and values in such a way that they
4571 List current \fBreadline\fP variable names and values.
4574 Display \fBreadline\fP key sequences bound to macros and the strings
4575 they output in such a way that they can be re-read.
4578 Display \fBreadline\fP key sequences bound to macros and the strings
4581 .B \-f \fIfilename\fP
4582 Read key bindings from \fIfilename\fP.
4584 .B \-q \fIfunction\fP
4585 Query about which keys invoke the named \fIfunction\fP.
4588 Remove any current binding for \fIkeyseq\fP.
4591 The return value is 0 unless an unrecognized option is given or an
4595 \fBbreak\fP [\fIn\fP]
4602 loop. If \fIn\fP is specified, break \fIn\fP levels.
4606 is greater than the number of enclosing loops, all enclosing loops
4607 are exited. The return value is 0 unless the shell is not executing
4612 \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
4613 Execute the specified shell builtin, passing it
4615 and return its exit status.
4616 This is useful when you wish to define a
4617 function whose name is the same as a shell builtin,
4618 but need the functionality of the
4619 builtin within the function itself. The \fBcd\fP builtin is
4620 commonly redefined this way. The return status is false if
4622 is not a shell builtin command.
4624 \fBcd\fP [\fB\-LP\fP] [\fIdir\fP]
4625 Change the current directory to \fIdir\fP. The variable
4634 defines the search path for the directory containing
4636 Alternative directory names in
4639 are separated by a colon (:). A null directory name in
4642 is the same as the current directory, i.e., ``\fB.\fP''. If
4644 begins with a slash (/),
4650 option says to use the physical directory structure instead of
4651 following symbolic links (see also the
4655 builtin command); the
4657 option forces symbolic links to be followed. An argument of
4662 The return value is true if the directory was successfully changed;
4665 \fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...]
4670 suppressing the normal shell function lookup. Only builtin
4671 commands or commands found in the
4674 are executed. If the
4676 option is given, the search for
4678 is performed using a default value for
4680 that is guaranteed to find all of the standard utilities.
4685 option is supplied, a description of
4689 option causes a single word indicating the command or file name
4694 option produces a more verbose description.
4699 option is supplied, the exit status is 0 if
4701 was found, and 1 if not. If neither option is supplied and
4702 an error occurred or
4704 cannot be found, the exit status is 127. Otherwise, the exit status of the
4706 builtin is the exit status of
4709 \fBcontinue\fP [\fIn\fP]
4710 Resume the next iteration of the enclosing
4719 is specified, resume at the \fIn\fPth enclosing loop.
4723 is greater than the number of enclosing loops, the last enclosing loop
4724 (the ``top-level'' loop) is resumed. The return value is 0 unless the
4725 shell is not executing a loop when
4730 \fBdeclare\fP [\fB\-afFirx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP]]
4732 \fBtypeset\fP [\fB\-afFirx\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP]]
4734 Declare variables and/or give them attributes.
4735 If no \fIname\fPs are given then display the values of variables.
4738 option will display the attributes and values of each
4742 is used, additional options are ignored.
4745 option inhibits the display of function definitions; only the
4746 function name and attributes are printed.
4751 The following options can
4752 be used to restrict output to variables with the specified attribute or
4753 to give variables attributes:
4758 Each \fIname\fP is an array variable (see
4763 Use function names only.
4766 The variable is treated as an integer; arithmetic evaluation (see
4768 .B "ARITHMETIC EVALUATION" ") "
4769 is performed when the variable is assigned a value.
4772 Make \fIname\fPs readonly. These names cannot then be assigned values
4773 by subsequent assignment statements.
4776 Mark \fIname\fPs for export to subsequent commands via the environment.
4779 Using `+' instead of `\-'
4780 turns off the attribute instead, with the exception that \fB+a\fP
4781 may not be used to destroy an array variable. When used in a function,
4783 \fIname\fP local, as with the
4785 command. The return value is 0 unless an illegal option is encountered,
4786 an attempt is made to define a function using "\-f foo=bar",
4787 an attempt is made to assign a value to a readonly variable,
4788 an attempt is made to assign a value to an array variable without
4789 using the compound assignment syntax (see
4791 above), one of the \fInames\fP is not a legal shell variable name,
4792 an attempt is made to turn off readonly status for a readonly variable,
4793 an attempt is made to turn off array status for an array variable,
4794 or an attempt is made to display a non-existent function with \-f.
4797 .B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP]
4798 Without options, displays the list of currently remembered directories.
4799 The default display is on a single line with directory names separated
4801 Directories are added to the list with the
4805 command removes entries from the list.
4810 Displays the \fIn\fPth entry counting from the left of the list
4813 when invoked without options, starting with zero.
4816 Displays the \fIn\fPth entry counting from the right of the list
4819 when invoked without options, starting with zero.
4822 Clears the directory stack by deleting all of the entries.
4825 Produces a longer listing; the default listing format uses a
4826 tilde to denote the home directory.
4829 Print the directory stack with one entry per line.
4832 Print the directory stack with one entry per line,
4833 prefixing each entry with its index in the stack.
4836 The return value is 0 unless an
4837 illegal option is supplied or \fIn\fP indexes beyond the end
4838 of the directory stack.
4841 \fBdisown\fP [\fB\-h\fP] [\fIjobspec\fP ...]
4842 Without options, each
4844 is removed from the table of active jobs.
4845 If the \fB\-h\fP option is given, the job is not removed from the table,
4846 but is marked so that
4849 is not sent to the job if the shell receives a
4854 is present, the \fIcurrent job\fP is used. The return value is
4857 does not specify a valid job.
4859 \fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...]
4860 Output the \fIarg\fPs, separated by spaces, followed by a newline.
4861 The return status is always 0.
4862 If \fB\-n\fP is specified, the trailing newline is
4863 suppressed. If the \fB\-e\fP option is given, interpretation of
4864 the following backslash-escaped characters is enabled. The
4866 option disables the interpretation of these escape characters,
4867 even on systems where they are interpreted by default.
4871 to mean the end of options.
4873 interprets the following escape sequences:
4884 suppress trailing newline
4908 the character whose ASCII code is \fInnn\fP (octal)
4912 \fBenable\fP [\fB\-adnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...]
4913 Enable and disable builtin shell commands. This allows
4914 the execution of a disk command which has the same name as a shell
4915 builtin without specifying a full file name.
4916 If \fB\-n\fP is used, each \fIname\fP
4917 is disabled; otherwise,
4918 \fInames\fP are enabled. For example, to use the
4920 binary found via the
4923 instead of the shell builtin version, run
4924 \f(CWenable -n test\fP.
4927 option means to load the new builtin command
4931 on systems that support dynamic loading. The
4933 option will delete a builtin previously loaded with
4935 If no \fIname\fP arguments are given, or if the
4937 option is supplied, a list of shell builtins is printed.
4938 With no other option arguments, the list consists of all enabled
4940 If \fB\-n\fP is supplied, only disabled builtins are printed.
4941 If \fB\-a\fP is supplied, the list printed includes all builtins, with an
4942 indication of whether or not each is enabled.
4943 If \fB\-s\fP is supplied, the output is restricted to the POSIX
4944 \fIspecial\fP builtins.
4945 The return value is 0 unless a
4947 is not a shell builtin or there is a problem loading a new builtin
4948 from a shared object.
4950 \fBeval\fP [\fIarg\fP ...]
4951 The \fIarg\fPs are read and concatenated together into a single
4952 command. This command is then read and executed by the shell, and
4953 its exit status is returned as the value of
4957 or only null arguments,
4961 \fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP] [\fIarguments\fP]
4964 is specified, it replaces the shell.
4965 No new process is created. The
4967 become the arguments to \fIcommand\fP.
4971 the shell places a dash in the zeroth arg passed to
4979 to be executed with an empty environment. If
4981 is supplied, the shell passes
4983 as the zeroth argument to the executed command. If
4985 cannot be executed for some reason, a non-interactive shell exits,
4986 unless the shell option
4988 is enabled, in which case it returns failure.
4989 An interactive shell returns failure if the file cannot be executed.
4992 is not specified, any redirections take effect in the current shell,
4993 and the return status is 0.
4995 \fBexit\fP [\fIn\fP]
4996 Cause the shell to exit
4997 with a status of \fIn\fP. If
4999 is omitted, the exit status
5000 is that of the last command executed.
5004 is executed before the shell terminates.
5007 \fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ...
5013 are marked for automatic export to the environment of
5014 subsequently executed commands. If the
5022 are given, or if the
5024 option is supplied, a list
5025 of all names that are exported in this shell is printed.
5028 option causes the export property to be removed from the
5031 returns an exit status of 0 unless an illegal option is
5033 one of the \fInames\fP is not a legal shell variable name, or
5037 that is not a function.
5040 \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-nlr\fP] [\fIfirst\fP] [\fIlast\fP]
5042 \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
5044 Fix Command. In the first form, a range of commands from
5048 is selected from the history list.
5052 may be specified as a string (to locate the last command beginning
5053 with that string) or as a number (an index into the history list,
5054 where a negative number is used as an offset from the current
5057 is not specified it is set to
5058 the current command for listing (so that
5060 prints the last 10 commands) and to
5065 is not specified it is set to the previous
5066 command for editing and \-16 for listing.
5071 the command numbers when listing. The
5073 flag reverses the order of
5074 the commands. If the
5077 the commands are listed on
5078 standard output. Otherwise, the editor given by
5081 on a file containing those commands. If
5087 variable is used, and
5094 is not set. If neither variable is set,
5096 is used. When editing is complete, the edited commands are
5097 echoed and executed.
5099 In the second form, \fIcommand\fP is re-executed after each instance
5100 of \fIpat\fP is replaced by \fIrep\fP.
5101 A useful alias to use with this is
5103 .if t \f(CWr='fc \-s'\fP,
5107 runs the last command beginning with
5113 re-executes the last command.
5115 If the first form is used, the return value is 0 unless an illegal
5116 option is encountered or
5120 specify history lines out of range.
5123 option is supplied, the return value is the value of the last
5124 command executed or failure if an error occurs with the temporary
5125 file of commands. If the second form is used, the return status
5126 is that of the command re-executed, unless
5128 does not specify a valid history line, in which case
5132 \fBfg\fP [\fIjobspec\fP]
5135 in the foreground, and make it the current job. If
5137 is not present, the shell's notion of the \fIcurrent job\fP is used.
5138 The return value is that of the command placed into the foreground,
5139 or failure if run when job control is disabled or, when run with
5140 job control enabled, if
5142 does not specify a valid job or
5144 specifies a job that was started without job control.
5146 \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIargs\fP]
5148 is used by shell procedures to parse positional parameters.
5150 contains the option letters to be recognized; if a letter
5151 is followed by a colon, the option is expected to have an
5152 argument, which should be separated from it by white space.
5153 Each time it is invoked,
5155 places the next option in the shell variable
5159 if it does not exist,
5160 and the index of the next argument to be processed into the
5166 is initialized to 1 each time the shell or a shell script
5167 is invoked. When an option requires an argument,
5169 places that argument into the variable
5172 The shell does not reset
5175 automatically; it must be manually reset between multiple
5178 within the same shell invocation if a new set of parameters
5182 can report errors in two ways. If the first character of
5186 error reporting is used. In normal operation diagnostic messages
5187 are printed when illegal options or missing option arguments are
5192 is set to 0, no error message will be displayed, even if the first
5197 If an illegal option is seen,
5202 prints an error message and unsets
5208 the option character found is placed in
5211 and no diagnostic message is printed.
5213 If a required argument is not found, and
5216 a question mark (\^\fB?\fP\^) is placed in
5219 is unset, and a diagnostic message is printed.
5222 is silent, then a colon (\^\fB:\fP\^) is placed in
5227 is set to the option character found.
5230 normally parses the positional parameters, but if more arguments are
5234 parses those instead.
5236 returns true if an option, specified or unspecified, is found.
5237 It returns false if the end of options is encountered or an
5240 \fBhash\fP [\fB\-r\fP] [\fB\-p\fP \fIfilename\fP] [\fIname\fP]
5243 the full file name of the command is determined by searching
5249 option is supplied, no path search is performed, and
5251 is used as the full file name of the command.
5254 option causes the shell to forget all
5255 remembered locations. If no arguments are given, information
5256 about remembered commands is printed.
5257 The return status is true unless a
5259 is not found or an illegal option is supplied.
5261 \fBhelp\fP [\fIpattern\fP]
5262 Display helpful information about builtin commands. If
5266 gives detailed help on all commands matching
5268 otherwise help for all the builtins and shell control structures
5269 is printed. The return status is 0 unless no command matches
5273 \fBhistory\fP [\fB\-c\fP] [\fIn\fP]
5275 \fBhistory\fP \fB\-anrw\fP [\fIfilename\fP]
5277 \fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP]
5279 \fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP]
5281 With no options, display the command
5282 history list with line numbers. Lines listed
5285 have been modified. An argument of
5289 lines. If \fIfilename\fP is supplied, it is used as the
5290 name of the history file; if not, the value of
5293 is used. Options, if supplied, have the following meanings:
5298 Append the ``new'' history lines (history lines entered since the
5299 beginning of the current \fBbash\fP session) to the history file.
5302 Read the history lines not already read from the history
5303 file into the current history list. These are lines
5304 appended to the history file since the beginning of the
5305 current \fBbash\fP session.
5308 Read the contents of the history file
5309 and use them as the current history.
5312 Write the current history to the history file, overwriting the
5313 history file's contents.
5316 Clear the history list by deleting all the entries.
5319 Perform history substitution on the following \fIargs\fP and display
5320 the result on the standard output.
5321 Does not store the results in the history list.
5322 Each \fIarg\fP must be quoted to disable normal history expansion.
5327 in the history list as a single entry. The last command in the
5328 history list is removed before the
5333 The return value is 0 unless an illegal option is encountered or an
5334 error occurs while reading or writing the history file.
5338 \fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ]
5340 \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ]
5342 The first form lists the active jobs. The options have the following
5349 in addition to the normal information.
5352 List only the process ID of the job's process group
5356 Display information only about jobs that have changed status since
5357 the user was last notified of their status.
5360 Restrict output to running jobs.
5363 Restrict output to stopped jobs.
5368 is given, output is restricted to information about that job.
5369 The return status is 0 unless an illegal option is encountered
5384 with the corresponding process group ID, and executes
5388 returning its exit status.
5392 \fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ...
5394 \fBkill\fP \fB\-l\fP [\fIsignum\fP | \fIsigspec\fP]
5396 Send the signal named by
5400 to the processes named by
5405 is either a signal name such as
5410 is a signal number. If
5412 is a signal name, the name may be
5413 given with or without the
5419 is not present, then
5422 is assumed. An argument of
5424 lists the signal names. If any arguments are supplied when
5426 is given, the names of the specified signals are listed, and
5427 the return status is 0. The arguments to
5429 may be either signal names or signal numbers; if signal names
5430 are given, the corresponding signal number is displayed.
5432 returns true if at least one signal was successfully sent, or false
5433 if an error occurs or an illegal option is encountered.
5435 \fBlet\fP \fIarg\fP [\fIarg\fP ...]
5438 is an arithmetic expression to be evaluated (see
5440 .BR "ARITHMETIC EVALUATION" ).
5445 returns 1; 0 is returned otherwise.
5447 \fBlocal\fP [\fIname\fP[=\fIvalue\fP] ...]
5448 For each argument, create a local variable named
5454 is used within a function, it causes the variable
5456 to have a visible scope restricted to that function and its children.
5459 writes a list of local variables to the standard output. It is
5462 when not within a function. The return status is 0 unless
5464 is used outside a function, or an illegal
5471 \fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP]
5472 Removes entries from the directory stack. With no arguments,
5473 removes the top directory from the stack, and performs a
5475 to the new top directory.
5476 Arguments, if supplied, have the following meanings:
5481 Removes the \fIn\fPth entry counting from the left of the list
5484 starting with zero. For example: ``popd +0''
5485 removes the first directory, ``popd +1'' the second.
5488 Removes the \fIn\fPth entry counting from the right of the list
5491 starting with zero. For example: ``popd -0''
5492 removes the last directory, ``popd -1'' the next to last.
5495 Suppresses the normal change of directory when removing directories
5496 from the stack, so that only the stack is manipulated.
5501 command is successful, a
5503 is performed as well, and the return status is 0.
5505 returns false if an illegal option is encountered, the directory stack
5506 is empty, a non-existent directory stack entry is specified, or the
5507 directory change fails.
5511 \fBpushd\fP [\fB\-n\fP] [\fIdir\fP]
5513 \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP]
5515 Adds a directory to the top of the directory stack, or rotates
5516 the stack, making the new top of the stack the current working
5517 directory. With no arguments, exchanges the top two directories
5518 and returns 0, unless the directory stack is empty.
5519 Arguments, if supplied, have the following meanings:
5524 Rotates the stack so that the \fIn\fPth directory
5525 (counting from the left of the list shown by
5531 Rotates the stack so that the \fIn\fPth directory
5532 (counting from the right of the list shown by
5534 starting with zero) is at the top.
5537 Suppresses the normal change of directory when adding directories
5538 to the stack, so that only the stack is manipulated.
5543 to the directory stack at the top, making it the
5544 new current working directory.
5549 command is successful, a
5551 is performed as well.
5552 If the first form is used,
5554 returns 0 unless the cd to
5556 fails. With the second form,
5558 returns 0 unless the directory stack is empty,
5559 a non-existent directory stack element is specified,
5560 or the directory change to the specified new current directory
5564 \fBpwd\fP [\fB\-LP\fP]
5565 Print the absolute file name of the current working directory.
5566 The file name printed contains no symbolic links if the
5568 option is supplied or the
5572 builtin command is enabled.
5575 option is used, symbolic links are followed.
5576 The return status is 0 unless an error occurs while
5577 reading the name of the current directory.
5579 \fBread\fP [\fB\-er\fP] [\fB\-a\fP \fIaname\fP] [\fB\-p\fP \fIprompt\fP] [\fIname\fP ...]
5580 One line is read from the standard input, and the first word
5581 is assigned to the first
5583 the second word to the second
5585 and so on, with leftover words assigned to the last
5587 Only the characters in
5590 are recognized as word delimiters. Options, if supplied, have the
5596 A backslash-newline pair is not ignored, and
5597 the backslash is considered to be part of the line.
5600 Display \fIprompt\fP, without a
5601 trailing newline, before attempting to read any input. The prompt
5602 is displayed only if input is coming from a terminal.
5605 The words are assigned to sequential indices
5606 of the array variable
5610 is unset before any new values are assigned.
5613 If the standard input
5614 is coming from a terminal,
5619 above) is used to obtain the line.
5624 are supplied, the line read is assigned to the variable
5627 The return code is zero, unless end-of-file is encountered.
5630 \fBreadonly\fP [\fB\-apf\fP] [\fIname\fP ...]
5633 \fInames\fP are marked readonly; the values of these
5635 may not be changed by subsequent assignment.
5638 option is supplied, the functions corresponding to the
5643 option restricts the variables to arrays.
5646 arguments are given, or if the
5648 option is supplied, a list of all readonly names is printed.
5649 The return status is 0 unless an illegal option is encountered,
5652 is not a legal shell variable name, or
5656 that is not a function.
5658 \fBreturn\fP [\fIn\fP]
5659 Causes a function to exit with the return value specified by
5663 is omitted, the return status is that of the last command
5664 executed in the function body. If used outside a function,
5665 but during execution of a script by the
5667 (\fBsource\fP) command, it causes the shell to stop executing
5668 that script and return either
5670 or the exit status of the last command executed within the
5671 script as the exit status of the script. If used outside a
5672 function and not during execution of a script by \fB.\fP\^,
5673 the return status is false.
5675 \fBset\fP [\fB\-\-abefhkmnptuvxBCHP\fP] [\fB\-o\fP \fIoption\fP] [\fIarg\fP ...]
5676 Without options, the name and value of each shell variable are displayed
5677 in a format that can be re-used as input.
5678 When options are specified, they set or unset shell attributes.
5679 Any arguments remaining after the options are processed are treated
5680 as values for the positional parameters and are assigned, in order, to
5685 Options, if specified, have the following meanings:
5690 Automatically mark variables which are modified or created for export
5691 to the environment of subsequent commands.
5694 Report the status of terminated background jobs
5695 immediately, rather than before the next primary prompt. This is
5696 effective only when job control is enabled.
5699 Exit immediately if a \fIsimple command\fP (see
5702 above) exits with a non-zero status. The shell does not exit if the
5703 command that fails is part of an
5710 statement, part of a
5714 list, or if the command's return value is
5719 Disable pathname expansion.
5722 Remember the location of commands as they are looked up for execution.
5723 This is on by default.
5726 All arguments in the form of assignment statements
5727 are placed in the environment for a command, not just
5728 those that precede the command name.
5731 Monitor mode. Job control is enabled. This flag is on
5732 by default for interactive shells on systems that support
5736 above). Background processes run in a separate process
5737 group and a line containing their exit status is printed
5738 upon their completion.
5741 Read commands but do not execute them. This may be used to
5742 check a shell script for syntax errors. This is ignored by
5745 .B \-o \fIoption\-name\fP
5746 The \fIoption\-name\fP can be one of the following:
5758 Use an emacs-style command line editing interface. This is enabled
5759 by default when the shell is interactive, unless the shell is started
5777 Enable command history, as described above under
5780 This option is on by default in interactive shells.
5783 The effect is as if the shell command \f(CWIGNOREEOF=10\fP had been executed
5825 Change the behavior of
5827 where the default operation differs
5828 from the POSIX 1003.2 standard to match the standard.
5839 Use a vi-style command line editing interface.
5848 is supplied with no \fIoption\-name\fP, the values of the current options are
5852 is supplied with no \fIoption\-name\fP, a series of
5854 commands to recreate the current option settings is displayed on
5855 the standard output.
5861 mode. In this mode, the
5863 file is not processed, and shell functions
5864 are not inherited from the environment. This is enabled automatically
5865 on startup if the effective user (group) id is not equal to the real
5866 user (group) id. Turning this option off causes the effective user
5867 and group ids to be set to the real user and group ids.
5870 Exit after reading and executing one command.
5873 Treat unset variables as an error when performing
5874 parameter expansion. If expansion is attempted on an
5875 unset variable, the shell prints an error message, and,
5876 if not interactive, exits with a non-zero status.
5879 Print shell input lines as they are read.
5882 After expanding each \fIsimple command\fP,
5883 display the expanded value of
5886 followed by the command and its expanded arguments.
5889 The shell performs brace expansion (see
5891 above). This is on by default.
5896 does not overwrite an existing file with the
5901 redirection operators. This may be overridden when
5902 creating output files by using the redirection operator
5910 style history substitution. This flag is on by
5911 default when the shell is interactive.
5914 If set, the shell does not follow symbolic links when executing
5917 that change the current working directory. It uses the
5918 physical directory structure instead. By default,
5920 follows the logical chain of directories when performing commands
5921 which change the current directory.
5924 If no arguments follow this flag, then the positional parameters are
5925 unset. Otherwise, the positional parameters are set to the
5926 \fIarg\fPs, even if some of them begin with a
5930 Signal the end of options, cause all remaining \fIarg\fPs to be
5931 assigned to the positional parameters. The
5935 options are turned off.
5936 If there are no \fIarg\fPs,
5937 the positional parameters remain unchanged.
5940 The flags are off by default
5941 unless otherwise noted.
5942 Using + rather than \- causes these flags
5943 to be turned off. The
5944 flags can also be specified as options to an
5945 invocation of the shell. The current
5946 set of flags may be found in
5948 The return status is always true
5949 unless an illegal option is encountered.
5952 \fBshift\fP [\fIn\fP]
5953 The positional parameters from \fIn\fP+1 ... are renamed to
5956 Parameters represented by the numbers \fB$#\fP
5957 down to \fB$#\fP\-\fIn\fP+1 are unset.
5959 must be a non-negative number less than or equal to \fB$#\fP.
5962 is 0, no parameters are changed.
5965 is not given, it is assumed to be 1.
5968 is greater than \fB$#\fP, the positional parameters are not changed.
5969 The return status is greater than zero if
5973 or less than zero; otherwise 0.
5975 \fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...]
5976 Toggle the values of variables controlling optional shell behavior.
5977 With no options, or with the
5979 option, a list of all settable options is displayed, with
5980 an indication of whether or not each is set. Other options have
5981 the following meanings:
5986 Enable (set) each \fIoptname\fP.
5989 Disable (unset) each \fIoptname\fP.
5992 Suppresses normal output (quiet mode); the return status indicates
5993 whether the \fIoptname\fP is set or unset.
5994 If multiple \fIoptname\fP arguments are given with
5996 the return status is zero if all \fIoptnames\fP are enabled; non-zero
6000 Restricts the values of \fIoptname\fP to be those defined for the
6011 is used with no \fIoptname\fP arguments, the display is limited to
6012 those options which are set or unset, respectively.
6013 Unless otherwise noted, the \fBshopt\fP options are disabled (unset)
6016 The return status when listing options is zero if all \fIoptnames\fP
6017 are enabled, non-zero otherwise. When setting or unsetting options,
6018 the return status is zero unless an \fIoptname\fP is not a legal shell
6021 The list of \fBshopt\fP options is:
6027 If set, an argument to the
6029 builtin command that
6030 is not a directory is assumed to be the name of a variable whose
6031 value is the directory to change to.
6034 If set, minor errors in the spelling of a directory component in a
6036 command will be corrected.
6037 The errors checked for are transposed characters,
6038 a missing character, and one character too many.
6039 If a correction is found, the corrected file name is printed,
6040 and the command proceeds.
6041 This option is only used by interactive shells.
6044 If set, \fBbash\fP checks that a command found in the hash
6045 table exists before trying to execute it. If a hashed command no
6046 longer exists, a normal path search is performed.
6049 If set, \fBbash\fP checks the window size after each command
6050 and, if necessary, updates the values of
6060 attempts to save all lines of a multiple-line
6061 command in the same history entry. This allows
6062 easy re-editing of multi-line commands.
6067 includes filenames beginning with a `.' in the results of pathname
6071 If set, a non-interactive shell will not exit if
6072 it cannot execute the file specified as an argument to the
6074 builtin command. An interactive shell does not exit if
6079 If set, aliases are expanded as described above under
6082 This option is enabled by default for interactive shells.
6085 If set, the history list is appended to the file named by the value
6088 variable when the shell exits, rather than overwriting the file.
6093 is being used, a user is given the opportunity to re-edit a
6094 failed history substitution.
6099 is being used, the results of history substitution are not immediately
6100 passed to the shell parser. Instead, the resulting line is loaded into
6101 the \fBreadline\fP editing buffer, allowing further modification.
6106 is being used, bash will attempt to perform hostname completion when a
6107 word beginning with \fB@\fP is being completed (see
6113 This is enabled by default.
6115 .B interactive_comments
6116 If set, allow a word beginning with
6118 to cause that word and all remaining characters on that
6119 line to be ignored in an interactive shell (see
6122 above). This option is enabled by default.
6127 option is enabled, multi-line commands are saved to the history with
6128 embedded newlines rather than using semicolon separators where possible.
6131 If set, and a file that \fBbash\fP is checking for mail has been
6132 accessed since the last time it was checked, the message ``The mail in
6133 \fImailfile\fP has been read'' is displayed.
6138 allows patterns which match no
6140 .B Pathname Expansion
6142 to expand to a null string, rather than themselves.
6145 If set, prompt strings undergo variable and parameter expansion after
6146 being expanded as described in
6149 above. This option is enabled by default.
6154 builtin prints an error message when the shift count exceeds the
6155 number of positional parameters.
6159 \fBsource\fP (\fB.\fP) builtin uses the value of
6162 to find the directory containing the file supplied as an argument.
6163 This is enabled by default.
6166 \fBsuspend\fP [\fB\-f\fP]
6167 Suspend the execution of this shell until it receives a
6172 option says not to complain if this is
6173 a login shell; just suspend anyway. The return status is 0 unless
6174 the shell is a login shell and
6176 is not supplied, or if job control is not enabled.
6179 \fBtest\fP \fIexpr\fP
6181 \fB[\fP \fIexpr\fP \fB]\fP
6182 Return a status of 0 or 1 depending on
6183 the evaluation of the conditional expression
6185 Expressions may be unary or binary. Unary
6186 expressions are often used to examine the status of a file. There
6187 are string operators and numeric comparison operators as well. Each
6188 operator and operand must be a separate argument. If \fIfile\fP
6189 is of the form /dev/fd/\fIn\fP, then file descriptor \fIn\fP is
6190 checked. Expressions are composed of the following primaries:
6195 True if \fIfile\fP exists and is a block special file.
6198 True if \fIfile\fP exists and is a character special file.
6201 True if \fIfile\fP exists and is a directory.
6204 True if \fIfile\fP exists.
6207 True if \fIfile\fP exists and is a regular file.
6210 True if \fIfile\fP exists and is set-group-id.
6213 True if \fIfile\fP has its ``sticky'' bit set.
6216 True if \fIfile\fP exists and is a symbolic link.
6219 True if \fIfile\fP exists and is a named pipe.
6222 True if \fIfile\fP exists and is readable.
6225 True if \fIfile\fP exists and has a size greater than zero.
6228 True if \fIfile\fP exists and is a socket.
6233 is opened on a terminal.
6236 True if \fIfile\fP exists and its set-user-id bit is set.
6239 True if \fIfile\fP exists and is writable.
6242 True if \fIfile\fP exists and is executable.
6245 True if \fIfile\fP exists and is owned by the effective user id.
6248 True if \fIfile\fP exists and is owned by the effective group id.
6250 \fIfile1\fP \-\fBnt\fP \fIfile2\fP
6251 True if \fIfile1\fP is newer (according to
6252 modification date) than \fIfile2\fP.
6254 \fIfile1\fP \-\fBot\fP \fIfile2\fP
6255 True if \fIfile1\fP is older than \fIfile2\fP.
6257 \fIfile1\fP \fB\-ef\fP \fIfile2\fP
6258 True if \fIfile1\fP and \fIfile2\fP have the same device and
6261 .B \-o \fIoptname\fP
6262 True if shell option
6265 See the list of options under the description of the
6272 True if the length of \fIstring\fP is zero.
6277 True if the length of
6281 \fIstring1\fP \fB=\fP \fIstring2\fP
6282 True if the strings are equal. \fB==\fP may be used in place of
6285 \fIstring1\fP \fB!=\fP \fIstring2\fP
6286 True if the strings are not equal.
6288 \fIstring1\fP \fB<\fP \fIstring2\fP
6289 True if \fIstring1\fP sorts before \fIstring2\fP lexicographically.
6291 \fIstring1\fP \fB>\fP \fIstring2\fP
6292 True if \fIstring1\fP sorts after \fIstring2\fP lexicographically.
6299 \fIexpr1\fP \-\fBa\fP \fIexpr2\fP
6306 \fIexpr1\fP \-\fBo\fP \fIexpr2\fP
6313 .I \fIarg1\fP \fBOP\fP \fIarg2\fP
6324 These arithmetic binary operators return true if \fIarg1\fP
6325 is equal to, not equal to, less than, less than or equal to,
6326 greater than, or greater than or equal to \fIarg2\fP, respectively.
6330 may be positive or negative integers.
6335 Print the accumulated user and system times for the shell and
6336 for processes run from the shell. The return status is 0.
6338 \fBtrap\fP [\fB\-lp\fP] [\fIarg\fP] [\fIsigspec\fP ...]
6341 is to be read and executed when the shell receives
6348 all specified signals are
6349 reset to their original values (the values they had
6350 upon entrance to the shell).
6353 is the null string the signal specified by each
6355 is ignored by the shell and by the commands it invokes.
6360 then the trap commands associated with
6363 are displayed. If no arguments are supplied or if
6368 prints the list of commands associated with each signal number.
6372 a signal name defined in <\fIsignal.h\fP>, or a signal number.
6380 is executed on exit from the shell. If a
6387 is executed after every \fIsimple command\fP (see
6393 option causes the shell to print a list of signal names and
6394 their corresponding numbers.
6395 Signals ignored upon entry to the shell cannot be trapped or reset.
6396 Trapped signals are reset to their original values in a child
6397 process when it is created.
6398 The return status is false if any
6400 is invalid; otherwise
6404 \fBtype\fP [\fB\-all\fP] [\fB\-type\fP | \fB\-path\fP] \fIname\fP [\fIname\fP ...]
6408 would be interpreted if used as a command name.
6413 prints a string which is one of
6422 is an alias, shell reserved word, function, builtin, or disk file,
6426 is not found, then nothing is printed, and an exit status of false
6432 either returns the name of the disk file
6433 that would be executed if
6435 were specified as a command name,
6440 If a command is hashed,
6442 prints the hashed value, not necessarily the file that appears
6450 prints all of the places that contain
6453 This includes aliases and functions,
6456 flag is not also used.
6457 The table of hashed commands is not consulted
6473 returns true if any of the arguments are found, false if
6476 \fBulimit\fP [\fB\-SHacdflmnpstuv\fP [\fIlimit\fP]]
6477 Provides control over the resources available to the shell and to
6478 processes started by it, on systems that allow such control. The
6481 can be a number in the unit specified for the resource, or the
6484 The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is
6485 set for the given resource. A hard limit cannot be increased once it
6486 is set; a soft limit may be increased up to the value of the hard limit.
6487 If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard
6491 is omitted, the current value of the soft limit of the resource is
6492 printed, unless the \fB\-H\fP option is given. When more than one
6493 resource is specified, the limit name and unit are printed before the value.
6494 Other options are interpreted as follows:
6499 All current limits are reported
6502 The maximum size of core files created
6505 The maximum size of a process's data segment
6508 The maximum size of files created by the shell
6511 The maximum size that may be locked into memory
6514 The maximum resident set size
6517 The maximum number of open file descriptors (most systems do not
6518 allow this value to be set)
6521 The pipe size in 512-byte blocks (this may not be set)
6524 The maximum stack size
6527 The maximum amount of cpu time in seconds
6530 The maximum number of processes available to a single user
6533 The maximum amount of virtual memory available to the shell
6538 is given, it is the new value of the specified resource (the
6540 option is display only).
6541 If no option is given, then
6543 is assumed. Values are in 1024-byte increments, except for
6545 which is in seconds,
6547 which is in units of 512-byte blocks,
6552 which are unscaled values. The return status is 0
6553 unless an illegal option is encountered, a non-numeric argument
6554 other than \fBunlimited\fP is supplied as \fIlimit\fP, or an
6555 error occurs while setting a new limit.
6558 \fBumask\fP [\fB\-S\fP] [\fImode\fP]
6559 The user file-creation mask is set to
6563 begins with a digit, it
6564 is interpreted as an octal number; otherwise
6565 it is interpreted as a symbolic mode mask similar
6570 is omitted, or if the
6572 option is supplied, the
6573 current value of the mask is printed.
6576 option causes the mask to be printed in symbolic form; the
6577 default output is an octal number.
6578 The return status is 0 if the mode was successfully changed or if
6579 no \fImode\fP argument was supplied, and false otherwise.
6581 \fBunalias\fP [\-\fBa\fP] [\fIname\fP ...]
6582 Remove \fIname\fPs from the list of defined aliases. If
6584 is supplied, all alias definitions are removed. The return
6585 value is true unless a supplied
6587 is not a defined alias.
6589 \fBunset\fP [\-\fBfv\fP] [\fIname\fP ...]
6592 remove the corresponding variable or function.
6593 If no options are supplied, or the
6595 option is given, each
6597 refers to a shell variable.
6598 Read-only variables may not be unset.
6604 refers to a shell function, and the function definition
6606 Each unset variable or function is removed from the environment
6607 passed to subsequent commands.
6620 are unset, they lose their special properties, even if they are
6621 subsequently reset. The exit status is true unless a
6623 does not exist or is readonly.
6625 \fBwait\fP [\fIn\fP]
6626 Wait for the specified process and return its termination
6630 ID or a job specification; if a job spec is given, all processes
6631 in that job's pipeline are waited for. If
6633 is not given, all currently active child processes
6634 are waited for, and the return status is zero. If
6636 specifies a non-existent process or job, the return status is
6637 127. Otherwise, the return status is the exit status of the last
6638 process or job waited for.
6641 .SH "RESTRICTED SHELL"
6645 is started with the name
6649 option is supplied at invocation,
6650 the shell becomes restricted.
6651 A restricted shell is used to
6652 set up an environment more controlled than the standard shell.
6653 It behaves identically to
6655 with the exception that the following are disallowed:
6657 changing directories with \fBcd\fP
6659 setting or unsetting the values of
6664 specifying command names containing
6667 specifying a file name containing a
6669 as an argument to the
6673 importing function definitions from the shell environment at startup
6675 redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
6679 builtin command to replace the shell with another command
6681 adding or deleting builtin commands with the
6695 turning off restricted mode with
6698 These restrictions are enforced after any startup files are read.
6700 When a command that is found to be a shell script is executed (see
6702 .B "COMMAND EXECUTION"
6705 turns off any restrictions in the shell spawned to execute the
6710 \fIBash Features\fP, Brian Fox and Chet Ramey
6712 \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
6714 \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
6716 \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE
6718 \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
6720 \fIemacs\fP(1), \fIvi\fP(1)
6728 The \fBbash\fP executable
6731 The systemwide initialization file, executed for login shells
6734 The personal initialization file, executed for login shells
6737 The individual per-interactive-shell startup file
6740 Individual \fIreadline\fP initialization file
6743 Brian Fox, Free Software Foundation
6747 Chet Ramey, Case Western Reserve University
6751 If you find a bug in
6753 you should report it. But first, you should
6754 make sure that it really is a bug, and that it appears in the latest
6759 Once you have determined that a bug actually exists, use the
6761 command to submit a bug report.
6762 If you have a fix, you are encouraged to mail that as well!
6763 Suggestions and `philosophical' bug reports may be mailed
6764 to \fPbug-bash\fP@\fIprep.ai.MIT.Edu\fP or posted to the Usenet
6768 ALL bug reports should include:
6772 The version number of \fBbash\fR
6774 The hardware and operating system
6776 The compiler used to compile
6778 A description of the bug behaviour
6780 A short script or `recipe' which exercises the bug
6784 inserts the first three items automatically into the template
6785 it provides for filing a bug report.
6787 Comments and bug reports concerning
6788 this manual page should be directed to
6789 .IR chet@ins.CWRU.Edu .
6792 It's too big and too slow.
6794 There are some subtle differences between
6796 and traditional versions of
6798 mostly because of the
6803 Aliases are confusing in some uses.
6805 Shell builtin commands and functions are not stoppable/restartable.
6807 Compound commands and command sequences of the form `a ; b ; c'
6808 are not handled gracefully when process suspension is attempted.
6809 When a process is stopped, the shell immediately executes the next
6810 command in the sequence.
6811 It suffices to place the sequence of commands between
6812 parentheses to force it into a subshell, which may be stopped as
6815 Commands inside of \fB$(\fP...\fB)\fP command substitution are not
6816 parsed until substitution is attempted. This will delay error
6817 reporting until some time after the command is entered.
6819 Array variables may not (yet) be exported.
projects / platform / upstream / bash.git / blob