2 .\" MAN PAGE COMMENTS to
5 .\" Information Network Services
6 .\" Case Western Reserve University
9 .\" Last Change: Fri May 5 10:44:39 EDT 1995
11 .\" bash_builtins, strip all but Built-Ins section
13 .TH BASH 1 "1995 May 5" 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 by the Free Software Foundation, Inc.
54 .if t Bash is Copyright \(co 1989, 1991 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 is
92 flag is present, or if no arguments remain after option
93 processing, then commands are read from the standard input.
94 This option allows the positional parameters to be set
95 when invoking an interactive shell.
100 signals the end of options and disables further option processing.
101 Any arguments after the
103 are treated as filenames and arguments. An argument of
105 is equivalent to an argument of \fB\-\fP.
109 also interprets a number of multi\-character options. These options must
110 appear on the command line before the single\-character options to be
116 Do not read and execute the personal initialization file
118 if the shell is interactive.
119 This option is on by default if the shell is invoked as
123 Do not read either the system\-wide startup file
125 or any of the personal initialization files
126 .IR ~/.bash_profile ,
132 normally reads these files when it is invoked as a login shell (see
137 \fB\-rcfile\fP \fIfile\fP
138 Execute commands from
140 instead of the standard personal initialization file
142 if the shell is interactive (see
148 Show the version number of this instance of
153 Do not be verbose when starting up (do not show the shell version or any
154 other information). This is the default.
159 act as if it had been invoked as a login shell.
161 .B \-nobraceexpansion
162 Do not perform curly brace expansion (see
169 library to read command lines if interactive.
172 Change the behavior of bash where the default operation differs
173 from the Posix 1003.2 standard to match the standard
176 If arguments remain after option processing, and neither the
180 option has been supplied, the first argument is assumed to
181 be the name of a file containing shell commands. If
183 is invoked in this fashion,
185 is set to the name of the file, and the positional parameters
186 are set to the remaining arguments.
188 reads and executes commands from this file, then exits.
190 exit status is the exit status of the last command executed
199 A sequence of characters considered as a single unit by the shell.
206 consisting only of alphanumeric characters and underscores, and
207 beginning with an alphabetic character or an underscore. Also
212 A character that, when unquoted, separates words. One of the following:
216 .if t \fB| & ; ( ) < > space tab\fP
217 .if n \fB| & ; ( ) < > space tab\fP
222 A \fItoken\fP that performs a control function. It is one of the following
226 .if t \fB\(bv\|\(bv & && ; ;; ( ) | <newline>\fP
227 .if n \fB|| & && ; ;; ( ) | <newline>\fP
231 \fIReserved words\fP are words that have a special meaning to the shell.
232 The following words are recognized as reserved when unquoted and either
233 the first word of a simple command (see
236 below) or the third word of a
244 .if n ! case do done elif else esac fi for function if in select then until while { }
245 .if t ! case do done elif else esac fi for function if in select then until while { }
251 A \fIsimple command\fP is a sequence of optional variable assignments
252 followed by \fIblank\fP\-separated words and redirections, and
253 terminated by a \fIcontrol operator\fP. The first word
254 specifies the command to be executed. The remaining words are
255 passed as arguments to the invoked command.
257 The return value of a \fIsimple command\fP is its exit status, or
258 128+\fIn\^\fP if the command is terminated by signal
262 A \fIpipeline\fP is a sequence of one or more commands separated by
265 The format for a pipeline is:
268 [ ! ] \fIcommand\fP [ \fB|\fP \fIcommand2\fP ... ]
271 The standard output of
273 is connected to the standard input of
275 This connection is performed before any redirections specified by the
283 precedes a pipeline, the exit status of that
284 pipeline is the logical NOT of the exit status of the last command.
285 Otherwise, the status of the pipeline is the exit status of the last
286 command. The shell waits for all commands in the pipeline to
287 terminate before returning a value.
289 Each command in a pipeline is executed as a separate process (i.e., in a
293 A \fIlist\fP is a sequence of one or more pipelines separated by one
300 and terminated by one of
306 Of these list operators,
310 have equal precedence, followed by
314 which have equal precedence.
316 If a command is terminated by the control operator
318 the shell executes the command in the \fIbackground\fP
319 in a subshell. The shell does not wait for the command to
320 finish, and the return status is 0. Commands separated by a
322 are executed sequentially; the shell waits for each
323 command to terminate in turn. The return status is the
324 exit status of the last command executed.
326 The control operators
330 denote AND lists and OR lists, respectively.
331 An AND list has the form
334 \fIcommand\fP \fB&&\fP \fIcommand2\fP
338 is executed if, and only if,
340 returns an exit status of zero.
342 An OR list has the form
345 \fIcommand\fP \fB\(bv\|\(bv\fP \fIcommand2\fP
350 is executed if and only if
352 returns a non\-zero exit status. The return status of
353 AND and OR lists is the exit status of the last command
354 executed in the list.
355 .SS Compound Commands
357 A \fIcompound command\fP is one of the following:
360 \fIlist\fP is executed in a subshell. Variable assignments and builtin
361 commands that affect the shell's environment do not remain in effect
362 after the command completes. The return status is the exit status of
366 \fIlist\fP is simply executed in the current shell environment. This is
367 known as a \fIgroup command\fP. The return status is the exit status of
370 \fBfor\fP \fIname\fP [ \fBin\fP \fIword\fP; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
371 The list of words following \fBin\fP is expanded, generating a list
372 of items. The variable \fIname\fP is set to each element of this list
373 in turn, and \fIlist\fP is executed each time. If the \fBin\fP
374 \fIword\fP is omitted, the \fBfor\fP command executes \fIlist\fP
375 once for each positional parameter that is set (see
380 \fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP; ] \fBdo\fP \fIlist\fP ; \fBdone\fP
381 The list of words following \fBin\fP is expanded, generating a list
382 of items. The set of expanded words is printed on the standard
383 error, each preceded by a number. If the \fBin\fP
384 \fIword\fP is omitted, the positional parameters are printed (see
389 prompt is then displayed and a line read from the standard input.
390 If the line consists of the number corresponding to one of
391 the displayed words, then the value of
393 is set to that word. If the line is empty, the words and prompt
394 are displayed again. If EOF is read, the command completes. Any
395 other value read causes
397 to be set to null. The line read is saved in the variable
401 is executed after each selection until a
408 is the exit status of the last command executed in
410 or zero if no commands were executed.
412 \fBcase\fP \fIword\fP \fBin\fP [ \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
413 ... ) \fIlist\fP ;; ] ... \fBesac\fP
414 A \fBcase\fP command first expands \fIword\fP, and tries to match
415 it against each \fIpattern\fP in turn, using the same matching rules
416 as for pathname expansion (see
417 .B Pathname Expansion
418 below). When a match is found, the
419 corresponding \fIlist\fP is executed. After the first match, no
420 subsequent matches are attempted. The exit status is zero if no
421 patterns are matches. Otherwise, it is the exit status of the
422 last command executed in \fIlist\fP.
424 \fBif\fP \fIlist\fP \fBthen\fP \fIlist\fP \
425 [ \fBelif\fP \fIlist\fP \fBthen\fP \fIlist\fP ] ... \
426 [ \fBelse\fP \fIlist\fP ] \fBfi\fP
430 is executed. If its exit status is zero, the
431 \fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP
432 \fIlist\fP is executed in turn, and if its exit status is zero,
433 the corresponding \fBthen\fP \fIlist\fP is executed and the
434 command completes. Otherwise, the \fBelse\fP \fIlist\fP is
435 executed, if present. The exit status is the exit status of the
436 last command executed, or zero if no condition tested true.
439 \fBwhile\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP
441 \fBuntil\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP
443 The \fBwhile\fP command continuously executes the \fBdo\fP
444 \fIlist\fP as long as the last command in \fIlist\fP returns
445 an exit status of zero. The \fBuntil\fP command is identical
446 to the \fBwhile\fP command, except that the test is negated;
450 is executed as long as the last command in
452 returns a non\-zero exit status.
453 The exit status of the \fBwhile\fP and \fBuntil\fP commands
455 of the last \fBdo\fP \fIlist\fP command executed, or zero if
458 [ \fBfunction\fP ] \fIname\fP () { \fIlist\fP; }
459 This defines a function named \fIname\fP. The \fIbody\fP of the
462 of commands between { and }. This list
463 is executed whenever \fIname\fP is specified as the
464 name of a simple command. The exit status of a function is
465 the exit status of the last command executed in the body. (See
470 In a non\-interactive shell, or an interactive shell in which the
471 .B -o interactive\-comments
472 option to the \fBset\fP builtin is enabled, a word beginning with
474 causes that word and all remaining characters on that line to
475 be ignored. An interactive shell without the
476 .B -o interactive\-comments
477 option enabled does not allow comments.
479 \fIQuoting\fP is used to remove the special meaning of certain
480 characters or words to the shell. Quoting can be used to
481 disable special treatment for special characters, to prevent
482 reserved words from being recognized as such, and to prevent
485 Each of the \fImetacharacters\fP listed above under
488 has special meaning to the shell and must be quoted if they are to
489 represent themselves. There are three quoting mechanisms: the
490 .IR "escape character" ,
491 single quotes, and double quotes.
493 A non-quoted backslash (\fB\e\fP) is the
494 .IR "escape character" .
495 It preserves the literal value of the next character that follows,
496 with the exception of <newline>. If a \fB\e\fP<newline> pair
497 appears, and the backslash is not quoted, the \fB\e\fP<newline>
498 is treated as a line continuation (that is, it is effectively ignored).
500 Enclosing characters in single quotes preserves the literal value
501 of each character within the quotes. A single quote may not occur
502 between single quotes, even when preceded by a backslash.
504 Enclosing characters in double quotes preserves the literal value
505 of all characters within the quotes, with the exception of
514 retain their special meaning within double quotes. The backslash
515 retains its special meaning only when followed by one of the following
523 A double quote may be quoted within double quotes by preceding it with
526 The special parameters
530 have special meaning when in double
538 is an entity that stores values, somewhat like a
539 variable in a conventional programming language. It can be a
541 a number, or one of the special characters listed below under
542 .BR "Special Parameters" .
543 For the shell's purposes, a
545 is a parameter denoted by a
548 A parameter is set if it has been assigned a value. The null string is
549 a valid value. Once a variable is set, it may be unset only by using
554 .B SHELL BUILTIN COMMANDS
559 may be assigned to by a statement of the form
562 \fIname\fP=[\fIvalue\fP]
567 is not given, the variable is assigned the null string. All
569 undergo tilde expansion, parameter and variable expansion, command
570 substitution, arithmetic expansion, and quote removal. If
577 .BR "SHELL BUILTIN COMMANDS" )
580 is subject to arithmetic expansion even if the $[...] syntax does
581 not appear. Word splitting is not performed, with the exception
582 of \fB"$@"\fP as explained below under
583 .BR "Special Parameters" .
584 Pathname expansion is not performed.
585 .SS Positional Parameters
588 .I positional parameter
589 is a parameter denoted by one or more
590 digits, other than the single digit 0. Positional parameters are
591 assigned from the shell's arguments when it is invoked,
592 and may be reassigned using the
594 builtin command. Positional parameters may not be assigned to
595 with assignment statements. The positional parameters are
596 temporarily replaced when a shell function is executed (see
601 When a positional parameter consisting of more than a single
602 digit is expanded, it must be enclosed in braces (see
606 .SS Special Parameters
608 The shell treats several parameters specially. These parameters may
609 only be referenced; assignment to them is not allowed.
613 Expands to the positional parameters, starting from one. When the
614 expansion occurs within double quotes, it expands to a single word
615 with the value of each parameter separated by the first character
619 special variable. That is, ``\fB$*\fP'' is equivalent
620 to ``\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP'', where
622 is the first character of the value of the
628 is null or unset, the parameters are separated by spaces.
631 Expands to the positional parameters, starting from one. When the
632 expansion occurs within double quotes, each parameter expands as a
633 separate word. That is, ``
636 ``\fB$1\fP'' ``\fB$2\fP'' ...
637 When there are no positional parameters, ``\fB$@\fP'' and
639 expand to nothing (i.e., they are removed).
642 Expands to the number of positional parameters in decimal.
645 Expands to the status of the most recently executed foreground
649 Expands to the current option flags as specified upon invocation,
652 builtin command, or those set by the shell itself
658 Expands to the process ID of the shell. In a () subshell, it
659 expands to the process ID of the current shell, not the
663 Expands to the process ID of the most recently executed background
664 (asynchronous) command.
667 Expands to the name of the shell or shell script. This is set at
668 shell initialization. If
670 is invoked with a file of commands,
672 is set to the name of that file. If
678 is set to the first argument after the string to be
679 executed, if one is present. Otherwise, it is set
680 to the pathname used to invoke
682 as given by argument zero.
685 Expands to the last argument to the previous command, after expansion.
686 Also set to the full pathname of each command executed and placed in
687 the environment exported to that command.
691 The following variables are set by the shell:
696 The process ID of the shell's parent.
699 The current working directory as set by the
704 The previous working directory as set by the
709 Set to the line of input read by the
711 builtin command when no arguments are supplied.
714 Expands to the user ID of the current user, initialized at shell startup.
717 Expands to the effective user ID of the current user, initialized at
721 Expands to the full pathname used to invoke this instance of
725 Expands to the version number of this instance of
729 Incremented by one each time an instance of
734 Each time this parameter is referenced, a random integer is
735 generated. The sequence of random numbers may be initialized by assigning
742 is unset, it loses its special properties, even if it is
746 Each time this parameter is
747 referenced, the number of seconds since shell invocation is returned. If a
751 the value returned upon subsequent
753 the number of seconds since the assignment plus the value assigned.
757 is unset, it loses its special properties, even if it is
761 Each time this parameter is referenced, the shell substitutes
762 a decimal number representing the current sequential line number
763 (starting with 1) within a script or function. When not in a
764 script or function, the value substituted is not guaranteed to
765 be meaningful. When in a function, the value is not
766 the number of the source line that the command appears
767 on (that information has been lost by the time the function is
768 executed), but is an approximation of the number of
770 executed in the current function.
774 is unset, it loses its special properties, even if it is
778 The history number, or index in the history list, of the current
782 is unset, it loses its special properties, even if it is
786 The value of the last option argument processed by the
790 .B SHELL BUILTIN COMMANDS
794 The index of the next argument to be processed by the
798 .B SHELL BUILTIN COMMANDS
802 Automatically set to a string that uniquely
803 describes the type of machine on which
805 is executing. The default is system-dependent.
808 Automatically set to a string that
809 describes the operating system on which
811 is executing. The default is system-dependent.
814 The following variables are used by the shell. In some cases,
816 assigns a default value to a variable; these cases are noted
823 .I Internal Field Separator
825 for word splitting after expansion and to
826 split lines into words with the
828 builtin command. The default value is
829 ``<space><tab><newline>''.
832 The search path for commands. It
833 is a colon-separated list of directories in which
834 the shell looks for commands (see
837 below). The default path is system\-dependent,
838 and is set by the administrator who installs
840 A common value is ``/usr/gnu/bin:/usr/local/bin:/usr/ucb:/bin:/usr/bin:.''.
843 The home directory of the current user; the default argument for the
844 \fBcd\fP builtin command.
847 The search path for the
849 command. This is a colon-separated
850 list of directories in which the shell looks for destination directories
853 command. A sample value is
857 If this parameter is set when \fBbash\fP is executing a shell script,
858 its value is interpreted as a filename containing commands to
859 initialize the shell, as in
864 is subjected to parameter expansion, command substitution, and arithmetic
865 expansion before being interpreted as a pathname.
868 is not used to search for the resultant pathname.
871 If this parameter is set to a filename and the
876 informs the user of the arrival of mail in the specified file.
882 checks for mail. The default is 60 seconds. When it is time to check
883 for mail, the shell does so before prompting.
884 If this variable is unset, the shell disables mail checking.
887 A colon-separated list of pathnames to be checked for mail.
888 The message to be printed may be specified by separating the pathname from
889 the message with a `?'. $_ stands for the name of the current mailfile.
893 \fBMAILPATH\fP='/usr/spool/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"'
896 supplies a default value for this variable, but the location of the user
897 mail files that it uses is system dependent (e.g., /usr/spool/mail/\fB$USER\fP).
901 If set, and a file that \fBbash\fP is checking for mail has been
902 accessed since the last time it was checked, the message ``The mail in
903 \fImailfile\fP has been read'' is printed.
906 The value of this parameter is expanded (see
909 below) and used as the primary prompt string. The default value is
913 The value of this parameter is expanded
914 and used as the secondary prompt string. The default is
918 The value of this parameter is used as the prompt for the
926 The value of this parameter is expanded
927 and the value is printed before each command
929 displays during an execution trace. The first character of
932 is replicated multiple times, as necessary, to indicate multiple
933 levels of indirection. The default is ``\fB+ \fP''.
936 The number of commands to remember in the command history (see
939 below). The default value is 500.
942 The name of the file in which command history is saved. (See
945 below.) The default value is \fI~/.bash_history\fP. If unset, the
946 command history is not saved when an interactive shell exits.
949 The maximum number of lines contained in the history file. When this
950 variable is assigned a value, the history file is truncated, if
951 necessary, to contain no more than that number of lines. The default
955 If set to the value 1,
957 displays error messages generated by the
961 .B SHELL BUILTIN COMMANDS
965 is initialized to 1 each time the shell is invoked or a shell
969 If set, the value is executed as a command prior to issuing each primary
974 action of the shell on receipt of an
977 character as the sole input. If set, the value is the number of
981 characters typed as the first characters on an input line before
983 exits. If the variable exists but does not have a numeric value, or
984 has no value, the default value is 10. If it does not exist,
987 signifies the end of input to the shell. This is only in effect for
991 If set to a value greater than zero, the value is interpreted as the
992 number of seconds to wait for input after issuing the primary prompt.
994 terminates after waiting for that number of seconds if input does
998 The default editor for the
1003 A colon-separated list of suffixes to ignore when performing
1004 filename completion (see
1007 below). A filename whose suffix matches one of the entries in
1010 is excluded from the list of matched filenames. A sample
1014 The filename for the readline startup file, overriding the default
1025 reports terminated background jobs immediately, rather than waiting
1026 until before printing the next primary prompt (see also the
1037 If set to a value of
1039 lines which begin with a
1041 character are not entered on the history list. If set to
1044 lines matching the last history line are not entered.
1047 combines the two options.
1048 If unset, or if set to any other value than those above,
1050 by the parser are saved on the history list.
1052 .B command_oriented_history
1055 attempts to save all lines of a multiple\-line
1056 command in the same history entry. This allows
1057 easy re\-editing of multi\-line commands.
1059 .B glob_dot_filenames
1062 includes filenames beginning with a `.' in the results of pathname
1065 .B allow_null_glob_expansion
1068 allows pathname patterns which match no
1070 .B Pathname Expansion
1072 to expand to a null string, rather than themselves.
1075 The two or three characters which control history expansion
1076 and tokenization (see
1078 .B HISTORY EXPANSION
1079 below). The first character is the
1080 .IR "history expansion character" ,
1081 that is, the character which signals the start of a history
1082 expansion, normally `\fB!\fP'.
1083 The second character is the
1084 .IR "quick substitution"
1085 character, which is used as shorthand for re-running the previous
1086 command entered, substituting one string for another in the command.
1087 The default is `\fB^\fP'.
1088 The optional third character is the character
1089 which signifies that the remainder of the line is a comment, when found
1090 as the first character of a word, normally `\fB#\fP'. The history
1091 comment character causes history substitution to be skipped for the
1092 remaining words on the line. It does not necessarily cause the shell
1093 parser to treat the rest of the line as a comment.
1096 If set, the shell does not follow symbolic links when executing
1097 commands that change the current working directory. It uses the
1098 physical directory structure instead. By default,
1100 follows the logical chain of directories when performing commands
1101 which change the current directory, such as
1103 See also the description of the \fB\-P\fP option to the \fBset\fP
1106 .B SHELL BUILTIN COMMANDS
1110 .B hostname_completion_file
1114 Contains the name of a file in the same format as
1116 that should be read when the shell needs to complete a
1117 hostname. The file may be changed interactively; the next
1118 time hostname completion is attempted
1120 adds the contents of the new file to the already existing database.
1125 does not overwrite an existing file with the
1130 redirection operators. This variable may be overridden when
1131 creating output files by using the redirection operator
1135 (see also the \fB\-C\fP option to the
1140 This variable controls how the shell interacts with the user and
1141 job control. If this variable is set, single word simple
1142 commands without redirections are treated as candidates for resumption
1143 of an existing stopped job. There is no ambiguity allowed; if there is
1144 more than one job beginning with the string typed, the job most recently
1145 accessed is selected. The
1147 of a stopped job, in this context, is the command line used to
1151 the string supplied must match the name of a stopped job exactly;
1154 the string supplied needs to match a substring of the name of a
1157 value provides functionality analogous to the
1162 below). If set to any other value, the supplied string must
1163 be a prefix of a stopped job's name; this provides functionality
1168 .B no_exit_on_failed_exec
1169 If this variable exists, a non-interactive shell will not exit if
1170 it cannot execute the file specified in the
1172 builtin command. An interactive shell does not exit if
1177 If this is set, an argument to the
1179 builtin command that
1180 is not a directory is assumed to be the name of a variable whose
1181 value is the directory to change to.
1184 Expansion is performed on the command line after it has been split into
1185 words. There are seven kinds of expansion performed:
1186 .IR "brace expansion" ,
1187 .IR "tilde expansion" ,
1188 .IR "parameter and variable expansion" ,
1189 .IR "command substitution" ,
1190 .IR "arithmetic expansion" ,
1191 .IR "word splitting" ,
1193 .IR "pathname expansion" .
1195 The order of expansions is: brace expansion, tilde expansion,
1196 parameter, variable, command, and arithmetic substitution (done
1197 in a left\-to\-right fashion), word splitting, and pathname
1200 On systems that can support it, there is an additional expansion
1201 available: \fIprocess substitution\fP.
1203 Only brace expansion, word splitting, and pathname expansion
1204 can change the number of words of the expansion; other expansions
1205 expand a single word to a single word.
1206 The single exception to this is the expansion of
1207 ``\fB$@\fP'' as explained above (see
1212 .I "Brace expansion"
1213 is a mechanism by which arbitrary strings
1214 may be generated. This mechanism is similar to
1215 \fIpathname expansion\fP, but the filenames generated
1216 need not exist. Patterns to be brace expanded take
1217 the form of an optional
1219 followed by a series of comma-separated strings
1220 between a pair of braces, followed by an optional
1222 The preamble is prepended to each string contained
1223 within the braces, and the postamble is then appended
1224 to each resulting string, expanding left to right.
1226 Brace expansions may be nested. The results of each expanded
1227 string are not sorted; left to right order is preserved.
1228 For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'.
1230 Brace expansion is performed before any other expansions,
1231 and any characters special to other expansions are preserved
1232 in the result. It is strictly textual.
1234 does not apply any syntactic interpretation to the context of the
1235 expansion or the text between the braces.
1237 A correctly-formed brace expansion must contain unquoted opening
1238 and closing braces, and at least one unquoted comma.
1239 Any incorrectly formed brace expansion is left unchanged.
1241 This construct is typically used as shorthand when the common
1242 prefix of the strings to be generated is longer than in the
1246 mkdir /usr/local/src/bash/{old,new,dist,bugs}
1250 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
1253 Brace expansion introduces a slight incompatibility with
1254 traditional versions of
1258 does not treat opening or closing braces specially when they
1259 appear as part of a word, and preserves them in the output.
1261 removes braces from words as a consequence of brace
1262 expansion. For example, a word entered to
1265 appears identically in the output. The same word is
1270 If strict compatibility with
1275 .B \-nobraceexpansion
1280 or disable brace expansion with the
1286 .B SHELL BUILTIN COMMANDS
1290 If a word begins with a tilde character (`\fB~\fP'), all of the characters
1291 preceding the first slash (or all characters, if there is no slash)
1292 are treated as a possible \fIlogin name\fP. If this \fIlogin name\fP
1293 is the null string, the tilde is replaced with the value of the
1300 is unset, the home directory of
1301 the user executing the shell is substituted instead.
1303 If a `+' follows the tilde, the value of
1306 replaces the tilde and `+'. If
1307 a `\-' follows, the value of
1311 If the value following the tilde is a valid \fIlogin name\fP,
1312 the tilde and \fIlogin name\fP are replaced with the home directory
1313 associated with that name. If the name is invalid, or the tilde
1314 expansion fails, the word is unchanged.
1316 Each variable assignment is checked for unquoted
1317 instances of tildes following a
1321 In these cases, tilde substitution is also performed. Consequently, one
1322 may use pathnames with tildes in assignments to
1330 and the shell assigns the expanded value.
1331 .SS Parameter Expansion
1333 The `\fB$\fP' character introduces parameter expansion,
1334 command substitution, or arithmetic expansion. The parameter name
1335 or symbol to be expanded may be enclosed in braces, which
1336 are optional but serve to protect the variable to be expanded from
1337 characters immediately following it which could be
1338 interpreted as part of the name.
1343 The value of \fIparameter\fP is substituted. The braces are required
1346 is a positional parameter with more than one digit,
1349 is followed by a character which is not to be
1350 interpreted as part of its name.
1353 In each of the cases below, \fIword\fP is subject to tilde expansion,
1354 parameter expansion, command substitution, and arithmetic expansion.
1355 \fBBash\fP tests for a parameter that is unset or null; omitting the
1356 colon results in a test only for a parameter that is unset.
1360 ${\fIparameter\fP\fB:\-\fP\fIword\fP}
1361 \fBUse Default Values\fP. If
1363 is unset or null, the expansion of
1365 is substituted. Otherwise, the value of
1369 ${\fIparameter\fP\fB:=\fP\fIword\fP}
1370 \fBAssign Default Values\fP.
1373 is unset or null, the expansion of
1379 is then substituted. Positional parameters and special parameters may
1380 not be assigned to in this way.
1382 ${\fIparameter\fP\fB:?\fP\fIword\fP}
1383 \fBDisplay Error if Null or Unset\fP.
1386 is null or unset, the expansion of \fIword\fP (or a message to that effect
1389 is not present) is written to the standard error and the shell, if it
1390 is not interactive, exits. Otherwise, the value of \fIparameter\fP is
1393 ${\fIparameter\fP\fB:+\fP\fIword\fP}
1394 \fBUse Alternate Value\fP.
1397 is null or unset, nothing is substituted, otherwise the expansion of
1401 ${\fB#\fP\fIparameter\fP}
1402 The length in characters of the value of \fIparameter\fP is substituted.
1403 If \fIparameter\fP is
1407 the length substituted is the length of
1409 expanded within double quotes.
1412 ${\fIparameter\fP\fB#\fP\fIword\fP}
1414 ${\fIparameter\fP\fB##\fP\fIword\fP}
1418 is expanded to produce a pattern just as in pathname
1419 expansion. If the pattern matches the beginning of
1422 then the expansion is the value of
1424 with the shortest matching pattern deleted (the ``\fB#\fP''
1425 case) or the longest
1426 matching pattern deleted (the ``\fB##\fP'' case).
1429 ${\fIparameter\fP\fB%\fP\fIword\fP}
1431 ${\fIparameter\fP\fB%%\fP\fIword\fP}
1433 The \fIword\fP is expanded to produce a pattern just as in
1434 pathname expansion. If the pattern matches a
1435 trailing portion of the value of
1437 then the expansion is the value of
1439 with the shortest matching pattern deleted
1440 (the ``\fB%\fP'' case) or the longest
1441 matching pattern deleted (the ``\fB%%\fP'' case).
1442 .SS Command Substitution
1444 \fICommand substitution\fP allows the output of a command to replace
1445 the command name. There are two forms:
1449 \fB$(\fP\fIcommand\fP\|\fB)\fP
1453 \fB`\fP\fIcommand\fP\fB`\fP
1457 performs the expansion by executing \fIcommand\fP and
1458 replacing the command substitution with the standard output of the
1459 command, with any trailing newlines deleted.
1461 When the old\-style backquote form of substitution is used,
1462 backslash retains its literal meaning except when followed by
1467 When using the $(\^\fIcommand\fP\|) form, all characters between the
1468 parentheses make up the command; none are treated specially.
1470 Command substitutions may be nested. To nest when using the old form,
1471 escape the inner backquotes with backslashes.
1473 If the substitution appears within double quotes, word splitting and
1474 pathname expansion are not performed on the results.
1475 .SS Arithmetic Expansion
1477 Arithmetic expansion allows the evaluation of an arithmetic expression
1478 and the substitution of the result. There are two formats for
1479 arithmetic expansion:
1482 \fB$[\fP\fIexpression\fP\fB]\fP
1484 \fB$((\fP\fIexpression\fP\fB))\fP
1489 is treated as if it were within double quotes, but a double quote
1490 inside the braces or parentheses
1491 is not treated specially. All tokens in the
1492 expression undergo parameter expansion, command substitution,
1493 and quote removal. Arithmetic substitutions may be nested.
1495 The evaluation is performed according to the rules listed below under
1497 .BR "ARITHMETIC EVALUATION" .
1502 prints a message indicating failure and no substitution occurs.
1503 .SS Process Substitution
1505 \fIProcess substitution\fP is supported on systems that support named
1506 pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files.
1507 It takes the form of
1508 \fB<(\fP\fIlist\^\fP\fB)\fP
1510 \fB>(\fP\fIlist\^\fP\fB)\fP.
1511 The process \fIlist\fP is run with its input or output connected to a
1512 \fIFIFO\fP or some file in \fB/dev/fd\fP. The name of this file is
1513 passed as an argument to the current command as the result of the
1514 expansion. If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to
1515 the file will provide input for \fIlist\fP. If the
1516 \fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an
1517 argument should be read to obtain the output of \fIlist\fP.
1519 On systems that support it, \fIprocess substitution\fP is performed
1521 .IR "parameter and variable expansion" ,
1522 .IR "command substitution" ,
1524 .IR "arithmetic expansion" .
1527 The shell scans the results of
1528 parameter expansion,
1529 command substitution,
1531 arithmetic expansion
1532 that did not occur within double quotes for
1533 .IR "word splitting" .
1535 The shell treats each character of
1538 as a delimiter, and splits the results of the other
1539 expansions into words on these characters. If the
1544 .BR <space><tab><newline> ,
1549 characters serves to delimit words. If
1552 has a value other than the default, then sequences of
1553 the whitespace characters
1557 are ignored at the beginning and end of the
1558 word, as long as the whitespace character is in the
1565 whitespace character).
1572 whitespace, along with any adjacent
1575 whitespace characters, delimits a field.
1579 whitespace characters is also treated as a delimiter.
1583 is null, no word splitting occurs.
1588 Explicit null arguments (\^\f3"\^"\fP or \^\f3'\^'\fP\^)
1589 are retained. Implicit null arguments, resulting from the expansion
1592 that have no values, are removed.
1594 Note that if no expansion occurs, no splitting
1596 .SS Pathname Expansion
1598 After word splitting,
1601 option has been set,
1610 If one of these characters appears, then the word is
1613 and replaced with an alphabetically sorted list of
1614 pathnames matching the pattern.
1615 If no matching pathnames are found,
1616 and the shell variable
1617 .B allow_null_glob_expansion
1618 is unset, the word is left unchanged.
1619 If the variable is set, and no matches are found,
1620 the word is removed.
1621 When a pattern is used for pathname generation,
1624 at the start of a name or immediately following a slash
1625 must be matched explicitly, unless the shell variable
1626 .B glob_dot_filenames
1627 is set. The slash character must always be matched
1628 explicitly. In other cases, the
1630 character is not treated specially.
1632 The special pattern characters have the following meanings:
1637 Matches any string, including the null string.
1640 Matches any single character.
1643 Matches any one of the enclosed characters. A pair of characters
1644 separated by a minus sign denotes a
1646 any character lexically between those two characters, inclusive,
1647 is matched. If the first character following the
1653 then any character not enclosed is matched. A
1657 may be matched by including it as the first or last character
1662 After the preceding expansions, all unquoted occurrences of the
1666 and \^\f3"\fP\^ are removed.
1668 Before a command is executed, its input and output
1671 using a special notation interpreted by the shell.
1672 Redirection may also be used to open and close files for the
1673 current shell execution environment. The following redirection
1674 operators may precede or appear anywhere within a
1678 Redirections are processed in the order they appear, from
1681 In the following descriptions, if the file descriptor number is
1682 omitted, and the first character of the redirection operator is
1684 the redirection refers to the standard input (file descriptor
1685 0). If the first character of the redirection operator is
1687 the redirection refers to the standard output (file descriptor
1690 The word that follows the redirection operator in the following
1691 descriptions is subjected to brace expansion, tilde expansion,
1692 parameter expansion, command substitution, arithmetic expansion,
1693 quote removal, and pathname expansion. If it expands to more
1698 Note that the order of redirections is significant. For example,
1702 ls \fB>\fP dirlist 2\fB>&\fP1
1705 directs both standard output and standard error to the file
1710 ls 2\fB>&\fP1 \fB>\fP dirlist
1713 directs only the standard output to file
1715 because the standard error was duplicated as standard output
1716 before the standard output was redirected to
1718 .SS Redirecting Input
1720 Redirection of input causes the file whose name results from
1723 to be opened for reading on file descriptor
1725 or the standard input (file descriptor 0) if
1729 The general format for redirecting input is:
1732 [\fIn\fP]\fB<\fP\fIword\fP
1734 .SS Redirecting Output
1736 Redirection of output causes the file whose name results from
1739 to be opened for writing on file descriptor
1741 or the standard output (file descriptor 1) if
1743 is not specified. If the file does not exist it is created;
1744 if it does exist it is truncated to zero size.
1746 The general format for redirecting output is:
1749 [\fIn\fP]\fB>\fP\fIword\fP
1752 If the redirection operator is
1754 then the value of the
1758 builtin command is not tested, and file creation is attempted.
1759 (See also the description of
1762 .B "Shell Variables"
1764 .SS Appending Redirected Output
1766 Redirection of output in this fashion
1767 causes the file whose name results from
1770 to be opened for appending on file descriptor
1772 or the standard output (file descriptor 1) if
1774 is not specified. If the file does not exist it is created.
1776 The general format for appending output is:
1779 [\fIn\fP]\fB>>\fP\fIword\fP
1782 .SS Redirecting Standard Output and Standard Error
1786 standard output (file descriptor 1) and
1787 the standard error output (file descriptor 2)
1788 to be redirected to the file whose name is the
1791 with this construct.
1793 There are two formats for redirecting standard output and
1804 Of the two forms, the first is preferred.
1805 This is semantically equivalent to
1808 \fB>\fP\fIword\fP 2\fB>&\fP1
1812 This type of redirection instructs the shell to read input from the
1813 current source until a line containing only
1815 (with no trailing blanks)
1817 the lines read up to that point are then used as the standard
1818 input for a command.
1820 The format of here-documents is as follows:
1824 \fB<<\fP[\fB\-\fP]\fIword\fP
1830 No parameter expansion, command substitution, pathname
1831 expansion, or arithmetic expansion is performed on
1833 If any characters in
1837 is the result of quote removal on
1839 and the lines in the here-document are not expanded. Otherwise,
1840 all lines of the here-document are subjected to parameter expansion,
1841 command substitution, and arithmetic expansion. In the latter
1846 must be used to quote the characters
1852 If the redirection operator is
1854 then all leading tab characters are stripped from input lines and the
1858 here-documents within shell scripts to be indented in a
1860 .SS "Duplicating File Descriptors"
1862 The redirection operator
1865 [\fIn\fP]\fB<&\fP\fIword\fP
1868 is used to duplicate input file descriptors.
1871 expands to one or more digits, the file descriptor denoted by
1873 is made to be a copy of that file descriptor. If
1881 is not specified, the standard input (file descriptor 0) is used.
1886 [\fIn\fP]\fB>&\fP\fIword\fP
1889 is used similarly to duplicate output file descriptors. If
1891 is not specified, the standard output (file descriptor 1) is used.
1892 As a special case, if \fIn\fP is omitted, and \fIword\fP does not
1893 expand to one or more digits, the standard output and standard
1894 error are redirected as described previously.
1895 .SS "Opening File Descriptors for Reading and Writing"
1897 The redirection operator
1900 [\fIn\fP]\fB<>\fP\fIword\fP
1903 causes the file whose name is the expansion of
1905 to be opened for both reading and writing on file descriptor
1907 or as the standard input and standard output if
1909 is not specified. If the file does not exist, it is created.
1911 A shell function, defined as described above under
1913 .BR "SHELL GRAMMAR" ,
1914 stores a series of commands for later execution.
1915 Functions are executed in the context of the
1916 current shell; no new process is created to interpret
1917 them (contrast this with the execution of a shell script).
1918 When a function is executed, the arguments to the
1919 function become the positional parameters
1920 during its execution. The special parameter
1922 is updated to reflect the change. Positional parameter 0
1925 Variables local to the function may be declared with the
1927 builtin command. Ordinarily, variables and their values
1928 are shared between the function and its caller.
1930 If the builtin command
1932 is executed in a function, the function completes and
1933 execution resumes with the next command after the function
1934 call. When a function completes, the values of the
1935 positional parameters and the special parameter
1937 are restored to the values they had prior to function
1940 Function names and definitions may be listed with the
1946 builtin commands. Functions may be exported so that subshells
1947 automatically have them defined with the
1953 Functions may be recursive. No limit is imposed on the number
1956 The shell maintains a list of
1958 that may be set and unset with the
1962 builtin commands (see
1964 .B SHELL BUILTIN COMMANDS
1966 The first word of each command, if unquoted,
1967 is checked to see if it has an
1968 alias. If so, that word is replaced by the text of the alias.
1969 The alias name and the replacement text may contain any valid
1970 shell input, including the
1972 listed above, with the exception that the alias name may not
1973 contain \fI=\fP. The first word of the replacement text is tested
1974 for aliases, but a word that is identical to an alias being expanded
1975 is not expanded a second time. This means that one may alias
1981 does not try to recursively expand the replacement text.
1982 If the last character of the alias value is a
1984 then the next command
1985 word following the alias is also checked for alias expansion.
1987 Aliases are created and listed with the
1989 command, and removed with the
1993 There is no mechanism for using arguments in the replacement text,
1996 If arguments are needed, a shell function should be used.
1998 Aliases are not expanded when the shell is not interactive.
2000 The rules concerning the definition and use of aliases are
2003 always reads at least one complete line
2004 of input before executing any
2005 of the commands on that line. Aliases are expanded when a
2006 command is read, not when it is executed. Therefore, an
2007 alias definition appearing on the same line as another
2008 command does not take effect until the next line of input is read.
2009 This means that the commands following the alias definition
2010 on that line are not affected by the new alias.
2011 This behavior is also an issue when functions are executed.
2012 Aliases are expanded when the function definition is read,
2013 not when the function is executed, because a function definition
2014 is itself a compound command. As a consequence, aliases
2015 defined in a function are not available until after that
2016 function is executed. To be safe, always put
2017 alias definitions on a separate line, and do not use
2019 in compound commands.
2021 Note that for almost every purpose, aliases are superseded by
2025 refers to the ability to selectively stop (\fIsuspend\fP)
2026 the execution of processes and continue (\fIresume\fP)
2027 their execution at a later point. A user typically employs
2028 this facility via an interactive interface supplied jointly
2029 by the system's terminal driver and
2032 The shell associates a
2034 with each pipeline. It keeps a table of currently executing
2035 jobs, which may be listed with the
2039 starts a job asynchronously (in the
2041 it prints a line that looks like:
2047 indicating that this job is job number 1 and that the process ID
2048 of the last process in the pipeline associated with this job is 25647.
2049 All of the processes in a single pipeline are members of the same job.
2053 abstraction as the basis for job control.
2055 To facilitate the implementation of the user interface to job
2056 control, the system maintains the notion of a \fIcurrent terminal
2057 process group ID\fP. Members of this process group (processes whose
2058 process group ID is equal to the current terminal process group ID)
2059 receive keyboard-generated signals such as
2062 These processes are said to be in the
2065 processes are those whose process group ID differs from the terminal's;
2066 such processes are immune to keyboard-generated signals.
2067 Only foreground processes are allowed to read from or write to the
2068 terminal. Background processes which attempt to read from (write to) the
2071 .B SIGTTIN (SIGTTOU)
2072 signal by the terminal driver,
2073 which, unless caught, suspends the process.
2075 If the operating system on which
2080 allows you to use it.
2083 character (typically
2085 Control-Z) while a process is running
2086 causes that process to be stopped and returns you to
2089 .I "delayed suspend"
2090 character (typically
2092 Control-Y) causes the process to be stopped when it
2093 attempts to read input from the terminal, and control to
2096 You may then manipulate the state of this job, using the
2098 command to continue it in the background, the
2100 command to continue it in the foreground, or
2103 command to kill it. A \fB^Z\fP takes effect immediately,
2104 and has the additional side effect of causing pending output
2105 and typeahead to be discarded.
2107 There are a number of ways to refer to a job in the shell.
2110 introduces a job name. Job number
2112 may be referred to as
2114 A job may also be referred to using a prefix of the name used to
2115 start it, or using a substring that appears in its command line.
2120 job. If a prefix matches more than one job,
2122 reports an error. Using
2124 on the other hand, refers to any job containing the string
2126 in its command line. If the substring matches more than one job,
2128 reports an error. The symbols
2132 refer to the shell's notion of the
2134 which is the last job stopped while it was in
2138 may be referenced using
2140 In output pertaining to jobs (e.g., the output of the
2142 command), the current job is always flagged with a
2144 and the previous job with a
2147 Simply naming a job can be used to bring it into the
2152 bringing job 1 from the background into the foreground.
2155 resumes job 1 in the background, equivalent to
2158 The shell learns immediately whenever a job changes state.
2161 waits until it is about to print a prompt before reporting
2162 changes in a job's status so as to not interrupt
2163 any other output. If the
2170 reports such changes immediately. (See also the description of
2173 .B "Shell Variables"
2176 If you attempt to exit
2178 while jobs are stopped, the shell prints a message warning you. You
2181 command to inspect their status. If you do this, or try to exit
2182 again immediately, you are not warned again, and the stopped
2183 jobs are terminated.
2185 When \fBbash\fP is interactive, it ignores
2188 (so that \fBkill 0\fP does not kill an interactive shell),
2192 is caught and handled (so that the \fBwait\fP builtin is interruptible).
2193 In all cases, \fBbash\fP ignores
2196 If job control is in effect,
2207 Synchronous jobs started by \fBbash\fP have signals set to the
2208 values inherited by the shell from its parent. When job control
2209 is not in effect, background jobs (jobs started with
2217 Commands run as a result of command substitution ignore the
2218 keyboard-generated job control signals
2226 .SH "COMMAND EXECUTION"
2227 After a command has been split into words, if it results in a
2228 simple command and an optional list of arguments, the following
2231 If the command name contains no slashes, the shell attempts to
2232 locate it. If there exists a shell function by that name, that
2233 function is invoked as described above in
2236 If the name does not match a function, the shell searches for
2237 it in the list of shell builtins. If a match is found, that
2240 If the name is neither a shell function nor a builtin,
2241 and contains no slashes,
2243 searches each element of the
2246 for a directory containing an executable file by that name.
2247 If the search is unsuccessful, the shell prints an error
2248 message and returns a nonzero exit status.
2250 If the search is successful, or if the command name contains
2251 one or more slashes, the shell executes the named program.
2252 Argument 0 is set to the name given, and the remaining arguments
2253 to the command are set to the arguments given, if any.
2255 If this execution fails because the file is not in executable
2256 format, and the file is not a directory, it is assumed to be
2257 a \fIshell script\fP, a file
2258 containing shell commands. A subshell is spawned to execute
2259 it. This subshell reinitializes itself, so
2260 that the effect is as if a new shell had been invoked
2261 to handle the script, with the exception that the locations of
2262 commands remembered by the parent (see
2266 \fBSHELL BUILTIN COMMANDS\fP)
2267 are retained by the child.
2269 If the program is a file beginning with
2271 the remainder of the first line specifies an interpreter
2272 for the program. The shell executes the
2273 specified interpreter on operating systems that do not
2274 handle this executable format themselves. The arguments to the
2275 interpreter consist of a single optional argument following the
2276 interpreter name on the first line of the program, followed
2277 by the name of the program, followed by the command
2280 When a program is invoked it is given an array of strings
2284 \fIname\fP\-\fIvalue\fP pairs, of the form
2285 .IR "name\fR=\fPvalue" .
2287 The shell allows you to manipulate the environment in several
2288 ways. On invocation, the shell scans its own environment and
2289 creates a parameter for each name found, automatically marking
2292 to child processes. Executed commands inherit the environment.
2297 commands allow parameters and functions to be added to and
2298 deleted from the environment. If the value of a parameter
2299 in the environment is modified, the new value becomes part
2300 of the environment, replacing the old. The environment
2301 inherited by any executed command consists of the shell's
2302 initial environment, whose values may be modified in the shell,
2303 less any pairs removed by the
2305 command, plus any additions via the
2311 The environment for any
2313 or function may be augmented temporarily by prefixing it with
2314 parameter assignments, as described above in
2317 These assignment statements affect only the environment seen
2322 flag is set (see the
2324 builtin command below), then
2326 parameter assignments are placed in the environment for a command,
2327 not just those that precede the command name.
2331 invokes an external command, the variable
2333 is set to the full path name of the command and passed to that
2334 command in its environment.
2336 For the purposes of the shell, a command which exits with a
2337 zero exit status has succeeded. An exit status of zero
2338 indicates success. A non\-zero exit status indicates failure.
2339 When a command terminates on a fatal signal, \fBbash\fP uses
2340 the value of 128+\fBsignal\fP as the exit status.
2342 If a command is not found, the child process created to
2343 execute it returns a status of 127. If a command is found
2344 but is not executable, the return status is 126.
2346 \fBBash\fP itself returns the exit status of the last command
2347 executed, unless a syntax error occurs, in which case it exits
2348 with a non\-zero value. See also the \fBexit\fP builtin
2351 When executing interactively,
2353 displays the primary prompt
2356 when it is ready to read a command, and the secondary prompt
2359 when it needs more input to complete a command.
2361 allows these prompt strings to be customized by inserting a number of
2362 backslash-escaped special characters that are decoded as follows:
2367 the current time in HH:MM:SS format
2370 the date in "Weekday Month Date" format (e.g., "Tue May 26")
2376 the name of the shell, the basename of
2378 (the portion following the final slash)
2381 the current working directory
2384 the basename of the current working directory
2387 the username of the current user
2393 the command number of this command
2396 the history number of this command
2399 if the effective UID is 0, a
2405 the character corresponding to the octal number \fBnnn\fP
2411 begin a sequence of non-printing characters, which could be used to
2412 embed a terminal control sequence into the prompt
2415 end a sequence of non-printing characters
2419 The command number and the history number are usually different:
2420 the history number of a command is its position in the history
2421 list, which may include commands restored from the history file
2425 below), while the command number is the position in the sequence
2426 of commands executed during the current shell session.
2427 After the string is decoded, it is expanded via
2428 parameter expansion,
2429 command substitution, arithmetic expansion, and word splitting.
2431 This is the library that handles reading input when using an interactive
2434 option is given. By default, the line editing commands
2435 are similar to those of emacs.
2436 A vi-style line editing interface is also available.
2438 In this section, the emacs-style notation is used to denote
2439 keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
2440 means Control\-N. Similarly,
2442 keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards
2445 key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
2448 key. This makes ESC the \fImeta prefix\fP.
2449 The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP,
2450 or press the Escape key
2451 then hold the Control key while pressing the
2455 The default key-bindings may be changed with an
2457 file. The value of the shell variable
2460 if set, is used instead of
2462 Other programs that use this library may add their own commands
2465 For example, placing
2468 M\-Control\-u: universal\-argument
2472 C\-Meta\-u: universal\-argument
2476 would make M\-C\-u execute the readline command
2477 .IR universal\-argument .
2479 The following symbolic character names are recognized:
2491 In addition to command names, readline allows keys to be bound
2492 to a string that is inserted when the key is pressed (a \fImacro\fP).
2494 Readline is customized by putting commands in an initialization
2495 file. The name of this file is taken from the value of the
2498 variable. If that variable is unset, the default is
2500 When a program which uses the readline library starts up, the
2501 init file is read, and the key bindings and variables are set.
2502 There are only a few basic constructs allowed in the
2503 readline init file. Blank lines are ignored.
2504 Lines beginning with a \fB#\fP are comments.
2505 Lines beginning with a \fB$\fP indicate conditional
2506 constructs. Other lines
2507 denote key bindings and variable settings.
2509 The syntax for controlling key bindings in the
2511 file is simple. All that is required is the name of the
2512 command or the text of a macro and a key sequence to which
2513 it should be bound. The name may be specified in one of two ways:
2514 as a symbolic key name, possibly with \fIMeta-\fP or \fIControl-\fP
2515 prefixes, or as a key sequence.
2516 When using the form \fBkeyname\fP:\fIfunction-name\fP or \fImacro\fP,
2518 is the name of a key spelled out in English. For example:
2521 Control-u: universal\-argument
2523 Meta-Rubout: backward-kill-word
2525 Control-o: ">&output"
2528 In the above example,
2530 is bound to the function
2531 .BR universal\-argument ,
2533 is bound to the function
2534 .BR backward\-kill\-word ,
2537 is bound to run the macro
2538 expressed on the right hand side (that is, to insert the text
2542 In the second form, \fB"keyseq"\fP:\fIfunction-name\fP or \fImacro\fP,
2546 above in that strings denoting
2547 an entire key sequence may be specified by placing the sequence
2548 within double quotes. Some GNU Emacs style key escapes can be
2549 used, as in the following example.
2552 "\eC-u": universal\-argument
2554 "\eC-x\eC-r": re\-read\-init\-file
2556 "\ee[11~": "Function Key 1"
2561 is again bound to the function
2562 .BR universal\-argument .
2564 is bound to the function
2565 .BR re\-read\-init\-file ,
2568 is bound to insert the text
2569 .BR "Function Key 1" .
2570 The full set of escape sequences is
2592 When entering the text of a macro, single or double quotes should
2593 be used to indicate a macro definition. Unquoted text
2594 is assumed to be a function name. Backslash
2595 will quote any character in the macro text, including " and '.
2598 allows the current readline key bindings to be displayed or modified
2601 builtin command. The editing mode may be switched during interactive
2606 builtin command (see
2608 .B SHELL BUILTIN COMMANDS
2611 Readline has variables that can be used to further customize its
2612 behavior. A variable may be set in the
2614 file with a statement of the form
2617 \fBset\fP \fIvariable\-name\fP \fIvalue\fP
2620 Except where noted, readline variables can take the values
2624 The variables and their default values are:
2628 .B horizontal\-scroll\-mode (Off)
2629 When set to \fBOn\fP, makes readline use a single line for display,
2630 scrolling the input horizontally on a single screen line when it
2631 becomes longer than the screen width rather than wrapping to a new line.
2633 .B editing\-mode (emacs)
2634 Controls whether readline begins with a set of key bindings similar
2635 to \fIemacs\fP or \fIvi\fP.
2637 can be set to either
2642 .B mark\-modified\-lines (Off)
2643 If set to \fBOn\fP, history lines that have been modified are displayed
2644 with a preceding asterisk (\fB*\fP).
2646 .B bell\-style (audible)
2647 Controls what happens when readline wants to ring the terminal bell.
2648 If set to \fBnone\fP, readline never rings the bell. If set to
2649 \fBvisible\fP, readline uses a visible bell if one is available.
2650 If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
2652 .B comment\-begin (``#'')
2653 The string that is inserted in \fBvi\fP mode when the
2655 command is executed.
2658 If set to \fBOn\fP, readline will enable eight-bit input (that is,
2659 it will not strip the high bit from the characters it reads),
2660 regardless of what the terminal claims it can support.
2662 .B convert\-meta (On)
2663 If set to \fBOn\fP, readline will convert characters with the
2664 eighth bit set to an ASCII key sequence
2665 by stripping the eighth bit and prepending an
2666 escape character (in effect, using escape as the \fImeta prefix\fP).
2668 .B output\-meta (Off)
2669 If set to \fBOn\fP, readline will display characters with the
2670 eighth bit set directly rather than as a meta-prefixed escape
2673 .B completion\-query\-items (100)
2674 This determines when the user is queried about viewing
2675 the number of possible completions
2676 generated by the \fBpossible\-completions\fP command.
2677 It may be set to any integer value greater than or equal to
2678 zero. If the number of possible completions is greater than
2679 or equal to the value of this variable, the user is asked whether
2680 or not he wishes to view them; otherwise they are simply listed
2684 Set the current readline keymap. The set of legal keymap names is
2685 \fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
2688 \fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is
2689 equivalent to \fIemacs-standard\fP. The default value is
2693 also affects the default keymap.
2695 .B show\-all\-if\-ambiguous (Off)
2696 This alters the default behavior of the completion functions. If
2699 words which have more than one possible completion cause the
2700 matches to be listed immediately instead of ringing the bell.
2702 .B expand\-tilde (Off)
2703 If set to \fBon\fP, tilde expansion is performed when readline
2704 attempts word completion.
2707 Readline implements a facility similar in spirit to the conditional
2708 compilation features of the C preprocessor which allows key
2709 bindings and variable settings to be performed as the result
2710 of tests. There are three parser directives used.
2714 construct allows bindings to be made based on the
2715 editing mode, the terminal being used, or the application using
2716 readline. The text of the test extends to the end of the line;
2717 no characters are required to isolate it.
2720 The \fBmode=\fP form of the \fB$if\fP directive is used to test
2721 whether readline is in emacs or vi mode.
2722 This may be used in conjunction
2723 with the \fBset keymap\fP command, for instance, to set bindings in
2724 the \fIemacs-standard\fP and \fIemacs-ctlx\fP keymaps only if
2725 readline is starting out in emacs mode.
2727 The \fBterm=\fP form may be used to include terminal-specific
2728 key bindings, perhaps to bind the key sequences output by the
2729 terminal's function keys. The word on the right side of the
2731 is tested against the full name of the terminal and the portion
2732 of the terminal name before the first \fB\-\fP. This allows
2739 .IP \fBapplication\fP
2740 The \fBapplication\fP construct is used to include
2741 application\-specific settings. Each program using the readline
2742 library sets the \fIapplication name\fP, and an initialization
2743 file can test for a particular value.
2744 This could be used to bind key sequences to functions useful for
2745 a specific program. For instance, the following command adds a
2746 key sequence that quotes the current or previous word in Bash:
2750 # Quote the current or previous word
2751 "\eC-xq": "\eeb\e"\eef\e""
2757 This command, as you saw in the previous example, terminates an
2760 Commands in this branch of the \fB$if\fP directive are executed if
2763 Readline commands may be given numeric
2765 which normally act as a repeat count. Sometimes, however, it is the
2766 sign of the argument that is significant. Passing a negative argument
2767 to a command that acts in the forward direction (e.g., \fBkill\-line\fP)
2768 causes that command to act in a backward direction. Commands whose
2769 behavior with arguments deviates from this are noted.
2771 When a command is described as \fIkilling\fP text, the text
2772 deleted is saved for possible future retrieval
2773 (\fIyanking\fP). The killed text is saved in a
2774 \fIkill\-ring\fP. Consecutive kills cause the text to be
2775 accumulated into one unit, which can be yanked all at once.
2776 Commands which do not kill text separate the chunks of text
2779 The following is a list of the names of the commands and the default
2780 key sequences to which they are bound.
2781 .SS Commands for Moving
2785 .B beginning\-of\-line (C\-a)
2786 Move to the start of the current line.
2788 .B end\-of\-line (C\-e)
2789 Move to the end of the line.
2791 .B forward\-char (C\-f)
2792 Move forward a character.
2794 .B backward\-char (C\-b)
2795 Move back a character.
2797 .B forward\-word (M\-f)
2798 Move forward to the end of the next word. Words are composed of
2799 alphanumeric characters (letters and digits).
2801 .B backward\-word (M\-b)
2802 Move back to the start of this, or the previous, word. Words are
2803 composed of alphanumeric characters (letters and digits).
2805 .B clear\-screen (C\-l)
2806 Clear the screen leaving the current line at the top of the screen.
2807 With an argument, refresh the current line without clearing the
2810 .B redraw\-current\-line
2811 Refresh the current line. By default, this is unbound.
2813 .SS Commands for Manipulating the History
2817 .B accept\-line (Newline, Return)
2818 Accept the line regardless of where the cursor is. If this line is
2819 non\-empty, add it to the history list according to the state of the
2822 variable. If the line is a modified history
2823 line, then restore the history line to its original state.
2825 .B previous\-history (C\-p)
2826 Fetch the previous command from the history list, moving back in
2829 .B next\-history (C\-n)
2830 Fetch the next command from the history list, moving forward in the
2833 .B beginning\-of\-history (M\-<)
2834 Move to the first line in the history.
2836 .B end\-of\-history (M\->)
2837 Move to the end of the input history, i.e., the line currently being
2840 .B reverse\-search\-history (C\-r)
2841 Search backward starting at the current line and moving `up' through
2842 the history as necessary. This is an incremental search.
2844 .B forward\-search\-history (C\-s)
2845 Search forward starting at the current line and moving `down' through
2846 the history as necessary. This is an incremental search.
2848 .B non\-incremental\-reverse\-search\-history (M\-p)
2849 Search backward through the history starting at the current line
2850 using a non\-incremental search for a string supplied by the user.
2852 .B non\-incremental\-forward\-search\-history (M\-n)
2853 Search forward through the history using a non\-incremental search for
2854 a string supplied by the user.
2856 .B history\-search\-forward
2857 Search forward through the history for the string of characters
2858 between the start of the current line and the current point. This
2859 is a non-incremental search. By default, this command is unbound.
2861 .B history\-search\-backward
2862 Search backward through the history for the string of characters
2863 between the start of the current line and the current point. This
2864 is a non-incremental search. By default, this command is unbound.
2866 .B yank\-nth\-arg (M\-C\-y)
2867 Insert the first argument to the previous command (usually
2868 the second word on the previous line) at point (the current
2869 cursor position). With an argument
2871 insert the \fIn\fPth word from the previous command (the words
2872 in the previous command begin with word 0). A negative argument
2873 inserts the \fIn\fPth word from the end of the previous command.
2876 yank\-last\-arg (M\-.\^, M\-_\^)
2877 Insert the last argument to the previous command (the last word on
2878 the previous line). With an argument,
2879 behave exactly like \fByank-nth-arg\fP.
2881 .B shell\-expand\-line (M\-C\-e)
2882 Expand the line the way the shell does when it reads it. This
2883 performs alias and history expansion as well as all of the shell
2884 word expansions. See
2886 .B HISTORY EXPANSION
2887 below for a description of history expansion.
2889 .B history\-expand\-line (M\-^)
2890 Perform history expansion on the current line. See
2892 .B HISTORY EXPANSION
2893 below for a description of history expansion.
2895 .B insert\-last\-argument (M\-.\^, M\-_\^)
2896 A synonym for \fByank\-last\-arg\fP.
2898 .B operate-and-get-next (C\-o)
2899 Accept the current line for execution and fetch the next line
2900 relative to the current line from the history for editing. Any
2901 argument is ignored.
2903 .SS Commands for Changing Text
2907 .B delete\-char (C\-d)
2908 Delete the character under the cursor. If point is at the
2909 beginning of the line, there are no characters in the line, and
2910 the last character typed was not
2916 .B backward\-delete\-char (Rubout)
2917 Delete the character behind the cursor. When given a numeric argument,
2918 save the deleted text on the kill\-ring.
2920 .B quoted\-insert (C\-q, C\-v)
2921 Add the next character that you type to the line verbatim. This is
2922 how to insert characters like \fBC\-q\fP, for example.
2924 .B tab\-insert (C-v TAB)
2925 Insert a tab character.
2927 .B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
2928 Insert the character typed.
2930 .B transpose\-chars (C\-t)
2931 Drag the character before point forward over the character at point.
2932 Point moves forward as well. If point is at the end of the line, then
2933 transpose the two characters before point. Negative arguments don't work.
2935 .B transpose\-words (M\-t)
2936 Drag the word behind the cursor past the word in front of the cursor
2937 moving the cursor over that word as well.
2939 .B upcase\-word (M\-u)
2940 Uppercase the current (or following) word. With a negative argument,
2941 do the previous word, but do not move point.
2943 .B downcase\-word (M\-l)
2944 Lowercase the current (or following) word. With a negative argument,
2945 do the previous word, but do not move point.
2947 .B capitalize\-word (M\-c)
2948 Capitalize the current (or following) word. With a negative argument,
2949 do the previous word, but do not move point.
2951 .SS Killing and Yanking
2955 .B kill\-line (C\-k)
2956 Kill the text from the current cursor position to the end of the line.
2958 .B backward\-kill\-line (C\-x C\-Rubout)
2959 Kill backward to the beginning of the line.
2961 .B unix\-line\-discard (C\-u)
2962 Kill backward from point to the beginning of the line.
2963 .\" There is no real difference between this and backward-kill-line
2965 .B kill\-whole\-line
2966 Kill all characters on the current line, no matter where the
2967 cursor is. By default, this is unbound.
2969 .B kill\-word (M\-d)
2970 Kill from the cursor to the end of the current word, or if between
2971 words, to the end of the next word. Word boundaries are the same as
2972 those used by \fBforward\-word\fP.
2974 .B backward\-kill\-word (M\-Rubout)
2975 Kill the word behind the cursor. Word boundaries are the same as
2976 those used by \fBbackward\-word\fP.
2978 .B unix\-word\-rubout (C\-w)
2979 Kill the word behind the cursor, using white space as a word boundary.
2980 The word boundaries are different from backward\-kill\-word.
2982 .B delete\-horizontal\-space
2983 Delete all spaces and tabs around point. By default, this is unbound.
2986 Yank the top of the kill ring into the buffer at the cursor.
2989 Rotate the kill\-ring, and yank the new top. Only works following
2994 .SS Numeric Arguments
2998 .B digit\-argument (M\-0, M\-1, ..., M\-\-)
2999 Add this digit to the argument already accumulating, or start a new
3000 argument. M\-\- starts a negative argument.
3002 .B universal\-argument
3003 Each time this is executed, the argument count is multiplied by four.
3004 The argument count is initially one, so executing this function the
3005 first time makes the argument count four. By default, this is not
3013 Attempt to perform completion on the text before point.
3015 attempts completion treating the text as a variable (if the
3016 text begins with \fB$\fP), username (if the text begins with
3017 \fB~\fP), hostname (if the text begins with \fB@\fP), or
3018 command (including aliases and functions) in turn. If none
3019 of these produces a match, filename completion is attempted.
3021 .B possible\-completions (M-?)
3022 List the possible completions of the text before point.
3024 .B insert\-completions
3025 Insert all completions of the text before point
3026 that would have been generated by
3027 \fBpossible\-completions\fP. By default, this
3028 is not bound to a key.
3030 .B complete\-filename (M\-/)
3031 Attempt filename completion on the text before point.
3033 .B possible\-filename\-completions (C\-x /)
3034 List the possible completions of the text before point,
3035 treating it as a filename.
3037 .B complete\-username (M\-~)
3038 Attempt completion on the text before point, treating
3041 .B possible\-username\-completions (C\-x ~)
3042 List the possible completions of the text before point,
3043 treating it as a username.
3045 .B complete\-variable (M\-$)
3046 Attempt completion on the text before point, treating
3047 it as a shell variable.
3049 .B possible\-variable\-completions (C\-x $)
3050 List the possible completions of the text before point,
3051 treating it as a shell variable.
3053 .B complete\-hostname (M\-@)
3054 Attempt completion on the text before point, treating
3057 .B possible\-hostname\-completions (C\-x @)
3058 List the possible completions of the text before point,
3059 treating it as a hostname.
3061 .B complete\-command (M\-!)
3062 Attempt completion on the text before point, treating
3063 it as a command name. Command completion attempts to
3064 match the text against aliases, reserved words, shell
3065 functions, builtins, and finally executable filenames,
3068 .B possible\-command\-completions (C\-x !)
3069 List the possible completions of the text before point,
3070 treating it as a command name.
3072 .B dynamic\-complete\-history (M-TAB)
3073 Attempt completion on the text before point, comparing
3074 the text against lines from the history list for possible
3077 .B complete\-into\-braces (M\-{)
3078 Perform filename completion and return the list of possible completions
3079 enclosed within braces so the list is available to the shell (see
3087 .B start\-kbd\-macro (C-x (\^)
3088 Begin saving the characters typed into the current keyboard macro.
3090 .B end\-kbd\-macro (C-x )\^)
3091 Stop saving the characters typed into the current keyboard macro
3092 and save the definition.
3094 .B call\-last\-kbd\-macro (C-x e)
3095 Re-execute the last keyboard macro defined, by making the characters
3096 in the macro appear as if typed at the keyboard.
3102 .B re\-read\-init\-file (C\-x C\-r)
3103 Read in the contents of your init file, and incorporate
3104 any bindings or variable assignments found there.
3107 Abort the current editing command and
3108 ring the terminal's bell (subject to the setting of
3111 .B do\-uppercase\-version (M\-a, M\-b, ...)
3112 Run the command that is bound to the corresponding uppercase
3115 .B prefix\-meta (ESC)
3116 Metafy the next character typed.
3123 .B undo (C\-_, C\-x C\-u)
3124 Incremental undo, separately remembered for each line.
3126 .B revert\-line (M\-r)
3127 Undo all changes made to this line. This is like typing the
3129 command enough times to return the line to its initial state.
3131 .B tilde\-expand (M\-~)
3132 Perform tilde expansion on the current word.
3135 Print all of the functions and their key bindings to the
3136 readline output stream. If a numeric argument is supplied,
3137 the output is formatted in such a way that it can be made part
3138 of an \fIinputrc\fP file.
3140 .B display\-shell\-version (C\-x C\-v)
3141 Display version information about the current instance of
3145 When interactive, the shell provides access to the \fIcommand history\fP,
3146 the list of commands previously typed. The text of the last
3149 commands (default 500) is saved in a history list. The shell
3150 stores each command in the history list prior to parameter and
3151 variable expansion (see
3154 above) but after history expansion is performed, subject to the
3155 values of the shell variables
3156 .B command_oriented_history
3160 On startup, the history is initialized from the file named by
3164 (default \fI~/.bash_history\fP).
3167 is truncated, if necessary, to contain no more than
3175 .B SHELL BUILTIN COMMANDS
3176 below) may be used to list or edit and re-execute a portion of
3180 builtin can be used to display the history list and manipulate the
3181 history file. When using the command-line editing, search commands
3182 are available in each editing mode that provide access to the
3183 history list. When an interactive shell exits, the last
3186 lines are copied from the history list to
3192 is unset, or if the history file is unwritable, the history is
3194 .SH "HISTORY EXPANSION"
3196 The shell supports a history expansion feature that
3197 is similar to the history expansion in
3199 This section describes what syntax features are available. This
3200 feature is enabled by default for interactive shells, and can be
3205 builtin command (see
3207 .B SHELL BUILTIN COMMANDS
3208 below). Non-interactive shells do not perform history expansion.
3210 History expansion is performed immediately after a complete line
3211 is read, before the shell breaks it into words.
3212 It takes place in two parts. The first is to determine
3213 which line from the previous history to use during
3214 substitution. The second is to select portions of that line for
3215 inclusion into the current one. The line selected from the
3216 previous history is the \fIevent\fP, and the portions of that
3217 line that are acted upon are \fIwords\fP. The line is broken
3218 into words in the same fashion as when reading input, so that
3219 several \fImetacharacter\fP\-separated words surrounded by quotes
3220 are considered as one word. Only backslash (\^\fB\e\fP\^)
3221 and single quotes can quote
3222 the history escape character, which is \^\fB!\fP\^ by default.
3224 The shell allows control of the various characters used by the
3225 history expansion mechanism (see the description of
3228 .BR "Shell Variables" ).
3229 .SS Event Designators
3231 An event designator is a reference to a command line entry in the
3237 Start a history substitution, except when followed by a
3242 Refer to the previous command. This is a synonym for `!\-1'.
3245 Refer to command line
3249 Refer to the current command line minus
3253 Refer to the most recent command starting with
3256 .B !?\fIstring\fR\fB[?]\fR
3257 Refer to the most recent command containing
3260 .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u
3261 Quick substitution. Repeat the last command, replacing
3266 ``!!:s/\fIstring1\fP/\fIstring2\fP/''
3267 (see \fBModifiers\fP below).
3270 The entire command line typed so far.
3272 .SS Word Designators
3276 separates the event specification from the word
3277 designator. It can be omitted if the word designator begins with a
3283 Words are numbered from the beginning of the line,
3284 with the first word being denoted by a 0 (zero).
3289 The zeroth word. For the shell, this is the command
3296 The first argument. That is, word 1.
3302 The word matched by the most recent `?\fIstring\fR?' search.
3305 A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'.
3308 All of the words but the zeroth. This is a synonym
3309 for `\fI1\-$\fP'. It is not an error to use
3311 if there is just one
3312 word in the event; the empty string is returned in that case.
3315 Abbreviates \fIx\-$\fP.
3318 Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word.
3322 After the optional word designator, you can add a sequence of one
3323 or more of the following modifiers, each preceded by a `:'.
3329 Remove a trailing pathname component, leaving only the head.
3332 Remove a trailing suffix of the form \fI.xxx\fP, leaving the
3336 Remove all but the trailing suffix.
3339 Remove all leading pathname components, leaving the tail.
3342 Print the new command but do not execute it.
3345 Quote the substituted words, escaping further substitutions.
3348 Quote the substituted words as with
3350 but break into words at
3354 .B s/\fIold\fP/\fInew\fP/
3357 for the first occurrence of
3359 in the event line. Any delimiter can be used in place of /. The
3360 final delimiter is optional if it is the last character of the
3361 event line. The delimiter may be quoted in
3365 with a single backslash. If & appears in
3369 A single backslash will quote the &.
3372 Repeat the previous substitution.
3375 Cause changes to be applied over the entire event line. This is
3376 used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')
3377 or `\fB:&\fP'. If used with
3378 `\fB:s\fP', any delimiter can be used
3379 in place of /, and the final delimiter is optional
3380 if it is the last character of the event line.
3382 .SH "ARITHMETIC EVALUATION"
3383 The shell allows arithmetic expressions to be evaluated, under
3384 certain circumstances (see the \fBlet\fP builtin command and
3385 \fBArithmetic Expansion\fP).
3387 is done in long integers with no check for overflow, though division
3388 by 0 is trapped and flagged as an error. The following list of
3389 operators is grouped into levels of equal-precedence operators.
3390 The levels are listed in order of decreasing precedence.
3395 unary minus and plus
3398 logical and bitwise negation
3401 multiplication, division, remainder
3404 addition, subtraction
3407 left and right bitwise shifts
3413 equality and inequality
3419 bitwise exclusive OR
3430 .B = *= /= %= += \-= <<= >>= &= ^= |=
3434 Shell variables are allowed as operands; parameter expansion is
3435 performed before the expression is evaluated.
3436 The value of a parameter is coerced to a long integer within
3437 an expression. A shell variable need not have its integer attribute
3438 turned on to be used in an expression.
3440 Constants with a leading 0 are interpreted as octal numbers.
3441 A leading \fI0x\fP or \fI0X\fP denotes hexadecimal. Otherwise,
3442 numbers take the form [\fIbase#\fP]n, where \fIbase\fP is a
3443 decimal number between 2 and 36 representing the arithmetic
3444 base, and \fIn\fP is a number in that base. If \fIbase\fP is
3445 omitted, then base 10 is used.
3447 Operators are evaluated in order of precedence. Sub-expressions in
3448 parentheses are evaluated first and may override the precedence
3450 .SH "SHELL BUILTIN COMMANDS"
3451 .\" start of bash_builtins
3455 \fB:\fP [\fIarguments\fP]
3457 No effect; the command does nothing beyond expanding
3459 and performing any specified
3460 redirections. A zero exit code is returned.
3463 \fB .\| \fP \fIfilename\fP [\fIarguments\fP]
3465 \fBsource\fP \fIfilename\fP [\fIarguments\fP]
3467 Read and execute commands from
3470 shell environment and return the exit status of the last command
3475 does not contain a slash, pathnames in
3478 are used to find the directory containing
3480 The file searched for in
3483 need not be executable. The current directory is
3484 searched if no file is found in
3487 If any \fIarguments\fP are supplied, they become the positional
3488 parameters when \fIfile\fP is executed. Otherwise the positional
3489 parameters are unchanged.
3490 The return status is the status of the last command exited within
3491 the script (0 if no commands are executed), and false if
3495 \fBalias\fP [\fIname\fP[=\fIvalue\fP] ...]
3496 \fBAlias\fP with no arguments prints the list of aliases in the form
3497 \fIname\fP=\fIvalue\fP on standard output. When arguments are
3498 supplied, an alias is defined for
3500 whose \fIvalue\fP is given. A trailing space in
3501 \fIvalue\fP causes the next
3502 word to be checked for alias substitution when the alias is
3503 expanded. For each \fIname\fP in the argument list for which
3504 no \fIvalue\fP is supplied, the name and value of the alias is
3505 printed. \fBAlias\fP returns true
3506 unless a \fIname\fP is given for which no alias has been defined.
3508 \fBbg\fP [\fIjobspec\fP]
3509 Place \fIjobspec\fP in the background, as if it had been started with
3511 If \fIjobspec\fP is not present, the shell's notion of the
3512 \fIcurrent job\fP is used.
3515 returns 0 unless run when job control is disabled or, when run with
3516 job control enabled, if \fIjobspec\fP was not found or started without
3520 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lvd\fP] [\fB-q\fP \fIname\fP]
3522 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB-f\fP \fIfilename\fP
3524 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction-name\fP
3528 key and function bindings, or bind a key sequence to a
3530 function or macro. The binding syntax accepted is identical to that of
3532 but each binding must be passed as a separate argument;
3533 e.g., '"\eC-x\eC-r": re\-read\-init\-file'. Options, if supplied, have the
3541 as the keymap to be affected by the subsequent bindings.
3545 \fIemacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move,
3548 \fIvi\fP is equivalent to \fIvi-command\fP; \fIemacs\fP is
3549 equivalent to \fIemacs-standard\fP.
3552 List the names of all \fBreadline\fP functions
3555 List current function names and bindings
3558 Dump function names and bindings in such a way that they can be re-read
3560 .B \-f \fIfilename\fP
3561 Read key bindings from \fIfilename\fP
3563 .B \-q \fIfunction\fP
3564 Query about which keys invoke the named \fIfunction\fP
3567 The return value is 0 unless an unrecognized option is given or an
3571 \fBbreak\fP [\fIn\fP]
3577 loop. If \fIn\fP is specified, break \fIn\fP levels.
3581 is greater than the number of enclosing loops, all enclosing loops
3582 are exited. The return value is 0 unless the shell is not executing
3587 \fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP]
3588 Execute the specified shell builtin, passing it
3590 and return its exit status.
3591 This is useful when you wish to define a
3592 function whose name is the same as a shell builtin,
3593 but need the functionality of the
3594 builtin within the function itself. The \fBcd\fP builtin is
3595 commonly redefined this way. The return status is false if
3597 is not a shell builtin command.
3599 \fBcd\fP [\fIdir\fP]
3600 Change the current directory to \fIdir\fP. The variable
3609 defines the search path for
3610 the directory containing
3612 Alternative directory names are
3613 separated by a colon (:). A null directory name in
3617 the current directory, i.e., ``\fB.\fP''. If
3619 begins with a slash (/),
3623 is not used. An argument of
3628 The return value is true if the directory was successfully changed;
3631 \fBcommand\fP [\fB-pVv\fP] \fIcommand\fP [\fIarg\fP ...]
3636 suppressing the normal shell function lookup. Only builtin
3637 commands or commands found in the
3640 are executed. If the
3642 option is given, the search for
3644 is performed using a default value for
3646 that is guaranteed to find all of the standard utilities.
3651 option is supplied, a description of
3655 option causes a single word indicating the command or pathname
3660 option produces a more verbose description.
3663 disables option checking for the rest of the arguments.
3668 option is supplied, the exit status is 0 if
3670 was found, and 1 if not. If neither option is supplied and
3671 an error occurred or
3673 cannot be found, the exit status is 127. Otherwise, the exit status of the
3675 builtin is the exit status of
3678 \fBcontinue\fP [\fIn\fP]
3679 Resume the next iteration of the enclosing
3687 is specified, resume at the \fIn\fPth enclosing loop.
3691 is greater than the number of enclosing loops, the last enclosing loop
3692 (the `top\-level' loop) is resumed. The return value is 0 unless the
3693 shell is not executing a loop when
3698 \fBdeclare\fP [\fB\-frxi\fP] [\fIname\fP[=\fIvalue\fP]]
3700 \fBtypeset\fP [\fB\-frxi\fP] [\fIname\fP[=\fIvalue\fP]]
3702 Declare variables and/or give them attributes. If no \fIname\fPs are
3703 given, then display the values of variables instead. The options can
3704 be used to restrict output to variables with the specified attribute.
3709 Use function names only
3712 Make \fIname\fPs readonly. These names cannot then be assigned values
3713 by subsequent assignment statements.
3716 Mark \fIname\fPs for export to subsequent commands via the environment.
3719 The variable is treated as an integer; arithmetic evaluation (see
3721 .B "ARITHMETIC EVALUATION" ") "
3722 is performed when the variable is assigned a value.
3725 Using `+' instead of `\-'
3726 turns off the attribute instead. When used in a function, makes
3727 \fIname\fPs local, as with the
3729 command. The return value is 0 unless an illegal option is encountered,
3730 an attempt is made to define a function using "-f foo=bar",
3731 one of the \fInames\fP is not a legal shell variable name,
3732 an attempt is made to turn off readonly status for a readonly variable,
3733 or an attempt is made to display a non-existant function with -f.
3736 .B dirs [\fB-l\fP] [\fB+/\-n\fP]
3737 Display the list of currently remembered directories. Directories
3738 are added to the list with the
3742 command moves back up through the list.
3747 displays the \fIn\fPth entry counting from the left of the list
3750 when invoked without options, starting with zero.
3753 displays the \fIn\fPth entry counting from the right of the list
3756 when invoked without options, starting with zero.
3759 produces a longer listing; the default listing format uses a
3760 tilde to denote the home directory.
3763 The return value is 0 unless an
3764 illegal option is supplied or \fIn\fP indexes beyond the end
3765 of the directory stack.
3768 \fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...]
3769 Output the \fIarg\fPs, separated by spaces. The return status is
3770 always 0. If \fB\-n\fP is specified, the trailing newline is
3771 suppressed. If the \fB\-e\fP option is given, interpretation of
3772 the following backslash-escaped characters is enabled. The
3774 option disables the interpretation of these escape characters,
3775 even on systems where they are interpreted by default.
3786 suppress trailing newline
3807 the character whose ASCII code is \fInnn\fP (octal)
3811 \fBenable\fP [\fB\-n\fP] [\fB\-all\fP] [\fIname\fP ...]
3812 Enable and disable builtin shell commands. This allows
3813 the execution of a disk command which has the same name as a shell
3814 builtin without specifying a full pathname.
3815 If \fB\-n\fP is used, each \fIname\fP
3816 is disabled; otherwise,
3817 \fInames\fP are enabled. For example, to use the
3819 binary found via the
3822 instead of the shell builtin version, type
3823 ``enable -n test''. If no arguments are given,
3824 a list of all enabled shell builtins is printed.
3825 If only \fB\-n\fP is supplied, a list of all disabled
3826 builtins is printed. If only \fB\-all\fP is supplied,
3827 the list printed includes all builtins, with an
3828 indication of whether or not each is enabled.
3834 The return value is 0 unless a
3836 is not a shell builtin.
3838 \fBeval\fP [\fIarg\fP ...]
3839 The \fIarg\fPs are read and concatenated together into a single
3840 command. This command is then read and executed by the shell, and
3841 its exit status is returned as the value of the
3843 command. If there are no
3845 or only null arguments,
3849 \fBexec\fP [[\fB\-\fP] \fIcommand\fP [\fIarguments\fP]]
3852 is specified, it replaces the shell.
3853 No new process is created. The
3855 become the arguments to \fIcommand\fP.
3856 If the first argument is
3858 the shell places a dash in the zeroth arg passed to
3860 This is what login does. If the file
3861 cannot be executed for some reason, a non-interactive shell exits,
3862 unless the shell variable \fBno_exit_on_failed_exec\fP exists, in
3863 which case it returns failure. An interactive shell returns failure
3864 if the file cannot be executed.
3867 is not specified, any redirections take effect in the current shell,
3868 and the return status is 0.
3870 \fBexit\fP [\fIn\fP]
3871 Cause the shell to exit
3872 with a status of \fIn\fP. If
3874 is omitted, the exit status
3875 is that of the last command executed.
3879 is executed before the shell terminates.
3882 \fBexport\fP [\fB\-nf\fP\^] [\fIname\fP[=\fIword\fP]] ...
3888 are marked for automatic export to the environment of
3889 subsequently executed commands. If the
3897 are given, or if the
3899 option is supplied, a list
3900 of all names that are exported in this shell is printed.
3903 option causes the export property to be removed from the
3904 named variables. An argument of
3906 disables option checking for the rest of the arguments.
3908 returns an exit status of 0 unless an illegal option is
3910 one of the \fInames\fP is not a legal shell variable name, or
3914 that is not a function.
3917 \fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-nlr\fP] [\fIfirst\fP] [\fIlast\fP]
3919 \fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP]
3921 Fix Command. In the first form, a range of commands from
3925 is selected from the history list.
3929 may be specified as a string (to locate the last command beginning
3930 with that string) or as a number (an index into the history list,
3931 where a negative number is used as an offset from the current
3934 is not specified it is set to
3935 the current command for listing (so that
3937 prints the last 10 commands) and to
3942 is not specified it is set to the previous
3943 command for editing and \-16 for listing.
3948 the command numbers when listing. The
3950 flag reverses the order of
3951 the commands. If the
3954 the commands are listed on
3955 standard output. Otherwise, the editor given by
3958 on a file containing those commands. If
3964 variable is used, and
3971 is not set. If neither variable is set,
3973 is used. When editing is complete, the edited commands are
3974 echoed and executed.
3976 In the second form, \fIcommand\fP is re-executed after each instance
3977 of \fIpat\fP is replaced by \fIrep\fP.
3978 A useful alias to use with this is ``r=fc \-s'',
3979 so that typing ``r cc''
3980 runs the last command beginning with ``cc'' and typing ``r''
3981 re-executes the last command.
3983 If the first form is used, the return value is 0 unless an illegal
3984 option is encountered or
3988 specify history lines out of range.
3991 option is supplied, the return value is the value of the last
3992 command executed or failure if an error occurs with the temporary
3993 file of commands. If the second form is used, the return status
3994 is that of the command re-executed, unless
3996 does not specify a valid history line, in which case
4000 \fBfg\fP [\fIjobspec\fP]
4003 in the foreground, and make it the current job. If
4005 is not present, the shell's notion of the \fIcurrent job\fP is used.
4006 The return value is that of the command placed into the foreground,
4007 or failure if run when job control is disabled or, when run with
4008 job control enabled, if
4010 does not specify a valid job or
4012 specifies a job that was started without job control.
4014 \fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIargs\fP]
4016 is used by shell procedures to parse positional parameters.
4018 contains the option letters to be recognized; if a letter
4019 is followed by a colon, the option is expected to have an
4020 argument, which should be separated from it by white space.
4021 Each time it is invoked,
4023 places the next option in the shell variable
4027 if it does not exist,
4028 and the index of the next argument to be processed into the
4034 is initialized to 1 each time the shell or a shell script
4035 is invoked. When an option requires an argument,
4037 places that argument into the variable
4040 The shell does not reset
4043 automatically; it must be manually reset between multiple
4046 within the same shell invocation if a new set of parameters
4050 can report errors in two ways. If the first character of
4054 error reporting is used. In normal operation diagnostic messages
4055 are printed when illegal options or missing option arguments are
4060 is set to 0, no error message will be displayed, even if the first
4065 If an illegal option is seen,
4070 prints an error message and unsets
4076 the option character found is placed in
4079 and no diagnostic message is printed.
4081 If a required argument is not found, and
4084 a question mark (\^\fB?\fP\^) is placed in
4087 is unset, and a diagnostic message is printed.
4090 is silent, then a colon (\^\fB:\fP\^) is placed in
4095 is set to the option character found.
4098 normally parses the positional parameters, but if more arguments are
4102 parses those instead.
4104 returns true if an option, specified or unspecified, is found.
4105 It returns false if the end of options is encountered or an
4108 \fBhash\fP [\fB\-r\fP] [\fIname\fP]
4111 the full pathname of the command is determined
4114 option causes the shell to forget all
4115 remembered locations. If no arguments are given, information
4116 about remembered commands is printed.
4119 disables option checking for the rest of the arguments. The return
4120 status is true unless a
4122 is not found or an illegal option is supplied.
4124 \fBhelp\fP [\fIpattern\fP]
4125 Display helpful information about builtin commands. If
4129 gives detailed help on all commands matching
4131 otherwise a list of the builtins is printed. The return status is 0
4132 unless no command matches
4136 \fBhistory\fP [\fIn\fP]
4138 \fBhistory\fP \fB\-rwan\fP [\fIfilename\fP]
4140 .\"\fBhistory\fP \fB\-s\fP \fIargs\fP
4142 With no options, display the command
4143 history list with line numbers. Lines listed
4146 have been modified. An argument of
4150 lines. If a non-option argument is supplied, it is used as the
4151 name of the history file; if not, the value of
4154 is used. Options, if supplied, have the following meanings:
4159 Append the ``new'' history lines (history lines entered since the
4160 beginning of the current \fBbash\fP session) to the history file
4163 Read the history lines not already read from the history
4164 file into the current history list. These are lines
4165 appended to the history file since the beginning of the
4166 current \fBbash\fP session.
4169 Read the contents of the history file
4170 and use them as the current history
4173 Write the current history to the history file, overwriting the
4174 history file's contents.
4178 .\"substitution on the following \fIargs\fP and display
4179 .\"the result on the standard output.
4182 The return value is 0 unless an illegal option is encountered or an
4183 error occurs while reading or writing the history file.
4187 \fBjobs\fP [\fB\-lnp\fP] [ \fIjobspec\fP ... ]
4189 \fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ]
4191 The first form lists the active jobs. The
4193 option lists process IDs
4194 in addition to the normal information; the
4196 option lists only the process ID of the job's process group
4199 option displays only jobs that have changed status since
4202 is given, output is restricted to information about that job.
4203 The return status is 0 unless an illegal option is encountered
4218 with the corresponding process group ID, and executes
4222 returning its exit status.
4225 \fBkill\fP [\fB-s sigspec\fP | \fB\-sigspec\fP] [\fIpid\fP | \fIjobspec\fP] ...
4227 \fBkill\fP \fB\-l\fP [\fIsignum\fP]
4229 Send the signal named by
4231 to the processes named by
4236 is either a signal name such as
4239 or a signal number. If
4241 is a signal name, the name is case insensitive and may be
4242 given with or without the
4248 is not present, then
4251 is assumed. An argument of
4253 lists the signal names. If any arguments are supplied when
4255 is given, the names of the specified signals are listed, and
4256 the return status is 0.
4259 disables option checking for the rest of the arguments.
4261 returns true if at least one signal was successfully sent, or false
4262 if an error occurs or an illegal option is encountered.
4264 \fBlet\fP \fIarg\fP [\fIarg\fP ...]
4267 is an arithmetic expression to be evaluated (see
4269 .BR "ARITHMETIC EVALUATION" ).
4274 returns 1; 0 is returned otherwise.
4276 \fBlocal\fP [\fIname\fP[=\fIvalue\fP] ...]
4277 For each argument, create a local variable named
4283 is used within a function, it causes the variable
4285 to have a visible scope restricted to that function and its children.
4288 writes a list of local variables to the standard output. It is
4291 when not within a function. The return status is 0 unless
4293 is used outside a function, or an illegal
4300 \fBpopd\fP [\fB+/\-n\fP]
4301 Removes entries from the directory stack. With no arguments,
4302 removes the top directory from the stack, and performs a
4304 to the new top directory.
4309 removes the \fIn\fPth entry counting from the left of the list
4312 starting with zero. For example: ``popd +0''
4313 removes the first directory, ``popd +1'' the second.
4316 removes the \fIn\fPth entry counting from the right of the list
4319 starting with zero. For example: ``popd -0''
4320 removes the last directory, ``popd -1'' the next to last.
4325 command is successful, a
4327 is performed as well, and the return status is 0.
4329 returns false if an illegal option is encountered, the directory stack
4330 is empty, a non-existent directory stack entry is specified, or the
4331 directory change fails.
4335 \fBpushd\fP [\fIdir\fP]
4337 \fBpushd\fP \fB+/\-n\fP
4339 Adds a directory to the top of the directory stack, or rotates
4340 the stack, making the new top of the stack the current working
4341 directory. With no arguments, exchanges the top two directories
4342 and returns 0, unless the directory stack is empty.
4347 Rotates the stack so that the \fIn\fPth directory
4348 (counting from the left of the list shown by
4353 Rotates the stack so that the \fIn\fPth directory
4354 (counting from the right) is at the top.
4359 to the directory stack at the top, making it the
4360 new current working directory.
4365 command is successful, a
4367 is performed as well.
4368 If the first form is used,
4370 returns 0 unless the cd to
4372 fails. With the second form,
4374 returns 0 unless the directory stack is empty,
4375 a non-existant directory stack element is specified,
4376 or the directory change to the specified new current directory
4381 Print the absolute pathname of the current working directory.
4382 The path printed contains no symbolic links if the
4386 builtin command is set.
4387 See also the description of
4391 above). The return status is 0 unless an error occurs while
4392 reading the pathname of the current directory.
4394 \fBread\fP [\fB\-r\fP] [\fIname\fP ...]
4395 One line is read from the standard input, and the first word
4396 is assigned to the first
4398 the second word to the second
4400 and so on, with leftover words assigned to the last
4406 are recognized as word delimiters. If no
4408 are supplied, the line read is assigned to the variable
4411 The return code is zero, unless end-of-file is encountered. If the
4414 is given, a backslash-newline pair is not ignored, and
4415 the backslash is considered to be part of the line.
4418 \fBreadonly\fP [\fB\-f\fP] [\fIname\fP ...]
4423 \fInames\fP are marked readonly and the values of these
4425 may not be changed by subsequent assignment.
4428 option is supplied, the functions corresponding to the
4430 marked. If no arguments are given, or if the
4432 option is supplied, a list of all readonly names
4436 disables option checking for the rest of the arguments. The
4437 return status is 0 unless an illegal option is encountered,
4438 one of the \fInames\fP is not a legal shell variable name, or
4442 that is not a function.
4444 \fBreturn\fP [\fIn\fP]
4445 Causes a function to exit with the return value specified by
4449 is omitted, the return status is that of the last command
4450 executed in the function body. If used outside a function,
4451 but during execution of a script by the
4453 (\fBsource\fP) command, it causes the shell to stop executing
4454 that script and return either
4456 or the exit status of the last command executed within the
4457 script as the exit status of the script. If used outside a
4458 function and not during execution of a script by \fB.\fP\^,
4459 the return status is false.
4461 \fBset\fP [\fB\-\-abefhkmnptuvxldCHP\fP] [\fB-o\fP \fIoption\fP] [\fIarg\fP ...]
4466 Automatically mark variables which are modified or created for export
4467 to the environment of subsequent commands.
4470 Cause the status of terminated background jobs to be reported
4471 immediately, rather than before the next primary prompt.
4479 Exit immediately if a \fIsimple-command\fP (see
4482 above) exits with a non\-zero status. The shell does not exit if the
4483 command that fails is part of an
4490 statement, part of a
4494 list, or if the command's return value is
4499 Disable pathname expansion.
4502 Locate and remember function commands as functions are
4503 defined. Function commands are normally looked up when
4504 the function is executed.
4507 All keyword arguments are placed in the environment for a
4508 command, not just those that precede the command name.
4511 Monitor mode. Job control is enabled. This flag is on
4512 by default for interactive shells on systems that support
4516 above). Background processes run in a separate process
4517 group and a line containing their exit status is printed
4518 upon their completion.
4521 Read commands but do not execute them. This may be used to
4522 check a shell script for syntax errors. This is ignored for
4525 .B \-o \fIoption-name\fP
4526 The \fIoption-name\fP can be one of the following:
4534 The shell performs brace expansion (see
4536 above). This is on by default.
4539 Use an emacs-style command line editing interface. This is enabled
4540 by default when the shell is interactive, unless the shell is started
4554 The effect is as if the shell command `IGNOREEOF=10' had been executed
4559 .B interactive\-comments
4560 Allow a word beginning with
4562 to cause that word and all remaining characters on that
4563 line to be ignored in an interactive shell (see
4601 Change the behavior of bash where the default operation differs
4602 from the Posix 1003.2 standard to match the standard.
4613 Use a vi-style command line editing interface.
4619 If no \fIoption-name\fP is supplied, the values of the current options are
4626 mode. In this mode, the
4628 file is not processed, and shell functions
4629 are not inherited from the environment. This is enabled automatically
4630 on startup if the effective user (group) id is not equal to the real
4631 user (group) id. Turning this option off causes the effective user
4632 and group ids to be set to the real user and group ids.
4635 Exit after reading and executing one command.
4638 Treat unset variables as an error when performing
4639 parameter expansion. If expansion is attempted on an
4640 unset variable, the shell prints an error message, and,
4641 if not interactive, exits with a non\-zero status.
4644 Print shell input lines as they are read.
4647 After expanding each
4648 .IR simple-command ,
4650 displays the expanded value of
4653 followed by the command and its expanded arguments.
4656 Save and restore the binding of \fIname\fP in a
4657 \fBfor\fP \fIname\fP [in \fBword\fP] command (see
4663 Disable the hashing of commands that are looked up for execution.
4664 Normally, commands are remembered in a hash table, and once
4665 found, do not have to be looked up again.
4668 The effect is as if the shell command `noclobber=' had been executed
4676 style history substitution. This flag is on by
4677 default when the shell is interactive.
4680 If set, do not follow symbolic links when performing commands such as
4682 which change the current directory. The physical directory is
4686 If no arguments follow this flag, then the positional parameters are
4687 unset. Otherwise, the positional parameters are set to the
4688 \fIarg\fPs, even if some of them begin with a
4692 Signal the end of options, cause all remaining \fIarg\fPs to be
4693 assigned to the positional parameters. The
4697 options are turned off.
4698 If there are no \fIarg\fPs,
4699 the positional parameters remain unchanged.
4702 The flags are off by default
4703 unless otherwise noted.
4704 Using + rather than \- causes these flags
4705 to be turned off. The
4706 flags can also be specified as options to an
4707 invocation of the shell. The current
4708 set of flags may be found in
4710 After the option arguments are processed,
4711 the remaining \fIn\fP \fIarg\fPs are treated
4712 as values for the positional
4713 parameters and are assigned, in order, to
4718 If no options or \fIarg\fPs are supplied,
4719 all shell variables are printed. The return status is always true
4720 unless an illegal option is encountered.
4723 \fBshift\fP [\fIn\fP]
4724 The positional parameters from \fIn\fP+1 ... are renamed to
4727 Parameters represented by the numbers \fB$#\fP
4728 down to \fB$#\fP\-\fIn\fP+1 are unset.
4731 is 0, no parameters are changed.
4734 is not given, it is assumed to be 1.
4736 must be a non-negative number less than or equal to \fB$#\fP.
4739 is greater than \fB$#\fP, the positional parameters are not changed.
4740 The return status is greater than 0 if
4744 or less than 0; otherwise 0.
4746 \fBsuspend\fP [\fB\-f\fP]
4747 Suspend the execution of this shell until it receives a
4752 option says not to complain if this is
4753 a login shell; just suspend anyway. The return status is 0 unless
4754 the shell is a login shell and
4756 is not supplied, or if job control is not enabled.
4759 \fBtest\fP \fIexpr\fP
4761 \fB[\fP \fIexpr\fP \fB]\fP
4762 Return a status of 0 (true) or 1 (false) depending on
4763 the evaluation of the conditional expression
4765 Expressions may be unary or binary. Unary
4766 expressions are often used to examine the status of a file. There
4767 are string operators and numeric comparison operators as well. Each
4768 operator and operand must be a separate argument. If \fIfile\fP
4769 is of the form /dev/fd/\fIn\fP, then file descriptor \fIn\fP is
4775 True if \fIfile\fP exists and is block special.
4778 True if \fIfile\fP exists and is character special.
4781 True if \fIfile\fP exists and is a directory.
4784 True if \fIfile\fP exists.
4787 True if \fIfile\fP exists and is a regular file.
4790 True if \fIfile\fP exists and is set-group-id.
4793 True if \fIfile\fP has its ``sticky'' bit set.
4796 True if \fIfile\fP exists and is a symbolic link.
4799 True if \fIfile\fP exists and is a named pipe.
4802 True if \fIfile\fP exists and is readable.
4805 True if \fIfile\fP exists and has a size greater than zero.
4808 True if \fIfile\fP exists and is a socket.
4813 is opened on a terminal.
4816 True if \fIfile\fP exists and its set-user-id bit is set.
4819 True if \fIfile\fP exists and is writable.
4822 True if \fIfile\fP exists and is executable.
4825 True if \fIfile\fP exists and is owned by the effective user id.
4828 True if \fIfile\fP exists and is owned by the effective group id.
4830 \fIfile1\fP \-\fBnt\fP \fIfile2\fP
4831 True if \fIfile1\fP is newer (according to
4832 modification date) than \fIfile2\fP.
4834 \fIfile1\fP \-\fBot\fP \fIfile2\fP
4835 True if \fIfile1\fP is older than file2.
4837 \fIfile1\fP \fB\-ef\fP \fIfile\fP
4838 True if \fIfile1\fP and \fIfile2\fP have the same device and
4842 True if the length of \fIstring\fP is zero.
4847 True if the length of
4851 \fIstring1\fP \fB=\fP \fIstring2\fP
4852 True if the strings are equal.
4854 \fIstring1\fP \fB!=\fP \fIstring2\fP
4855 True if the strings are not equal.
4862 \fIexpr1\fP \-\fBa\fP \fIexpr2\fP
4869 \fIexpr1\fP \-\fBo\fP \fIexpr2\fP
4876 .I arg1 \fBOP\fP arg2
4887 These arithmetic binary operators return true if \fIarg1\fP
4888 is equal, not-equal, less-than, less-than-or-equal,
4889 greater-than, or greater-than-or-equal than \fIarg2\fP,
4894 may be positive integers, negative integers, or the special
4895 expression \fB\-l\fP \fIstring\fP, which evaluates to the
4902 Print the accumulated user and system times for the shell and
4903 for processes run from the shell. The return status is 0.
4905 \fBtrap\fP [\fB\-l\fP] [\fIarg\fP] [\fIsigspec\fP]
4908 is to be read and executed when the shell receives
4915 all specified signals are
4916 reset to their original values (the values they had
4917 upon entrance to the shell). If
4919 is the null string this
4920 signal is ignored by the shell and by the
4921 commands it invokes.
4924 a signal name defined in <\fIsignal.h\fP>, or a signal number.
4932 is executed on exit from
4933 the shell. With no arguments,
4935 prints the list of commands associated with each signal number.
4938 option causes the shell to
4939 print a list of signal names and their corresponding
4940 numbers. An argument of
4942 disables option checking for the rest of the arguments.
4943 Signals ignored upon entry to the shell cannot be trapped or reset.
4944 Trapped signals are reset to their original values in a child
4945 process when it is created. The return status is false if either
4946 the trap name or number is invalid; otherwise
4950 \fBtype\fP [\fB\-all\fP] [\fB\-type\fP | \fB\-path\fP] \fIname\fP [\fIname\fP ...]
4954 would be interpreted if used as a command name.
4959 prints a phrase which is one of
4968 is an alias, shell reserved word, function, builtin, or disk file,
4969 respectively. If the name is not found, then nothing is printed,
4970 and an exit status of false is returned.
4975 either returns the name of the disk file
4976 that would be executed if
4978 were specified as a command name,
4983 If a command is hashed,
4985 prints the hashed value, not necessarily the file that appears
4993 prints all of the places that contain
4996 This includes aliases and functions,
4999 flag is not also used.
5000 The table of hashed commands is not consulted
5017 disables option checking for the rest of the arguments.
5019 returns true if any of the arguments are found, false if
5022 \fBulimit\fP [\fB\-SHacdfmstpnuv\fP [\fIlimit\fP]]
5024 provides control over the resources available to the shell and to
5025 processes started by it, on systems that allow such control. The
5028 can be a number in the unit specified for the resource, or the
5031 The \fBH\fP and \fBS\fP options specify that the hard or soft limit is
5032 set for the given resource. A hard limit cannot be increased once it
5033 is set; a soft limit may be increased up to the value of the hard limit.
5034 If neither \fBH\fP nor \fBS\fP is specified, the command applies to the
5037 is omitted, the current value of the soft limit of the resource is
5038 printed, unless the \fBH\fP option is given. When more than one resource
5039 is specified, the limit name and unit is printed before the value.
5040 Other options are interpreted as follows:
5045 all current limits are reported
5048 the maximum size of core files created
5051 the maximum size of a process's data segment
5054 the maximum size of files created by the shell
5057 the maximum resident set size
5060 the maximum stack size
5063 the maximum amount of cpu time in seconds
5066 the pipe size in 512-byte blocks (this may not be set)
5069 the maximum number of open file descriptors (most systems do not
5070 allow this value to be set, only displayed)
5073 the maximum number of processes available to a single user
5076 The maximum amount of virtual memory available to the shell
5081 disables option checking for the rest of the arguments. If
5083 is given, it is the new value of the specified resource (the
5085 option is display only).
5086 If no option is given, then
5088 is assumed. Values are in 1024-byte increments, except for
5090 which is in seconds,
5092 which is in units of 512-byte blocks,
5097 which are unscaled values. The return status is 0
5098 unless an illegal option is encountered, a non-numeric argument
5099 other than \fBunlimited\fP is supplied as \fIlimit\fP, or an
5100 error occurs while setting a new limit.
5103 \fBumask\fP [\fB\-S\fP] [\fImode\fP]
5104 The user file-creation mask is set to
5108 begins with a digit, it
5109 is interpreted as an octal number; otherwise
5110 it is interpreted as a symbolic mode mask similar
5115 is omitted, or if the
5117 option is supplied, the
5118 current value of the mask is printed. The
5120 option causes the mask to be printed in symbolic form; the
5121 default output is an octal number.
5124 disables option checking for the rest of the arguments. The
5125 return status is 0 if the mode was successfully changed or if
5126 no \fImode\fP argument was supplied, and false otherwise.
5128 \fBunalias\fP [\-\fBa\fP] [\fIname\fP ...]
5129 Remove \fIname\fPs from the list of defined aliases. If
5131 is supplied, all alias definitions are removed. The return
5132 value is true unless a supplied
5134 is not a defined alias.
5136 \fBunset\fP [\-\fBfv\fP] [\fIname\fP ...]
5139 remove the corresponding variable or, given the
5144 disables option checking for the rest of the arguments.
5161 cannot be unset. If any of
5171 are unset, they lose their special properties, even if they are
5172 subsequently reset. The exit status is true unless a
5174 does not exist or is non-unsettable.
5176 \fBwait\fP [\fIn\fP]
5177 Wait for the specified process and return its termination
5181 ID or a job specification; if a job spec is given, all processes
5182 in that job's pipeline are waited for. If
5184 is not given, all currently active child processes
5185 are waited for, and the return status is zero. If
5187 specifies a non-existant process or job, the return status is
5188 127. Otherwise, the return status is the exit status of the last
5189 process or job waited for.
5193 A \fIlogin shell\fP is one whose first character of argument zero is a
5195 or one started with the
5199 An \fIinteractive\fP shell is one whose standard input and output are
5200 both connected to terminals (as determined by
5202 or one started with the
5214 allowing a shell script or a startup file to test this state.
5218 On login (subject to the \fB\-noprofile\fP option):
5219 if \fI/etc/profile\fP exists, source it.
5221 if \fI~/.bash_profile\fP exists, source it,
5222 else if \fI~/.bash_login\fP exists, source it,
5223 else if \fI~/.profile\fP exists, source it.
5226 if \fI~/.bash_logout\fP exists, source it.
5228 Non-login interactive shells:
5229 On startup (subject to the \fB\-norc\fP and \fB\-rcfile\fP options):
5230 if \fI~/.bashrc\fP exists, source it.
5232 Non-interactive shells:
5234 if the environment variable \fBENV\fP is non-null, expand
5235 it and source the file it names, as if the command
5236 if [ "$ENV" ]; then . $ENV; fi
5237 had been executed, but do not use \fBPATH\fP to search
5238 for the pathname. When not started in Posix mode, bash
5239 looks for \fBBASH_ENV\fP before \fBENV\fP.
5243 If Bash is invoked as
5245 it tries to mimic the behavior of
5247 as closely as possible. For a login shell, it attempts to
5254 option may still be used to disable this behavior.
5257 does not attempt to source any other startup files.
5265 command line option, it follows the Posix standard for
5266 startup files. In this mode, the
5268 variable is expanded and that file sourced; no other startup
5273 \fIBash Features\fP, Brian Fox and Chet Ramey
5275 \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey
5277 \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey
5279 \fIA System V Compatible Implementation of 4.2\s-1BSD\s+1 Job Control\fP, David Lennert
5281 \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE
5283 \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
5285 \fIemacs\fP(1), \fIvi\fP(1)
5293 The \fBbash\fP executable
5296 The systemwide initialization file, executed for login shells
5299 The personal initialization file, executed for login shells
5302 The individual per-interactive-shell startup file
5305 Individual \fIreadline\fP initialization file
5309 Brian Fox, Free Software Foundation (primary author)
5313 Chet Ramey, Case Western Reserve University
5317 If you find a bug in
5319 you should report it. But first, you should
5320 make sure that it really is a bug, and that it appears in the latest
5325 Once you have determined that a bug actually exists, use the
5327 command to submit a bug report.
5328 If you have a fix, you are welcome to mail that
5330 Suggestions and `philosophical' bug reports may be mailed
5331 to \fPbug-bash\fP@\fIprep.ai.MIT.Edu\fP or posted to the Usenet
5335 ALL bug reports should include:
5339 The version number of \fBbash\fR
5341 The hardware and operating system
5343 The compiler used to compile
5345 A description of the bug behaviour
5347 A short script or `recipe' which exercises the bug
5351 inserts the first three items automatically into the template
5352 it provides for filing a bug report.
5354 Comments and bug reports concerning
5355 this manual page should be directed to
5356 .IR chet@ins.CWRU.Edu .
5359 It's too big and too slow.
5361 There are some subtle differences between
5363 and traditional versions of
5365 mostly because of the
5370 Aliases are confusing in some uses.
projects / platform / upstream / bash.git / blob