diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/bash.1 | 11764 |
1 files changed, 11764 insertions, 0 deletions
diff --git a/doc/bash.1 b/doc/bash.1 new file mode 100644 index 0000000..55c5622 --- /dev/null +++ b/doc/bash.1 @@ -0,0 +1,11764 @@ +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Case Western Reserve University +.\" chet.ramey@case.edu +.\" +.\" Last Change: Mon Sep 19 11:13:21 EDT 2022 +.\" +.\" bash_builtins, strip all but Built-Ins section +.if \n(zZ=1 .ig zZ +.if \n(zY=1 .ig zY +.TH BASH 1 "2022 September 19" "GNU Bash 5.2" +.\" +.\" There's some problem with having a `@' +.\" in a tagged paragraph with the BSD man macros. +.\" It has to do with `@' appearing in the }1 macro. +.\" This is a problem on 4.3 BSD and Ultrix, but Sun +.\" appears to have fixed it. +.\" If you're seeing the characters +.\" `@u-3p' appearing before the lines reading +.\" `possible-hostname-completions +.\" and `complete-hostname' down in READLINE, +.\" then uncomment this redefinition. +.\" +.\" .de }1 +.\" .ds ]X \&\\*(]B\\ +.\" .nr )E 0 +.\" .if !"\\$1"" .nr )I \\$1n +.\" .}f +.\" .ll \\n(LLu +.\" .in \\n()Ru+\\n(INu+\\n()Iu +.\" .ti \\n(INu +.\" .ie !\\n()Iu+\\n()Ru-\w\\*(]Xu-3p \{\\*(]X +.\" .br\} +.\" .el \\*(]X\h|\\n()Iu+\\n()Ru\c +.\" .}f +.\" .. +.\" +.\" File Name macro. This used to be `.PN', for Path Name, +.\" but Sun doesn't seem to like that very much. +.\" +.de FN +\fI\|\\$1\|\fP +.. +.SH NAME +bash \- GNU Bourne-Again SHell +.SH SYNOPSIS +.B bash +[options] +[command_string | file] +.SH COPYRIGHT +.if n Bash is Copyright (C) 1989-2022 by the Free Software Foundation, Inc. +.if t Bash is Copyright \(co 1989-2022 by the Free Software Foundation, Inc. +.SH DESCRIPTION +.B Bash +is an \fBsh\fR-compatible command language interpreter that +executes commands read from the standard input or from a file. +.B Bash +also incorporates useful features from the \fIKorn\fP and \fIC\fP +shells (\fBksh\fP and \fBcsh\fP). +.PP +.B Bash +is intended to be a conformant implementation of the +Shell and Utilities portion of the IEEE POSIX specification +(IEEE Standard 1003.1). +.B Bash +can be configured to be POSIX-conformant by default. +.SH OPTIONS +All of the single-character shell options documented in the +description of the \fBset\fR builtin command, including \fB\-o\fP, +can be used as options when the shell is invoked. +In addition, \fBbash\fR +interprets the following options when it is invoked: +.PP +.PD 0 +.TP 10 +.B \-c +If the +.B \-c +option is present, then commands are read from the first non-option argument +.IR command_string . +If there are arguments after the +.IR command_string , +the first argument is assigned to +.B $0 +and any remaining arguments are assigned to the positional parameters. +The assignment to +.B $0 +sets the name of the shell, which is used in warning and error messages. +.TP +.B \-i +If the +.B \-i +option is present, the shell is +.IR interactive . +.TP +.B \-l +Make +.B bash +act as if it had been invoked as a login shell (see +.SM +.B INVOCATION +below). +.TP +.B \-r +If the +.B \-r +option is present, the shell becomes +.I restricted +(see +.SM +.B "RESTRICTED SHELL" +below). +.TP +.B \-s +If the +.B \-s +option is present, or if no arguments remain after option +processing, then commands are read from the standard input. +This option allows the positional parameters to be set +when invoking an interactive shell or when reading input +through a pipe. +.TP +.B \-D +A list of all double-quoted strings preceded by \fB$\fP +is printed on the standard output. +These are the strings that +are subject to language translation when the current locale +is not \fBC\fP or \fBPOSIX\fP. +This implies the \fB\-n\fP option; no commands will be executed. +.TP +.B [\-+]O [\fIshopt_option\fP] +\fIshopt_option\fP is one of the shell options accepted by the +\fBshopt\fP builtin (see +.SM +.B SHELL BUILTIN COMMANDS +below). +If \fIshopt_option\fP is present, \fB\-O\fP sets the value of that option; +\fB+O\fP unsets it. +If \fIshopt_option\fP is not supplied, the names and values of the shell +options accepted by \fBshopt\fP are printed on the standard output. +If the invocation option is \fB+O\fP, the output is displayed in a format +that may be reused as input. +.TP +.B \-\- +A +.B \-\- +signals the end of options and disables further option processing. +Any arguments after the +.B \-\- +are treated as filenames and arguments. An argument of +.B \- +is equivalent to \fB\-\-\fP. +.PD +.PP +.B Bash +also interprets a number of multi-character options. +These options must appear on the command line before the +single-character options to be recognized. +.PP +.PD 0 +.TP +.B \-\-debugger +Arrange for the debugger profile to be executed before the shell +starts. +Turns on extended debugging mode (see the description of the +.B extdebug +option to the +.B shopt +builtin below). +.TP +.B \-\-dump\-po\-strings +Equivalent to \fB\-D\fP, but the output is in the GNU \fIgettext\fP +\fBpo\fP (portable object) file format. +.TP +.B \-\-dump\-strings +Equivalent to \fB\-D\fP. +.TP +.B \-\-help +Display a usage message on standard output and exit successfully. +.TP +\fB\-\-init\-file\fP \fIfile\fP +.PD 0 +.TP +\fB\-\-rcfile\fP \fIfile\fP +.PD +Execute commands from +.I file +instead of the standard personal initialization file +.I ~/.bashrc +if the shell is interactive (see +.SM +.B INVOCATION +below). +.TP +.B \-\-login +Equivalent to \fB\-l\fP. +.TP +.B \-\-noediting +Do not use the GNU +.B readline +library to read command lines when the shell is interactive. +.TP +.B \-\-noprofile +Do not read either the system-wide startup file +.FN /etc/profile +or any of the personal initialization files +.IR ~/.bash_profile , +.IR ~/.bash_login , +or +.IR ~/.profile . +By default, +.B bash +reads these files when it is invoked as a login shell (see +.SM +.B INVOCATION +below). +.TP +.B \-\-norc +Do not read and execute the personal initialization file +.I ~/.bashrc +if the shell is interactive. +This option is on by default if the shell is invoked as +.BR sh . +.TP +.B \-\-posix +Change the behavior of \fBbash\fP where the default operation differs +from the POSIX standard to match the standard (\fIposix mode\fP). +See +.SM +.B "SEE ALSO" +below for a reference to a document that details how posix mode affects +bash's behavior. +.TP +.B \-\-restricted +The shell becomes restricted (see +.SM +.B "RESTRICTED SHELL" +below). +.TP +.B \-\-verbose +Equivalent to \fB\-v\fP. +.TP +.B \-\-version +Show version information for this instance of +.B bash +on the standard output and exit successfully. +.PD +.SH ARGUMENTS +If arguments remain after option processing, and neither the +.B \-c +nor the +.B \-s +option has been supplied, the first argument is assumed to +be the name of a file containing shell commands. +If +.B bash +is invoked in this fashion, +.B $0 +is set to the name of the file, and the positional parameters +are set to the remaining arguments. +.B Bash +reads and executes commands from this file, then exits. +\fBBash\fP's exit status is the exit status of the last command +executed in the script. +If no commands are executed, the exit status is 0. +An attempt is first made to open the file in the current directory, and, +if no file is found, then the shell searches the directories in +.SM +.B PATH +for the script. +.SH INVOCATION +A \fIlogin shell\fP is one whose first character of argument zero is a +.BR \- , +or one started with the +.B \-\-login +option. +.PP +An \fIinteractive\fP shell is one started without non-option arguments +(unless \fB\-s\fP is specified) +and without the +.B \-c +option, +whose standard input and error are +both connected to terminals (as determined by +.IR isatty (3)), +or one started with the +.B \-i +option. +.SM +.B PS1 +is set and +.B $\- +includes +.B i +if +.B bash +is interactive, +allowing a shell script or a startup file to test this state. +.PP +The following paragraphs describe how +.B bash +executes its startup files. +If any of the files exist but cannot be read, +.B bash +reports an error. +Tildes are expanded in filenames as described below under +.B "Tilde Expansion" +in the +.SM +.B EXPANSION +section. +.PP +When +.B bash +is invoked as an interactive login shell, or as a non-interactive shell +with the \fB\-\-login\fP option, it first reads and +executes commands from the file \fI/etc/profile\fP, if that +file exists. +After reading that file, it looks for \fI~/.bash_profile\fP, +\fI~/.bash_login\fP, and \fI~/.profile\fP, in that order, and reads +and executes commands from the first one that exists and is readable. +The +.B \-\-noprofile +option may be used when the shell is started to inhibit this behavior. +.PP +When an interactive login shell exits, +or a non-interactive login shell executes the \fBexit\fP builtin command, +.B bash +reads and executes commands from the file \fI~/.bash_logout\fP, if it +exists. +.PP +When an interactive shell that is not a login shell is started, +.B bash +reads and executes commands from \fI~/.bashrc\fP, if that file exists. +This may be inhibited by using the +.B \-\-norc +option. +The \fB\-\-rcfile\fP \fIfile\fP option will force +.B bash +to read and execute commands from \fIfile\fP instead of \fI~/.bashrc\fP. +.PP +When +.B bash +is started non-interactively, to run a shell script, for example, it +looks for the variable +.SM +.B BASH_ENV +in the environment, expands its value if it appears there, and uses the +expanded value as the name of a file to read and execute. +.B Bash +behaves as if the following command were executed: +.sp .5 +.RS +.if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP +.if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi +.RE +.sp .5 +but the value of the +.SM +.B PATH +variable is not used to search for the filename. +.PP +If +.B bash +is invoked with the name +.BR sh , +it tries to mimic the startup behavior of historical versions of +.B sh +as closely as possible, +while conforming to the POSIX standard as well. +When invoked as an interactive login shell, or a non-interactive +shell with the \fB\-\-login\fP option, it first attempts to +read and execute commands from +.I /etc/profile +and +.IR ~/.profile , +in that order. +The +.B \-\-noprofile +option may be used to inhibit this behavior. +When invoked as an interactive shell with the name +.BR sh , +.B bash +looks for the variable +.SM +.BR ENV , +expands its value if it is defined, and uses the +expanded value as the name of a file to read and execute. +Since a shell invoked as +.B sh +does not attempt to read and execute commands from any other startup +files, the +.B \-\-rcfile +option has no effect. +A non-interactive shell invoked with the name +.B sh +does not attempt to read any other startup files. +When invoked as +.BR sh , +.B bash +enters +.I posix +mode after the startup files are read. +.PP +When +.B bash +is started in +.I posix +mode, as with the +.B \-\-posix +command line option, it follows the POSIX standard for startup files. +In this mode, interactive shells expand the +.SM +.B ENV +variable and commands are read and executed from the file +whose name is the expanded value. +No other startup files are read. +.PP +.B Bash +attempts to determine when it is being run with its standard input +connected to a network connection, as when executed by +the historical remote shell daemon, usually \fIrshd\fP, +or the secure shell daemon \fIsshd\fP. +If +.B bash +determines it is being run non-interactively in this fashion, +it reads and executes commands from \fI~/.bashrc\fP, +if that file exists and is readable. +It will not do this if invoked as \fBsh\fP. +The +.B \-\-norc +option may be used to inhibit this behavior, and the +.B \-\-rcfile +option may be used to force another file to be read, but neither +\fIrshd\fP nor \fIsshd\fP generally invoke the shell with those options +or allow them to be specified. +.PP +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the \fB\-p\fP option is not supplied, no startup +files are read, shell functions are not inherited from the environment, the +.SM +.BR SHELLOPTS , +.SM +.BR BASHOPTS , +.SM +.BR CDPATH , +and +.SM +.B GLOBIGNORE +variables, if they appear in the environment, are ignored, +and the effective user id is set to the real user id. +If the \fB\-p\fP option is supplied at invocation, the startup behavior is +the same, but the effective user id is not reset. +.SH DEFINITIONS +The following definitions are used throughout the rest of this +document. +.PD 0 +.TP +.B blank +A space or tab. +.TP +.B word +A sequence of characters considered as a single unit by the shell. +Also known as a +.BR token . +.TP +.B name +A +.I word +consisting only of alphanumeric characters and underscores, and +beginning with an alphabetic character or an underscore. Also +referred to as an +.BR identifier . +.TP +.B metacharacter +A character that, when unquoted, separates words. One of the following: +.br +.RS +.PP +.if t \fB| & ; ( ) < > space tab newline\fP +.if n \fB| & ; ( ) < > space tab newline\fP +.RE +.TP +.B control operator +A \fItoken\fP that performs a control function. It is one of the following +symbols: +.RS +.PP +.if t \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP +.if n \fB|| & && ; ;; ;& ;;& ( ) | |& <newline>\fP +.RE +.PD +.SH "RESERVED WORDS" +\fIReserved words\fP are words that have a special meaning to the shell. +The following words are recognized as reserved when unquoted and either +the first word of a command (see +.SM +.B SHELL GRAMMAR +below), the third word of a +.B case +or +.B select +command +(only \fBin\fP is valid), or the third word of a +.B for +command (only \fBin\fP and \fBdo\fP are valid): +.if t .RS +.PP +.B +.if n ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]] +.if t ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]] +.if t .RE +.SH "SHELL GRAMMAR" +This section describes the syntax of the various forms of shell commands. +.SS Simple Commands +A \fIsimple command\fP is a sequence of optional variable assignments +followed by \fBblank\fP-separated words and redirections, and +terminated by a \fIcontrol operator\fP. The first word +specifies the command to be executed, and is passed as argument zero. +The remaining words are passed as arguments to the invoked command. +.PP +The return value of a \fIsimple command\fP is its exit status, or +128+\fIn\^\fP if the command is terminated by signal +.IR n . +.SS Pipelines +A \fIpipeline\fP is a sequence of one or more commands separated by +one of the control operators +.B | +or \fB|&\fP. +The format for a pipeline is: +.RS +.PP +[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] \fIcommand2\fP ... ] +.RE +.PP +The standard output of +.I command1 +is connected via a pipe to the standard input of +.IR command2 . +This connection is performed before any redirections specified by the +.IR command1 (see +.SM +.B REDIRECTION +below). +If \fB|&\fP is used, \fIcommand1\fP's standard error, in addition to its +standard output, is connected to +\fIcommand2\fP's standard input through the pipe; +it is shorthand for \fB2>&1 |\fP. +This implicit redirection of the standard error to the standard output is +performed after any redirections specified by \fIcommand1\fP. +.PP +The return status of a pipeline is the exit status of the last +command, unless the \fBpipefail\fP option is enabled. +If \fBpipefail\fP is enabled, the pipeline's return status is the +value of the last (rightmost) command to exit with a non-zero status, +or zero if all commands exit successfully. +If the reserved word +.B ! +precedes a pipeline, the exit status of that pipeline is the logical +negation of the exit status as described above. +The shell waits for all commands in the pipeline to +terminate before returning a value. +.PP +If the +.B time +reserved word precedes a pipeline, the elapsed as well as user and +system time consumed by its execution are reported when the pipeline +terminates. +The \fB\-p\fP option changes the output format to that specified by POSIX. +When the shell is in \fIposix mode\fP, it does not recognize +\fBtime\fP as a reserved word if the next token begins with a `-'. +The +.SM +.B TIMEFORMAT +variable may be set to a format string that specifies how the timing +information should be displayed; see the description of +.SM +.B TIMEFORMAT +under +.B "Shell Variables" +below. +.PP +When the shell is in \fIposix mode\fP, \fBtime\fP +may be followed by a newline. In this case, the shell displays the +total user and system time consumed by the shell and its children. +The +.SM +.B TIMEFORMAT +variable may be used to specify the format of +the time information. +.PP +Each command in a multi-command pipeline, +where pipes are created, +is executed in a \fIsubshell\fP, which is a +separate process. +See +.SM +\fBCOMMAND EXECUTION ENVIRONMENT\fP +for a description of subshells and a subshell environment. +If the \fBlastpipe\fP option is enabled using the \fBshopt\fP builtin +(see the description of \fBshopt\fP below), +the last element of a pipeline may be run by the shell process +when job control is not active. +.SS Lists +A \fIlist\fP is a sequence of one or more pipelines separated by one +of the operators +.BR ; , +.BR & , +.BR && , +or +.BR || , +and optionally terminated by one of +.BR ; , +.BR & , +or +.BR <newline> . +.PP +Of these list operators, +.B && +and +.B || +have equal precedence, followed by +.B ; +and +.BR & , +which have equal precedence. +.PP +A sequence of one or more newlines may appear in a \fIlist\fP instead +of a semicolon to delimit commands. +.PP +If a command is terminated by the control operator +.BR & , +the shell executes the command in the \fIbackground\fP +in a subshell. +The shell does not wait for the command to +finish, and the return status is 0. +These are referred to as \fIasynchronous\fP commands. +Commands separated by a +.B ; +are executed sequentially; the shell waits for each +command to terminate in turn. The return status is the +exit status of the last command executed. +.PP +AND and OR lists are sequences of one or more pipelines separated by the +\fB&&\fP and \fB||\fP control operators, respectively. +AND and OR lists are executed with left associativity. +An AND list has the form +.RS +.PP +\fIcommand1\fP \fB&&\fP \fIcommand2\fP +.RE +.PP +.I command2 +is executed if, and only if, +.I command1 +returns an exit status of zero (success). +.PP +An OR list has the form +.RS +.PP +\fIcommand1\fP \fB||\fP \fIcommand2\fP +.RE +.PP +.I command2 +is executed if, and only if, +.I command1 +returns a non-zero exit status. +The return status of +AND and OR lists is the exit status of the last command +executed in the list. +.SS Compound Commands +A \fIcompound command\fP is one of the following. +In most cases a \fIlist\fP in a command's description may be separated from +the rest of the command by one or more newlines, and may be followed by a +newline in place of a semicolon. +.TP +(\fIlist\fP) +\fIlist\fP is executed in a subshell (see +.SM +\fBCOMMAND EXECUTION ENVIRONMENT\fP +below for a description of a subshell environment). +Variable assignments and builtin +commands that affect the shell's environment do not remain in effect +after the command completes. The return status is the exit status of +\fIlist\fP. +.TP +{ \fIlist\fP; } +\fIlist\fP is simply executed in the current shell environment. +\fIlist\fP must be terminated with a newline or semicolon. +This is known as a \fIgroup command\fP. +The return status is the exit status of +\fIlist\fP. +Note that unlike the metacharacters \fB(\fP and \fB)\fP, \fB{\fP and +\fB}\fP are \fIreserved words\fP and must occur where a reserved +word is permitted to be recognized. Since they do not cause a word +break, they must be separated from \fIlist\fP by whitespace or another +shell metacharacter. +.TP +((\fIexpression\fP)) +The \fIexpression\fP is evaluated according to the rules described +below under +.SM +.BR "ARITHMETIC EVALUATION" . +If the value of the expression is non-zero, the return status is 0; +otherwise the return status is 1. +The \fIexpression\fP +undergoes the same expansions +as if it were within double quotes, +but double quote characters in \fIexpression\fP are not treated specially +and are removed. +.TP +\fB[[\fP \fIexpression\fP \fB]]\fP +Return a status of 0 or 1 depending on the evaluation of +the conditional expression \fIexpression\fP. +Expressions are composed of the primaries described below under +.SM +.BR "CONDITIONAL EXPRESSIONS" . +The words between the \fB[[\fP and \fB]]\fP do not undergo word splitting +and pathname expansion. +The shell performs tilde expansion, parameter and +variable expansion, arithmetic expansion, command substitution, process +substitution, and quote removal on those words +(the expansions that would occur if the words were enclosed in double quotes). +Conditional operators such as \fB\-f\fP must be unquoted to be recognized +as primaries. +.if t .sp 0.5 +.if n .sp 1 +When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort +lexicographically using the current locale. +.if t .sp 0.5 +.if n .sp 1 +When the \fB==\fP and \fB!=\fP operators are used, the string to the +right of the operator is considered a pattern and matched according +to the rules described below under \fBPattern Matching\fP, +as if the \fBextglob\fP shell option were enabled. +The \fB=\fP operator is equivalent to \fB==\fP. +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +The return value is 0 if the string matches (\fB==\fP) or does not match +(\fB!=\fP) the pattern, and 1 otherwise. +Any part of the pattern may be quoted to force the quoted portion +to be matched as a string. +.if t .sp 0.5 +.if n .sp 1 +An additional binary operator, \fB=~\fP, is available, with the same +precedence as \fB==\fP and \fB!=\fP. +When it is used, the string to the right of the operator is considered +a POSIX extended regular expression and matched accordingly +(using the POSIX \fIregcomp\fP and \fIregexec\fP interfaces +usually described in \fIregex\fP(3)). +The return value is 0 if the string matches +the pattern, and 1 otherwise. +If the regular expression is syntactically incorrect, the conditional +expression's return value is 2. +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +If any part of the pattern is quoted, the quoted portion is matched literally. +This means every character in the quoted portion matches itself, +instead of having any special pattern matching meaning. +If the pattern is stored in a shell variable, quoting the variable +expansion forces the entire pattern to be matched literally. +Treat bracket expressions in regular expressions carefully, +since normal quoting and pattern characters lose their meanings +between brackets. +.if t .sp 0.5 +.if n .sp 1 +The pattern will match if it matches any part of the string. +Anchor the pattern using the \fB^\fP and \fB$\fP regular expression +operators to force it to match the entire string. +The array variable +.SM +.B BASH_REMATCH +records which parts of the string matched the pattern. +The element of +.SM +.B BASH_REMATCH +with index 0 contains the portion of +the string matching the entire regular expression. +Substrings matched by parenthesized subexpressions within the regular +expression are saved in the remaining +.SM +.B BASH_REMATCH +indices. The element of +.SM +.B BASH_REMATCH +with index \fIn\fP is the portion of the +string matching the \fIn\fPth parenthesized subexpression. +Bash sets +.SM +.B BASH_REMATCH +in the global scope; declaring it as a local variable will lead to +unexpected results. +.if t .sp 0.5 +.if n .sp 1 +Expressions may be combined using the following operators, listed +in decreasing order of precedence: +.if t .sp 0.5 +.if n .sp 1 +.RS +.PD 0 +.TP +.B ( \fIexpression\fP ) +Returns the value of \fIexpression\fP. +This may be used to override the normal precedence of operators. +.TP +.B ! \fIexpression\fP +True if +.I expression +is false. +.TP +\fIexpression1\fP \fB&&\fP \fIexpression2\fP +True if both +.I expression1 +and +.I expression2 +are true. +.TP +\fIexpression1\fP \fB||\fP \fIexpression2\fP +True if either +.I expression1 +or +.I expression2 +is true. +.PD +.LP +The \fB&&\fP and \fB||\fP +operators do not evaluate \fIexpression2\fP if the value of +\fIexpression1\fP is sufficient to determine the return value of +the entire conditional expression. +.RE +.TP +\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP ; \fBdone\fP +The list of words following \fBin\fP is expanded, generating a list +of items. +The variable \fIname\fP is set to each element of this list +in turn, and \fIlist\fP is executed each time. +If the \fBin\fP \fIword\fP is omitted, the \fBfor\fP command executes +\fIlist\fP once for each positional parameter that is set (see +.SM +.B PARAMETERS +below). +The return status is the exit status of the last command that executes. +If the expansion of the items following \fBin\fP results in an empty +list, no commands are executed, and the return status is 0. +.TP +\fBfor\fP (( \fIexpr1\fP ; \fIexpr2\fP ; \fIexpr3\fP )) ; \fBdo\fP \fIlist\fP ; \fBdone\fP +First, the arithmetic expression \fIexpr1\fP is evaluated according +to the rules described below under +.SM +.BR "ARITHMETIC EVALUATION" . +The arithmetic expression \fIexpr2\fP is then evaluated repeatedly +until it evaluates to zero. +Each time \fIexpr2\fP evaluates to a non-zero value, \fIlist\fP is +executed and the arithmetic expression \fIexpr3\fP is evaluated. +If any expression is omitted, it behaves as if it evaluates to 1. +The return value is the exit status of the last command in \fIlist\fP +that is executed, or false if any of the expressions is invalid. +.TP +\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP ] ; \fBdo\fP \fIlist\fP ; \fBdone\fP +The list of words following \fBin\fP is expanded, generating a list +of items, and the set of expanded words is printed on the standard +error, each preceded by a number. If the \fBin\fP +\fIword\fP is omitted, the positional parameters are printed (see +.SM +.B PARAMETERS +below). +.B select +then displays the +.SM +.B PS3 +prompt and reads a line from the standard input. +If the line consists of a number corresponding to one of +the displayed words, then the value of +.I name +is set to that word. +If the line is empty, the words and prompt are displayed again. +If EOF is read, the \fBselect\fP command completes and returns 1. +Any other value read causes +.I name +to be set to null. The line read is saved in the variable +.SM +.BR REPLY . +The +.I list +is executed after each selection until a +.B break +command is executed. +The exit status of +.B select +is the exit status of the last command executed in +.IR list , +or zero if no commands were executed. +.TP +\fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \ +... ) \fIlist\fP ;; ] ... \fBesac\fP +A \fBcase\fP command first expands \fIword\fP, and tries to match +it against each \fIpattern\fP in turn, using the matching rules +described under +.B Pattern Matching +below. +The \fIword\fP is expanded using tilde +expansion, parameter and variable expansion, arithmetic expansion, +command substitution, process substitution and quote removal. +Each \fIpattern\fP examined is expanded using tilde +expansion, parameter and variable expansion, arithmetic expansion, +command substitution, process substitution, and quote removal. +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +When a match is found, the corresponding \fIlist\fP is executed. +If the \fB;;\fP operator is used, no subsequent matches are attempted after +the first pattern match. +Using \fB;&\fP in place of \fB;;\fP causes execution to continue with +the \fIlist\fP associated with the next set of patterns. +Using \fB;;&\fP in place of \fB;;\fP causes the shell to test the next +pattern list in the statement, if any, and execute any associated \fIlist\fP +on a successful match, +continuing the case statement execution as if the pattern list had not matched. +The exit status is zero if no +pattern matches. Otherwise, it is the exit status of the +last command executed in \fIlist\fP. +.TP +\fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \ +[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \ +[ \fBelse\fP \fIlist\fP; ] \fBfi\fP +The +.B if +.I list +is executed. If its exit status is zero, the +\fBthen\fP \fIlist\fP is executed. Otherwise, each \fBelif\fP +\fIlist\fP is executed in turn, and if its exit status is zero, +the corresponding \fBthen\fP \fIlist\fP is executed and the +command completes. Otherwise, the \fBelse\fP \fIlist\fP is +executed, if present. The exit status is the exit status of the +last command executed, or zero if no condition tested true. +.TP +\fBwhile\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP +.PD 0 +.TP +\fBuntil\fP \fIlist-1\fP; \fBdo\fP \fIlist-2\fP; \fBdone\fP +.PD +The \fBwhile\fP command continuously executes the list +\fIlist-2\fP as long as the last command in the list \fIlist-1\fP returns +an exit status of zero. The \fBuntil\fP command is identical +to the \fBwhile\fP command, except that the test is negated: +.I list-2 +is executed as long as the last command in +.I list-1 +returns a non-zero exit status. +The exit status of the \fBwhile\fP and \fBuntil\fP commands +is the exit status +of the last command executed in \fIlist-2\fP, or zero if +none was executed. +.SS Coprocesses +A \fIcoprocess\fP is a shell command preceded by the \fBcoproc\fP reserved +word. +A coprocess is executed asynchronously in a subshell, as if the command +had been terminated with the \fB&\fP control operator, with a two-way pipe +established between the executing shell and the coprocess. +.PP +The syntax for a coprocess is: +.RS +.PP +\fBcoproc\fP [\fINAME\fP] \fIcommand\fP [\fIredirections\fP] +.RE +.PP +This creates a coprocess named \fINAME\fP. +\fIcommand\fP may be either a simple command or a compound +command (see above). +\fINAME\fP is a shell variable name. +If \fINAME\fP is not supplied, the default name is \fBCOPROC\fP. +.PP +The recommended form to use for a coprocess is +.RS +.PP +\fBcoproc\fP \fINAME\fP { \fIcommand\fP [\fIredirections\fP]; } +.RE +.PP +This form is recommended because simple commands result in the coprocess +always being named \fBCOPROC\fP, and it is simpler to use and more complete +than the other compound commands. +.PP +If \fIcommand\fP is a compound command, \fINAME\fP is optional. The +word following \fBcoproc\fP determines whether that word is interpreted +as a variable name: it is interpreted as \fINAME\fP if it is not a +reserved word that introduces a compound command. +If \fIcommand\fP is a simple command, \fINAME\fP is not allowed; this +is to avoid confusion between \fINAME\fP and the first word of the simple +command. +.PP +When the coprocess is executed, the shell creates an array variable (see +.B Arrays +below) named \fINAME\fP in the context of the executing shell. +The standard output of +.I command +is connected via a pipe to a file descriptor in the executing shell, +and that file descriptor is assigned to \fINAME\fP[0]. +The standard input of +.I command +is connected via a pipe to a file descriptor in the executing shell, +and that file descriptor is assigned to \fINAME\fP[1]. +This pipe is established before any redirections specified by the +command (see +.SM +.B REDIRECTION +below). +The file descriptors can be utilized as arguments to shell commands +and redirections using standard word expansions. +Other than those created to execute command and process substitutions, +the file descriptors are not available in subshells. +.PP +The process ID of the shell spawned to execute the coprocess is +available as the value of the variable \fINAME\fP_PID. +The \fBwait\fP +builtin command may be used to wait for the coprocess to terminate. +.PP +Since the coprocess is created as an asynchronous command, +the \fBcoproc\fP command always returns success. +The return status of a coprocess is the exit status of \fIcommand\fP. +.SS Shell Function Definitions +A shell function is an object that is called like a simple command and +executes a compound command with a new set of positional parameters. +Shell functions are declared as follows: +.TP +\fIfname\fP () \fIcompound\-command\fP [\fIredirection\fP] +.PD 0 +.TP +\fBfunction\fP \fIfname\fP [()] \fIcompound\-command\fP [\fIredirection\fP] +.PD +This defines a function named \fIfname\fP. +The reserved word \fBfunction\fP is optional. +If the \fBfunction\fP reserved word is supplied, the parentheses are optional. +The \fIbody\fP of the function is the compound command +.I compound\-command +(see \fBCompound Commands\fP above). +That command is usually a \fIlist\fP of commands between { and }, but +may be any command listed under \fBCompound Commands\fP above. +If the \fBfunction\fP reserved word is used, but the +parentheses are not supplied, the braces are recommended. +\fIcompound\-command\fP is executed whenever \fIfname\fP is specified as the +name of a simple command. +When in \fIposix mode\fP, \fIfname\fP must be a valid shell \fIname\fP +and may not be the name of one of the +POSIX \fIspecial builtins\fP. +In default mode, a function name can be any unquoted shell word that does +not contain \fB$\fP. +Any redirections (see +.SM +.B REDIRECTION +below) specified when a function is defined are performed +when the function is executed. +The exit status of a function definition is zero unless a syntax error +occurs or a readonly function with the same name already exists. +When executed, the exit status of a function is the exit status of the +last command executed in the body. (See +.SM +.B FUNCTIONS +below.) +.SH COMMENTS +In a non-interactive shell, or an interactive shell in which the +.B interactive_comments +option to the +.B shopt +builtin is enabled (see +.SM +.B "SHELL BUILTIN COMMANDS" +below), a word beginning with +.B # +causes that word and all remaining characters on that line to +be ignored. An interactive shell without the +.B interactive_comments +option enabled does not allow comments. The +.B interactive_comments +option is on by default in interactive shells. +.SH QUOTING +\fIQuoting\fP is used to remove the special meaning of certain +characters or words to the shell. Quoting can be used to +disable special treatment for special characters, to prevent +reserved words from being recognized as such, and to prevent +parameter expansion. +.PP +Each of the \fImetacharacters\fP listed above under +.SM +.B DEFINITIONS +has special meaning to the shell and must be quoted if it is to +represent itself. +.PP +When the command history expansion facilities are being used +(see +.SM +.B HISTORY EXPANSION +below), the +\fIhistory expansion\fP character, usually \fB!\fP, must be quoted +to prevent history expansion. +.PP +There are three quoting mechanisms: the +.IR "escape character" , +single quotes, and double quotes. +.PP +A non-quoted backslash (\fB\e\fP) is the +.IR "escape character" . +It preserves the literal value of the next character that follows, +with the exception of <newline>. If a \fB\e\fP<newline> pair +appears, and the backslash is not itself quoted, the \fB\e\fP<newline> +is treated as a line continuation (that is, it is removed from the +input stream and effectively ignored). +.PP +Enclosing characters in single quotes preserves the literal value +of each character within the quotes. A single quote may not occur +between single quotes, even when preceded by a backslash. +.PP +Enclosing characters in double quotes preserves the literal value +of all characters within the quotes, with the exception of +.BR $ , +.BR \` , +.BR \e , +and, when history expansion is enabled, +.BR ! . +When the shell is in \fIposix mode\fP, the \fB!\fP has no special meaning +within double quotes, even when history expansion is enabled. +The characters +.B $ +and +.B \` +retain their special meaning within double quotes. The backslash +retains its special meaning only when followed by one of the following +characters: +.BR $ , +.BR \` , +\^\fB"\fP\^, +.BR \e , +or +.BR <newline> . +A double quote may be quoted within double quotes by preceding it with +a backslash. +If enabled, history expansion will be performed unless an +.B ! +appearing in double quotes is escaped using a backslash. +The backslash preceding the +.B ! +is not removed. +.PP +The special parameters +.B * +and +.B @ +have special meaning when in double +quotes (see +.SM +.B PARAMETERS +below). +.PP +Character sequences of the form \fB$\fP\(aq\fIstring\fP\(aq are treated +as a special variant of single quotes. +The sequence expands to \fIstring\fP, with backslash-escaped characters +in \fIstring\fP replaced as specified by the ANSI C standard. +Backslash escape sequences, if present, are decoded as follows: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ee +.TP +.B \eE +an escape character +.TP +.B \ef +form feed +.TP +.B \en +new line +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\e +backslash +.TP +.B \e\(aq +single quote +.TP +.B \e\(dq +double quote +.TP +.B \e? +question mark +.TP +.B \e\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(one to three octal digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.TP +.B \eu\fIHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHH\fP (one to four hex digits) +.TP +.B \eU\fIHHHHHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHHHHHH\fP (one to eight hex digits) +.TP +.B \ec\fIx\fP +a control-\fIx\fP character +.PD +.RE +.LP +The expanded result is single-quoted, as if the dollar sign had +not been present. +.PP +A double-quoted string preceded by a dollar sign (\fB$\fP\(dq\fIstring\fP\(dq) +will cause the string to be translated according to the current locale. +The \fIgettext\fP infrastructure performs the lookup and +translation, using the \fBLC_MESSAGES\fP, \fBTEXTDOMAINDIR\fP, +and \fBTEXTDOMAIN\fP shell variables. +If the current locale is \fBC\fP or \fBPOSIX\fP, +if there are no translations available, +or if the string is not translated, +the dollar sign is ignored. +This is a form of double quoting, so the string remains double-quoted +by default, whether or not it is translated and replaced. +If the \fBnoexpand_translation\fP option is enabled +using the \fBshopt\fP builtin, +translated strings are single-quoted instead of double-quoted. +See the description of +.B shopt +below under +.SM +.BR SHELL BUILTIN COMMANDS . +.SH PARAMETERS +A +.I parameter +is an entity that stores values. +It can be a +.IR name , +a number, or one of the special characters listed below under +.BR "Special Parameters" . +A +.I variable +is a parameter denoted by a +.IR name . +A variable has a \fIvalue\fP and zero or more \fIattributes\fP. +Attributes are assigned using the +.B declare +builtin command (see +.B declare +below in +.SM +.BR "SHELL BUILTIN COMMANDS" ). +.PP +A parameter is set if it has been assigned a value. The null string is +a valid value. Once a variable is set, it may be unset only by using +the +.B unset +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.PP +A +.I variable +may be assigned to by a statement of the form +.RS +.PP +\fIname\fP=[\fIvalue\fP] +.RE +.PP +If +.I value +is not given, the variable is assigned the null string. All +.I values +undergo tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote +removal (see +.SM +.B EXPANSION +below). If the variable has its +.B integer +attribute set, then +.I value +is evaluated as an arithmetic expression even if the $((...)) expansion is +not used (see +.B "Arithmetic Expansion" +below). +Word splitting and pathname expansion are not performed. +Assignment statements may also appear as arguments to the +.BR alias , +.BR declare , +.BR typeset , +.BR export , +.BR readonly , +and +.B local +builtin commands (\fIdeclaration\fP commands). +When in \fIposix mode\fP, these builtins may appear in a command after +one or more instances of the \fBcommand\fP builtin and retain these +assignment statement properties. +.PP +In the context where an assignment statement is assigning a value +to a shell variable or array index, the += operator can be used to +append to or add to the variable's previous value. +This includes arguments to builtin commands such as \fBdeclare\fP that +accept assignment statements (\fIdeclaration\fP commands). +When += is applied to a variable for which the \fBinteger\fP attribute has been +set, \fIvalue\fP is evaluated as an arithmetic expression and added to the +variable's current value, which is also evaluated. +When += is applied to an array variable using compound assignment (see +.B Arrays +below), the +variable's value is not unset (as it is when using =), and new values are +appended to the array beginning at one greater than the array's maximum index +(for indexed arrays) or added as additional key\-value pairs in an +associative array. +When applied to a string-valued variable, \fIvalue\fP is expanded and +appended to the variable's value. +.PP +A variable can be assigned the \fInameref\fP attribute using the +\fB\-n\fP option to the \fBdeclare\fP or \fBlocal\fP builtin commands +(see the descriptions of \fBdeclare\fP and \fBlocal\fP below) +to create a \fInameref\fP, or a reference to another variable. +This allows variables to be manipulated indirectly. +Whenever the nameref variable is referenced, assigned to, unset, or has +its attributes modified (other than using or changing the \fInameref\fP +attribute itself), the +operation is actually performed on the variable specified by the nameref +variable's value. +A nameref is commonly used within shell functions to refer to a variable +whose name is passed as an argument to the function. +For instance, if a variable name is passed to a shell function as its first +argument, running +.sp .5 +.RS +.if t \f(CWdeclare -n ref=$1\fP +.if n declare -n ref=$1 +.RE +.sp .5 +inside the function creates a nameref variable \fBref\fP whose value is +the variable name passed as the first argument. +References and assignments to \fBref\fP, and changes to its attributes, +are treated as references, assignments, and attribute modifications +to the variable whose name was passed as \fB$1\fP. +If the control variable in a \fBfor\fP loop has the nameref attribute, +the list of words can be a list of shell variables, and a name reference +will be established for each word in the list, in turn, when the loop is +executed. +Array variables cannot be given the \fBnameref\fP attribute. +However, nameref variables can reference array variables and subscripted +array variables. +Namerefs can be unset using the \fB\-n\fP option to the \fBunset\fP builtin. +Otherwise, if \fBunset\fP is executed with the name of a nameref variable +as an argument, the variable referenced by the nameref variable will be unset. +.SS Positional Parameters +A +.I positional parameter +is a parameter denoted by one or more +digits, other than the single digit 0. Positional parameters are +assigned from the shell's arguments when it is invoked, +and may be reassigned using the +.B set +builtin command. Positional parameters may not be assigned to +with assignment statements. The positional parameters are +temporarily replaced when a shell function is executed (see +.SM +.B FUNCTIONS +below). +.PP +When a positional parameter consisting of more than a single +digit is expanded, it must be enclosed in braces (see +.SM +.B EXPANSION +below). +.SS Special Parameters +The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. +.PD 0 +.TP +.B * +Expands to the positional parameters, starting from one. +When the expansion is not within double quotes, each positional parameter +expands to a separate word. +In contexts where it is performed, those words +are subject to further word splitting and pathname expansion. +When the expansion occurs within double quotes, it expands to a single word +with the value of each parameter separated by the first character of the +.SM +.B IFS +special variable. That is, "\fB$*\fP" is equivalent +to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where +.I c +is the first character of the value of the +.SM +.B IFS +variable. If +.SM +.B IFS +is unset, the parameters are separated by spaces. +If +.SM +.B IFS +is null, the parameters are joined without intervening separators. +.TP +.B @ +Expands to the positional parameters, starting from one. +In contexts where word splitting is performed, this expands each +positional parameter to a separate word; if not within double +quotes, these words are subject to word splitting. +In contexts where word splitting is not performed, +this expands to a single word +with each positional parameter separated by a space. +When the +expansion occurs within double quotes, each parameter expands to a +separate word. That is, "\fB$@\fP" is equivalent to +"\fB$1\fP" "\fB$2\fP" ... +If the double-quoted expansion occurs within a word, the expansion of +the first parameter is joined with the beginning part of the original +word, and the expansion of the last parameter is joined with the last +part of the original word. +When there are no positional parameters, "\fB$@\fP" and +.B $@ +expand to nothing (i.e., they are removed). +.TP +.B # +Expands to the number of positional parameters in decimal. +.TP +.B ? +Expands to the exit status of the most recently executed foreground +pipeline. +.TP +.B \- +Expands to the current option flags as specified upon invocation, +by the +.B set +builtin command, or those set by the shell itself +(such as the +.B \-i +option). +.TP +.B $ +Expands to the process ID of the shell. In a subshell, it +expands to the process ID of the current shell, not the +subshell. +.TP +.B ! +Expands to the process ID of the job most recently placed into the +background, whether executed as an asynchronous command or using +the \fBbg\fP builtin (see +.SM +.B "JOB CONTROL" +below). +.TP +.B 0 +Expands to the name of the shell or shell script. This is set at +shell initialization. If +.B bash +is invoked with a file of commands, +.B $0 +is set to the name of that file. If +.B bash +is started with the +.B \-c +option, then +.B $0 +is set to the first argument after the string to be +executed, if one is present. Otherwise, it is set +to the filename used to invoke +.BR bash , +as given by argument zero. +.PD +.SS Shell Variables +The following variables are set by the shell: +.PP +.PD 0 +.TP +.B _ +At shell startup, set to the pathname used to invoke the +shell or shell script being executed as passed in the environment +or argument list. +Subsequently, expands to the last argument to the previous simple +command executed in the foreground, after expansion. +Also set to the full pathname used to invoke each command executed +and placed in the environment exported to that command. +When checking mail, this parameter holds the name of the mail file +currently being checked. +.TP +.B BASH +Expands to the full filename used to invoke this instance of +.BR bash . +.TP +.B BASHOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the +.B \-s +option to the +.B shopt +builtin command (see +.SM +.B "SHELL BUILTIN COMMANDS" +below). The options appearing in +.SM +.B BASHOPTS +are those reported as +.I on +by \fBshopt\fP. +If this variable is in the environment when +.B bash +starts up, each shell option in the list will be enabled before +reading any startup files. +This variable is read-only. +.TP +.B BASHPID +Expands to the process ID of the current \fBbash\fP process. +This differs from \fB$$\fP under certain circumstances, such as subshells +that do not require \fBbash\fP to be re-initialized. +Assignments to +.SM +.B BASHPID +have no effect. +If +.B BASHPID +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_ALIASES +An associative array variable whose members correspond to the internal +list of aliases as maintained by the \fBalias\fP builtin. +Elements added to this array appear in the alias list; however, +unsetting array elements currently does not cause aliases to be removed +from the alias list. +If +.B BASH_ALIASES +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_ARGC +An array variable whose values are the number of parameters in each +frame of the current \fBbash\fP execution call stack. +The number of +parameters to the current subroutine (shell function or script executed +with \fB.\fP or \fBsource\fP) is at the top of the stack. +When a subroutine is executed, the number of parameters passed is pushed onto +.SM +.BR BASH_ARGC . +The shell sets +.SM +.B BASH_ARGC +only when in extended debugging mode (see the description of the +.B extdebug +option to the +.B shopt +builtin below). +Setting \fBextdebug\fP after the shell has started to execute a script, +or referencing this variable when \fBextdebug\fP is not set, +may result in inconsistent values. +.TP +.B BASH_ARGV +An array variable containing all of the parameters in the current \fBbash\fP +execution call stack. The final parameter of the last subroutine call +is at the top of the stack; the first parameter of the initial call is +at the bottom. When a subroutine is executed, the parameters supplied +are pushed onto +.SM +.BR BASH_ARGV . +The shell sets +.SM +.B BASH_ARGV +only when in extended debugging mode +(see the description of the +.B extdebug +option to the +.B shopt +builtin below). +Setting \fBextdebug\fP after the shell has started to execute a script, +or referencing this variable when \fBextdebug\fP is not set, +may result in inconsistent values. +.TP +.B BASH_ARGV0 +When referenced, this variable expands to the name of the shell or shell +script (identical to +.BR $0 ; +see the description of special parameter 0 above). +Assignment to +.B BASH_ARGV0 +causes the value assigned to also be assigned to \fB$0\fP. +If +.B BASH_ARGV0 +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_CMDS +An associative array variable whose members correspond to the internal +hash table of commands as maintained by the \fBhash\fP builtin. +Elements added to this array appear in the hash table; however, +unsetting array elements currently does not cause command names to be removed +from the hash table. +If +.B BASH_CMDS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_COMMAND +The command currently being executed or about to be executed, unless the +shell is executing a command as the result of a trap, +in which case it is the command executing at the time of the trap. +If +.B BASH_COMMAND +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_EXECUTION_STRING +The command argument to the \fB\-c\fP invocation option. +.TP +.B BASH_LINENO +An array variable whose members are the line numbers in source files +where each corresponding member of +.SM +.B FUNCNAME +was invoked. +\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP is the line number in the source +file (\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP) where +\fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called +(or \fB${BASH_LINENO[\fP\fI$i-1\fP\fB]}\fP if referenced within another +shell function). +Use +.SM +.B LINENO +to obtain the current line number. +.TP +.B BASH_LOADABLES_PATH +A colon-separated list of directories in which the shell looks for +dynamically loadable builtins specified by the +.B enable +command. +.TP +.B BASH_REMATCH +An array variable whose members are assigned by the \fB=~\fP binary +operator to the \fB[[\fP conditional command. +The element with index 0 is the portion of the string +matching the entire regular expression. +The element with index \fIn\fP is the portion of the +string matching the \fIn\fPth parenthesized subexpression. +.TP +.B BASH_SOURCE +An array variable whose members are the source filenames +where the corresponding shell function names in the +.SM +.B FUNCNAME +array variable are defined. +The shell function +\fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP is defined in the file +\fB${BASH_SOURCE[\fP\fI$i\fP\fB]}\fP and called from +\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP. +.TP +.B BASH_SUBSHELL +Incremented by one within each subshell or subshell environment when +the shell begins executing in that environment. +The initial value is 0. +If +.B BASH_SUBSHELL +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B BASH_VERSINFO +A readonly array variable whose members hold version information for +this instance of +.BR bash . +The values assigned to the array members are as follows: +.sp .5 +.RS +.TP 24 +.B BASH_VERSINFO[\fR0\fP] +The major version number (the \fIrelease\fP). +.TP +.B BASH_VERSINFO[\fR1\fP] +The minor version number (the \fIversion\fP). +.TP +.B BASH_VERSINFO[\fR2\fP] +The patch level. +.TP +.B BASH_VERSINFO[\fR3\fP] +The build version. +.TP +.B BASH_VERSINFO[\fR4\fP] +The release status (e.g., \fIbeta1\fP). +.TP +.B BASH_VERSINFO[\fR5\fP] +The value of +.SM +.BR MACHTYPE . +.RE +.TP +.B BASH_VERSION +Expands to a string describing the version of this instance of +.BR bash . +.TP +.B COMP_CWORD +An index into \fB${COMP_WORDS}\fP of the word containing the current +cursor position. +This variable is available only in shell functions invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_KEY +The key (or final key of a key sequence) used to invoke the current +completion function. +.TP +.B COMP_LINE +The current command line. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_POINT +The index of the current cursor position relative to the beginning of +the current command. +If the current cursor position is at the end of the current command, +the value of this variable is equal to \fB${#COMP_LINE}\fP. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_TYPE +Set to an integer value corresponding to the type of completion attempted +that caused a completion function to be called: +\fITAB\fP, for normal completion, +\fI?\fP, for listing completions after successive tabs, +\fI!\fP, for listing alternatives on partial word completion, +\fI@\fP, to list completions if the word is not unmodified, +or +\fI%\fP, for menu completion. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COMP_WORDBREAKS +The set of characters that the \fBreadline\fP library treats as word +separators when performing word completion. +If +.SM +.B COMP_WORDBREAKS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B COMP_WORDS +An array variable (see \fBArrays\fP below) consisting of the individual +words in the current command line. +The line is split into words as \fBreadline\fP would split it, using +.SM +.B COMP_WORDBREAKS +as described above. +This variable is available only in shell functions invoked by the +programmable completion facilities (see \fBProgrammable Completion\fP +below). +.TP +.B COPROC +An array variable (see \fBArrays\fP below) created to hold the file descriptors +for output from and input to an unnamed coprocess (see \fBCoprocesses\fP +above). +.TP +.B DIRSTACK +An array variable (see +.B Arrays +below) containing the current contents of the directory stack. +Directories appear in the stack in the order they are displayed by the +.B dirs +builtin. +Assigning to members of this array variable may be used to modify +directories already in the stack, but the +.B pushd +and +.B popd +builtins must be used to add and remove directories. +Assignment to this variable will not change the current directory. +If +.SM +.B DIRSTACK +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B EPOCHREALTIME +Each time this parameter is referenced, it expands to the number of seconds +since the Unix Epoch (see \fItime\fP\fR(3)\fP) as a floating point value +with micro-second granularity. +Assignments to +.SM +.B EPOCHREALTIME +are ignored. +If +.SM +.B EPOCHREALTIME +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B EPOCHSECONDS +Each time this parameter is referenced, it expands to the number of seconds +since the Unix Epoch (see \fItime\fP\fR(3)\fP). +Assignments to +.SM +.B EPOCHSECONDS +are ignored. +If +.SM +.B EPOCHSECONDS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B EUID +Expands to the effective user ID of the current user, initialized at +shell startup. This variable is readonly. +.TP +.B FUNCNAME +An array variable containing the names of all shell functions +currently in the execution call stack. +The element with index 0 is the name of any currently-executing +shell function. +The bottom-most element (the one with the highest index) is +.if t \f(CW"main"\fP. +.if n "main". +This variable exists only when a shell function is executing. +Assignments to +.SM +.B FUNCNAME +have no effect. +If +.SM +.B FUNCNAME +is unset, it loses its special properties, even if it is +subsequently reset. +.if t .sp 0.5 +.if n .sp 1 +This variable can be used with \fBBASH_LINENO\fP and \fBBASH_SOURCE\fP. +Each element of \fBFUNCNAME\fP has corresponding elements in +\fBBASH_LINENO\fP and \fBBASH_SOURCE\fP to describe the call stack. +For instance, \fB${FUNCNAME[\fP\fI$i\fP\fB]}\fP was called from the file +\fB${BASH_SOURCE[\fP\fI$i+1\fP\fB]}\fP at line number +\fB${BASH_LINENO[\fP\fI$i\fP\fB]}\fP. +The \fBcaller\fP builtin displays the current call stack using this +information. +.TP +.B GROUPS +An array variable containing the list of groups of which the current +user is a member. +Assignments to +.SM +.B GROUPS +have no effect. +If +.SM +.B GROUPS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B HISTCMD +The history number, or index in the history list, of the current +command. +Assignments to +.SM +.B HISTCMD +are ignored. +If +.SM +.B HISTCMD +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B HOSTNAME +Automatically set to the name of the current host. +.TP +.B HOSTTYPE +Automatically set to a string that uniquely +describes the type of machine on which +.B bash +is executing. +The default is system-dependent. +.TP +.B LINENO +Each time this parameter is referenced, the shell substitutes +a decimal number representing the current sequential line number +(starting with 1) within a script or function. When not in a +script or function, the value substituted is not guaranteed to +be meaningful. +If +.SM +.B LINENO +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B MACHTYPE +Automatically set to a string that fully describes the system +type on which +.B bash +is executing, in the standard GNU \fIcpu-company-system\fP format. +The default is system-dependent. +.TP +.B MAPFILE +An array variable (see \fBArrays\fP below) created to hold the text +read by the \fBmapfile\fP builtin when no variable name is supplied. +.TP +.B OLDPWD +The previous working directory as set by the +.B cd +command. +.TP +.B OPTARG +The value of the last option argument processed by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.TP +.B OPTIND +The index of the next argument to be processed by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.TP +.B OSTYPE +Automatically set to a string that +describes the operating system on which +.B bash +is executing. +The default is system-dependent. +.TP +.B PIPESTATUS +An array variable (see +.B Arrays +below) containing a list of exit status values from the processes +in the most-recently-executed foreground pipeline (which may +contain only a single command). +.TP +.B PPID +The process ID of the shell's parent. This variable is readonly. +.TP +.B PWD +The current working directory as set by the +.B cd +command. +.TP +.B RANDOM +Each time this parameter is referenced, it expands to a random integer +between 0 and 32767. +Assigning +a value to +.SM +.BR RANDOM +initializes (seeds) the sequence of random numbers. +If +.SM +.B RANDOM +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B READLINE_ARGUMENT +Any numeric argument given to a readline command that was defined using +.if t \f(CWbind -x\fP +.if n "bind -x" +(see +.SM +.B "SHELL BUILTIN COMMANDS" +below) +when it was invoked. +.TP +.B READLINE_LINE +The contents of the +.B readline +line buffer, for use with +.if t \f(CWbind -x\fP +.if n "bind -x" +(see +.SM +.B "SHELL BUILTIN COMMANDS" +below). +.TP +.B READLINE_MARK +The position of the mark (saved insertion point) in the +.B readline +line buffer, for use with +.if t \f(CWbind -x\fP +.if n "bind -x" +(see +.SM +.B "SHELL BUILTIN COMMANDS" +below). +The characters between the insertion point and the mark are often +called the \fIregion\fP. +.TP +.B READLINE_POINT +The position of the insertion point in the +.B readline +line buffer, for use with +.if t \f(CWbind -x\fP +.if n "bind -x" +(see +.SM +.B "SHELL BUILTIN COMMANDS" +below). +.TP +.B REPLY +Set to the line of input read by the +.B read +builtin command when no arguments are supplied. +.TP +.B SECONDS +Each time this parameter is +referenced, it expands to the number of seconds since shell invocation. +If a value is assigned to +.SM +.BR SECONDS , +the value returned upon subsequent +references is +the number of seconds since the assignment plus the value assigned. +The number of seconds at shell invocation and the current time are always +determined by querying the system clock. +If +.SM +.B SECONDS +is unset, it loses its special properties, even if it is +subsequently reset. +.TP +.B SHELLOPTS +A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the +.B \-o +option to the +.B set +builtin command (see +.SM +.B "SHELL BUILTIN COMMANDS" +below). The options appearing in +.SM +.B SHELLOPTS +are those reported as +.I on +by \fBset \-o\fP. +If this variable is in the environment when +.B bash +starts up, each shell option in the list will be enabled before +reading any startup files. +This variable is read-only. +.TP +.B SHLVL +Incremented by one each time an instance of +.B bash +is started. +.TP +.B SRANDOM +This variable expands to a 32-bit pseudo-random number each time it is +referenced. The random number generator is not linear on systems that +support \f(CW/dev/urandom\fP or \fIarc4random\fP, so each returned number +has no relationship to the numbers preceding it. +The random number generator cannot be seeded, so assignments to this +variable have no effect. +If +.SM +.B SRANDOM +is unset, it loses its special properties, +even if it is subsequently reset. +.TP +.B UID +Expands to the user ID of the current user, initialized at shell startup. +This variable is readonly. +.PD +.PP +The following variables are used by the shell. In some cases, +.B bash +assigns a default value to a variable; these cases are noted +below. +.PP +.PD 0 +.TP +.B BASH_COMPAT +The value is used to set the shell's compatibility level. +See +.SM +.B "SHELL COMPATIBILITY MODE" +below for a description of the various compatibility +levels and their effects. +The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42) +corresponding to the desired compatibility level. +If \fBBASH_COMPAT\fP is unset or set to the empty string, the compatibility +level is set to the default for the current version. +If \fBBASH_COMPAT\fP is set to a value that is not one of the valid +compatibility levels, the shell prints an error message and sets the +compatibility level to the default for the current version. +The valid values correspond to the compatibility levels +described below under +.SM +.BR "SHELL COMPATIBILITY MODE" . +For example, 4.2 and 42 are valid values that correspond +to the \fBcompat42\fP \fBshopt\fP option +and set the compatibility level to 42. +The current version is also a valid value. +.TP +.B BASH_ENV +If this parameter is set when \fBbash\fP is executing a shell script, +its value is interpreted as a filename containing commands to +initialize the shell, as in +.IR ~/.bashrc . +The value of +.SM +.B BASH_ENV +is subjected to parameter expansion, command substitution, and arithmetic +expansion before being interpreted as a filename. +.SM +.B PATH +is not used to search for the resultant filename. +.TP +.B BASH_XTRACEFD +If set to an integer corresponding to a valid file descriptor, \fBbash\fP +will write the trace output generated when +.if t \f(CWset -x\fP +.if n \fIset -x\fP +is enabled to that file descriptor. +The file descriptor is closed when +.SM +.B BASH_XTRACEFD +is unset or assigned a new value. +Unsetting +.SM +.B BASH_XTRACEFD +or assigning it the empty string causes the +trace output to be sent to the standard error. +Note that setting +.SM +.B BASH_XTRACEFD +to 2 (the standard error file +descriptor) and then unsetting it will result in the standard error +being closed. +.TP +.B CDPATH +The search path for the +.B cd +command. +This is a colon-separated list of directories in which the shell looks +for destination directories specified by the +.B cd +command. +A sample value is +.if t \f(CW".:~:/usr"\fP. +.if n ".:~:/usr". +.TP +.B CHILD_MAX +Set the number of exited child status values for the shell to remember. +Bash will not allow this value to be decreased below a POSIX-mandated +minimum, and there is a maximum value (currently 8192) that this may +not exceed. +The minimum value is system-dependent. +.TP +.B COLUMNS +Used by the \fBselect\fP compound command to determine the terminal width +when printing selection lists. +Automatically set if the +.B checkwinsize +option is enabled or in an interactive shell upon receipt of a +.SM +.BR SIGWINCH . +.TP +.B COMPREPLY +An array variable from which \fBbash\fP reads the possible completions +generated by a shell function invoked by the programmable completion +facility (see \fBProgrammable Completion\fP below). +Each array element contains one possible completion. +.TP +.B EMACS +If \fBbash\fP finds this variable in the environment when the shell starts +with value +.if t \f(CWt\fP, +.if n "t", +it assumes that the shell is running in an Emacs shell buffer and disables +line editing. +.TP +.B ENV +Expanded and executed similarly to +.SM +.B BASH_ENV +(see \fBINVOCATION\fP above) +when an interactive shell is invoked in \fIposix mode\fP. +.TP +.B EXECIGNORE +A colon-separated list of shell patterns (see \fBPattern Matching\fP) +defining the list of filenames to be ignored by command search using +\fBPATH\fP. +Files whose full pathnames match one of these patterns are not considered +executable files for the purposes of completion and command execution +via \fBPATH\fP lookup. +This does not affect the behavior of the \fB[\fP, \fBtest\fP, and \fB[[\fP +commands. +Full pathnames in the command hash table are not subject to \fBEXECIGNORE\fP. +Use this variable to ignore shared library files that have the executable +bit set, but are not executable files. +The pattern matching honors the setting of the \fBextglob\fP shell +option. +.TP +.B FCEDIT +The default editor for the +.B fc +builtin command. +.TP +.B FIGNORE +A colon-separated list of suffixes to ignore when performing +filename completion (see +.SM +.B READLINE +below). +A filename whose suffix matches one of the entries in +.SM +.B FIGNORE +is excluded from the list of matched filenames. +A sample value is +.if t \f(CW".o:~"\fP. +.if n ".o:~". +.TP +.B FUNCNEST +If set to a numeric value greater than 0, defines a maximum function +nesting level. Function invocations that exceed this nesting level +will cause the current command to abort. +.TP +.B GLOBIGNORE +A colon-separated list of patterns defining the set of file names to +be ignored by pathname expansion. +If a file name matched by a pathname expansion pattern also matches one +of the patterns in +.SM +.BR GLOBIGNORE , +it is removed from the list of matches. +.TP +.B HISTCONTROL +A colon-separated list of values controlling how commands are saved on +the history list. +If the list of values includes +.IR ignorespace , +lines which begin with a +.B space +character are not saved in the history list. +A value of +.I ignoredups +causes lines matching the previous history entry to not be saved. +A value of +.I ignoreboth +is shorthand for \fIignorespace\fP and \fIignoredups\fP. +A value of +.I erasedups +causes all previous lines matching the current line to be removed from +the history list before that line is saved. +Any value not in the above list is ignored. +If +.SM +.B HISTCONTROL +is unset, or does not include a valid value, +all lines read by the shell parser are saved on the history list, +subject to the value of +.SM +.BR HISTIGNORE . +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +.SM +.BR HISTCONTROL . +.TP +.B HISTFILE +The name of the file in which command history is saved (see +.SM +.B HISTORY +below). The default value is \fI~/.bash_history\fP. If unset, the +command history is not saved when a shell exits. +.TP +.B HISTFILESIZE +The maximum number of lines contained in the history file. When this +variable is assigned a value, the history file is truncated, if +necessary, +to contain no more than that number of lines by removing the oldest entries. +The history file is also truncated to this size after +writing it when a shell exits. +If the value is 0, the history file is truncated to zero size. +Non-numeric values and numeric values less than zero inhibit truncation. +The shell sets the default value to the value of \fBHISTSIZE\fP +after reading any startup files. +.TP +.B HISTIGNORE +A colon-separated list of patterns used to decide which command lines +should be saved on the history list. Each pattern is anchored at the +beginning of the line and must match the complete line (no implicit +`\fB*\fP' is appended). Each pattern is tested against the line +after the checks specified by +.SM +.B HISTCONTROL +are applied. +In addition to the normal shell pattern matching characters, `\fB&\fP' +matches the previous history line. `\fB&\fP' may be escaped using a +backslash; the backslash is removed before attempting a match. +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +.SM +.BR HISTIGNORE . +The pattern matching honors the setting of the \fBextglob\fP shell +option. +.TP +.B HISTSIZE +The number of commands to remember in the command history (see +.SM +.B HISTORY +below). +If the value is 0, commands are not saved in the history list. +Numeric values less than zero result in every command being saved +on the history list (there is no limit). +The shell sets the default value to 500 after reading any startup files. +.TP +.B HISTTIMEFORMAT +If this variable is set and not null, its value is used as a format string +for \fIstrftime\fP(3) to print the time stamp associated with each history +entry displayed by the \fBhistory\fP builtin. +If this variable is set, time stamps are written to the history file so +they may be preserved across shell sessions. +This uses the history comment character to distinguish timestamps from +other history lines. +.TP +.B HOME +The home directory of the current user; the default argument for the +\fBcd\fP builtin command. +The value of this variable is also used when performing tilde expansion. +.TP +.B HOSTFILE +Contains the name of a file in the same format as +.FN /etc/hosts +that should be read when the shell needs to complete a +hostname. +The list of possible hostname completions may be changed while the +shell is running; +the next time hostname completion is attempted after the +value is changed, +.B bash +adds the contents of the new file to the existing list. +If +.SM +.B HOSTFILE +is set, but has no value, or does not name a readable file, +\fBbash\fP attempts to read +.FN /etc/hosts +to obtain the list of possible hostname completions. +When +.SM +.B HOSTFILE +is unset, the hostname list is cleared. +.TP +.B IFS +The +.I Internal Field Separator +that is used +for word splitting after expansion and to +split lines into words with the +.B read +builtin command. The default value is +``<space><tab><newline>''. +.TP +.B IGNOREEOF +Controls the +action of an interactive shell on receipt of an +.SM +.B EOF +character as the sole input. If set, the value is the number of +consecutive +.SM +.B EOF +characters which must be +typed as the first characters on an input line before +.B bash +exits. If the variable exists but does not have a numeric value, or +has no value, the default value is 10. If it does not exist, +.SM +.B EOF +signifies the end of input to the shell. +.TP +.B INPUTRC +The filename for the +.B readline +startup file, overriding the default of +.FN ~/.inputrc +(see +.SM +.B READLINE +below). +.TP +.B INSIDE_EMACS +If this variable appears in the environment when the shell starts, +\fBbash\fP assumes that it is running inside an Emacs shell buffer +and may disable line editing, depending on the value of \fBTERM\fP. +.TP +.B LANG +Used to determine the locale category for any category not specifically +selected with a variable starting with \fBLC_\fP. +.TP +.B LC_ALL +This variable overrides the value of +.SM +.B LANG +and any other +\fBLC_\fP variable specifying a locale category. +.TP +.B LC_COLLATE +This variable determines the collation order used when sorting the +results of pathname expansion, and determines the behavior of range +expressions, equivalence classes, and collating sequences within +pathname expansion and pattern matching. +.TP +.B LC_CTYPE +This variable determines the interpretation of characters and the +behavior of character classes within pathname expansion and pattern +matching. +.TP +.B LC_MESSAGES +This variable determines the locale used to translate double-quoted +strings preceded by a \fB$\fP. +.TP +.B LC_NUMERIC +This variable determines the locale category used for number formatting. +.TP +.B LC_TIME +This variable determines the locale category used for data and time +formatting. +.TP +.B LINES +Used by the \fBselect\fP compound command to determine the column length +for printing selection lists. +Automatically set if the +.B checkwinsize +option is enabled or in an interactive shell upon receipt of a +.SM +.BR SIGWINCH . +.TP +.B MAIL +If this parameter is set to a file or directory name and the +.SM +.B MAILPATH +variable is not set, +.B bash +informs the user of the arrival of mail in the specified file or +Maildir-format directory. +.TP +.B MAILCHECK +Specifies how +often (in seconds) +.B bash +checks for mail. The default is 60 seconds. When it is time to check +for mail, the shell does so before displaying the primary prompt. +If this variable is unset, or set to a value that is not a number +greater than or equal to zero, the shell disables mail checking. +.TP +.B MAILPATH +A colon-separated list of filenames to be checked for mail. +The message to be printed when mail arrives in a particular file +may be specified by separating the filename from the message with a `?'. +When used in the text of the message, \fB$_\fP expands to the name of +the current mailfile. +Example: +.RS +.PP +\fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":~/shell\-mail?"$_ has mail!"\(aq +.PP +.B Bash +can be configured to supply +a default value for this variable (there is no value by default), +but the location of the user +mail files that it uses is system dependent (e.g., /var/mail/\fB$USER\fP). +.RE +.TP +.B OPTERR +If set to the value 1, +.B bash +displays error messages generated by the +.B getopts +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SM +.B OPTERR +is initialized to 1 each time the shell is invoked or a shell +script is executed. +.TP +.B PATH +The search path for commands. It +is a colon-separated list of directories in which +the shell looks for commands (see +.SM +.B COMMAND EXECUTION +below). +A zero-length (null) directory name in the value of +.SM +.B PATH +indicates the current directory. +A null directory name may appear as two adjacent colons, or as an initial +or trailing colon. +The default path is system-dependent, +and is set by the administrator who installs +.BR bash . +A common value is +.na +.if t \f(CW/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin\fP. +.if n ``/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin''. +.ad +.TP +.B POSIXLY_CORRECT +If this variable is in the environment when \fBbash\fP starts, the shell +enters \fIposix mode\fP before reading the startup files, as if the +.B \-\-posix +invocation option had been supplied. If it is set while the shell is +running, \fBbash\fP enables \fIposix mode\fP, as if the command +.if t \f(CWset -o posix\fP +.if n \fIset -o posix\fP +had been executed. +When the shell enters \fIposix mode\fP, it sets this variable if it was +not already set. +.TP +.B PROMPT_COMMAND +If this variable is set, and is an array, +the value of each set element is executed as a command +prior to issuing each primary prompt. +If this is set but not an array variable, +its value is used as a command to execute instead. +.TP +.B PROMPT_DIRTRIM +If set to a number greater than zero, the value is used as the number of +trailing directory components to retain when expanding the \fB\ew\fP and +\fB\eW\fP prompt string escapes (see +.SM +.B PROMPTING +below). Characters removed are replaced with an ellipsis. +.TP +.B PS0 +The value of this parameter is expanded (see +.SM +.B PROMPTING +below) and displayed by interactive shells after reading a command +and before the command is executed. +.TP +.B PS1 +The value of this parameter is expanded (see +.SM +.B PROMPTING +below) and used as the primary prompt string. The default value is +``\fB\es\-\ev\e$ \fP''. +.TP +.B PS2 +The value of this parameter is expanded as with +.SM +.B PS1 +and used as the secondary prompt string. The default is +``\fB> \fP''. +.TP +.B PS3 +The value of this parameter is used as the prompt for the +.B select +command (see +.SM +.B SHELL GRAMMAR +above). +.TP +.B PS4 +The value of this parameter is expanded as with +.SM +.B PS1 +and the value is printed before each command +.B bash +displays during an execution trace. The first character of +the expanded value of +.SM +.B PS4 +is replicated multiple times, as necessary, to indicate multiple +levels of indirection. The default is ``\fB+ \fP''. +.TP +.B SHELL +This variable expands to the full pathname to the shell. +If it is not set when the shell starts, +.B bash +assigns to it the full pathname of the current user's login shell. +.TP +.B TIMEFORMAT +The value of this parameter is used as a format string specifying +how the timing information for pipelines prefixed with the +.B time +reserved word should be displayed. +The \fB%\fP character introduces an escape sequence that is +expanded to a time value or other information. +The escape sequences and their meanings are as follows; the +braces denote optional portions. +.sp .5 +.RS +.PD 0 +.TP 10 +.B %% +A literal \fB%\fP. +.TP +.B %[\fIp\fP][l]R +The elapsed time in seconds. +.TP +.B %[\fIp\fP][l]U +The number of CPU seconds spent in user mode. +.TP +.B %[\fIp\fP][l]S +The number of CPU seconds spent in system mode. +.TP +.B %P +The CPU percentage, computed as (%U + %S) / %R. +.PD +.RE +.IP +The optional \fIp\fP is a digit specifying the \fIprecision\fP, +the number of fractional digits after a decimal point. +A value of 0 causes no decimal point or fraction to be output. +At most three places after the decimal point may be specified; +values of \fIp\fP greater than 3 are changed to 3. +If \fIp\fP is not specified, the value 3 is used. +.IP +The optional \fBl\fP specifies a longer format, including +minutes, of the form \fIMM\fPm\fISS\fP.\fIFF\fPs. +The value of \fIp\fP determines whether or not the fraction is +included. +.IP +If this variable is not set, \fBbash\fP acts as if it had the +value \fB$\(aq\enreal\et%3lR\enuser\et%3lU\ensys\et%3lS\(aq\fP. +If the value is null, no timing information is displayed. +A trailing newline is added when the format string is displayed. +.PD 0 +.TP +.B TMOUT +If set to a value greater than zero, +.SM +.B TMOUT +is treated as the +default timeout for the \fBread\fP builtin. +The \fBselect\fP command terminates if input does not arrive +after +.SM +.B TMOUT +seconds when input is coming from a terminal. +In an interactive shell, the value is interpreted as the +number of seconds to wait for a line of input after issuing the +primary prompt. +.B Bash +terminates after waiting for that number of seconds if a complete +line of input does not arrive. +.TP +.B TMPDIR +If set, \fBbash\fP uses its value as the name of a directory in which +\fBbash\fP creates temporary files for the shell's use. +.TP +.B auto_resume +This variable controls how the shell interacts with the user and +job control. If this variable is set, single word simple +commands without redirections are treated as candidates for resumption +of an existing stopped job. There is no ambiguity allowed; if there is +more than one job beginning with the string typed, the job most recently +accessed is selected. The +.I name +of a stopped job, in this context, is the command line used to +start it. +If set to the value +.IR exact , +the string supplied must match the name of a stopped job exactly; +if set to +.IR substring , +the string supplied needs to match a substring of the name of a +stopped job. The +.I substring +value provides functionality analogous to the +.B %? +job identifier (see +.SM +.B JOB CONTROL +below). If set to any other value, the supplied string must +be a prefix of a stopped job's name; this provides functionality +analogous to the \fB%\fP\fIstring\fP job identifier. +.TP +.B histchars +The two or three characters which control history expansion +and tokenization (see +.SM +.B HISTORY EXPANSION +below). The first character is the \fIhistory expansion\fP character, +the character which signals the start of a history +expansion, normally `\fB!\fP'. +The second character is the \fIquick substitution\fP +character, which is used as shorthand for re-running the previous +command entered, substituting one string for another in the command. +The default is `\fB^\fP'. +The optional third character is the character +which indicates that the remainder of the line is a comment when found +as the first character of a word, normally `\fB#\fP'. The history +comment character causes history substitution to be skipped for the +remaining words on the line. It does not necessarily cause the shell +parser to treat the rest of the line as a comment. +.PD +.SS Arrays +.B Bash +provides one-dimensional indexed and associative array variables. +Any variable may be used as an indexed array; the +.B declare +builtin will explicitly declare an array. +There is no maximum +limit on the size of an array, nor any requirement that members +be indexed or assigned contiguously. +Indexed arrays are referenced using integers (including arithmetic +expressions) and are zero-based; associative arrays are referenced +using arbitrary strings. +Unless otherwise noted, indexed array indices must be non-negative integers. +.PP +An indexed array is created automatically if any variable is assigned to +using the syntax \fIname\fP[\fIsubscript\fP]=\fIvalue\fP. The +.I subscript +is treated as an arithmetic expression that must evaluate to a number. +To explicitly declare an indexed array, use +.B declare \-a \fIname\fP +(see +.SM +.B SHELL BUILTIN COMMANDS +below). +.B declare \-a \fIname\fP[\fIsubscript\fP] +is also accepted; the \fIsubscript\fP is ignored. +.PP +Associative arrays are created using +.BR "declare \-A \fIname\fP" . +.PP +Attributes may be +specified for an array variable using the +.B declare +and +.B readonly +builtins. Each attribute applies to all members of an array. +.PP +Arrays are assigned to using compound assignments of the form +\fIname\fP=\fB(\fPvalue\fI1\fP ... value\fIn\fP\fB)\fP, where each +\fIvalue\fP may be of the form [\fIsubscript\fP]=\fIstring\fP. +Indexed array assignments do not require anything but \fIstring\fP. +Each \fIvalue\fP in the list is expanded using all the shell expansions +described below under +.SM +.BR EXPANSION . +When assigning to indexed arrays, if the optional brackets and subscript +are supplied, that index is assigned to; +otherwise the index of the element assigned is the last index assigned +to by the statement plus one. Indexing starts at zero. +.PP +When assigning to an associative array, the words in a compound assignment +may be either assignment statements, for which the subscript is required, +or a list of words that is interpreted as a sequence of alternating keys +and values: +\fIname\fP=\fB( \fP\fIkey1 value1 key2 value2\fP ...\fB)\fP. +These are treated identically to +\fIname\fP=\fB(\fP [\fIkey1\fP]=\fIvalue1\fP [\fIkey2\fP]=\fIvalue2\fP ...\fB)\fP. +The first word in the list determines how the remaining words +are interpreted; all assignments in a list must be of the same type. +When using key/value pairs, the keys may not be missing or empty; +a final missing value is treated like the empty string. +.PP +This syntax is also accepted by the +.B declare +builtin. Individual array elements may be assigned to using the +\fIname\fP[\fIsubscript\fP]=\fIvalue\fP syntax introduced above. +When assigning to an indexed array, if +.I name +is subscripted by a negative number, that number is +interpreted as relative to one greater than the maximum index of +\fIname\fP, so negative indices count back from the end of the +array, and an index of \-1 references the last element. +.PP +The += operator will append to an array variable when assigning +using the compound assignment syntax; see +.SM +.B PARAMETERS +above. +.PP +Any element of an array may be referenced using +${\fIname\fP[\fIsubscript\fP]}. The braces are required to avoid +conflicts with pathname expansion. If +\fIsubscript\fP is \fB@\fP or \fB*\fP, the word expands to +all members of \fIname\fP. These subscripts differ only when the +word appears within double quotes. If the word is double-quoted, +${\fIname\fP[*]} expands to a single +word with the value of each array member separated by the first +character of the +.SM +.B IFS +special variable, and ${\fIname\fP[@]} expands each element of +\fIname\fP to a separate word. When there are no array members, +${\fIname\fP[@]} expands to nothing. +If the double-quoted expansion occurs within a word, the expansion of +the first parameter is joined with the beginning part of the original +word, and the expansion of the last parameter is joined with the last +part of the original word. +This is analogous to the expansion +of the special parameters \fB*\fP and \fB@\fP (see +.B Special Parameters +above). ${#\fIname\fP[\fIsubscript\fP]} expands to the length of +${\fIname\fP[\fIsubscript\fP]}. If \fIsubscript\fP is \fB*\fP or +\fB@\fP, the expansion is the number of elements in the array. +If the +.I subscript +used to reference an element of an indexed array +evaluates to a number less than zero, it is +interpreted as relative to one greater than the maximum index of the array, +so negative indices count back from the end of the +array, and an index of \-1 references the last element. +.PP +Referencing an array variable without a subscript is equivalent to +referencing the array with a subscript of 0. +Any reference to a variable using a valid subscript is legal, and +.B bash +will create an array if necessary. +.PP +An array variable is considered set if a subscript has been assigned a +value. The null string is a valid value. +.PP +It is possible to obtain the keys (indices) of an array as well as the values. +${\fB!\fP\fIname\fP[\fI@\fP]} and ${\fB!\fP\fIname\fP[\fI*\fP]} +expand to the indices assigned in array variable \fIname\fP. +The treatment when in double quotes is similar to the expansion of the +special parameters \fI@\fP and \fI*\fP within double quotes. +.PP +The +.B unset +builtin is used to destroy arrays. \fBunset\fP \fIname\fP[\fIsubscript\fP] +destroys the array element at index \fIsubscript\fP, +for both indexed and associative arrays. +Negative subscripts to indexed arrays are interpreted as described above. +Unsetting the last element of an array variable does not unset the variable. +\fBunset\fP \fIname\fP, where \fIname\fP is an array, +removes the entire array. +\fBunset\fP \fIname\fP[\fIsubscript\fP], where +\fIsubscript\fP is \fB*\fP or \fB@\fP, behaves differently depending on +whether \fIname\fP is an indexed or associative array. +If \fIname\fP is an associative array, this unsets the element with +subscript \fB*\fP or \fB@\fP. +If \fIname\fP is an indexed array, unset removes all of the elements but +does not remove the array itself. +.PP +When using a variable name with a subscript as an argument to a command, +such as with \fBunset\fP, without using the word expansion syntax +described above, the argument is subject to pathname expansion. +If pathname expansion is not desired, the argument should be quoted. +.PP +The +.BR declare , +.BR local , +and +.B readonly +builtins each accept a +.B \-a +option to specify an indexed array and a +.B \-A +option to specify an associative array. +If both options are supplied, +.B \-A +takes precedence. +The +.B read +builtin accepts a +.B \-a +option to assign a list of words read from the standard input +to an array. The +.B set +and +.B declare +builtins display array values in a way that allows them to be +reused as assignments. +.SH EXPANSION +Expansion is performed on the command line after it has been split into +words. There are seven kinds of expansion performed: +.IR "brace expansion" , +.IR "tilde expansion" , +.IR "parameter and variable expansion" , +.IR "command substitution" , +.IR "arithmetic expansion" , +.IR "word splitting" , +and +.IR "pathname expansion" . +.PP +The order of expansions is: +brace expansion; +tilde expansion, parameter and variable expansion, arithmetic expansion, +and command substitution (done in a left-to-right fashion); +word splitting; +and pathname expansion. +.PP +On systems that can support it, there is an additional expansion +available: \fIprocess substitution\fP. +This is performed at the +same time as tilde, parameter, variable, and arithmetic expansion and +command substitution. +.PP +After these expansions are performed, quote characters present in the +original word are removed unless they have been quoted themselves +(\fIquote removal\fP). +.PP +Only brace expansion, word splitting, and pathname expansion +can increase the number of words of the expansion; other expansions +expand a single word to a single word. +The only exceptions to this are the expansions of +"\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP", +and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP +as explained above (see +.SM +.BR PARAMETERS ). +.SS Brace Expansion +.I "Brace expansion" +is a mechanism by which arbitrary strings +may be generated. This mechanism is similar to +\fIpathname expansion\fP, but the filenames generated +need not exist. Patterns to be brace expanded take +the form of an optional +.IR preamble , +followed by either a series of comma-separated strings or +a sequence expression between a pair of braces, followed by +an optional +.IR postscript . +The preamble is prefixed to each string contained +within the braces, and the postscript is then appended +to each resulting string, expanding left to right. +.PP +Brace expansions may be nested. The results of each expanded +string are not sorted; left to right order is preserved. +For example, a\fB{\fPd,c,b\fB}\fPe expands into `ade ace abe'. +.PP +A sequence expression takes the form +\fB{\fP\fIx\fP\fB..\fP\fIy\fP\fB[..\fP\fIincr\fP\fB]}\fP, +where \fIx\fP and \fIy\fP are either integers or single letters, +and \fIincr\fP, an optional increment, is an integer. +When integers are supplied, the expression expands to each number between +\fIx\fP and \fIy\fP, inclusive. +Supplied integers may be prefixed with \fI0\fP to force each term to have the +same width. +When either \fIx\fP or \fPy\fP begins with a zero, the shell +attempts to force all generated terms to contain the same number of digits, +zero-padding where necessary. +When letters are supplied, the expression expands to each character +lexicographically between \fIx\fP and \fIy\fP, inclusive, +using the default C locale. +Note that both \fIx\fP and \fIy\fP must be of the same type +(integer or letter). +When the increment is supplied, it is used as the difference between +each term. The default increment is 1 or \-1 as appropriate. +.PP +Brace expansion is performed before any other expansions, +and any characters special to other expansions are preserved +in the result. It is strictly textual. +.B Bash +does not apply any syntactic interpretation to the context of the +expansion or the text between the braces. +.PP +A correctly-formed brace expansion must contain unquoted opening +and closing braces, and at least one unquoted comma or a valid +sequence expression. +Any incorrectly formed brace expansion is left unchanged. +A \fB{\fP or \fB,\fP may be quoted with a backslash to prevent its +being considered part of a brace expression. +To avoid conflicts with parameter expansion, the string \fB${\fP +is not considered eligible for brace expansion, and inhibits brace +expansion until the closing \fB}\fP. +.PP +This construct is typically used as shorthand when the common +prefix of the strings to be generated is longer than in the +above example: +.RS +.PP +mkdir /usr/local/src/bash/{old,new,dist,bugs} +.RE +or +.RS +chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} +.RE +.PP +Brace expansion introduces a slight incompatibility with +historical versions of +.BR sh . +.B sh +does not treat opening or closing braces specially when they +appear as part of a word, and preserves them in the output. +.B Bash +removes braces from words as a consequence of brace +expansion. For example, a word entered to +.B sh +as \fIfile{1,2}\fP +appears identically in the output. The same word is +output as +.I file1 file2 +after expansion by +.BR bash . +If strict compatibility with +.B sh +is desired, start +.B bash +with the +.B +B +option or disable brace expansion with the +.B +B +option to the +.B set +command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SS Tilde Expansion +If a word begins with an unquoted tilde character (`\fB~\fP'), all of +the characters preceding the first unquoted slash (or all characters, +if there is no unquoted slash) are considered a \fItilde-prefix\fP. +If none of the characters in the tilde-prefix are quoted, the +characters in the tilde-prefix following the tilde are treated as a +possible \fIlogin name\fP. +If this login name is the null string, the tilde is replaced with the +value of the shell parameter +.SM +.BR HOME . +If +.SM +.B HOME +is unset, the home directory of the user executing the shell is +substituted instead. +Otherwise, the tilde-prefix is replaced with the home directory +associated with the specified login name. +.PP +If the tilde-prefix is a `~+', the value of the shell variable +.SM +.B PWD +replaces the tilde-prefix. +If the tilde-prefix is a `~\-', the value of the shell variable +.SM +.BR OLDPWD , +if it is set, is substituted. +If the characters following the tilde in the tilde-prefix consist +of a number \fIN\fP, optionally prefixed +by a `+' or a `\-', the tilde-prefix is replaced with the corresponding +element from the directory stack, as it would be displayed by the +.B dirs +builtin invoked with the tilde-prefix as an argument. +If the characters following the tilde in the tilde-prefix consist of a +number without a leading `+' or `\-', `+' is assumed. +.PP +If the login name is invalid, or the tilde expansion fails, the word +is unchanged. +.PP +Each variable assignment is checked for unquoted tilde-prefixes immediately +following a +.B : +or the first +.BR = . +In these cases, tilde expansion is also performed. +Consequently, one may use filenames with tildes in assignments to +.SM +.BR PATH , +.SM +.BR MAILPATH , +and +.SM +.BR CDPATH , +and the shell assigns the expanded value. +.PP +Bash also performs tilde expansion on words satisfying the conditions of +variable assignments (as described above under +.SM +.BR PARAMETERS ) +when they appear as arguments to simple commands. +Bash does not do this, except for the \fIdeclaration\fP commands listed +above, when in \fIposix mode\fP. +.SS Parameter Expansion +The `\fB$\fP' character introduces parameter expansion, +command substitution, or arithmetic expansion. The parameter name +or symbol to be expanded may be enclosed in braces, which +are optional but serve to protect the variable to be expanded from +characters immediately following it which could be +interpreted as part of the name. +.PP +When braces are used, the matching ending brace is the first `\fB}\fP' +not escaped by a backslash or within a quoted string, and not within an +embedded arithmetic expansion, command substitution, or parameter +expansion. +.PP +.PD 0 +.TP +${\fIparameter\fP} +The value of \fIparameter\fP is substituted. The braces are required +when +.I parameter +is a positional parameter with more than one digit, +or when +.I parameter +is followed by a character which is not to be +interpreted as part of its name. +The \fIparameter\fP is a shell parameter as described above +\fBPARAMETERS\fP) or an array reference (\fBArrays\fP). +.PD +.PP +If the first character of \fIparameter\fP is an exclamation point (\fB!\fP), +and \fIparameter\fP is not a \fInameref\fP, +it introduces a level of indirection. +\fBBash\fP uses the value formed by expanding the rest of +\fIparameter\fP as the new \fIparameter\fP; this is then +expanded and that value is used in the rest of the expansion, rather +than the expansion of the original \fIparameter\fP. +This is known as \fIindirect expansion\fP. +The value is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +If \fIparameter\fP is a nameref, this expands to the name of the +parameter referenced by \fIparameter\fP instead of performing the +complete indirect expansion. +The exceptions to this are the expansions of ${\fB!\fP\fIprefix\fP\fB*\fP} and +${\fB!\fP\fIname\fP[\fI@\fP]} described below. +The exclamation point must immediately follow the left brace in order to +introduce indirection. +.PP +In each of the cases below, \fIword\fP is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +.PP +When not performing substring expansion, using the forms documented below +(e.g., \fB:-\fP), +\fBbash\fP tests for a parameter that is unset or null. Omitting the colon +results in a test only for a parameter that is unset. +.PP +.PD 0 +.TP +${\fIparameter\fP\fB:\-\fP\fIword\fP} +\fBUse Default Values\fP. If +.I parameter +is unset or null, the expansion of +.I word +is substituted. Otherwise, the value of +.I parameter +is substituted. +.TP +${\fIparameter\fP\fB:=\fP\fIword\fP} +\fBAssign Default Values\fP. +If +.I parameter +is unset or null, the expansion of +.I word +is assigned to +.IR parameter . +The value of +.I parameter +is then substituted. Positional parameters and special parameters may +not be assigned to in this way. +.TP +${\fIparameter\fP\fB:?\fP\fIword\fP} +\fBDisplay Error if Null or Unset\fP. +If +.I parameter +is null or unset, the expansion of \fIword\fP (or a message to that effect +if +.I word +is not present) is written to the standard error and the shell, if it +is not interactive, exits. Otherwise, the value of \fIparameter\fP is +substituted. +.TP +${\fIparameter\fP\fB:+\fP\fIword\fP} +\fBUse Alternate Value\fP. +If +.I parameter +is null or unset, nothing is substituted, otherwise the expansion of +.I word +is substituted. +.TP +${\fIparameter\fP\fB:\fP\fIoffset\fP} +.PD 0 +.TP +${\fIparameter\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP} +.PD +\fBSubstring Expansion\fP. +Expands to up to \fIlength\fP characters of the value of \fIparameter\fP +starting at the character specified by \fIoffset\fP. +If \fIparameter\fP is \fB@\fP or \fB*\fP, an indexed array subscripted by +\fB@\fP or \fB*\fP, or an associative array name, the results differ as +described below. +If \fIlength\fP is omitted, expands to the substring of the value of +\fIparameter\fP starting at the character specified by \fIoffset\fP +and extending to the end of the value. +\fIlength\fP and \fIoffset\fP are arithmetic expressions (see +.SM +.B +ARITHMETIC EVALUATION +below). +.sp 1 +If \fIoffset\fP evaluates to a number less than zero, the value +is used as an offset in characters +from the end of the value of \fIparameter\fP. +If \fIlength\fP evaluates to a number less than zero, +it is interpreted as an offset in characters +from the end of the value of \fIparameter\fP rather than +a number of characters, and the expansion is the characters between +\fIoffset\fP and that result. +Note that a negative offset must be separated from the colon by at least +one space to avoid being confused with the \fB:-\fP expansion. +.sp 1 +If \fIparameter\fP is \fB@\fP or \fB*\fP, the result is \fIlength\fP +positional parameters beginning at \fIoffset\fP. +A negative \fIoffset\fP is taken relative to one greater than the greatest +positional parameter, so an offset of \-1 evaluates to the last positional +parameter. +It is an expansion error if \fIlength\fP evaluates to a number less than +zero. +.sp 1 +If \fIparameter\fP is an indexed array name subscripted by @ or *, +the result is the \fIlength\fP +members of the array beginning with ${\fIparameter\fP[\fIoffset\fP]}. +A negative \fIoffset\fP is taken relative to one greater than the maximum +index of the specified array. +It is an expansion error if \fIlength\fP evaluates to a number less than +zero. +.sp 1 +Substring expansion applied to an associative array produces undefined +results. +.sp 1 +Substring indexing is zero-based unless the positional parameters +are used, in which case the indexing starts at 1 by default. +If \fIoffset\fP is 0, and the positional parameters are used, \fB$0\fP is +prefixed to the list. +.TP +${\fB!\fP\fIprefix\fP\fB*\fP} +.PD 0 +.TP +${\fB!\fP\fIprefix\fP\fB@\fP} +.PD +\fBNames matching prefix\fP. +Expands to the names of variables whose names begin with \fIprefix\fP, +separated by the first character of the +.SM +.B IFS +special variable. +When \fI@\fP is used and the expansion appears within double quotes, each +variable name expands to a separate word. +.TP +${\fB!\fP\fIname\fP[\fI@\fP]} +.PD 0 +.TP +${\fB!\fP\fIname\fP[\fI*\fP]} +.PD +\fBList of array keys\fP. +If \fIname\fP is an array variable, expands to the list of array indices +(keys) assigned in \fIname\fP. +If \fIname\fP is not an array, expands to 0 if \fIname\fP is set and null +otherwise. +When \fI@\fP is used and the expansion appears within double quotes, each +key expands to a separate word. +.TP +${\fB#\fP\fIparameter\fP} +\fBParameter length\fP. +The length in characters of the value of \fIparameter\fP is substituted. +If +.I parameter +is +.B * +or +.BR @ , +the value substituted is the number of positional parameters. +If +.I parameter +is an array name subscripted by +.B * +or +.BR @ , +the value substituted is the number of elements in the array. +If +.I parameter +is an indexed array name subscripted by a negative number, that number is +interpreted as relative to one greater than the maximum index of +\fIparameter\fP, so negative indices count back from the end of the +array, and an index of \-1 references the last element. +.TP +${\fIparameter\fP\fB#\fP\fIword\fP} +.PD 0 +.TP +${\fIparameter\fP\fB##\fP\fIword\fP} +.PD +\fBRemove matching prefix pattern\fP. +The +.I word +is expanded to produce a pattern just as in pathname +expansion, and matched against the expanded value of +.I parameter +using the rules described under +.B Pattern Matching +below. +If the pattern matches the beginning of +the value of +.IR parameter , +then the result of the expansion is the expanded value of +.I parameter +with the shortest matching pattern (the ``\fB#\fP'' case) or the +longest matching pattern (the ``\fB##\fP'' case) deleted. +If +.I parameter +is +.B @ +or +.BR * , +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +${\fIparameter\fP\fB%\fP\fIword\fP} +.PD 0 +.TP +${\fIparameter\fP\fB%%\fP\fIword\fP} +.PD +\fBRemove matching suffix pattern\fP. +The \fIword\fP is expanded to produce a pattern just as in +pathname expansion, and matched against the expanded value of +.I parameter +using the rules described under +.B Pattern Matching +below. +If the pattern matches a trailing portion of the expanded value of +.IR parameter , +then the result of the expansion is the expanded value of +.I parameter +with the shortest matching pattern (the ``\fB%\fP'' case) or the +longest matching pattern (the ``\fB%%\fP'' case) deleted. +If +.I parameter +is +.B @ +or +.BR * , +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +${\fIparameter\fP\fB/\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.PD 0 +.TP +${\fIparameter\fP\fB//\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.TP +${\fIparameter\fP\fB/#\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.TP +${\fIparameter\fP\fB/%\fP\fIpattern\fP\fB/\fP\fIstring\fP} +.PD +\fBPattern substitution\fP. +The \fIpattern\fP is expanded to produce a pattern just as in +pathname expansion. +\fIParameter\fP is expanded and the longest match of \fIpattern\fP +against its value is replaced with \fIstring\fP. +\fIstring\fP undergoes tilde expansion, parameter and variable expansion, +arithmetic expansion, command and process substitution, and quote removal. +The match is performed using the rules described under +.B Pattern Matching +below. +In the first form above, only the first match is replaced. +If there are two slashes separating \fIparameter\fP and \fIpattern\fP +(the second form above), all matches of \fIpattern\fP are +replaced with \fIstring\fP. +If \fIpattern\fP is preceded by \fB#\fP (the third form above), +it must match at the beginning of the expanded value of \fIparameter\fP. +If \fIpattern\fP is preceded by \fB%\fP (the fourth form above), +it must match at the end of the expanded value of \fIparameter\fP. +If the expansion of \fIstring\fP is null, +matches of \fIpattern\fP are deleted. +If \fIstring\fP is null, +matches of \fIpattern\fP are deleted +and the \fB/\fP following \fIpattern\fP may be omitted. +.sp 1 +If the \fBpatsub_replacement\fP shell option is enabled using \fBshopt\fP, +any unquoted instances of \fB&\fP in \fIstring\fP are replaced with the +matching portion of \fIpattern\fP. +.sp 1 +Quoting any part of \fIstring\fP inhibits replacement in the +expansion of the quoted portion, including replacement strings stored +in shell variables. +Backslash will escape \fB&\fP in \fIstring\fP; the backslash is removed +in order to permit a literal \fB&\fP in the replacement string. +Backslash can also be used to escape a backslash; \fB\e\e\fP results in +a literal backslash in the replacement. +Users should take care if \fIstring\fP is double-quoted to avoid +unwanted interactions between the backslash and double-quoting, since +backslash has special meaning within double quotes. +Pattern substitution performs the check for unquoted \fB&\fP after +expanding \fIstring\fP; +shell programmers should quote any occurrences of \fB&\fP +they want to be taken literally in the replacement +and ensure any instances of \fB&\fP they want to be replaced are unquoted. +.sp 1 +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +If +.I parameter +is +.B @ +or +.BR * , +the substitution operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the substitution operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +${\fIparameter\fP\fB^\fP\fIpattern\fP} +.PD 0 +.TP +${\fIparameter\fP\fB^^\fP\fIpattern\fP} +.TP +${\fIparameter\fP\fB,\fP\fIpattern\fP} +.TP +${\fIparameter\fP\fB,,\fP\fIpattern\fP} +.PD +\fBCase modification\fP. +This expansion modifies the case of alphabetic characters in \fIparameter\fP. +The \fIpattern\fP is expanded to produce a pattern just as in +pathname expansion. +Each character in the expanded value of \fIparameter\fP is tested against +\fIpattern\fP, and, if it matches the pattern, its case is converted. +The pattern should not attempt to match more than one character. +The \fB^\fP operator converts lowercase letters matching \fIpattern\fP +to uppercase; the \fB,\fP operator converts matching uppercase letters +to lowercase. +The \fB^^\fP and \fB,,\fP expansions convert each matched character in the +expanded value; the \fB^\fP and \fB,\fP expansions match and convert only +the first character in the expanded value. +If \fIpattern\fP is omitted, it is treated like a \fB?\fP, which matches +every character. +If +.I parameter +is +.B @ +or +.BR * , +the case modification operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the case modification operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.TP +${\fIparameter\fP\fB@\fP\fIoperator\fP} +\fBParameter transformation\fP. +The expansion is either a transformation of the value of \fIparameter\fP +or information about \fIparameter\fP itself, depending on the value of +\fIoperator\fP. Each \fIoperator\fP is a single letter: +.sp 1 +.RS +.PD 0 +.TP +.B U +The expansion is a string that is the value of \fIparameter\fP with lowercase +alphabetic characters converted to uppercase. +.TP +.B u +The expansion is a string that is the value of \fIparameter\fP with the first +character converted to uppercase, if it is alphabetic. +.TP +.B L +The expansion is a string that is the value of \fIparameter\fP with uppercase +alphabetic characters converted to lowercase. +.TP +.B Q +The expansion is a string that is the value of \fIparameter\fP quoted in a +format that can be reused as input. +.TP +.B E +The expansion is a string that is the value of \fIparameter\fP with backslash +escape sequences expanded as with the \fB$\(aq...\(aq\fP quoting mechanism. +.TP +.B P +The expansion is a string that is the result of expanding the value of +\fIparameter\fP as if it were a prompt string (see \fBPROMPTING\fP below). +.TP +.B A +The expansion is a string in the form of +an assignment statement or \fBdeclare\fP command that, if +evaluated, will recreate \fIparameter\fP with its attributes and value. +.TP +.B K +Produces a possibly-quoted version of the value of \fIparameter\fP, +except that it prints the values of +indexed and associative arrays as a sequence of quoted key-value pairs +(see \fBArrays\fP above). +.TP +.B a +The expansion is a string consisting of flag values representing +\fIparameter\fP's attributes. +.TP +.B k +Like the K transformation, but expands the keys and values of +indexed and associative arrays to separate words after word splitting. +.PD +.PP +If +.I parameter +is +.B @ +or +.BR * , +the operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If +.I parameter +is an array variable subscripted with +.B @ +or +.BR * , +the operation is applied to each member of the +array in turn, and the expansion is the resultant list. +.sp 1 +The result of the expansion is subject to word splitting and pathname +expansion as described below. +.RE +.SS Command Substitution +\fICommand substitution\fP allows the output of a command to replace +the command name. There are two forms: +.RS +.PP +\fB$(\fP\fIcommand\fP\|\fB)\fP +.RE +or +.RS +\fB\`\fP\fIcommand\fP\fB\`\fP +.RE +.PP +.B Bash +performs the expansion by executing \fIcommand\fP in a subshell environment +and replacing the command substitution with the standard output of the +command, with any trailing newlines deleted. +Embedded newlines are not deleted, but they may be removed during +word splitting. +The command substitution \fB$(cat \fIfile\fP)\fR can be replaced by +the equivalent but faster \fB$(< \fIfile\fP)\fR. +.PP +When the old-style backquote form of substitution is used, +backslash retains its literal meaning except when followed by +.BR $ , +.BR \` , +or +.BR \e . +The first backquote not preceded by a backslash terminates the +command substitution. +When using the $(\^\fIcommand\fP\|) form, all characters between the +parentheses make up the command; none are treated specially. +.PP +Command substitutions may be nested. To nest when using the backquoted form, +escape the inner backquotes with backslashes. +.PP +If the substitution appears within double quotes, word splitting and +pathname expansion are not performed on the results. +.SS Arithmetic Expansion +Arithmetic expansion allows the evaluation of an arithmetic expression +and the substitution of the result. The format for arithmetic expansion is: +.RS +.PP +\fB$((\fP\fIexpression\fP\fB))\fP +.RE +.PP +The +.I expression +undergoes the same expansions +as if it were within double quotes, +but double quote characters in \fIexpression\fP are not treated specially +and are removed. +All tokens in the expression undergo parameter and variable expansion, +command substitution, and quote removal. +The result is treated as the arithmetic expression to be evaluated. +Arithmetic expansions may be nested. +.PP +The evaluation is performed according to the rules listed below under +.SM +.BR "ARITHMETIC EVALUATION" . +If +.I expression +is invalid, +.B bash +prints a message indicating failure and no substitution occurs. +.SS Process Substitution +\fIProcess substitution\fP allows a process's input or output to be +referred to using a filename. +It takes the form of +\fB<(\fP\fIlist\^\fP\fB)\fP +or +\fB>(\fP\fIlist\^\fP\fB)\fP. +The process \fIlist\fP is run asynchronously, and its input or output +appears as a filename. +This filename is +passed as an argument to the current command as the result of the +expansion. +If the \fB>(\fP\fIlist\^\fP\fB)\fP form is used, writing to +the file will provide input for \fIlist\fP. If the +\fB<(\fP\fIlist\^\fP\fB)\fP form is used, the file passed as an +argument should be read to obtain the output of \fIlist\fP. +Process substitution is supported on systems that support named +pipes (\fIFIFOs\fP) or the \fB/dev/fd\fP method of naming open files. +.PP +When available, process substitution is performed +simultaneously with parameter and variable expansion, +command substitution, +and arithmetic expansion. +.SS Word Splitting +The shell scans the results of +parameter expansion, +command substitution, +and +arithmetic expansion +that did not occur within double quotes for +.IR "word splitting" . +.PP +The shell treats each character of +.SM +.B IFS +as a delimiter, and splits the results of the other +expansions into words using these characters as field terminators. +If +.SM +.B IFS +is unset, or its +value is exactly +.BR <space><tab><newline> , +the default, then +sequences of +.BR <space> , +.BR <tab> , +and +.B <newline> +at the beginning and end of the results of the previous +expansions are ignored, and +any sequence of +.SM +.B IFS +characters not at the beginning or end serves to delimit words. +If +.SM +.B IFS +has a value other than the default, then sequences of +the whitespace characters +.BR space , +.BR tab , +and +.B newline +are ignored at the beginning and end of the +word, as long as the whitespace character is in the +value of +.SM +.B IFS +(an +.SM +.B IFS +whitespace character). +Any character in +.SM +.B IFS +that is not +.SM +.B IFS +whitespace, along with any adjacent +.SM +.B IFS +whitespace characters, delimits a field. +A sequence of +.SM +.B IFS +whitespace characters is also treated as a delimiter. +If the value of +.SM +.B IFS +is null, no word splitting occurs. +.PP +Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained +and passed to commands as empty strings. +Unquoted implicit null arguments, resulting from the expansion of +parameters that have no values, are removed. +If a parameter with no value is expanded within double quotes, a +null argument results and is retained +and passed to a command as an empty string. +When a quoted null argument appears as part of a word whose expansion is +non-null, the null argument is removed. +That is, the word +\f(CW\-d\(aq\^\(aq\fP becomes \f(CW\-d\fP after word splitting and +null argument removal. +.PP +Note that if no expansion occurs, no splitting +is performed. +.SS Pathname Expansion +After word splitting, +unless the +.B \-f +option has been set, +.B bash +scans each word for the characters +.BR * , +.BR ? , +and +.BR [ . +If one of these characters appears, and is not quoted, then the word is +regarded as a +.IR pattern , +and replaced with an alphabetically sorted list of +filenames matching the pattern +(see +.SM +.B "Pattern Matching" +below). +If no matching filenames are found, +and the shell option +.B nullglob +is not enabled, the word is left unchanged. +If the +.B nullglob +option is set, and no matches are found, +the word is removed. +If the +.B failglob +shell option is set, and no matches are found, an error message +is printed and the command is not executed. +If the shell option +.B nocaseglob +is enabled, the match is performed without regard to the case +of alphabetic characters. +When a pattern is used for pathname expansion, +the character +.B ``.'' +at the start of a name or immediately following a slash +must be matched explicitly, unless the shell option +.B dotglob +is set. +In order to match the filenames +.B ``.'' +and +.BR ``..'' , +the pattern must begin with ``.'' (for example, ``.?''), +even if +.B dotglob +is set. +If the +.B globskipdots +shell option is enabled, the filenames +.B ``.'' +and +.BR ``..'' +are never matched, even if the pattern begins with a +.BR ``.'' . +When not matching pathnames, the +.B ``.'' +character is not treated specially. +When matching a pathname, the slash character must always be +matched explicitly by a slash in the pattern, but in other matching +contexts it can be matched by a special pattern character as described +below under +.SM +.BR "Pattern Matching" . +See the description of +.B shopt +below under +.SM +.B SHELL BUILTIN COMMANDS +for a description of the +.BR nocaseglob , +.BR nullglob , +.BR globskipdots , +.BR failglob , +and +.B dotglob +shell options. +.PP +The +.SM +.B GLOBIGNORE +shell variable may be used to restrict the set of file names matching a +.IR pattern . +If +.SM +.B GLOBIGNORE +is set, each matching file name that also matches one of the patterns in +.SM +.B GLOBIGNORE +is removed from the list of matches. +If the \fBnocaseglob\fP option is set, the matching against the patterns in +.SM +.B GLOBIGNORE +is performed without regard to case. +The filenames +.B ``.'' +and +.B ``..'' +are always ignored when +.SM +.B GLOBIGNORE +is set and not null. However, setting +.SM +.B GLOBIGNORE +to a non-null value has the effect of enabling the +.B dotglob +shell option, so all other filenames beginning with a +.B ``.'' +will match. +To get the old behavior of ignoring filenames beginning with a +.BR ``.'' , +make +.B ``.*'' +one of the patterns in +.SM +.BR GLOBIGNORE . +The +.B dotglob +option is disabled when +.SM +.B GLOBIGNORE +is unset. +The pattern matching honors the setting of the \fBextglob\fP shell +option. +.PP +\fBPattern Matching\fP +.PP +Any character that appears in a pattern, other than the special pattern +characters described below, matches itself. The NUL character may not +occur in a pattern. A backslash escapes the following character; the +escaping backslash is discarded when matching. +The special pattern characters must be quoted if +they are to be matched literally. +.PP +The special pattern characters have the following meanings: +.PP +.PD 0 +.RS +.TP +.B * +Matches any string, including the null string. +When the \fBglobstar\fP shell option is enabled, and \fB*\fP is used in +a pathname expansion context, two adjacent \fB*\fPs used as a single +pattern will match all files and zero or more directories and +subdirectories. +If followed by a \fB/\fP, two adjacent \fB*\fPs will match only directories +and subdirectories. +.TP +.B ? +Matches any single character. +.TP +.B [...] +Matches any one of the enclosed characters. A pair of characters +separated by a hyphen denotes a +\fIrange expression\fP; +any character that falls between those two characters, inclusive, +using the current locale's collating sequence and character set, +is matched. If the first character following the +.B [ +is a +.B ! +or a +.B ^ +then any character not enclosed is matched. +The sorting order of characters in range expressions, +and the characters included in the range, +are determined by +the current locale and the values of the +.SM +.B LC_COLLATE +or +.SM +.B LC_ALL +shell variables, if set. +To obtain the traditional interpretation of range expressions, where +.B [a\-d] +is equivalent to +.BR [abcd] , +set value of the +.B LC_ALL +shell variable to +.BR C , +or enable the +.B globasciiranges +shell option. +A +.B \- +may be matched by including it as the first or last character +in the set. +A +.B ] +may be matched by including it as the first character +in the set. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +\fIcharacter classes\fP can be specified using the syntax +\fB[:\fP\fIclass\fP\fB:]\fP, where \fIclass\fP is one of the +following classes defined in the POSIX standard: +.PP +.RS +.B +.if n alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit +.if t alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit +.br +A character class matches any character belonging to that class. +The \fBword\fP character class matches letters, digits, and the character _. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +an \fIequivalence class\fP can be specified using the syntax +\fB[=\fP\fIc\fP\fB=]\fP, which matches all characters with the +same collation weight (as defined by the current locale) as +the character \fIc\fP. +.br +.if t .sp 0.5 +.if n .sp 1 +Within +.B [ +and +.BR ] , +the syntax \fB[.\fP\fIsymbol\fP\fB.]\fP matches the collating symbol +\fIsymbol\fP. +.RE +.RE +.PD +.PP +If the \fBextglob\fP shell option is enabled using the \fBshopt\fP +builtin, the shell recognizes several extended pattern matching operators. +In the following description, a \fIpattern-list\fP is a list of one +or more patterns separated by a \fB|\fP. +Composite patterns may be formed using one or more of the following +sub-patterns: +.sp 1 +.PD 0 +.RS +.TP +\fB?(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches zero or one occurrence of the given patterns +.TP +\fB*(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches zero or more occurrences of the given patterns +.TP +\fB+(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches one or more occurrences of the given patterns +.TP +\fB@(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches one of the given patterns +.TP +\fB!(\fP\^\fIpattern-list\^\fP\fB)\fP +Matches anything except one of the given patterns +.RE +.PD +.PP +The\fBextglob\fP option changes the behavior of the parser, since the +parentheses are normally treated as operators with syntactic meaning. +To ensure that extended matching patterns are parsed correctly, make sure +that \fBextglob\fP is enabled before parsing constructs containing the +patterns, including shell functions and command substitutions. +.PP +When matching filenames, the \fBdotglob\fP shell option determines +the set of filenames that are tested: +when \fBdotglob\fP is enabled, the set of filenames includes all files +beginning with ``.'', but ``.'' and ``..'' must be matched by a +pattern or sub-pattern that begins with a dot; +when it is disabled, the set does not +include any filenames beginning with ``.'' unless the pattern +or sub-pattern begins with a ``.''. +As above, ``.'' only has a special meaning when matching filenames. +.PP +Complicated extended pattern matching against long strings is slow, +especially when the patterns contain alternations and the strings +contain multiple matches. +Using separate matches against shorter strings, or using arrays of +strings instead of a single long string, may be faster. +.SS Quote Removal +After the preceding expansions, all unquoted occurrences of the +characters +.BR \e , +.BR \(aq , +and \^\f3"\fP\^ that did not result from one of the above +expansions are removed. +.SH REDIRECTION +Before a command is executed, its input and output +may be +.I redirected +using a special notation interpreted by the shell. +\fIRedirection\fP allows commands' file handles to be +duplicated, opened, closed, +made to refer to different files, +and can change the files the command reads from and writes to. +Redirection may also be used to modify file handles in the +current shell execution environment. +The following redirection +operators may precede or appear anywhere within a +.I simple command +or may follow a +.IR command . +Redirections are processed in the order they appear, from +left to right. +.PP +Each redirection that may be preceded by a file descriptor number +may instead be preceded by a word of the form {\fIvarname\fP}. +In this case, for each redirection operator except +>&- and <&-, the shell will allocate a file descriptor greater +than or equal to 10 and assign it to \fIvarname\fP. +If >&- or <&- is preceded +by {\fIvarname\fP}, the value of \fIvarname\fP defines the file +descriptor to close. +If {\fIvarname\fP} is supplied, the redirection persists beyond +the scope of the command, allowing the shell programmer to manage +the file descriptor's lifetime manually. +The \fBvarredir_close\fP shell option manages this behavior. +.PP +In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is +.BR < , +the redirection refers to the standard input (file descriptor +0). If the first character of the redirection operator is +.BR > , +the redirection refers to the standard output (file descriptor +1). +.PP +The word following the redirection operator in the following +descriptions, unless otherwise noted, is subjected to +brace expansion, tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, quote removal, +pathname expansion, and word splitting. +If it expands to more than one word, +.B bash +reports an error. +.PP +Note that the order of redirections is significant. For example, +the command +.RS +.PP +ls \fB>\fP dirlist 2\fB>&\fP1 +.RE +.PP +directs both standard output and standard error to the file +.IR dirlist , +while the command +.RS +.PP +ls 2\fB>&\fP1 \fB>\fP dirlist +.RE +.PP +directs only the standard output to file +.IR dirlist , +because the standard error was duplicated from the standard output +before the standard output was redirected to +.IR dirlist . +.PP +\fBBash\fP handles several filenames specially when they are used in +redirections, as described in the following table. +If the operating system on which \fBbash\fP is running provides these +special files, bash will use them; otherwise it will emulate them +internally with the behavior described below. +.RS +.PP +.PD 0 +.TP +.B /dev/fd/\fIfd\fP +If \fIfd\fP is a valid integer, file descriptor \fIfd\fP is duplicated. +.TP +.B /dev/stdin +File descriptor 0 is duplicated. +.TP +.B /dev/stdout +File descriptor 1 is duplicated. +.TP +.B /dev/stderr +File descriptor 2 is duplicated. +.TP +.B /dev/tcp/\fIhost\fP/\fIport\fP +If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP +is an integer port number or service name, \fBbash\fP attempts to open +the corresponding TCP socket. +.TP +.B /dev/udp/\fIhost\fP/\fIport\fP +If \fIhost\fP is a valid hostname or Internet address, and \fIport\fP +is an integer port number or service name, \fBbash\fP attempts to open +the corresponding UDP socket. +.PD +.RE +.PP +A failure to open or create a file causes the redirection to fail. +.PP +Redirections using file descriptors greater than 9 should be used with +care, as they may conflict with file descriptors the shell uses +internally. +.SS Redirecting Input +Redirection of input causes the file whose name results from +the expansion of +.I word +to be opened for reading on file descriptor +.IR n , +or the standard input (file descriptor 0) if +.I n +is not specified. +.PP +The general format for redirecting input is: +.RS +.PP +[\fIn\fP]\fB<\fP\fIword\fP +.RE +.SS Redirecting Output +Redirection of output causes the file whose name results from +the expansion of +.I word +to be opened for writing on file descriptor +.IR n , +or the standard output (file descriptor 1) if +.I n +is not specified. If the file does not exist it is created; +if it does exist it is truncated to zero size. +.PP +The general format for redirecting output is: +.RS +.PP +[\fIn\fP]\fB>\fP\fIword\fP +.RE +.PP +If the redirection operator is +.BR > , +and the +.B noclobber +option to the +.B set +builtin has been enabled, the redirection will fail if the file +whose name results from the expansion of \fIword\fP exists and is +a regular file. +If the redirection operator is +.BR >| , +or the redirection operator is +.B > +and the +.B noclobber +option to the +.B set +builtin command is not enabled, the redirection is attempted even +if the file named by \fIword\fP exists. +.SS Appending Redirected Output +Redirection of output in this fashion +causes the file whose name results from +the expansion of +.I word +to be opened for appending on file descriptor +.IR n , +or the standard output (file descriptor 1) if +.I n +is not specified. If the file does not exist it is created. +.PP +The general format for appending output is: +.RS +.PP +[\fIn\fP]\fB>>\fP\fIword\fP +.RE +.SS Redirecting Standard Output and Standard Error +This construct allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be redirected to the file whose name is the +expansion of +.IR word . +.PP +There are two formats for redirecting standard output and +standard error: +.RS +.PP +\fB&>\fP\fIword\fP +.RE +and +.RS +\fB>&\fP\fIword\fP +.RE +.PP +Of the two forms, the first is preferred. +This is semantically equivalent to +.RS +.PP +\fB>\fP\fIword\fP 2\fB>&\fP1 +.RE +.PP +When using the second form, \fIword\fP may not expand to a number or +\fB\-\fP. If it does, other redirection operators apply +(see \fBDuplicating File Descriptors\fP below) for compatibility +reasons. +.SS Appending Standard Output and Standard Error +This construct allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be appended to the file whose name is the +expansion of +.IR word . +.PP +The format for appending standard output and standard error is: +.RS +.PP +\fB&>>\fP\fIword\fP +.RE +.PP +This is semantically equivalent to +.RS +.PP +\fB>>\fP\fIword\fP 2\fB>&\fP1 +.RE +.PP +(see \fBDuplicating File Descriptors\fP below). +.SS Here Documents +This type of redirection instructs the shell to read input from the +current source until a line containing only +.I delimiter +(with no trailing blanks) +is seen. All of +the lines read up to that point are then used as the standard +input (or file descriptor \fIn\fP if \fIn\fP is specified) for a command. +.PP +The format of here-documents is: +.RS +.PP +.nf +[\fIn\fP]\fB<<\fP[\fB\-\fP]\fIword\fP + \fIhere-document\fP +\fIdelimiter\fP +.fi +.RE +.PP +No parameter and variable expansion, command substitution, +arithmetic expansion, or pathname expansion is performed on +.IR word . +If any part of +.I word +is quoted, the +.I delimiter +is the result of quote removal on +.IR word , +and the lines in the here-document are not expanded. +If \fIword\fP is unquoted, +all lines of the here-document are subjected to +parameter expansion, command substitution, and arithmetic expansion, +the character sequence +.B \e<newline> +is ignored, and +.B \e +must be used to quote the characters +.BR \e , +.BR $ , +and +.BR \` . +.PP +If the redirection operator is +.BR <<\- , +then all leading tab characters are stripped from input lines and the +line containing +.IR delimiter . +This allows +here-documents within shell scripts to be indented in a +natural fashion. +.SS "Here Strings" +A variant of here documents, the format is: +.RS +.PP +.nf +[\fIn\fP]\fB<<<\fP\fIword\fP +.fi +.RE +.PP +The \fIword\fP undergoes +tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote removal. +Pathname expansion and word splitting are not performed. +The result is supplied as a single string, with a newline appended, +to the command on its +standard input (or file descriptor \fIn\fP if \fIn\fP is specified). +.SS "Duplicating File Descriptors" +The redirection operator +.RS +.PP +[\fIn\fP]\fB<&\fP\fIword\fP +.RE +.PP +is used to duplicate input file descriptors. +If +.I word +expands to one or more digits, the file descriptor denoted by +.I n +is made to be a copy of that file descriptor. +If the digits in +.I word +do not specify a file descriptor open for input, a redirection error occurs. +If +.I word +evaluates to +.BR \- , +file descriptor +.I n +is closed. If +.I n +is not specified, the standard input (file descriptor 0) is used. +.PP +The operator +.RS +.PP +[\fIn\fP]\fB>&\fP\fIword\fP +.RE +.PP +is used similarly to duplicate output file descriptors. If +.I n +is not specified, the standard output (file descriptor 1) is used. +If the digits in +.I word +do not specify a file descriptor open for output, a redirection error occurs. +If +.I word +evaluates to +.BR \- , +file descriptor +.I n +is closed. +As a special case, if \fIn\fP is omitted, and \fIword\fP does not +expand to one or more digits or \fB\-\fP, the standard output and standard +error are redirected as described previously. +.SS "Moving File Descriptors" +The redirection operator +.RS +.PP +[\fIn\fP]\fB<&\fP\fIdigit\fP\fB\-\fP +.RE +.PP +moves the file descriptor \fIdigit\fP to file descriptor +.IR n , +or the standard input (file descriptor 0) if \fIn\fP is not specified. +\fIdigit\fP is closed after being duplicated to \fIn\fP. +.PP +Similarly, the redirection operator +.RS +.PP +[\fIn\fP]\fB>&\fP\fIdigit\fP\fB\-\fP +.RE +.PP +moves the file descriptor \fIdigit\fP to file descriptor +.IR n , +or the standard output (file descriptor 1) if \fIn\fP is not specified. +.SS "Opening File Descriptors for Reading and Writing" +The redirection operator +.RS +.PP +[\fIn\fP]\fB<>\fP\fIword\fP +.RE +.PP +causes the file whose name is the expansion of +.I word +to be opened for both reading and writing on file descriptor +.IR n , +or on file descriptor 0 if +.I n +is not specified. If the file does not exist, it is created. +.SH ALIASES +\fIAliases\fP allow a string to be substituted for a word when it is used +as the first word of a simple command. +The shell maintains a list of aliases that may be set and unset with the +.B alias +and +.B unalias +builtin commands (see +.SM +.B SHELL BUILTIN COMMANDS +below). +The first word of each simple command, if unquoted, +is checked to see if it has an +alias. If so, that word is replaced by the text of the alias. +The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and +any of the shell \fImetacharacters\fP or quoting characters +listed above may not appear in an alias name. +The replacement text may contain any valid shell input, +including shell metacharacters. +The first word of the replacement text is tested +for aliases, but a word that is identical to an alias being expanded +is not expanded a second time. +This means that one may alias +.B ls +to +.BR "ls \-F" , +for instance, and +.B bash +does not try to recursively expand the replacement text. +If the last character of the alias value is a +.IR blank , +then the next command +word following the alias is also checked for alias expansion. +.PP +Aliases are created and listed with the +.B alias +command, and removed with the +.B unalias +command. +.PP +There is no mechanism for using arguments in the replacement text. +If arguments are needed, use a shell function (see +.SM +.B FUNCTIONS +below). +.PP +Aliases are not expanded when the shell is not interactive, unless +the +.B expand_aliases +shell option is set using +.B shopt +(see the description of +.B shopt +under +.SM +\fBSHELL BUILTIN COMMANDS\fP +below). +.PP +The rules concerning the definition and use of aliases are +somewhat confusing. +.B Bash +always reads at least one complete line of input, +and all lines that make up a compound command, +before executing any of the commands on that line or the compound command. +Aliases are expanded when a +command is read, not when it is executed. Therefore, an +alias definition appearing on the same line as another +command does not take effect until the next line of input is read. +The commands following the alias definition +on that line are not affected by the new alias. +This behavior is also an issue when functions are executed. +Aliases are expanded when a function definition is read, +not when the function is executed, because a function definition +is itself a command. As a consequence, aliases +defined in a function are not available until after that +function is executed. To be safe, always put +alias definitions on a separate line, and do not use +.B alias +in compound commands. +.PP +For almost every purpose, aliases are superseded by +shell functions. +.SH FUNCTIONS +A shell function, defined as described above under +.SM +.BR "SHELL GRAMMAR" , +stores a series of commands for later execution. +When the name of a shell function is used as a simple command name, +the list of commands associated with that function name is executed. +Functions are executed in the context of the +current shell; no new process is created to interpret +them (contrast this with the execution of a shell script). +When a function is executed, the arguments to the +function become the positional parameters +during its execution. +The special parameter +.B # +is updated to reflect the change. Special parameter \fB0\fP +is unchanged. +The first element of the +.SM +.B FUNCNAME +variable is set to the name of the function while the function +is executing. +.PP +All other aspects of the shell execution +environment are identical between a function and its caller +with these exceptions: the +.SM +.B DEBUG +and +.B RETURN +traps (see the description of the +.B trap +builtin under +.SM +.B SHELL BUILTIN COMMANDS +below) are not inherited unless the function has been given the +\fBtrace\fP attribute (see the description of the +.SM +.B declare +builtin below) or the +\fB\-o functrace\fP shell option has been enabled with +the \fBset\fP builtin +(in which case all functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps), +and the +.SM +.B ERR +trap is not inherited unless the \fB\-o errtrace\fP shell option has +been enabled. +.PP +Variables local to the function may be declared with the +.B local +builtin command (\fIlocal variables\fP). +Ordinarily, variables and their values +are shared between the function and its caller. +If a variable is declared \fBlocal\fP, the variable's visible scope +is restricted to that function and its children (including the functions +it calls). +.PP +In the following description, the \fIcurrent scope\fP is a currently- +executing function. +Previous scopes consist of that function's caller and so on, +back to the "global" scope, where the shell is not executing +any shell function. +Consequently, a local variable at the current scope is a variable +declared using the \fBlocal\fP or \fBdeclare\fP builtins in the +function that is currently executing. +.PP +Local variables "shadow" variables with the same name declared at +previous scopes. +For instance, a local variable declared in a function +hides a global variable of the same name: references and assignments +refer to the local variable, leaving the global variable unmodified. +When the function returns, the global variable is once again visible. +.PP +The shell uses \fIdynamic scoping\fP to control a variable's visibility +within functions. +With dynamic scoping, visible variables and their values +are a result of the sequence of function calls that caused execution +to reach the current function. +The value of a variable that a function sees depends +on its value within its caller, if any, whether that caller is +the "global" scope or another shell function. +This is also the value that a local variable +declaration "shadows", and the value that is restored when the function +returns. +.PP +For example, if a variable \fIvar\fP is declared as local in function +\fIfunc1\fP, and \fIfunc1\fP calls another function \fIfunc2\fP, +references to \fIvar\fP made from within \fIfunc2\fP will resolve to the +local variable \fIvar\fP from \fIfunc1\fP, shadowing any global variable +named \fIvar\fP. +.PP +The \fBunset\fP builtin also acts using the same dynamic scope: if a +variable is local to the current scope, \fBunset\fP will unset it; +otherwise the unset will refer to the variable found in any calling scope +as described above. +If a variable at the current local scope is unset, it will remain so +(appearing as unset) +until it is reset in that scope or until the function returns. +Once the function returns, any instance of the variable at a previous +scope will become visible. +If the unset acts on a variable at a previous scope, any instance of a +variable with that name that had been shadowed will become visible +(see below how the \fBlocalvar_unset\fP shell option changes this behavior). +.PP +The \fBFUNCNEST\fP variable, if set to a numeric value greater +than 0, defines a maximum function nesting level. Function +invocations that exceed the limit cause the entire command to +abort. +.PP +If the builtin command +.B return +is executed in a function, the function completes and +execution resumes with the next command after the function +call. +Any command associated with the \fBRETURN\fP trap is executed +before execution resumes. +When a function completes, the values of the +positional parameters and the special parameter +.B # +are restored to the values they had prior to the function's +execution. +.PP +Function names and definitions may be listed with the +.B \-f +option to the +.B declare +or +.B typeset +builtin commands. The +.B \-F +option to +.B declare +or +.B typeset +will list the function names only +(and optionally the source file and line number, if the \fBextdebug\fP +shell option is enabled). +Functions may be exported so that child shell processes +(those created when executing a separate shell invocation) +automatically have them defined with the +.B \-f +option to the +.B export +builtin. +A function definition may be deleted using the \fB\-f\fP option to +the +.B unset +builtin. +.PP +Functions may be recursive. +The \fBFUNCNEST\fP variable may be used to limit the depth of the +function call stack and restrict the number of function invocations. +By default, no limit is imposed on the number of recursive calls. +.SH "ARITHMETIC EVALUATION" +The shell allows arithmetic expressions to be evaluated, under +certain circumstances (see the \fBlet\fP and \fBdeclare\fP builtin +commands, the \fB((\fP compound command, and \fBArithmetic Expansion\fP). +Evaluation is done in fixed-width integers with no check for overflow, +though division by 0 is trapped and flagged as an error. +The operators and their precedence, associativity, and values +are the same as in the C language. +The following list of operators is grouped into levels of +equal-precedence operators. +The levels are listed in order of decreasing precedence. +.PP +.PD 0 +.TP +.B \fIid\fP++ \fIid\fP\-\- +variable post-increment and post-decrement +.TP +.B \- + +unary minus and plus +.TP +.B ++\fIid\fP \-\-\fIid\fP +variable pre-increment and pre-decrement +.TP +.B ! ~ +logical and bitwise negation +.TP +.B ** +exponentiation +.TP +.B * / % +multiplication, division, remainder +.TP +.B + \- +addition, subtraction +.TP +.B << >> +left and right bitwise shifts +.TP +.B <= >= < > +comparison +.TP +.B == != +equality and inequality +.TP +.B & +bitwise AND +.TP +.B ^ +bitwise exclusive OR +.TP +.B | +bitwise OR +.TP +.B && +logical AND +.TP +.B || +logical OR +.TP +.B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP +conditional operator +.TP +.B = *= /= %= += \-= <<= >>= &= ^= |= +assignment +.TP +.B \fIexpr1\fP , \fIexpr2\fP +comma +.PD +.PP +Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. +Within an expression, shell variables may also be referenced by name +without using the parameter expansion syntax. +A shell variable that is null or unset evaluates to 0 when referenced +by name without using the parameter expansion syntax. +The value of a variable is evaluated as an arithmetic expression +when it is referenced, or when a variable which has been given the +\fIinteger\fP attribute using \fBdeclare \-i\fP is assigned a value. +A null value evaluates to 0. +A shell variable need not have its \fIinteger\fP attribute +turned on to be used in an expression. +.PP +Integer constants follow the C language definition, without suffixes or +character constants. +Constants with a leading 0 are interpreted as octal numbers. +A leading 0x or 0X denotes hexadecimal. +Otherwise, numbers take the form [\fIbase#\fP]n, where the optional \fIbase\fP +is a decimal number between 2 and 64 representing the arithmetic +base, and \fIn\fP is a number in that base. +If \fIbase#\fP is omitted, then base 10 is used. +When specifying \fIn\fP, +if a non-digit is required, +the digits greater than 9 are represented by the lowercase letters, +the uppercase letters, @, and _, in that order. +If \fIbase\fP is less than or equal to 36, lowercase and uppercase +letters may be used interchangeably to represent numbers between 10 +and 35. +.PP +Operators are evaluated in order of precedence. Sub-expressions in +parentheses are evaluated first and may override the precedence +rules above. +.SH "CONDITIONAL EXPRESSIONS" +Conditional expressions are used by the \fB[[\fP compound command and +the \fBtest\fP and \fB[\fP builtin commands to test file attributes +and perform string and arithmetic comparisons. +The \fBtest\fP and \fB[\fP commands determine their behavior based on +the number of arguments; see the descriptions of those commands for any +other command-specific actions. +.PP +Expressions are formed from the following unary or binary primaries. +\fBBash\fP handles several filenames specially when they are used in +expressions. +If the operating system on which \fBbash\fP is running provides these +special files, bash will use them; otherwise it will emulate them +internally with this behavior: +If any \fIfile\fP argument to one of the primaries is of the form +\fI/dev/fd/n\fP, then file descriptor \fIn\fP is checked. +If the \fIfile\fP argument to one of the primaries is one of +\fI/dev/stdin\fP, \fI/dev/stdout\fP, or \fI/dev/stderr\fP, file +descriptor 0, 1, or 2, respectively, is checked. +.PP +Unless otherwise specified, primaries that operate on files follow symbolic +links and operate on the target of the link, rather than the link itself. +.if t .sp 0.5 +.if n .sp 1 +When used with \fB[[\fP, the \fB<\fP and \fB>\fP operators sort +lexicographically using the current locale. +The \fBtest\fP command sorts using ASCII ordering. +.sp 1 +.PD 0 +.TP +.B \-a \fIfile\fP +True if \fIfile\fP exists. +.TP +.B \-b \fIfile\fP +True if \fIfile\fP exists and is a block special file. +.TP +.B \-c \fIfile\fP +True if \fIfile\fP exists and is a character special file. +.TP +.B \-d \fIfile\fP +True if \fIfile\fP exists and is a directory. +.TP +.B \-e \fIfile\fP +True if \fIfile\fP exists. +.TP +.B \-f \fIfile\fP +True if \fIfile\fP exists and is a regular file. +.TP +.B \-g \fIfile\fP +True if \fIfile\fP exists and is set-group-id. +.TP +.B \-h \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP +.B \-k \fIfile\fP +True if \fIfile\fP exists and its ``sticky'' bit is set. +.TP +.B \-p \fIfile\fP +True if \fIfile\fP exists and is a named pipe (FIFO). +.TP +.B \-r \fIfile\fP +True if \fIfile\fP exists and is readable. +.TP +.B \-s \fIfile\fP +True if \fIfile\fP exists and has a size greater than zero. +.TP +.B \-t \fIfd\fP +True if file descriptor +.I fd +is open and refers to a terminal. +.TP +.B \-u \fIfile\fP +True if \fIfile\fP exists and its set-user-id bit is set. +.TP +.B \-w \fIfile\fP +True if \fIfile\fP exists and is writable. +.TP +.B \-x \fIfile\fP +True if \fIfile\fP exists and is executable. +.TP +.B \-G \fIfile\fP +True if \fIfile\fP exists and is owned by the effective group id. +.TP +.B \-L \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP +.B \-N \fIfile\fP +True if \fIfile\fP exists and has been modified since it was last read. +.TP +.B \-O \fIfile\fP +True if \fIfile\fP exists and is owned by the effective user id. +.TP +.B \-S \fIfile\fP +True if \fIfile\fP exists and is a socket. +.TP +\fIfile1\fP \fB\-ef\fP \fIfile2\fP +True if \fIfile1\fP and \fIfile2\fP refer to the same device and +inode numbers. +.TP +\fIfile1\fP \-\fBnt\fP \fIfile2\fP +True if \fIfile1\fP is newer (according to modification date) than \fIfile2\fP, +or if \fIfile1\fP exists and \fPfile2\fP does not. +.TP +\fIfile1\fP \-\fBot\fP \fIfile2\fP +True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists +and \fIfile1\fP does not. +.TP +.B \-o \fIoptname\fP +True if the shell option +.I optname +is enabled. +See the list of options under the description of the +.B \-o +option to the +.B set +builtin below. +.TP +.B \-v \fIvarname\fP +True if the shell variable +.I varname +is set (has been assigned a value). +.TP +.B \-R \fIvarname\fP +True if the shell variable +.I varname +is set and is a name reference. +.TP +.B \-z \fIstring\fP +True if the length of \fIstring\fP is zero. +.TP +\fIstring\fP +.PD 0 +.TP +.B \-n \fIstring\fP +.PD +True if the length of +.I string +is non-zero. +.TP +\fIstring1\fP \fB==\fP \fIstring2\fP +.PD 0 +.TP +\fIstring1\fP \fB=\fP \fIstring2\fP +.PD +True if the strings are equal. \fB=\fP should be used +with the \fBtest\fP command for POSIX conformance. +When used with the \fB[[\fP command, this performs pattern matching as +described above (\fBCompound Commands\fP). +.TP +\fIstring1\fP \fB!=\fP \fIstring2\fP +True if the strings are not equal. +.TP +\fIstring1\fP \fB<\fP \fIstring2\fP +True if \fIstring1\fP sorts before \fIstring2\fP lexicographically. +.TP +\fIstring1\fP \fB>\fP \fIstring2\fP +True if \fIstring1\fP sorts after \fIstring2\fP lexicographically. +.TP +.I \fIarg1\fP \fBOP\fP \fIarg2\fP +.SM +.B OP +is one of +.BR \-eq , +.BR \-ne , +.BR \-lt , +.BR \-le , +.BR \-gt , +or +.BR \-ge . +These arithmetic binary operators return true if \fIarg1\fP +is equal to, not equal to, less than, less than or equal to, +greater than, or greater than or equal to \fIarg2\fP, respectively. +.I Arg1 +and +.I arg2 +may be positive or negative integers. +When used with the \fB[[\fP command, +.I Arg1 +and +.I Arg2 +are evaluated as arithmetic expressions (see +.SM +.B "ARITHMETIC EVALUATION" +above). +.PD +.SH "SIMPLE COMMAND EXPANSION" +When a simple command is executed, the shell performs the following +expansions, assignments, and redirections, from left to right, in +the following order. +.IP 1. +The words that the parser has marked as variable assignments (those +preceding the command name) and redirections are saved for later +processing. +.IP 2. +The words that are not variable assignments or redirections are +expanded. If any words remain after expansion, the first word +is taken to be the name of the command and the remaining words are +the arguments. +.IP 3. +Redirections are performed as described above under +.SM +.BR REDIRECTION . +.IP 4. +The text after the \fB=\fP in each variable assignment undergoes tilde +expansion, parameter expansion, command substitution, arithmetic expansion, +and quote removal before being assigned to the variable. +.PP +If no command name results, the variable assignments affect the current +shell environment. +In the case of such a command (one that consists only of assignment +statements and redirections), assignment statements are performed before +redirections. +Otherwise, the variables are added to the environment +of the executed command and do not affect the current shell environment. +If any of the assignments attempts to assign a value to a readonly variable, +an error occurs, and the command exits with a non-zero status. +.PP +If no command name results, redirections are performed, but do not +affect the current shell environment. A redirection error causes the +command to exit with a non-zero status. +.PP +If there is a command name left after expansion, execution proceeds as +described below. Otherwise, the command exits. If one of the expansions +contained a command substitution, the exit status of the command is +the exit status of the last command substitution performed. If there +were no command substitutions, the command exits with a status of zero. +.SH "COMMAND EXECUTION" +After a command has been split into words, if it results in a +simple command and an optional list of arguments, the following +actions are taken. +.PP +If the command name contains no slashes, the shell attempts to +locate it. If there exists a shell function by that name, that +function is invoked as described above in +.SM +.BR FUNCTIONS . +If the name does not match a function, the shell searches for +it in the list of shell builtins. If a match is found, that +builtin is invoked. +.PP +If the name is neither a shell function nor a builtin, +and contains no slashes, +.B bash +searches each element of the +.SM +.B PATH +for a directory containing an executable file by that name. +.B Bash +uses a hash table to remember the full pathnames of executable +files (see +.B hash +under +.SM +.B "SHELL BUILTIN COMMANDS" +below). +A full search of the directories in +.SM +.B PATH +is performed only if the command is not found in the hash table. +If the search is unsuccessful, the shell searches for a defined shell +function named \fBcommand_not_found_handle\fP. +If that function exists, it is invoked in a separate execution environment +with the original command and +the original command's arguments as its arguments, and the function's +exit status becomes the exit status of that subshell. +If that function is not defined, the shell prints an error +message and returns an exit status of 127. +.PP +If the search is successful, or if the command name contains +one or more slashes, the shell executes the named program in a +separate execution environment. +Argument 0 is set to the name given, and the remaining arguments +to the command are set to the arguments given, if any. +.PP +If this execution fails because the file is not in executable +format, and the file is not a directory, it is assumed to be +a \fIshell script\fP, a file +containing shell commands, and the shell creates a +new instance of itself +to execute it. +This subshell reinitializes itself, so +that the effect is as if a new shell had been invoked +to handle the script, with the exception that the locations of +commands remembered by the parent (see +.B hash +below under +.SM +\fBSHELL BUILTIN COMMANDS\fP) +are retained by the child. +.PP +If the program is a file beginning with +.BR #! , +the remainder of the first line specifies an interpreter +for the program. The shell executes the +specified interpreter on operating systems that do not +handle this executable format themselves. The arguments to the +interpreter consist of a single optional argument following the +interpreter name on the first line of the program, followed +by the name of the program, followed by the command +arguments, if any. +.SH COMMAND EXECUTION ENVIRONMENT +The shell has an \fIexecution environment\fP, which consists of the +following: +.IP \(bu +open files inherited by the shell at invocation, as modified by +redirections supplied to the \fBexec\fP builtin +.IP \(bu +the current working directory as set by \fBcd\fP, \fBpushd\fP, or +\fBpopd\fP, or inherited by the shell at invocation +.IP \(bu +the file creation mode mask as set by \fBumask\fP or inherited from +the shell's parent +.IP \(bu +current traps set by \fBtrap\fP +.IP \(bu +shell parameters that are set by variable assignment or with \fBset\fP +or inherited from the shell's parent in the environment +.IP \(bu +shell functions defined during execution or inherited from the shell's +parent in the environment +.IP \(bu +options enabled at invocation (either by default or with command-line +arguments) or by \fBset\fP +.IP \(bu +options enabled by \fBshopt\fP +.IP \(bu +shell aliases defined with \fBalias\fP +.IP \(bu +various process IDs, including those of background jobs, the value +of \fB$$\fP, and the value of +.SM +.B PPID +.PP +When a simple command other than a builtin or shell function +is to be executed, it +is invoked in a separate execution environment that consists of +the following. +Unless otherwise noted, the values are inherited from the shell. +.if n .sp 1 +.IP \(bu +the shell's open files, plus any modifications and additions specified +by redirections to the command +.IP \(bu +the current working directory +.IP \(bu +the file creation mode mask +.IP \(bu +shell variables and functions marked for export, along with variables +exported for the command, passed in the environment +.IP \(bu +traps caught by the shell are reset to the values inherited from the +shell's parent, and traps ignored by the shell are ignored +.PP +A command invoked in this separate environment cannot affect the +shell's execution environment. +.PP +A \fIsubshell\fP is a copy of the shell process. +.PP +Command substitution, commands grouped with parentheses, +and asynchronous commands are invoked in a +subshell environment that is a duplicate of the shell environment, +except that traps caught by the shell are reset to the values +that the shell inherited from its parent at invocation. Builtin +commands that are invoked as part of a pipeline are also executed in a +subshell environment. Changes made to the subshell environment +cannot affect the shell's execution environment. +.PP +Subshells spawned to execute command substitutions inherit the value of +the \fB\-e\fP option from the parent shell. When not in \fIposix mode\fP, +\fBbash\fP clears the \fB\-e\fP option in such subshells. +.PP +If a command is followed by a \fB&\fP and job control is not active, the +default standard input for the command is the empty file \fI/dev/null\fP. +Otherwise, the invoked command inherits the file descriptors of the calling +shell as modified by redirections. +.SH ENVIRONMENT +When a program is invoked it is given an array of strings +called the +.IR environment . +This is a list of +\fIname\fP\-\fIvalue\fP pairs, of the form +.IR "name\fR=\fPvalue" . +.PP +The shell provides several ways to manipulate the environment. +On invocation, the shell scans its own environment and +creates a parameter for each name found, automatically marking +it for +.I export +to child processes. Executed commands inherit the environment. +The +.B export +and +.B declare \-x +commands allow parameters and functions to be added to and +deleted from the environment. If the value of a parameter +in the environment is modified, the new value becomes part +of the environment, replacing the old. The environment +inherited by any executed command consists of the shell's +initial environment, whose values may be modified in the shell, +less any pairs removed by the +.B unset +command, plus any additions via the +.B export +and +.B declare \-x +commands. +.PP +The environment for any +.I simple command +or function may be augmented temporarily by prefixing it with +parameter assignments, as described above in +.SM +.BR PARAMETERS . +These assignment statements affect only the environment seen +by that command. +.PP +If the +.B \-k +option is set (see the +.B set +builtin command below), then +.I all +parameter assignments are placed in the environment for a command, +not just those that precede the command name. +.PP +When +.B bash +invokes an external command, the variable +.B _ +is set to the full filename of the command and passed to that +command in its environment. +.SH "EXIT STATUS" +The exit status of an executed command is the value returned by the +\fIwaitpid\fP system call or equivalent function. Exit statuses +fall between 0 and 255, though, as explained below, the shell may +use values above 125 specially. Exit statuses from shell builtins and +compound commands are also limited to this range. Under certain +circumstances, the shell will use special values to indicate specific +failure modes. +.PP +For the shell's purposes, a command which exits with a +zero exit status has succeeded. An exit status of zero +indicates success. A non-zero exit status indicates failure. +When a command terminates on a fatal signal \fIN\fP, \fBbash\fP uses +the value of 128+\fIN\fP as the exit status. +.PP +If a command is not found, the child process created to +execute it returns a status of 127. If a command is found +but is not executable, the return status is 126. +.PP +If a command fails because of an error during expansion or redirection, +the exit status is greater than zero. +.PP +Shell builtin commands return a status of 0 (\fItrue\fP) if +successful, and non-zero (\fIfalse\fP) if an error occurs +while they execute. +All builtins return an exit status of 2 to indicate incorrect usage, +generally invalid options or missing arguments. +.PP +The exit status of the last command is available in the special +parameter $?. +.PP +\fBBash\fP itself returns the exit status of the last command +executed, unless a syntax error occurs, in which case it exits +with a non-zero value. See also the \fBexit\fP builtin +command below. +.SH SIGNALS +When \fBbash\fP is interactive, in the absence of any traps, it ignores +.SM +.B SIGTERM +(so that \fBkill 0\fP does not kill an interactive shell), +and +.SM +.B SIGINT +is caught and handled (so that the \fBwait\fP builtin is interruptible). +In all cases, \fBbash\fP ignores +.SM +.BR SIGQUIT . +If job control is in effect, +.B bash +ignores +.SM +.BR SIGTTIN , +.SM +.BR SIGTTOU , +and +.SM +.BR SIGTSTP . +.PP +Non-builtin commands run by \fBbash\fP have signal handlers +set to the values inherited by the shell from its parent. +When job control is not in effect, asynchronous commands +ignore +.SM +.B SIGINT +and +.SM +.B SIGQUIT +in addition to these inherited handlers. +Commands run as a result of command substitution ignore the +keyboard-generated job control signals +.SM +.BR SIGTTIN , +.SM +.BR SIGTTOU , +and +.SM +.BR SIGTSTP . +.PP +The shell exits by default upon receipt of a +.SM +.BR SIGHUP . +Before exiting, an interactive shell resends the +.SM +.B SIGHUP +to all jobs, running or stopped. +Stopped jobs are sent +.SM +.B SIGCONT +to ensure that they receive the +.SM +.BR SIGHUP . +To prevent the shell from +sending the signal to a particular job, it should be removed from the +jobs table with the +.B disown +builtin (see +.SM +.B "SHELL BUILTIN COMMANDS" +below) or marked +to not receive +.SM +.B SIGHUP +using +.BR "disown \-h" . +.PP +If the +.B huponexit +shell option has been set with +.BR shopt , +.B bash +sends a +.SM +.B SIGHUP +to all jobs when an interactive login shell exits. +.PP +If \fBbash\fP is waiting for a command to complete and receives a signal +for which a trap has been set, the trap will not be executed until +the command completes. +When \fBbash\fP is waiting for an asynchronous command via the \fBwait\fP +builtin, the reception of a signal for which a trap has been set will +cause the \fBwait\fP builtin to return immediately with an exit status +greater than 128, immediately after which the trap is executed. +.PP +When job control is not enabled, and \fBbash\fP is waiting for a foreground +command to complete, the shell receives keyboard-generated signals +such as +.SM +.B SIGINT +(usually generated by \fB^C\fP) that users commonly intend to send +to that command. +This happens because the shell and the command are in the +same process group as the terminal, and \fB^C\fP sends +.SM +.B SIGINT +to all processes in that process group. +.PP +When \fBbash\fP is running without job control enabled and receives +.SM +.B SIGINT +while waiting for a foreground command, it waits until that foreground +command terminates and then decides what to do about the +.SM +.BR SIGINT : +.IP 1. +If the command terminates due to the +.SM +.BR SIGINT , +\fBbash\fP concludes +that the user meant to end the entire script, and acts on the +.SM +.B SIGINT +(e.g., by running a +.SM +.B SIGINT +trap or exiting itself); +.IP 2. +If the command does not terminate due to +.SM +.BR SIGINT , +the program handled the +.SM +.B SIGINT +itself and did not treat it as a fatal signal. +In that case, \fBbash\fP does not treat +.SM +.B SIGINT +as a fatal signal, either, instead assuming that the +.SM +.B SIGINT +was used as part of the program's normal operation +(e.g., emacs uses it to abort editing +commands) or deliberately discarded. +However, \fBbash\fP will run any +trap set on +.SM +.BR SIGINT , +as it does with any other trapped signal it +receives while it is waiting for the foreground command to +complete, for compatibility. +.SH "JOB CONTROL" +.I Job control +refers to the ability to selectively stop (\fIsuspend\fP) +the execution of processes and continue (\fIresume\fP) +their execution at a later point. A user typically employs +this facility via an interactive interface supplied jointly +by the operating system kernel's terminal driver and +.BR bash . +.PP +The shell associates a +.I job +with each pipeline. It keeps a table of currently executing +jobs, which may be listed with the +.B jobs +command. When +.B bash +starts a job asynchronously (in the +.IR background ), +it prints a line that looks like: +.RS +.PP +[1] 25647 +.RE +.PP +indicating that this job is job number 1 and that the process ID +of the last process in the pipeline associated with this job is 25647. +All of the processes in a single pipeline are members of the same job. +.B Bash +uses the +.I job +abstraction as the basis for job control. +.PP +To facilitate the implementation of the user interface to job +control, the operating system maintains the notion of a \fIcurrent terminal +process group ID\fP. Members of this process group (processes whose +process group ID is equal to the current terminal process group ID) +receive keyboard-generated signals such as +.SM +.BR SIGINT . +These processes are said to be in the +.IR foreground . +.I Background +processes are those whose process group ID differs from the terminal's; +such processes are immune to keyboard-generated signals. +Only foreground processes are allowed to read from or, if the +user so specifies with \f(CWstty tostop\fP, write to the +terminal. +Background processes which attempt to read from (write to when +\f(CWstty tostop\fP is in effect) the +terminal are sent a +.SM +.B SIGTTIN (SIGTTOU) +signal by the kernel's terminal driver, +which, unless caught, suspends the process. +.PP +If the operating system on which +.B bash +is running supports +job control, +.B bash +contains facilities to use it. +Typing the +.I suspend +character (typically +.BR ^Z , +Control-Z) while a process is running +causes that process to be stopped and returns control to +.BR bash . +Typing the +.I "delayed suspend" +character (typically +.BR ^Y , +Control-Y) causes the process to be stopped when it +attempts to read input from the terminal, and control to +be returned to +.BR bash . +The user may then manipulate the state of this job, using the +.B bg +command to continue it in the background, the +.B fg +command to continue it in the foreground, or +the +.B kill +command to kill it. A \fB^Z\fP takes effect immediately, +and has the additional side effect of causing pending output +and typeahead to be discarded. +.PP +There are a number of ways to refer to a job in the shell. +The character +.B % +introduces a job specification (\fIjobspec\fP). Job number +.I n +may be referred to as +.BR %n . +A job may also be referred to using a prefix of the name used to +start it, or using a substring that appears in its command line. +For example, +.B %ce +refers to a stopped +job whose command name begins with +.BR ce . +If a prefix matches more than one job, +.B bash +reports an error. Using +.BR %?ce , +on the other hand, refers to any job containing the string +.B ce +in its command line. If the substring matches more than one job, +.B bash +reports an error. The symbols +.B %% +and +.B %+ +refer to the shell's notion of the +.IR "current job" , +which is the last job stopped while it was in +the foreground or started in the background. +The +.I "previous job" +may be referenced using +.BR %\- . +If there is only a single job, \fB%+\fP and \fB%\-\fP can both be used +to refer to that job. +In output pertaining to jobs (e.g., the output of the +.B jobs +command), the current job is always flagged with a +.BR + , +and the previous job with a +.BR \- . +A single % (with no accompanying job specification) also refers to the +current job. +.PP +Simply naming a job can be used to bring it into the +foreground: +.B %1 +is a synonym for +\fB``fg %1''\fP, +bringing job 1 from the background into the foreground. +Similarly, +.B ``%1 &'' +resumes job 1 in the background, equivalent to +\fB``bg %1''\fP. +.PP +The shell learns immediately whenever a job changes state. +Normally, +.B bash +waits until it is about to print a prompt before reporting +changes in a job's status so as to not interrupt +any other output. If the +.B \-b +option to the +.B set +builtin command +is enabled, +.B bash +reports such changes immediately. +Any trap on +.SM +.B SIGCHLD +is executed for each child that exits. +.PP +If an attempt to exit +.B bash +is made while jobs are stopped (or, if the \fBcheckjobs\fP shell option has +been enabled using the \fBshopt\fP builtin, running), the shell prints a +warning message, and, if the \fBcheckjobs\fP option is enabled, lists the +jobs and their statuses. +The +.B jobs +command may then be used to inspect their status. +If a second attempt to exit is made without an intervening command, +the shell does not print another warning, and any stopped +jobs are terminated. +.PP +When the shell is waiting for a job or process using the \fBwait\fP +builtin, and job control is enabled, \fBwait\fP will return when the +job changes state. The \fB\-f\fP option causes \fBwait\fP to wait +until the job or process terminates before returning. +.SH PROMPTING +When executing interactively, +.B bash +displays the primary prompt +.SM +.B PS1 +when it is ready to read a command, and the secondary prompt +.SM +.B PS2 +when it needs more input to complete a command. +.B Bash +displays +.SM +.B PS0 +after it reads a command but before executing it. +.B Bash +displays +.SM +.B PS4 +as described above +before tracing each command when the \fB\-x\fP option is enabled. +.B Bash +allows these prompt strings to be customized by inserting a number of +backslash-escaped special characters that are decoded as follows: +.RS +.PD 0 +.TP +.B \ea +an ASCII bell character (07) +.TP +.B \ed +the date in "Weekday Month Date" format (e.g., "Tue May 26") +.TP +.B \eD{\fIformat\fP} +the \fIformat\fP is passed to \fIstrftime\fP(3) and the result is inserted +into the prompt string; an empty \fIformat\fP results in a locale-specific +time representation. The braces are required +.TP +.B \ee +an ASCII escape character (033) +.TP +.B \eh +the hostname up to the first `.' +.TP +.B \eH +the hostname +.TP +.B \ej +the number of jobs currently managed by the shell +.TP +.B \el +the basename of the shell's terminal device name +.TP +.B \en +newline +.TP +.B \er +carriage return +.TP +.B \es +the name of the shell, the basename of +.B $0 +(the portion following the final slash) +.TP +.B \et +the current time in 24-hour HH:MM:SS format +.TP +.B \eT +the current time in 12-hour HH:MM:SS format +.TP +.B \e@ +the current time in 12-hour am/pm format +.TP +.B \eA +the current time in 24-hour HH:MM format +.TP +.B \eu +the username of the current user +.TP +.B \ev +the version of \fBbash\fP (e.g., 2.00) +.TP +.B \eV +the release of \fBbash\fP, version + patch level (e.g., 2.00.0) +.TP +.B \ew +the value of the \fBPWD\fP shell variable (\fB$PWD\fP), +with +.SM +.B $HOME +abbreviated with a tilde +(uses the value of the +.SM +.B PROMPT_DIRTRIM +variable) +.TP +.B \eW +the basename of \fB$PWD\fP, +with +.SM +.B $HOME +abbreviated with a tilde +.TP +.B \e! +the history number of this command +.TP +.B \e# +the command number of this command +.TP +.B \e$ +if the effective UID is 0, a +.BR # , +otherwise a +.B $ +.TP +.B \e\fInnn\fP +the character corresponding to the octal number \fInnn\fP +.TP +.B \e\e +a backslash +.TP +.B \e[ +begin a sequence of non-printing characters, which could be used to +embed a terminal control sequence into the prompt +.TP +.B \e] +end a sequence of non-printing characters +.PD +.RE +.PP +The command number and the history number are usually different: +the history number of a command is its position in the history +list, which may include commands restored from the history file +(see +.SM +.B HISTORY +below), while the command number is the position in the sequence +of commands executed during the current shell session. +After the string is decoded, it is expanded via +parameter expansion, command substitution, arithmetic +expansion, and quote removal, subject to the value of the +.B promptvars +shell option (see the description of the +.B shopt +command under +.SM +.B "SHELL BUILTIN COMMANDS" +below). +This can have unwanted side effects if escaped portions of the string +appear within command substitution or contain characters special to +word expansion. +.SH READLINE +This is the library that handles reading input when using an interactive +shell, unless the +.B \-\-noediting +option is given at shell invocation. +Line editing is also used when using the \fB\-e\fP option to the +\fBread\fP builtin. +By default, the line editing commands are similar to those of Emacs. +A vi-style line editing interface is also available. +Line editing can be enabled at any time using the +.B \-o emacs +or +.B \-o vi +options to the +.B set +builtin (see +.SM +.B SHELL BUILTIN COMMANDS +below). +To turn off line editing after the shell is running, use the +.B +o emacs +or +.B +o vi +options to the +.B set +builtin. +.SS "Readline Notation" +In this section, the Emacs-style notation is used to denote +keystrokes. Control keys are denoted by C\-\fIkey\fR, e.g., C\-n +means Control\-N. Similarly, +.I meta +keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X. (On keyboards +without a +.I meta +key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key +then the +.I x +key. This makes ESC the \fImeta prefix\fP. +The combination M\-C\-\fIx\fP means ESC\-Control\-\fIx\fP, +or press the Escape key +then hold the Control key while pressing the +.I x +key.) +.PP +Readline commands may be given numeric +.IR arguments , +which normally act as a repeat count. +Sometimes, however, it is the sign of the argument that is significant. +Passing a negative argument to a command that acts in the forward +direction (e.g., \fBkill\-line\fP) causes that command to act in a +backward direction. +Commands whose behavior with arguments deviates from this are noted +below. +.PP +When a command is described as \fIkilling\fP text, the text +deleted is saved for possible future retrieval +(\fIyanking\fP). The killed text is saved in a +\fIkill ring\fP. Consecutive kills cause the text to be +accumulated into one unit, which can be yanked all at once. +Commands which do not kill text separate the chunks of text +on the kill ring. +.SS "Readline Initialization" +Readline is customized by putting commands in an initialization +file (the \fIinputrc\fP file). +The name of this file is taken from the value of the +.SM +.B INPUTRC +variable. If that variable is unset, the default is +.IR ~/.inputrc . +If that file does not exist or cannot be read, the ultimate default is +.IR /etc/inputrc . +When a program which uses the readline library starts up, the +initialization file is read, and the key bindings and variables +are set. +There are only a few basic constructs allowed in the +readline initialization file. +Blank lines are ignored. +Lines beginning with a \fB#\fP are comments. +Lines beginning with a \fB$\fP indicate conditional constructs. +Other lines denote key bindings and variable settings. +.PP +The default key-bindings may be changed with an +.I inputrc +file. +Other programs that use this library may add their own commands +and bindings. +.PP +For example, placing +.RS +.PP +M\-Control\-u: universal\-argument +.RE +or +.RS +C\-Meta\-u: universal\-argument +.RE +into the +.I inputrc +would make M\-C\-u execute the readline command +.IR universal\-argument . +.PP +The following symbolic character names are recognized: +.IR RUBOUT , +.IR DEL , +.IR ESC , +.IR LFD , +.IR NEWLINE , +.IR RET , +.IR RETURN , +.IR SPC , +.IR SPACE , +and +.IR TAB . +.PP +In addition to command names, readline allows keys to be bound +to a string that is inserted when the key is pressed (a \fImacro\fP). +.SS "Readline Key Bindings" +The syntax for controlling key bindings in the +.I inputrc +file is simple. All that is required is the name of the +command or the text of a macro and a key sequence to which +it should be bound. The name may be specified in one of two ways: +as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP +prefixes, or as a key sequence. +.PP +When using the form \fBkeyname\fP:\^\fIfunction\-name\fP or \fImacro\fP, +.I keyname +is the name of a key spelled out in English. For example: +.sp +.RS +Control-u: universal\-argument +.br +Meta-Rubout: backward-kill-word +.br +Control-o: "> output" +.RE +.LP +In the above example, +.I C\-u +is bound to the function +.BR universal\-argument , +.I M\-DEL +is bound to the function +.BR backward\-kill\-word , +and +.I C\-o +is bound to run the macro +expressed on the right hand side (that is, to insert the text +.if t \f(CW> output\fP +.if n ``> output'' +into the line). +.PP +In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP, +.B keyseq +differs from +.B keyname +above in that strings denoting +an entire key sequence may be specified by placing the sequence +within double quotes. Some GNU Emacs style key escapes can be +used, as in the following example, but the symbolic character names +are not recognized. +.sp +.RS +"\eC\-u": universal\-argument +.br +"\eC\-x\eC\-r": re\-read\-init\-file +.br +"\ee[11~": "Function Key 1" +.RE +.PP +In this example, +.I C\-u +is again bound to the function +.BR universal\-argument . +.I "C\-x C\-r" +is bound to the function +.BR re\-read\-init\-file , +and +.I "ESC [ 1 1 ~" +is bound to insert the text +.if t \f(CWFunction Key 1\fP. +.if n ``Function Key 1''. +.PP +The full set of GNU Emacs style escape sequences is +.RS +.PD 0 +.TP +.B \eC\- +control prefix +.TP +.B \eM\- +meta prefix +.TP +.B \ee +an escape character +.TP +.B \e\e +backslash +.TP +.B \e" +literal " +.TP +.B \e\(aq +literal \(aq +.RE +.PD +.PP +In addition to the GNU Emacs style escape sequences, a second +set of backslash escapes is available: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ed +delete +.TP +.B \ef +form feed +.TP +.B \en +newline +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(one to three digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.RE +.PD +.PP +When entering the text of a macro, single or double quotes must +be used to indicate a macro definition. +Unquoted text is assumed to be a function name. +In the macro body, the backslash escapes described above are expanded. +Backslash will quote any other character in the macro text, +including " and \(aq. +.PP +.B Bash +allows the current readline key bindings to be displayed or modified +with the +.B bind +builtin command. The editing mode may be switched during interactive +use by using the +.B \-o +option to the +.B set +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.SS "Readline Variables" +Readline has variables that can be used to further customize its +behavior. A variable may be set in the +.I inputrc +file with a statement of the form +.RS +.PP +\fBset\fP \fIvariable\-name\fP \fIvalue\fP +.RE +or using the \fBbind\fP builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). +.PP +Except where noted, readline variables can take the values +.B On +or +.B Off +(without regard to case). +Unrecognized variable names are ignored. +When a variable value is read, empty or null values, "on" (case-insensitive), +and "1" are equivalent to \fBOn\fP. All other values are equivalent to +\fBOff\fP. +The variables and their default values are: +.PP +.PD 0 +.TP +.B active\-region\-start\-color +A string variable that controls the text color and background when displaying +the text in the active region (see the description of +\fBenable\-active\-region\fP below). +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal before displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that puts the terminal in standout mode, +as obtained from the terminal's terminfo description. +A sample value might be \f(CW"\ee[01;33m"\fP. +.TP +.B active\-region\-end\-color +A string variable that "undoes" the effects of \fBactive\-region\-start\-color\fP +and restores "normal" terminal display appearance after displaying text +in the active region. +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal after displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that restores the terminal from standout mode, +as obtained from the terminal's terminfo description. +A sample value might be \f(CW"\ee[0m"\fP. +.TP +.B bell\-style (audible) +Controls what happens when readline wants to ring the terminal bell. +If set to \fBnone\fP, readline never rings the bell. If set to +\fBvisible\fP, readline uses a visible bell if one is available. +If set to \fBaudible\fP, readline attempts to ring the terminal's bell. +.TP +.B bind\-tty\-special\-chars (On) +If set to \fBOn\fP, readline attempts to bind the control characters +treated specially by the kernel's terminal driver to their readline +equivalents. +.TP +.B blink\-matching\-paren (Off) +If set to \fBOn\fP, readline attempts to briefly move the cursor to an +opening parenthesis when a closing parenthesis is inserted. +.TP +.B colored\-completion\-prefix (Off) +If set to \fBOn\fP, when listing completions, readline displays the +common prefix of the set of possible completions using a different color. +The color definitions are taken from the value of the \fBLS_COLORS\fP +environment variable. +If there is a color definition in \fB$LS_COLORS\fP for the custom suffix +"readline-colored-completion-prefix", readline uses this color for +the common prefix instead of its default. +.TP +.B colored\-stats (Off) +If set to \fBOn\fP, readline displays possible completions using different +colors to indicate their file type. +The color definitions are taken from the value of the \fBLS_COLORS\fP +environment variable. +.TP +.B comment\-begin (``#'') +The string that is inserted when the readline +.B insert\-comment +command is executed. +This command is bound to +.B M\-# +in emacs mode and to +.B # +in vi command mode. +.TP +.B completion\-display\-width (\-1) +The number of screen columns used to display possible matches +when performing completion. +The value is ignored if it is less than 0 or greater than the terminal +screen width. +A value of 0 will cause matches to be displayed one per line. +The default value is \-1. +.TP +.B completion\-ignore\-case (Off) +If set to \fBOn\fP, readline performs filename matching and completion +in a case\-insensitive fashion. +.TP +.B completion\-map\-case (Off) +If set to \fBOn\fP, and \fBcompletion\-ignore\-case\fP is enabled, readline +treats hyphens (\fI\-\fP) and underscores (\fI_\fP) as equivalent when +performing case\-insensitive filename matching and completion. +.TP +.B completion\-prefix\-display\-length (0) +The length in characters of the common prefix of a list of possible +completions that is displayed without modification. When set to a +value greater than zero, common prefixes longer than this value are +replaced with an ellipsis when displaying possible completions. +.TP +.B completion\-query\-items (100) +This determines when the user is queried about viewing +the number of possible completions +generated by the \fBpossible\-completions\fP command. +It may be set to any integer value greater than or equal to zero. +If the number of possible completions is greater than +or equal to the value of this variable, +readline will ask whether or not the user wishes to view them; +otherwise they are simply listed on the terminal. +A zero value means readline should never ask; negative values are +treated as zero. +.TP +.B convert\-meta (On) +If set to \fBOn\fP, readline will convert characters with the +eighth bit set to an ASCII key sequence +by stripping the eighth bit and prefixing an +escape character (in effect, using escape as the \fImeta prefix\fP). +The default is \fIOn\fP, but readline will set it to \fIOff\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B disable\-completion (Off) +If set to \fBOn\fP, readline will inhibit word completion. Completion +characters will be inserted into the line as if they had been +mapped to \fBself-insert\fP. +.TP +.B echo\-control\-characters (On) +When set to \fBOn\fP, on operating systems that indicate they support it, +readline echoes a character corresponding to a signal generated from the +keyboard. +.TP +.B editing\-mode (emacs) +Controls whether readline begins with a set of key bindings similar +to \fIEmacs\fP or \fIvi\fP. +.B editing\-mode +can be set to either +.B emacs +or +.BR vi . +.TP +.B emacs\-mode\-string (@) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when emacs editing mode is active. The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B enable\-active\-region (On) +The \fIpoint\fP is the current cursor position, and \fImark\fP refers +to a saved cursor position. +The text between the point and mark is referred to as the \fIregion\fP. +When this variable is set to \fIOn\fP, readline allows certain commands +to designate the region as \fIactive\fP. +When the region is active, readline highlights the text in the region using +the value of the \fBactive\-region\-start\-color\fP, which defaults to the +string that enables +the terminal's standout mode. +The active region shows the text inserted by bracketed-paste and any +matching text found by incremental and non-incremental history searches. +.TP +.B enable\-bracketed\-paste (On) +When set to \fBOn\fP, readline configures the terminal to insert each +paste into the editing buffer as a single string of characters, instead +of treating each character as if it had been read from the keyboard. +This prevents readline from executing any editing commands bound to key +sequences appearing in the pasted text. +.TP +.B enable\-keypad (Off) +When set to \fBOn\fP, readline will try to enable the application +keypad when it is called. Some systems need this to enable the +arrow keys. +.TP +.B enable\-meta\-key (On) +When set to \fBOn\fP, readline will try to enable any meta modifier +key the terminal claims to support when it is called. On many terminals, +the meta key is used to send eight-bit characters. +.TP +.B expand\-tilde (Off) +If set to \fBOn\fP, tilde expansion is performed when readline +attempts word completion. +.TP +.B history\-preserve\-point (Off) +If set to \fBOn\fP, the history code attempts to place point at the +same location on each history line retrieved with \fBprevious-history\fP +or \fBnext-history\fP. +.TP +.B history\-size (unset) +Set the maximum number of history entries saved in the history list. +If set to zero, any existing history entries are deleted and no new entries +are saved. +If set to a value less than zero, the number of history entries is not +limited. +By default, the number of history entries is set to the value of the +\fBHISTSIZE\fP shell variable. +If an attempt is made to set \fIhistory\-size\fP to a non-numeric value, +the maximum number of history entries will be set to 500. +.TP +.B horizontal\-scroll\-mode (Off) +When set to \fBOn\fP, makes readline use a single line for display, +scrolling the input horizontally on a single screen line when it +becomes longer than the screen width rather than wrapping to a new line. +This setting is automatically enabled for terminals of height 1. +.TP +.B input\-meta (Off) +If set to \fBOn\fP, readline will enable eight-bit input (that is, +it will not strip the eighth bit from the characters it reads), +regardless of what the terminal claims it can support. The name +.B meta\-flag +is a synonym for this variable. +The default is \fIOff\fP, but readline will set it to \fIOn\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B isearch\-terminators (``C\-[C\-J'') +The string of characters that should terminate an incremental +search without subsequently executing the character as a command. +If this variable has not been given a value, the characters +\fIESC\fP and \fIC\-J\fP will terminate an incremental search. +.TP +.B keymap (emacs) +Set the current readline keymap. The set of valid keymap names is +\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, +vi\-command\fP, and +.IR vi\-insert . +\fIvi\fP is equivalent to \fIvi\-command\fP; \fIemacs\fP is +equivalent to \fIemacs\-standard\fP. The default value is +.IR emacs ; +the value of +.B editing\-mode +also affects the default keymap. +.TP +.B keyseq\-timeout (500) +Specifies the duration \fIreadline\fP will wait for a character when reading an +ambiguous key sequence (one that can form a complete key sequence using +the input read so far, or can take additional input to complete a longer +key sequence). +If no input is received within the timeout, \fIreadline\fP will use the shorter +but complete key sequence. +The value is specified in milliseconds, so a value of 1000 means that +\fIreadline\fP will wait one second for additional input. +If this variable is set to a value less than or equal to zero, or to a +non-numeric value, \fIreadline\fP will wait until another key is pressed to +decide which key sequence to complete. +.TP +.B mark\-directories (On) +If set to \fBOn\fP, completed directory names have a slash +appended. +.TP +.B mark\-modified\-lines (Off) +If set to \fBOn\fP, history lines that have been modified are displayed +with a preceding asterisk (\fB*\fP). +.TP +.B mark\-symlinked\-directories (Off) +If set to \fBOn\fP, completed names which are symbolic links to directories +have a slash appended (subject to the value of +\fBmark\-directories\fP). +.TP +.B match\-hidden\-files (On) +This variable, when set to \fBOn\fP, causes readline to match files whose +names begin with a `.' (hidden files) when performing filename +completion. +If set to \fBOff\fP, the leading `.' must be +supplied by the user in the filename to be completed. +.TP +.B menu\-complete\-display\-prefix (Off) +If set to \fBOn\fP, menu completion displays the common prefix of the +list of possible completions (which may be empty) before cycling through +the list. +.TP +.B output\-meta (Off) +If set to \fBOn\fP, readline will display characters with the +eighth bit set directly rather than as a meta-prefixed escape +sequence. +The default is \fIOff\fP, but readline will set it to \fIOn\fP if the +locale contains eight-bit characters. +This variable is dependent on the \fBLC_CTYPE\fP locale category, and +may change if the locale is changed. +.TP +.B page\-completions (On) +If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager +to display a screenful of possible completions at a time. +.TP +.B print\-completions\-horizontally (Off) +If set to \fBOn\fP, readline will display completions with matches +sorted horizontally in alphabetical order, rather than down the screen. +.TP +.B revert\-all\-at\-newline (Off) +If set to \fBOn\fP, readline will undo all changes to history lines +before returning when \fBaccept\-line\fP is executed. By default, +history lines may be modified and retain individual undo lists across +calls to \fBreadline\fP. +.TP +.B show\-all\-if\-ambiguous (Off) +This alters the default behavior of the completion functions. If +set to +.BR On , +words which have more than one possible completion cause the +matches to be listed immediately instead of ringing the bell. +.TP +.B show\-all\-if\-unmodified (Off) +This alters the default behavior of the completion functions in +a fashion similar to \fBshow\-all\-if\-ambiguous\fP. +If set to +.BR On , +words which have more than one possible completion without any +possible partial completion (the possible completions don't share +a common prefix) cause the matches to be listed immediately instead +of ringing the bell. +.TP +.B show\-mode\-in\-prompt (Off) +If set to \fBOn\fP, add a string to the beginning of the prompt +indicating the editing mode: emacs, vi command, or vi insertion. +The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP). +.TP +.B skip\-completed\-text (Off) +If set to \fBOn\fP, this alters the default completion behavior when +inserting a single match into the line. It's only active when +performing completion in the middle of a word. If enabled, readline +does not insert characters from the completion that match characters +after point in the word being completed, so portions of the word +following the cursor are not duplicated. +.TP +.B vi\-cmd\-mode\-string ((cmd)) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in command mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B vi\-ins\-mode\-string ((ins)) +If the \fIshow\-mode\-in\-prompt\fP variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in insertion mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the \e1 and \e2 escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +.TP +.B visible\-stats (Off) +If set to \fBOn\fP, a character denoting a file's type as reported +by \fIstat\fP(2) is appended to the filename when listing possible +completions. +.PD +.SS "Readline Conditional Constructs" +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are four parser directives used. +.IP \fB$if\fP +The +.B $if +construct allows bindings to be made based on the +editing mode, the terminal being used, or the application using +readline. The text of the test, after any comparison operator, + extends to the end of the line; +unless otherwise noted, no characters are required to isolate it. +.RS +.IP \fBmode\fP +The \fBmode=\fP form of the \fB$if\fP directive is used to test +whether readline is in emacs or vi mode. +This may be used in conjunction +with the \fBset keymap\fP command, for instance, to set bindings in +the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if +readline is starting out in emacs mode. +.IP \fBterm\fP +The \fBterm=\fP form may be used to include terminal-specific +key bindings, perhaps to bind the key sequences output by the +terminal's function keys. The word on the right side of the +.B = +is tested against both the full name of the terminal and the portion +of the terminal name before the first \fB\-\fP. This allows +.I sun +to match both +.I sun +and +.IR sun\-cmd , +for instance. +.IP \fBversion\fP +The \fBversion\fP test may be used to perform comparisons against +specific readline versions. +The \fBversion\fP expands to the current readline version. +The set of comparison operators includes +.BR = , +(and +.BR == ), +.BR != , +.BR <= , +.BR >= , +.BR < , +and +.BR > . +The version number supplied on the right side of the operator consists +of a major version number, an optional decimal point, and an optional +minor version (e.g., \fB7.1\fP). If the minor version is omitted, it +is assumed to be \fB0\fP. +The operator may be separated from the string \fBversion\fP +and from the version number argument by whitespace. +.IP \fBapplication\fP +The \fBapplication\fP construct is used to include +application-specific settings. Each program using the readline +library sets the \fIapplication name\fP, and an initialization +file can test for a particular value. +This could be used to bind key sequences to functions useful for +a specific program. For instance, the following command adds a +key sequence that quotes the current or previous word in \fBbash\fP: +.sp 1 +.RS +.nf +\fB$if\fP Bash +# Quote the current or previous word +"\eC\-xq": "\eeb\e"\eef\e"" +\fB$endif\fP +.fi +.RE +.IP \fIvariable\fP +The \fIvariable\fP construct provides simple equality tests for readline +variables and values. +The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP. +The variable name must be separated from the comparison operator by +whitespace; the operator may be separated from the value on the right hand +side by whitespace. +Both string and boolean variables may be tested. Boolean variables must be +tested against the values \fIon\fP and \fIoff\fP. +.RE +.IP \fB$endif\fP +This command, as seen in the previous example, terminates an +\fB$if\fP command. +.IP \fB$else\fP +Commands in this branch of the \fB$if\fP directive are executed if +the test fails. +.IP \fB$include\fP +This directive takes a single filename as an argument and reads commands +and bindings from that file. For example, the following directive +would read \fI/etc/inputrc\fP: +.sp 1 +.RS +.nf +\fB$include\fP \^ \fI/etc/inputrc\fP +.fi +.RE +.SS Searching +Readline provides commands for searching through the command history +(see +.SM +.B HISTORY +below) for lines containing a specified string. +There are two search modes: +.I incremental +and +.IR non-incremental . +.PP +Incremental searches begin before the user has finished typing the +search string. +As each character of the search string is typed, readline displays +the next entry from the history matching the string typed so far. +An incremental search requires only as many characters as needed to +find the desired history entry. +The characters present in the value of the \fBisearch-terminators\fP +variable are used to terminate an incremental search. +If that variable has not been assigned a value the Escape and +Control-J characters will terminate an incremental search. +Control-G will abort an incremental search and restore the original +line. +When the search is terminated, the history entry containing the +search string becomes the current line. +.PP +To find other matching entries in the history list, type Control-S or +Control-R as appropriate. +This will search backward or forward in the history for the next +entry matching the search string typed so far. +Any other key sequence bound to a readline command will terminate +the search and execute that command. +For instance, a \fInewline\fP will terminate the search and accept +the line, thereby executing the command from the history list. +.PP +Readline remembers the last incremental search string. If two +Control-Rs are typed without any intervening characters defining a +new search string, any remembered search string is used. +.PP +Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. +.SS "Readline Command Names" +The following is a list of the names of the commands and the default +key sequences to which they are bound. +Command names without an accompanying key sequence are unbound by default. +In the following descriptions, \fIpoint\fP refers to the current cursor +position, and \fImark\fP refers to a cursor position saved by the +\fBset\-mark\fP command. +The text between the point and mark is referred to as the \fIregion\fP. +.SS Commands for Moving +.PD 0 +.TP +.B beginning\-of\-line (C\-a) +Move to the start of the current line. +.TP +.B end\-of\-line (C\-e) +Move to the end of the line. +.TP +.B forward\-char (C\-f) +Move forward a character. +.TP +.B backward\-char (C\-b) +Move back a character. +.TP +.B forward\-word (M\-f) +Move forward to the end of the next word. Words are composed of +alphanumeric characters (letters and digits). +.TP +.B backward\-word (M\-b) +Move back to the start of the current or previous word. +Words are composed of alphanumeric characters (letters and digits). +.TP +.B shell\-forward\-word +Move forward to the end of the next word. +Words are delimited by non-quoted shell metacharacters. +.TP +.B shell\-backward\-word +Move back to the start of the current or previous word. +Words are delimited by non-quoted shell metacharacters. +.TP +.B previous\-screen\-line +Attempt to move point to the same physical screen column on the previous +physical screen line. This will not have the desired effect if the current +readline line does not take up more than one physical line or if point is not +greater than the length of the prompt plus the screen width. +.TP +.B next\-screen\-line +Attempt to move point to the same physical screen column on the next +physical screen line. This will not have the desired effect if the current +readline line does not take up more than one physical line or if the length +of the current readline line is not greater than the length of the prompt +plus the screen width. +.TP +.B clear\-display (M\-C\-l) +Clear the screen and, if possible, the terminal's scrollback buffer, +then redraw the current line, +leaving the current line at the top of the screen. +.TP +.B clear\-screen (C\-l) +Clear the screen, +then redraw the current line, +leaving the current line at the top of the screen. +With an argument, refresh the current line without clearing the +screen. +.TP +.B redraw\-current\-line +Refresh the current line. +.PD +.SS Commands for Manipulating the History +.PD 0 +.TP +.B accept\-line (Newline, Return) +Accept the line regardless of where the cursor is. If this line is +non-empty, add it to the history list according to the state of the +.SM +.B HISTCONTROL +variable. If the line is a modified history +line, then restore the history line to its original state. +.TP +.B previous\-history (C\-p) +Fetch the previous command from the history list, moving back in +the list. +.TP +.B next\-history (C\-n) +Fetch the next command from the history list, moving forward in the +list. +.TP +.B beginning\-of\-history (M\-<) +Move to the first line in the history. +.TP +.B end\-of\-history (M\->) +Move to the end of the input history, i.e., the line currently being +entered. +.TP +.B operate\-and\-get\-next (C\-o) +Accept the current line for execution and fetch the next line +relative to the current line from the history for editing. +A numeric argument, if supplied, specifies the history entry to use instead +of the current line. +.TP +.B +fetch\-history +With a numeric argument, fetch that entry from the history list +and make it the current line. +Without an argument, move back to the first entry in the history list. +.TP +.B reverse\-search\-history (C\-r) +Search backward starting at the current line and moving `up' through +the history as necessary. This is an incremental search. +.TP +.B forward\-search\-history (C\-s) +Search forward starting at the current line and moving `down' through +the history as necessary. This is an incremental search. +.TP +.B non\-incremental\-reverse\-search\-history (M\-p) +Search backward through the history starting at the current line +using a non-incremental search for a string supplied by the user. +.TP +.B non\-incremental\-forward\-search\-history (M\-n) +Search forward through the history using a non-incremental search for +a string supplied by the user. +.TP +.B history\-search\-forward +Search forward through the history for the string of characters +between the start of the current line and the point. +This is a non-incremental search. +.TP +.B history\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the point. +This is a non-incremental search. +.TP +.B history\-substring\-search\-backward +Search backward through the history for the string of characters +between the start of the current line and the current cursor +position (the \fIpoint\fP). +The search string may match anywhere in a history line. +This is a non-incremental search. +.TP +.B history\-substring\-search\-forward +Search forward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +.TP +.B yank\-nth\-arg (M\-C\-y) +Insert the first argument to the previous command (usually +the second word on the previous line) at point. +With an argument +.IR n , +insert the \fIn\fPth word from the previous command (the words +in the previous command begin with word 0). A negative argument +inserts the \fIn\fPth word from the end of the previous command. +Once the argument \fIn\fP is computed, the argument is extracted +as if the "!\fIn\fP" history expansion had been specified. +.TP +.B +yank\-last\-arg (M\-.\^, M\-_\^) +Insert the last argument to the previous command (the last word of +the previous history entry). +With a numeric argument, behave exactly like \fByank\-nth\-arg\fP. +Successive calls to \fByank\-last\-arg\fP move back through the history +list, inserting the last word (or the word specified by the argument to +the first call) of each line in turn. +Any numeric argument supplied to these successive calls determines +the direction to move through the history. A negative argument switches +the direction through the history (back or forward). +The history expansion facilities are used to extract the last word, +as if the "!$" history expansion had been specified. +.TP +.B shell\-expand\-line (M\-C\-e) +Expand the line as the shell does. This +performs alias and history expansion as well as all of the shell +word expansions. See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B history\-expand\-line (M\-^) +Perform history expansion on the current line. +See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B magic\-space +Perform history expansion on the current line and insert a space. +See +.SM +.B HISTORY EXPANSION +below for a description of history expansion. +.TP +.B alias\-expand\-line +Perform alias expansion on the current line. +See +.SM +.B ALIASES +above for a description of alias expansion. +.TP +.B history\-and\-alias\-expand\-line +Perform history and alias expansion on the current line. +.TP +.B insert\-last\-argument (M\-.\^, M\-_\^) +A synonym for \fByank\-last\-arg\fP. +.TP +.B edit\-and\-execute\-command (C\-x C\-e) +Invoke an editor on the current command line, and execute the result as shell +commands. +\fBBash\fP attempts to invoke +.SM +.BR $VISUAL , +.SM +.BR $EDITOR , +and \fIemacs\fP as the editor, in that order. +.PD +.SS Commands for Changing Text +.PD 0 +.TP +.B \fIend\-of\-file\fP (usually C\-d) +The character indicating end-of-file as set, for example, by +.if t \f(CWstty\fP. +.if n ``stty''. +If this character is read when there are no characters +on the line, and point is at the beginning of the line, readline +interprets it as the end of input and returns +.SM +.BR EOF . +.TP +.B delete\-char (C\-d) +Delete the character at point. +If this function is bound to the +same character as the tty \fBEOF\fP character, as \fBC\-d\fP +commonly is, see above for the effects. +.TP +.B backward\-delete\-char (Rubout) +Delete the character behind the cursor. When given a numeric argument, +save the deleted text on the kill ring. +.TP +.B forward\-backward\-delete\-char +Delete the character under the cursor, unless the cursor is at the +end of the line, in which case the character behind the cursor is +deleted. +.TP +.B quoted\-insert (C\-q, C\-v) +Add the next character typed to the line verbatim. This is +how to insert characters like \fBC\-q\fP, for example. +.TP +.B tab\-insert (C\-v TAB) +Insert a tab character. +.TP +.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...) +Insert the character typed. +.TP +.B transpose\-chars (C\-t) +Drag the character before point forward over the character at point, +moving point forward as well. +If point is at the end of the line, then this transposes +the two characters before point. +Negative arguments have no effect. +.TP +.B transpose\-words (M\-t) +Drag the word before point past the word after point, +moving point over that word as well. +If point is at the end of the line, this transposes +the last two words on the line. +.TP +.B upcase\-word (M\-u) +Uppercase the current (or following) word. With a negative argument, +uppercase the previous word, but do not move point. +.TP +.B downcase\-word (M\-l) +Lowercase the current (or following) word. With a negative argument, +lowercase the previous word, but do not move point. +.TP +.B capitalize\-word (M\-c) +Capitalize the current (or following) word. With a negative argument, +capitalize the previous word, but do not move point. +.TP +.B overwrite\-mode +Toggle overwrite mode. With an explicit positive numeric argument, +switches to overwrite mode. With an explicit non-positive numeric +argument, switches to insert mode. This command affects only +\fBemacs\fP mode; \fBvi\fP mode does overwrite differently. +Each call to \fIreadline()\fP starts in insert mode. +In overwrite mode, characters bound to \fBself\-insert\fP replace +the text at point rather than pushing the text to the right. +Characters bound to \fBbackward\-delete\-char\fP replace the character +before point with a space. By default, this command is unbound. +.PD +.SS Killing and Yanking +.PD 0 +.TP +.B kill\-line (C\-k) +Kill the text from point to the end of the line. +.TP +.B backward\-kill\-line (C\-x Rubout) +Kill backward to the beginning of the line. +.TP +.B unix\-line\-discard (C\-u) +Kill backward from point to the beginning of the line. +The killed text is saved on the kill-ring. +.\" There is no real difference between this and backward-kill-line +.TP +.B kill\-whole\-line +Kill all characters on the current line, no matter where point is. +.TP +.B kill\-word (M\-d) +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as those used by \fBforward\-word\fP. +.TP +.B backward\-kill\-word (M\-Rubout) +Kill the word behind point. +Word boundaries are the same as those used by \fBbackward\-word\fP. +.TP +.B shell\-kill\-word +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as those used by \fBshell\-forward\-word\fP. +.TP +.B shell\-backward\-kill\-word +Kill the word behind point. +Word boundaries are the same as those used by \fBshell\-backward\-word\fP. +.TP +.B unix\-word\-rubout (C\-w) +Kill the word behind point, using white space as a word boundary. +The killed text is saved on the kill-ring. +.TP +.B unix\-filename\-rubout +Kill the word behind point, using white space and the slash character +as the word boundaries. +The killed text is saved on the kill-ring. +.TP +.B delete\-horizontal\-space (M\-\e) +Delete all spaces and tabs around point. +.TP +.B kill\-region +Kill the text in the current region. +.TP +.B copy\-region\-as\-kill +Copy the text in the region to the kill buffer. +.TP +.B copy\-backward\-word +Copy the word before point to the kill buffer. +The word boundaries are the same as \fBbackward\-word\fP. +.TP +.B copy\-forward\-word +Copy the word following point to the kill buffer. +The word boundaries are the same as \fBforward\-word\fP. +.TP +.B yank (C\-y) +Yank the top of the kill ring into the buffer at point. +.TP +.B yank\-pop (M\-y) +Rotate the kill ring, and yank the new top. Only works following +.B yank +or +.BR yank\-pop . +.PD +.SS Numeric Arguments +.PD 0 +.TP +.B digit\-argument (M\-0, M\-1, ..., M\-\-) +Add this digit to the argument already accumulating, or start a new +argument. M\-\- starts a negative argument. +.TP +.B universal\-argument +This is another way to specify an argument. +If this command is followed by one or more digits, optionally with a +leading minus sign, those digits define the argument. +If the command is followed by digits, executing +.B universal\-argument +again ends the numeric argument, but is otherwise ignored. +As a special case, if this command is immediately followed by a +character that is neither a digit nor minus sign, the argument count +for the next command is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four, a second time makes the +argument count sixteen, and so on. +.PD +.SS Completing +.PD 0 +.TP +.B complete (TAB) +Attempt to perform completion on the text before point. +.B Bash +attempts completion treating the text as a variable (if the +text begins with \fB$\fP), username (if the text begins with +\fB~\fP), hostname (if the text begins with \fB@\fP), or +command (including aliases and functions) in turn. If none +of these produces a match, filename completion is attempted. +.TP +.B possible\-completions (M\-?) +List the possible completions of the text before point. +.TP +.B insert\-completions (M\-*) +Insert all completions of the text before point +that would have been generated by +\fBpossible\-completions\fP. +.TP +.B menu\-complete +Similar to \fBcomplete\fP, but replaces the word to be completed +with a single match from the list of possible completions. +Repeated execution of \fBmenu\-complete\fP steps through the list +of possible completions, inserting each match in turn. +At the end of the list of completions, the bell is rung +(subject to the setting of \fBbell\-style\fP) +and the original text is restored. +An argument of \fIn\fP moves \fIn\fP positions forward in the list +of matches; a negative argument may be used to move backward +through the list. +This command is intended to be bound to \fBTAB\fP, but is unbound +by default. +.TP +.B menu\-complete\-backward +Identical to \fBmenu\-complete\fP, but moves backward through the list +of possible completions, as if \fBmenu\-complete\fP had been given a +negative argument. This command is unbound by default. +.TP +.B delete\-char\-or\-list +Deletes the character under the cursor if not at the beginning or +end of the line (like \fBdelete\-char\fP). +If at the end of the line, behaves identically to +\fBpossible\-completions\fP. +This command is unbound by default. +.TP +.B complete\-filename (M\-/) +Attempt filename completion on the text before point. +.TP +.B possible\-filename\-completions (C\-x /) +List the possible completions of the text before point, +treating it as a filename. +.TP +.B complete\-username (M\-~) +Attempt completion on the text before point, treating +it as a username. +.TP +.B possible\-username\-completions (C\-x ~) +List the possible completions of the text before point, +treating it as a username. +.TP +.B complete\-variable (M\-$) +Attempt completion on the text before point, treating +it as a shell variable. +.TP +.B possible\-variable\-completions (C\-x $) +List the possible completions of the text before point, +treating it as a shell variable. +.TP +.B complete\-hostname (M\-@) +Attempt completion on the text before point, treating +it as a hostname. +.TP +.B possible\-hostname\-completions (C\-x @) +List the possible completions of the text before point, +treating it as a hostname. +.TP +.B complete\-command (M\-!) +Attempt completion on the text before point, treating +it as a command name. Command completion attempts to +match the text against aliases, reserved words, shell +functions, shell builtins, and finally executable filenames, +in that order. +.TP +.B possible\-command\-completions (C\-x !) +List the possible completions of the text before point, +treating it as a command name. +.TP +.B dynamic\-complete\-history (M\-TAB) +Attempt completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. +.TP +.B dabbrev\-expand +Attempt menu completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. +.TP +.B complete\-into\-braces (M\-{) +Perform filename completion and insert the list of possible completions +enclosed within braces so the list is available to the shell (see +.B Brace Expansion +above). +.PD +.SS Keyboard Macros +.PD 0 +.TP +.B start\-kbd\-macro (C\-x (\^) +Begin saving the characters typed into the current keyboard macro. +.TP +.B end\-kbd\-macro (C\-x )\^) +Stop saving the characters typed into the current keyboard macro +and store the definition. +.TP +.B call\-last\-kbd\-macro (C\-x e) +Re-execute the last keyboard macro defined, by making the characters +in the macro appear as if typed at the keyboard. +.TP +.B print\-last\-kbd\-macro () +Print the last keyboard macro defined in a format suitable for the +\fIinputrc\fP file. +.PD +.SS Miscellaneous +.PD 0 +.TP +.B re\-read\-init\-file (C\-x C\-r) +Read in the contents of the \fIinputrc\fP file, and incorporate +any bindings or variable assignments found there. +.TP +.B abort (C\-g) +Abort the current editing command and +ring the terminal's bell (subject to the setting of +.BR bell\-style ). +.TP +.B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...) +If the metafied character \fIx\fP is uppercase, run the command +that is bound to the corresponding metafied lowercase character. +The behavior is undefined if \fIx\fP is already lowercase. +.TP +.B prefix\-meta (ESC) +Metafy the next character typed. +.SM +.B ESC +.B f +is equivalent to +.BR Meta\-f . +.TP +.B undo (C\-_, C\-x C\-u) +Incremental undo, separately remembered for each line. +.TP +.B revert\-line (M\-r) +Undo all changes made to this line. This is like executing the +.B undo +command enough times to return the line to its initial state. +.TP +.B tilde\-expand (M\-&) +Perform tilde expansion on the current word. +.TP +.B set\-mark (C\-@, M\-<space>) +Set the mark to the point. If a +numeric argument is supplied, the mark is set to that position. +.TP +.B exchange\-point\-and\-mark (C\-x C\-x) +Swap the point with the mark. The current cursor position is set to +the saved position, and the old cursor position is saved as the mark. +.TP +.B character\-search (C\-]) +A character is read and point is moved to the next occurrence of that +character. A negative argument searches for previous occurrences. +.TP +.B character\-search\-backward (M\-C\-]) +A character is read and point is moved to the previous occurrence of that +character. A negative argument searches for subsequent occurrences. +.TP +.B skip\-csi\-sequence +Read enough characters to consume a multi-key sequence such as those +defined for keys like Home and End. Such sequences begin with a +Control Sequence Indicator (CSI), usually ESC\-[. If this sequence is +bound to "\e[", keys producing such sequences will have no effect +unless explicitly bound to a readline command, instead of inserting +stray characters into the editing buffer. This is unbound by default, +but usually bound to ESC\-[. +.TP +.B insert\-comment (M\-#) +Without a numeric argument, the value of the readline +.B comment\-begin +variable is inserted at the beginning of the current line. +If a numeric argument is supplied, this command acts as a toggle: if +the characters at the beginning of the line do not match the value +of \fBcomment\-begin\fP, the value is inserted, otherwise +the characters in \fBcomment\-begin\fP are deleted from the beginning of +the line. +In either case, the line is accepted as if a newline had been typed. +The default value of +\fBcomment\-begin\fP causes this command to make the current line +a shell comment. +If a numeric argument causes the comment character to be removed, the line +will be executed by the shell. +.TP +.B spell\-correct\-word (C\-x s) +Perform spelling correction on the current word, treating it as a directory +or filename, in the same way as the \fBcdspell\fP shell option. +Word boundaries are the same as those used by \fBshell\-forward\-word\fP. +.TP +.B glob\-complete\-word (M\-g) +The word before point is treated as a pattern for pathname expansion, +with an asterisk implicitly appended. This pattern is used to +generate a list of matching filenames for possible completions. +.TP +.B glob\-expand\-word (C\-x *) +The word before point is treated as a pattern for pathname expansion, +and the list of matching filenames is inserted, replacing the word. +If a numeric argument is supplied, an asterisk is appended before +pathname expansion. +.TP +.B glob\-list\-expansions (C\-x g) +The list of expansions that would have been generated by +.B glob\-expand\-word +is displayed, and the line is redrawn. +If a numeric argument is supplied, an asterisk is appended before +pathname expansion. +.TP +.B dump\-functions +Print all of the functions and their key bindings to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-variables +Print all of the settable readline variables and their values to the +readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B dump\-macros +Print all of the readline key sequences bound to macros and the +strings they output. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an \fIinputrc\fP file. +.TP +.B display\-shell\-version (C\-x C\-v) +Display version information about the current instance of +.BR bash . +.PD +.SS Programmable Completion +When word completion is attempted for an argument to a command for +which a completion specification (a \fIcompspec\fP) has been defined +using the \fBcomplete\fP builtin (see +.SM +.B "SHELL BUILTIN COMMANDS" +below), the programmable completion facilities are invoked. +.PP +First, the command name is identified. +If the command word is the empty string (completion attempted at the +beginning of an empty line), any compspec defined with +the \fB\-E\fP option to \fBcomplete\fP is used. +If a compspec has been defined for that command, the +compspec is used to generate the list of possible completions for the word. +If the command word is a full pathname, a compspec for the full +pathname is searched for first. +If no compspec is found for the full pathname, an attempt is made to +find a compspec for the portion following the final slash. +If those searches do not result in a compspec, any compspec defined with +the \fB\-D\fP option to \fBcomplete\fP is used as the default. +If there is no default compspec, \fBbash\fP attempts alias expansion +on the command word as a final resort, and attempts to find a compspec +for the command word from any successful expansion. +.PP +Once a compspec has been found, it is used to generate the list of +matching words. +If a compspec is not found, the default \fBbash\fP completion as +described above under \fBCompleting\fP is performed. +.PP +First, the actions specified by the compspec are used. +Only matches which are prefixed by the word being completed are +returned. +When the +.B \-f +or +.B \-d +option is used for filename or directory name completion, the shell +variable +.SM +.B FIGNORE +is used to filter the matches. +.PP +Any completions specified by a pathname expansion pattern to the +\fB\-G\fP option are generated next. +The words generated by the pattern need not match the word +being completed. +The +.SM +.B GLOBIGNORE +shell variable is not used to filter the matches, but the +.SM +.B FIGNORE +variable is used. +.PP +Next, the string specified as the argument to the \fB\-W\fP option +is considered. +The string is first split using the characters in the +.SM +.B IFS +special variable as delimiters. +Shell quoting is honored. +Each word is then expanded using +brace expansion, tilde expansion, parameter and variable expansion, +command substitution, and arithmetic expansion, +as described above under +.SM +.BR EXPANSION . +The results are split using the rules described above under +\fBWord Splitting\fP. +The results of the expansion are prefix-matched against the word being +completed, and the matching words become the possible completions. +.PP +After these matches have been generated, any shell function or command +specified with the \fB\-F\fP and \fB\-C\fP options is invoked. +When the command or function is invoked, the +.SM +.BR COMP_LINE , +.SM +.BR COMP_POINT , +.SM +.BR COMP_KEY , +and +.SM +.B COMP_TYPE +variables are assigned values as described above under +\fBShell Variables\fP. +If a shell function is being invoked, the +.SM +.B COMP_WORDS +and +.SM +.B COMP_CWORD +variables are also set. +When the function or command is invoked, +the first argument (\fB$1\fP) is the name of the command whose arguments are +being completed, +the second argument (\fB$2\fP) is the word being completed, +and the third argument (\fB$3\fP) is the word preceding the word being +completed on the current command line. +No filtering of the generated completions against the word being completed +is performed; the function or command has complete freedom in generating +the matches. +.PP +Any function specified with \fB\-F\fP is invoked first. +The function may use any of the shell facilities, including the +\fBcompgen\fP builtin described below, to generate the matches. +It must put the possible completions in the +.SM +.B COMPREPLY +array variable, one per array element. +.PP +Next, any command specified with the \fB\-C\fP option is invoked +in an environment equivalent to command substitution. +It should print a list of completions, one per line, to the +standard output. +Backslash may be used to escape a newline, if necessary. +.PP +After all of the possible completions are generated, any filter +specified with the \fB\-X\fP option is applied to the list. +The filter is a pattern as used for pathname expansion; a \fB&\fP +in the pattern is replaced with the text of the word being completed. +A literal \fB&\fP may be escaped with a backslash; the backslash +is removed before attempting a match. +Any completion that matches the pattern will be removed from the list. +A leading \fB!\fP negates the pattern; in this case any completion +not matching the pattern will be removed. +If the +.B nocasematch +shell option is enabled, the match is performed without regard to the case +of alphabetic characters. +.PP +Finally, any prefix and suffix specified with the \fB\-P\fP and \fB\-S\fP +options are added to each member of the completion list, and the result is +returned to the readline completion code as the list of possible +completions. +.PP +If the previously-applied actions do not generate any matches, and the +\fB\-o dirnames\fP option was supplied to \fBcomplete\fP when the +compspec was defined, directory name completion is attempted. +.PP +If the \fB\-o plusdirs\fP option was supplied to \fBcomplete\fP when the +compspec was defined, directory name completion is attempted and any +matches are added to the results of the other actions. +.PP +By default, if a compspec is found, whatever it generates is returned +to the completion code as the full set of possible completions. +The default \fBbash\fP completions are not attempted, and the readline +default of filename completion is disabled. +If the \fB\-o bashdefault\fP option was supplied to \fBcomplete\fP when +the compspec was defined, the \fBbash\fP default completions are attempted +if the compspec generates no matches. +If the \fB\-o default\fP option was supplied to \fBcomplete\fP when the +compspec was defined, readline's default completion will be performed +if the compspec (and, if attempted, the default \fBbash\fP completions) +generate no matches. +.PP +When a compspec indicates that directory name completion is desired, +the programmable completion functions force readline to append a slash +to completed names which are symbolic links to directories, subject to +the value of the \fBmark\-directories\fP readline variable, regardless +of the setting of the \fBmark-symlinked\-directories\fP readline variable. +.PP +There is some support for dynamically modifying completions. This is +most useful when used in combination with a default completion specified +with \fBcomplete \-D\fP. +It's possible for shell functions executed as completion +handlers to indicate that completion should be retried by returning an +exit status of 124. If a shell function returns 124, and changes +the compspec associated with the command on which completion is being +attempted (supplied as the first argument when the function is executed), +programmable completion restarts from the beginning, with an +attempt to find a new compspec for that command. This allows a set of +completions to be built dynamically as completion is attempted, rather than +being loaded all at once. +.PP +For instance, assuming that there is a library of compspecs, each kept in a +file corresponding to the name of the command, the following default +completion function would load completions dynamically: +.PP +\f(CW_completion_loader() +.br +{ +.br + . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 +.br +} +.br +complete -D -F _completion_loader -o bashdefault -o default +.br +\fP +.SH HISTORY +When the +.B \-o history +option to the +.B set +builtin is enabled, the shell provides access to the +\fIcommand history\fP, +the list of commands previously typed. +The value of the +.SM +.B HISTSIZE +variable is used as the +number of commands to save in a history list. +The text of the last +.SM +.B HISTSIZE +commands (default 500) is saved. The shell +stores each command in the history list prior to parameter and +variable expansion (see +.SM +.B EXPANSION +above) but after history expansion is performed, subject to the +values of the shell variables +.SM +.B HISTIGNORE +and +.SM +.BR HISTCONTROL . +.PP +On startup, the history is initialized from the file named by +the variable +.SM +.B HISTFILE +(default \fI~/.bash_history\fP). +The file named by the value of +.SM +.B HISTFILE +is truncated, if necessary, to contain no more than +the number of lines specified by the value of +.SM +.BR HISTFILESIZE . +If \fBHISTFILESIZE\fP is unset, or set to null, a non-numeric value, +or a numeric value less than zero, the history file is not truncated. +When the history file is read, +lines beginning with the history comment character followed immediately +by a digit are interpreted as timestamps for the following history line. +These timestamps are optionally displayed depending on the value of the +.SM +.B HISTTIMEFORMAT +variable. +When a shell with history enabled exits, the last +.SM +.B $HISTSIZE +lines are copied from the history list to +.SM +.BR $HISTFILE . +If the +.B histappend +shell option is enabled +(see the description of +.B shopt +under +.SM +.B "SHELL BUILTIN COMMANDS" +below), the lines are appended to the history file, +otherwise the history file is overwritten. +If +.SM +.B HISTFILE +is unset, or if the history file is unwritable, the history is +not saved. +If the +.SM +.B HISTTIMEFORMAT +variable is set, time stamps are written to the history file, marked +with the history comment character, so +they may be preserved across shell sessions. +This uses the history comment character to distinguish timestamps from +other history lines. +After saving the history, the history file is truncated +to contain no more than +.SM +.B HISTFILESIZE +lines. If +.SM +.B HISTFILESIZE +is unset, or set to null, a non-numeric value, +or a numeric value less than zero, the history file is not truncated. +.PP +The builtin command +.B fc +(see +.SM +.B SHELL BUILTIN COMMANDS +below) may be used to list or edit and re-execute a portion of +the history list. +The +.B history +builtin may be used to display or modify the history list and +manipulate the history file. +When using command-line editing, search commands +are available in each editing mode that provide access to the +history list. +.PP +The shell allows control over which commands are saved on the history +list. The +.SM +.B HISTCONTROL +and +.SM +.B HISTIGNORE +variables may be set to cause the shell to save only a subset of the +commands entered. +The +.B cmdhist +shell option, if enabled, causes the shell to attempt to save each +line of a multi-line command in the same history entry, adding +semicolons where necessary to preserve syntactic correctness. +The +.B lithist +shell option causes the shell to save the command with embedded newlines +instead of semicolons. See the description of the +.B shopt +builtin below under +.SM +.B "SHELL BUILTIN COMMANDS" +for information on setting and unsetting shell options. +.SH "HISTORY EXPANSION" +The shell supports a history expansion feature that +is similar to the history expansion in +.BR csh . +This section describes what syntax features are available. This +feature is enabled by default for interactive shells, and can be +disabled using the +.B +H +option to the +.B set +builtin command (see +.SM +.B SHELL BUILTIN COMMANDS +below). Non-interactive shells do not perform history expansion +by default. +.PP +History expansions introduce words from the history list into +the input stream, making it easy to repeat commands, insert the +arguments to a previous command into the current input line, or +fix errors in previous commands quickly. +.PP +History expansion is performed immediately after a complete line +is read, before the shell breaks it into words, and is performed +on each line individually without taking quoting on previous lines into +account. +It takes place in two parts. +The first is to determine which line from the history list +to use during substitution. +The second is to select portions of that line for inclusion into +the current one. +The line selected from the history is the \fIevent\fP, +and the portions of that line that are acted upon are \fIwords\fP. +Various \fImodifiers\fP are available to manipulate the selected words. +The line is broken into words in the same fashion as when reading input, +so that several \fImetacharacter\fP-separated words surrounded by +quotes are considered one word. +History expansions are introduced by the appearance of the +history expansion character, which is \^\fB!\fP\^ by default. +Only backslash (\^\fB\e\fP\^) and single quotes can quote +the history expansion character, but the history expansion character is +also treated as quoted if it immediately precedes the closing double quote +in a double-quoted string. +.PP +Several characters inhibit history expansion if found immediately +following the history expansion character, even if it is unquoted: +space, tab, newline, carriage return, and \fB=\fP. +If the \fBextglob\fP shell option is enabled, \fB(\fP will also +inhibit expansion. +.PP +Several shell options settable with the +.B shopt +builtin may be used to tailor the behavior of history expansion. +If the +.B histverify +shell option is enabled (see the description of the +.B shopt +builtin below), and +.B readline +is being used, history substitutions are not immediately passed to +the shell parser. +Instead, the expanded line is reloaded into the +.B readline +editing buffer for further modification. +If +.B readline +is being used, and the +.B histreedit +shell option is enabled, a failed history substitution will be reloaded +into the +.B readline +editing buffer for correction. +The +.B \-p +option to the +.B history +builtin command may be used to see what a history expansion will +do before using it. +The +.B \-s +option to the +.B history +builtin may be used to add commands to the end of the history list +without actually executing them, so that they are available for +subsequent recall. +.PP +The shell allows control of the various characters used by the +history expansion mechanism (see the description of +.B histchars +above under +.BR "Shell Variables" ). +The shell uses +the history comment character to mark history timestamps when +writing the history file. +.SS Event Designators +An event designator is a reference to a command line entry in the +history list. +Unless the reference is absolute, events are relative to the current +position in the history list. +.PP +.PD 0 +.TP +.B ! +Start a history substitution, except when followed by a +.BR blank , +newline, carriage return, = +or ( (when the \fBextglob\fP shell option is enabled using +the \fBshopt\fP builtin). +.TP +.B !\fIn\fR +Refer to command line +.IR n . +.TP +.B !\-\fIn\fR +Refer to the current command minus +.IR n . +.TP +.B !! +Refer to the previous command. This is a synonym for `!\-1'. +.TP +.B !\fIstring\fR +Refer to the most recent command preceding the current position in the +history list starting with +.IR string . +.TP +.B !?\fIstring\fR\fB[?]\fR +Refer to the most recent command preceding the current position in the +history list containing +.IR string . +The trailing \fB?\fP may be omitted if +.I string +is followed immediately by a newline. +If \fIstring\fP is missing, the string from the most recent search is used; +it is an error if there is no previous search string. +.TP +.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u +Quick substitution. Repeat the previous command, replacing +.I string1 +with +.IR string2 . +Equivalent to +``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u'' +(see \fBModifiers\fP below). +.TP +.B !# +The entire command line typed so far. +.PD +.SS Word Designators +Word designators are used to select desired words from the event. +A +.B : +separates the event specification from the word designator. +It may be omitted if the word designator begins with a +.BR ^ , +.BR $ , +.BR * , +.BR \- , +or +.BR % . +Words are numbered from the beginning of the line, +with the first word being denoted by 0 (zero). +Words are inserted into the current line separated by single spaces. +.PP +.PD 0 +.TP +.B 0 (zero) +The zeroth word. For the shell, this is the command +word. +.TP +.I n +The \fIn\fRth word. +.TP +.B ^ +The first argument. That is, word 1. +.TP +.B $ +The last word. This is usually the last argument, but will expand to the +zeroth word if there is only one word in the line. +.TP +.B % +The first word matched by the most recent `?\fIstring\fR?' search, +if the search string begins with a character that is part of a word. +.TP +.I x\fB\-\fPy +A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. +.TP +.B * +All of the words but the zeroth. This is a synonym +for `\fI1\-$\fP'. It is not an error to use +.B * +if there is just one +word in the event; the empty string is returned in that case. +.TP +.B x* +Abbreviates \fIx\-$\fP. +.TP +.B x\- +Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. +If \fBx\fP is missing, it defaults to 0. +.PD +.PP +If a word designator is supplied without an event specification, the +previous command is used as the event. +.SS Modifiers +After the optional word designator, there may appear a sequence of +one or more of the following modifiers, each preceded by a `:'. +These modify, or edit, the word or words selected from the history event. +.PP +.PD 0 +.TP +.B h +Remove a trailing filename component, leaving only the head. +.TP +.B t +Remove all leading filename components, leaving the tail. +.TP +.B r +Remove a trailing suffix of the form \fI.xxx\fP, leaving the +basename. +.TP +.B e +Remove all but the trailing suffix. +.TP +.B p +Print the new command but do not execute it. +.TP +.B q +Quote the substituted words, escaping further substitutions. +.TP +.B x +Quote the substituted words as with +.BR q , +but break into words at +.B blanks +and newlines. +The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one +supplied is used. +.TP +.B s/\fIold\fP/\fInew\fP/ +Substitute +.I new +for the first occurrence of +.I old +in the event line. +Any character may be used as the delimiter in place of /. +The final delimiter is optional if it is the last character of the +event line. +The delimiter may be quoted in +.I old +and +.I new +with a single backslash. If & appears in +.IR new , +it is replaced by +.IR old . +A single backslash will quote the &. +If +.I old +is null, it is set to the last +.I old +substituted, or, if no previous history substitutions took place, +the last +.I string +in a +.B !?\fIstring\fR\fB[?]\fR +search. +If +.I new +is null, each matching +.I old +is deleted. +.TP +.B & +Repeat the previous substitution. +.TP +.B g +Cause changes to be applied over the entire event line. This is +used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') +or `\fB:&\fP'. If used with +`\fB:s\fP', any delimiter can be used +in place of /, and the final delimiter is optional +if it is the last character of the event line. +An \fBa\fP may be used as a synonym for \fBg\fP. +.TP +.B G +Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word +in the event line. +.PD +.SH "SHELL BUILTIN COMMANDS" +.\" start of bash_builtins +.zZ +.PP +Unless otherwise noted, each builtin command documented in this +section as accepting options preceded by +.B \- +accepts +.B \-\- +to signify the end of the options. +The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins +do not accept options and do not treat \fB\-\-\fP specially. +The \fBexit\fP, \fBlogout\fP, \fBreturn\fP, +\fBbreak\fP, \fBcontinue\fP, \fBlet\fP, +and \fBshift\fP builtins accept and process arguments beginning with +\fB\-\fP without requiring \fB\-\-\fP. +Other builtins that accept arguments but are not specified as accepting +options interpret arguments beginning with \fB\-\fP as invalid options and +require \fB\-\-\fP to prevent this interpretation. +.sp .5 +.PD 0 +.TP +\fB:\fP [\fIarguments\fP] +.PD +No effect; the command does nothing beyond expanding +.I arguments +and performing any specified +redirections. +The return status is zero. +.TP +\fB .\| \fP \fIfilename\fP [\fIarguments\fP] +.PD 0 +.TP +\fBsource\fP \fIfilename\fP [\fIarguments\fP] +.PD +Read and execute commands from +.I filename +in the current +shell environment and return the exit status of the last command +executed from +.IR filename . +If +.I filename +does not contain a slash, filenames in +.SM +.B PATH +are used to find the directory containing +.IR filename , +but \fIfilename\fP does not need to be executable. +The file searched for in +.SM +.B PATH +need not be executable. +When \fBbash\fP is not in \fIposix mode\fP, it searches +the current directory if no file is found in +.SM +.BR PATH . +If the +.B sourcepath +option to the +.B shopt +builtin command is turned off, the +.SM +.B PATH +is not searched. +If any \fIarguments\fP are supplied, they become the positional +parameters when \fIfilename\fP is executed. Otherwise the positional +parameters are unchanged. +If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on +\fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and +restored around the call to \fB.\fP, and \fB.\fP unsets the +\fBDEBUG\fP trap while it executes. +If \fB\-T\fP is not set, and the sourced file changes +the \fBDEBUG\fP trap, the new value is retained when \fB.\fP completes. +The return status is the status of the last command exited within +the script (0 if no commands are executed), and false if +.I filename +is not found or cannot be read. +.TP +\fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +\fBAlias\fP with no arguments or with the +.B \-p +option prints the list of aliases in the form +\fBalias\fP \fIname\fP=\fIvalue\fP on standard output. +When arguments are supplied, an alias is defined for +each \fIname\fP whose \fIvalue\fP is given. +A trailing space in \fIvalue\fP causes the next word to be +checked for alias substitution when the alias is expanded. +For each \fIname\fP in the argument list for which no \fIvalue\fP +is supplied, the name and value of the alias is printed. +\fBAlias\fP returns true unless a \fIname\fP is given for which +no alias has been defined. +.TP +\fBbg\fP [\fIjobspec\fP ...] +Resume each suspended job \fIjobspec\fP in the background, as if it +had been started with +.BR & . +If +.I jobspec +is not present, the shell's notion of the \fIcurrent job\fP is used. +.B bg +.I jobspec +returns 0 unless run when job control is disabled or, when run with +job control enabled, any specified \fIjobspec\fP was not found +or was started without job control. +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP] +.PD 0 +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP] +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP +.TP +\fBbind\fP \fIreadline-command-line\fP +.PD +Display current +.B readline +key and function bindings, bind a key sequence to a +.B readline +function or macro, or set a +.B readline +variable. +Each non-option argument is a command as it would appear in a +.B readline +initialization file such as +.IR .inputrc , +but each binding or command must be passed as a separate argument; +e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-m \fIkeymap\fP +Use +.I keymap +as the keymap to be affected by the subsequent bindings. +Acceptable +.I keymap +names are +\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, +vi\-move, vi\-command\fP, and +.IR vi\-insert . +\fIvi\fP is equivalent to \fIvi\-command\fP (\fIvi\-move\fP is also +a synonym); \fIemacs\fP is +equivalent to \fIemacs\-standard\fP. +.TP +.B \-l +List the names of all \fBreadline\fP functions. +.TP +.B \-p +Display \fBreadline\fP function names and bindings in such a way +that they can be re-read. +.TP +.B \-P +List current \fBreadline\fP function names and bindings. +.TP +.B \-s +Display \fBreadline\fP key sequences bound to macros and the strings +they output in such a way that they can be re-read. +.TP +.B \-S +Display \fBreadline\fP key sequences bound to macros and the strings +they output. +.TP +.B \-v +Display \fBreadline\fP variable names and values in such a way that they +can be re-read. +.TP +.B \-V +List current \fBreadline\fP variable names and values. +.TP +.B \-f \fIfilename\fP +Read key bindings from \fIfilename\fP. +.TP +.B \-q \fIfunction\fP +Query about which keys invoke the named \fIfunction\fP. +.TP +.B \-u \fIfunction\fP +Unbind all keys bound to the named \fIfunction\fP. +.TP +.B \-r \fIkeyseq\fP +Remove any current binding for \fIkeyseq\fP. +.TP +.B \-x \fIkeyseq\fP:\fIshell\-command\fP +Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is +entered. +When \fIshell\-command\fP is executed, the shell sets the +.SM +.B READLINE_LINE +variable to the contents of the \fBreadline\fP line buffer and the +.SM +.B READLINE_POINT +and +.SM +.B READLINE_MARK +variables to the current location of the insertion point and the saved +insertion point (the mark), respectively. +The shell assigns any numeric argument the user supplied to the +.SM +.B READLINE_ARGUMENT +variable. +If there was no argument, that variable is not set. +If the executed command changes the value of any of +.SM +.BR READLINE_LINE , +.SM +.BR READLINE_POINT , +or +.SM +.BR READLINE_MARK , +those new values will be reflected in the editing state. +.TP +.B \-X +List all key sequences bound to shell commands and the associated commands +in a format that can be reused as input. +.PD +.PP +The return value is 0 unless an unrecognized option is given or an +error occurred. +.RE +.TP +\fBbreak\fP [\fIn\fP] +Exit from within a +.BR for , +.BR while , +.BR until , +or +.B select +loop. If \fIn\fP is specified, break \fIn\fP levels. +.I n +must be \(>= 1. If +.I n +is greater than the number of enclosing loops, all enclosing loops +are exited. +The return value is 0 unless \fIn\fP is not greater than or equal to 1. +.TP +\fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP] +Execute the specified shell builtin, passing it +.IR arguments , +and return its exit status. +This is useful when defining a +function whose name is the same as a shell builtin, +retaining the functionality of the builtin within the function. +The \fBcd\fP builtin is commonly redefined this way. +The return status is false if +.I shell\-builtin +is not a shell builtin command. +.TP +\fBcaller\fP [\fIexpr\fP] +Returns the context of any active subroutine call (a shell function or +a script executed with the \fB.\fP or \fBsource\fP builtins). +Without \fIexpr\fP, \fBcaller\fP displays the line number and source +filename of the current subroutine call. +If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP +displays the line number, subroutine name, and source file corresponding +to that position in the current execution call stack. This extra +information may be used, for example, to print a stack trace. The +current frame is frame 0. +The return value is 0 unless the shell is not executing a subroutine +call or \fIexpr\fP does not correspond to a valid position in the +call stack. +.TP +\fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP] +Change the current directory to \fIdir\fP. +if \fIdir\fP is not supplied, the value of the +.SM +.B HOME +shell variable is the default. +The variable +.SM +.B CDPATH +defines the search path for the directory containing +.IR dir : +each directory name in +.SM +.B CDPATH +is searched for \fIdir\fP. +Alternative directory names in +.SM +.B CDPATH +are separated by a colon (:). A null directory name in +.SM +.B CDPATH +is the same as the current directory, i.e., ``\fB.\fP''. If +.I dir +begins with a slash (/), +then +.SM +.B CDPATH +is not used. The +.B \-P +option causes \fBcd\fP to use the physical directory structure +by resolving symbolic links while traversing \fIdir\fP and +before processing instances of \fI..\fP in \fIdir\fP (see also the +.B \-P +option to the +.B set +builtin command); the +.B \-L +option forces symbolic links to be followed by resolving the link +after processing instances of \fI..\fP in \fIdir\fP. +If \fI..\fP appears in \fIdir\fP, it is processed by removing the +immediately previous pathname component from \fIdir\fP, back to a slash +or the beginning of \fIdir\fP. +If the +.B \-e +option is supplied with +.BR \-P , +and the current working directory cannot be successfully determined +after a successful directory change, \fBcd\fP will return an unsuccessful +status. +On systems that support it, the \fB\-@\fP option presents the extended +attributes associated with a file as a directory. +An argument of +.B \- +is converted to +.SM +.B $OLDPWD +before the directory change is attempted. +If a non-empty directory name from +.SM +.B CDPATH +is used, or if +\fB\-\fP is the first argument, and the directory change is +successful, the absolute pathname of the new working directory is +written to the standard output. +If the directory change is successful, \fBcd\fP sets the value of the +\fBPWD\fP environment variable to the new directory name, and sets the +\fBOLDPWD\fP environment variable to the value of the current working +directory before the change. +The return value is true if the directory was successfully changed; +false otherwise. +.TP +\fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...] +Run +.I command +with +.I args +suppressing the normal shell function lookup. +Only builtin commands or commands found in the +.SM +.B PATH +are executed. If the +.B \-p +option is given, the search for +.I command +is performed using a default value for +.SM +.B PATH +that is guaranteed to find all of the standard utilities. +If either the +.B \-V +or +.B \-v +option is supplied, a description of +.I command +is printed. The +.B \-v +option causes a single word indicating the command or filename +used to invoke +.I command +to be displayed; the +.B \-V +option produces a more verbose description. +If the +.B \-V +or +.B \-v +option is supplied, the exit status is 0 if +.I command +was found, and 1 if not. If neither option is supplied and +an error occurred or +.I command +cannot be found, the exit status is 127. Otherwise, the exit status of the +.B command +builtin is the exit status of +.IR command . +.TP +\fBcompgen\fP [\fIoption\fP] [\fIword\fP] +Generate possible completion matches for \fIword\fP according to +the \fIoption\fPs, which may be any option accepted by the +.B complete +builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write +the matches to the standard output. +When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables +set by the programmable completion facilities, while available, will not +have useful values. +.sp 1 +The matches will be generated in the same way as if the programmable +completion code had generated them directly from a completion specification +with the same flags. +If \fIword\fP is specified, only those completions matching \fIword\fP +will be displayed. +.sp 1 +The return value is true unless an invalid option is supplied, or no +matches were generated. +.TP +\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] +.br +[\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP] +.PD 0 +.TP +\fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...] +.PD +Specify how arguments to each \fIname\fP should be completed. +If the \fB\-p\fP option is supplied, or if no options are supplied, +existing completion specifications are printed in a way that allows +them to be reused as input. +The \fB\-r\fP option removes a completion specification for +each \fIname\fP, or, if no \fIname\fPs are supplied, all +completion specifications. +The \fB\-D\fP option indicates that other supplied options and actions should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The \fB\-E\fP option indicates that other supplied options and actions should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The \fB\-I\fP option indicates that other supplied options and actions should +apply to completion on the initial non-assignment word on the line, or after +a command delimiter such as \fB;\fP or \fB|\fP, which is usually command +name completion. +If multiple options are supplied, the \fB\-D\fP option takes precedence +over \fB\-E\fP, and both take precedence over \fB\-I\fP. +If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other +\fIname\fP arguments are ignored; these completions only apply to the case +specified by the option. +.sp 1 +The process of applying these completion specifications when word completion +is attempted is described +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above under \fBProgrammable Completion\fP. +.sp 1 +Other options, if specified, have the following meanings. +The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options +(and, if necessary, the \fB\-P\fP and \fB\-S\fP options) +should be quoted to protect them from expansion before the +.B complete +builtin is invoked. +.RS +.PD 0 +.TP 8 +\fB\-o\fP \fIcomp-option\fP +The \fIcomp-option\fP controls several aspects of the compspec's behavior +beyond the simple generation of completions. +\fIcomp-option\fP may be one of: +.RS +.TP 8 +.B bashdefault +Perform the rest of the default \fBbash\fP completions if the compspec +generates no matches. +.TP 8 +.B default +Use readline's default filename completion if the compspec generates +no matches. +.TP 8 +.B dirnames +Perform directory name completion if the compspec generates no matches. +.TP 8 +.B filenames +Tell readline that the compspec generates filenames, so it can perform any +filename\-specific processing (like adding a slash to directory names, +quoting special characters, or suppressing trailing spaces). +Intended to be used with shell functions. +.TP 8 +.B noquote +Tell readline not to quote the completed words if they are filenames +(quoting filenames is the default). +.TP 8 +.B nosort +Tell readline not to sort the list of possible completions alphabetically. +.TP 8 +.B nospace +Tell readline not to append a space (the default) to words completed at +the end of the line. +.TP 8 +.B plusdirs +After any matches defined by the compspec are generated, +directory name completion is attempted and any +matches are added to the results of the other actions. +.RE +.TP 8 +\fB\-A\fP \fIaction\fP +The \fIaction\fP may be one of the following to generate a list of possible +completions: +.RS +.TP 8 +.B alias +Alias names. May also be specified as \fB\-a\fP. +.TP 8 +.B arrayvar +Array variable names. +.TP 8 +.B binding +\fBReadline\fP key binding names. +.TP 8 +.B builtin +Names of shell builtin commands. May also be specified as \fB\-b\fP. +.TP 8 +.B command +Command names. May also be specified as \fB\-c\fP. +.TP 8 +.B directory +Directory names. May also be specified as \fB\-d\fP. +.TP 8 +.B disabled +Names of disabled shell builtins. +.TP 8 +.B enabled +Names of enabled shell builtins. +.TP 8 +.B export +Names of exported shell variables. May also be specified as \fB\-e\fP. +.TP 8 +.B file +File names. May also be specified as \fB\-f\fP. +.TP 8 +.B function +Names of shell functions. +.TP 8 +.B group +Group names. May also be specified as \fB\-g\fP. +.TP 8 +.B helptopic +Help topics as accepted by the \fBhelp\fP builtin. +.TP 8 +.B hostname +Hostnames, as taken from the file specified by the +.SM +.B HOSTFILE +shell variable. +.TP 8 +.B job +Job names, if job control is active. May also be specified as \fB\-j\fP. +.TP 8 +.B keyword +Shell reserved words. May also be specified as \fB\-k\fP. +.TP 8 +.B running +Names of running jobs, if job control is active. +.TP 8 +.B service +Service names. May also be specified as \fB\-s\fP. +.TP 8 +.B setopt +Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin. +.TP 8 +.B shopt +Shell option names as accepted by the \fBshopt\fP builtin. +.TP 8 +.B signal +Signal names. +.TP 8 +.B stopped +Names of stopped jobs, if job control is active. +.TP 8 +.B user +User names. May also be specified as \fB\-u\fP. +.TP 8 +.B variable +Names of all shell variables. May also be specified as \fB\-v\fP. +.RE +.TP 8 +\fB\-C\fP \fIcommand\fP +\fIcommand\fP is executed in a subshell environment, and its output is +used as the possible completions. +Arguments are passed as with the \fB\-F\fP option. +.TP 8 +\fB\-F\fP \fIfunction\fP +The shell function \fIfunction\fP is executed in the current shell +environment. +When the function is executed, +the first argument (\fB$1\fP) is the name of the command whose arguments are +being completed, +the second argument (\fB$2\fP) is the word being completed, +and the third argument (\fB$3\fP) is the word preceding the word being +completed on the current command line. +When it finishes, the possible completions are retrieved from the value +of the +.SM +.B COMPREPLY +array variable. +.TP 8 +\fB\-G\fP \fIglobpat\fP +The pathname expansion pattern \fIglobpat\fP is expanded to generate +the possible completions. +.TP 8 +\fB\-P\fP \fIprefix\fP +\fIprefix\fP is added at the beginning of each possible completion +after all other options have been applied. +.TP 8 +\fB\-S\fP \fIsuffix\fP +\fIsuffix\fP is appended to each possible completion +after all other options have been applied. +.TP 8 +\fB\-W\fP \fIwordlist\fP +The \fIwordlist\fP is split using the characters in the +.SM +.B IFS +special variable as delimiters, and each resultant word is expanded. +Shell quoting is honored within \fIwordlist\fP, +in order to provide a +mechanism for the words to contain shell metacharacters or characters +in the value of +.SM +.BR IFS . +The possible completions are the members of the resultant list which +match the word being completed. +.TP 8 +\fB\-X\fP \fIfilterpat\fP +\fIfilterpat\fP is a pattern as used for pathname expansion. +It is applied to the list of possible completions generated by the +preceding options and arguments, and each completion matching +\fIfilterpat\fP is removed from the list. +A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this +case, any completion not matching \fIfilterpat\fP is removed. +.PD +.PP +The return value is true unless an invalid option is supplied, an option +other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP +argument, an attempt is made to remove a completion specification for +a \fIname\fP for which no specification exists, or +an error occurs adding a completion specification. +.RE +.TP +\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP] +Modify completion options for each \fIname\fP according to the +\fIoption\fPs, or for the +currently-executing completion if no \fIname\fPs are supplied. +If no \fIoption\fPs are given, display the completion options for each +\fIname\fP or the current completion. +The possible values of \fIoption\fP are those valid for the \fBcomplete\fP +builtin described above. +The \fB\-D\fP option indicates that other supplied options should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The \fB\-E\fP option indicates that other supplied options should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The \fB\-I\fP option indicates that other supplied options should +apply to completion on the initial non-assignment word on the line, +or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually +command name completion. +.sp 1 +The return value is true unless an invalid option is supplied, an attempt +is made to modify the options for a \fIname\fP for which no completion +specification exists, or an output error occurs. +.TP +\fBcontinue\fP [\fIn\fP] +Resume the next iteration of the enclosing +.BR for , +.BR while , +.BR until , +or +.B select +loop. +If +.I n +is specified, resume at the \fIn\fPth enclosing loop. +.I n +must be \(>= 1. If +.I n +is greater than the number of enclosing loops, the last enclosing loop +(the ``top-level'' loop) is resumed. +The return value is 0 unless \fIn\fP is not greater than or equal to 1. +.TP +\fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +.PD 0 +.TP +\fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +.PD +Declare variables and/or give them attributes. +If no \fIname\fPs are given then display the values of variables. +The +.B \-p +option will display the attributes and values of each +.IR name . +When +.B \-p +is used with \fIname\fP arguments, additional options, +other than \fB\-f\fP and \fB\-F\fP, are ignored. +When +.B \-p +is supplied without \fIname\fP arguments, it will display the attributes +and values of all variables having the attributes specified by the +additional options. +If no other options are supplied with \fB\-p\fP, \fBdeclare\fP will display +the attributes and values of all shell variables. The \fB\-f\fP option +will restrict the display to shell functions. +The +.B \-F +option inhibits the display of function definitions; only the +function name and attributes are printed. +If the \fBextdebug\fP shell option is enabled using \fBshopt\fP, +the source file name and line number where each \fIname\fP +is defined are displayed as well. The +.B \-F +option implies +.BR \-f . +The +.B \-g +option forces variables to be created or modified at the global scope, +even when \fBdeclare\fP is executed in a shell function. +It is ignored in all other cases. +The +.B \-I +option causes local variables to inherit the attributes +(except the \fInameref\fP attribute) +and value of any existing variable with the same +\fIname\fP at a surrounding scope. +If there is no existing variable, the local variable is initially unset. +The following options can +be used to restrict output to variables with the specified attribute or +to give variables attributes: +.RS +.PD 0 +.TP +.B \-a +Each \fIname\fP is an indexed array variable (see +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B \-A +Each \fIname\fP is an associative array variable (see +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B \-f +Use function names only. +.TP +.B \-i +The variable is treated as an integer; arithmetic evaluation (see +.SM +.B "ARITHMETIC EVALUATION" +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +is performed when the variable is assigned a value. +.TP +.B \-l +When the variable is assigned a value, all upper-case characters are +converted to lower-case. +The upper-case attribute is disabled. +.TP +.B \-n +Give each \fIname\fP the \fInameref\fP attribute, making +it a name reference to another variable. +That other variable is defined by the value of \fIname\fP. +All references, assignments, and attribute modifications +to \fIname\fP, except those using or changing the +\fB\-n\fP attribute itself, are performed on the variable referenced by +\fIname\fP's value. +The nameref attribute cannot be applied to array variables. +.TP +.B \-r +Make \fIname\fPs readonly. These names cannot then be assigned values +by subsequent assignment statements or unset. +.TP +.B \-t +Give each \fIname\fP the \fItrace\fP attribute. +Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from +the calling shell. +The trace attribute has no special meaning for variables. +.TP +.B \-u +When the variable is assigned a value, all lower-case characters are +converted to upper-case. +The lower-case attribute is disabled. +.TP +.B \-x +Mark \fIname\fPs for export to subsequent commands via the environment. +.PD +.PP +Using `+' instead of `\-' +turns off the attribute instead, +with the exceptions that \fB+a\fP and \fB+A\fP +may not be used to destroy array variables and \fB+r\fP will not +remove the readonly attribute. +When used in a function, +.B declare +and +.B typeset +make each +\fIname\fP local, as with the +.B local +command, +unless the \fB\-g\fP option is supplied. +If a variable name is followed by =\fIvalue\fP, the value of +the variable is set to \fIvalue\fP. +When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to +create array variables, additional attributes do not take effect until +subsequent assignments. +The return value is 0 unless an invalid option is encountered, +an attempt is made to define a function using +.if n ``\-f foo=bar'', +.if t \f(CW\-f foo=bar\fP, +an attempt is made to assign a value to a readonly variable, +an attempt is made to assign a value to an array variable without +using the compound assignment syntax (see +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP), +.el above), +one of the \fInames\fP is not a valid shell variable name, +an attempt is made to turn off readonly status for a readonly variable, +an attempt is made to turn off array status for an array variable, +or an attempt is made to display a non-existent function with \fB\-f\fP. +.RE +.TP +.B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP] +Without options, displays the list of currently remembered directories. +The default display is on a single line with directory names separated +by spaces. +Directories are added to the list with the +.B pushd +command; the +.B popd +command removes entries from the list. +The current directory is always the first directory in the stack. +.RS +.PD 0 +.TP +.B \-c +Clears the directory stack by deleting all of the entries. +.TP +.B \-l +Produces a listing using full pathnames; +the default listing format uses a tilde to denote the home directory. +.TP +.B \-p +Print the directory stack with one entry per line. +.TP +.B \-v +Print the directory stack with one entry per line, +prefixing each entry with its index in the stack. +.TP +\fB+\fP\fIn\fP +Displays the \fIn\fPth entry counting from the left of the list +shown by +.B dirs +when invoked without options, starting with zero. +.TP +\fB\-\fP\fIn\fP +Displays the \fIn\fPth entry counting from the right of the list +shown by +.B dirs +when invoked without options, starting with zero. +.PD +.PP +The return value is 0 unless an +invalid option is supplied or \fIn\fP indexes beyond the end +of the directory stack. +.RE +.TP +\fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ] +Without options, remove each +.I jobspec +from the table of active jobs. +If +.I jobspec +is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option +is supplied, the \fIcurrent job\fP is used. +If the \fB\-h\fP option is given, each +.I jobspec +is not removed from the table, but is marked so that +.SM +.B SIGHUP +is not sent to the job if the shell receives a +.SM +.BR SIGHUP . +If no +.I jobspec +is supplied, the +.B \-a +option means to remove or mark all jobs; the +.B \-r +option without a +.I jobspec +argument restricts operation to running jobs. +The return value is 0 unless a +.I jobspec +does not specify a valid job. +.TP +\fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...] +Output the \fIarg\fPs, separated by spaces, followed by a newline. +The return status is 0 unless a write error occurs. +If \fB\-n\fP is specified, the trailing newline is +suppressed. If the \fB\-e\fP option is given, interpretation of +the following backslash-escaped characters is enabled. The +.B \-E +option disables the interpretation of these escape characters, +even on systems where they are interpreted by default. +The \fBxpg_echo\fP shell option may be used to +dynamically determine whether or not \fBecho\fP expands these +escape characters by default. +.B echo +does not interpret \fB\-\-\fP to mean the end of options. +.B echo +interprets the following escape sequences: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ec +suppress further output +.TP +.B \ee +.TP +.B \eE +an escape character +.TP +.B \ef +form feed +.TP +.B \en +new line +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\e +backslash +.TP +.B \e0\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(zero to three octal digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.TP +.B \eu\fIHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHH\fP (one to four hex digits) +.TP +.B \eU\fIHHHHHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHHHHHH\fP (one to eight hex digits) +.PD +.RE +.TP +\fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...] +Enable and disable builtin shell commands. +Disabling a builtin allows a disk command which has the same name +as a shell builtin to be executed without specifying a full pathname, +even though the shell normally searches for builtins before disk commands. +If \fB\-n\fP is used, each \fIname\fP +is disabled; otherwise, +\fInames\fP are enabled. For example, to use the +.B test +binary found via the +.SM +.B PATH +instead of the shell builtin version, run +.if t \f(CWenable -n test\fP. +.if n ``enable -n test''. +The +.B \-f +option means to load the new builtin command +.I name +from shared object +.IR filename , +on systems that support dynamic loading. +Bash will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a +colon-separated list of directories in which to search for \fIfilename\fP. +The default is system-dependent. +The +.B \-d +option will delete a builtin previously loaded with +.BR \-f . +If no \fIname\fP arguments are given, or if the +.B \-p +option is supplied, a list of shell builtins is printed. +With no other option arguments, the list consists of all enabled +shell builtins. +If \fB\-n\fP is supplied, only disabled builtins are printed. +If \fB\-a\fP is supplied, the list printed includes all builtins, with an +indication of whether or not each is enabled. +If \fB\-s\fP is supplied, the output is restricted to the POSIX +\fIspecial\fP builtins. +If no options are supplied and a \fIname\fP is not a shell builtin, +\fBenable\fP will attempt to load \fIname\fP from a shared object named +\fIname\fP, as if the command were +.if t \f(CWenable \-f\fP \fIname name\fP . +.if n ``enable -f \fIname name\fP . +The return value is 0 unless a +.I name +is not a shell builtin or there is an error loading a new builtin +from a shared object. +.TP +\fBeval\fP [\fIarg\fP ...] +The \fIarg\fPs are read and concatenated together into a single +command. This command is then read and executed by the shell, and +its exit status is returned as the value of +.BR eval . +If there are no +.IR args , +or only null arguments, +.B eval +returns 0. +.TP +\fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]] +If +.I command +is specified, it replaces the shell. +No new process is created. The +.I arguments +become the arguments to \fIcommand\fP. +If the +.B \-l +option is supplied, +the shell places a dash at the beginning of the zeroth argument passed to +.IR command . +This is what +.IR login (1) +does. The +.B \-c +option causes +.I command +to be executed with an empty environment. If +.B \-a +is supplied, the shell passes +.I name +as the zeroth argument to the executed command. +If +.I command +cannot be executed for some reason, a non-interactive shell exits, +unless the +.B execfail +shell option +is enabled. In that case, it returns failure. +An interactive shell returns failure if the file cannot be executed. +A subshell exits unconditionally if \fBexec\fP fails. +If +.I command +is not specified, any redirections take effect in the current shell, +and the return status is 0. If there is a redirection error, the +return status is 1. +.TP +\fBexit\fP [\fIn\fP] +Cause the shell to exit +with a status of \fIn\fP. If +.I n +is omitted, the exit status +is that of the last command executed. +A trap on +.SM +.B EXIT +is executed before the shell terminates. +.TP +\fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ... +.PD 0 +.TP +.B export \-p +.PD +The supplied +.I names +are marked for automatic export to the environment of +subsequently executed commands. If the +.B \-f +option is given, the +.I names +refer to functions. +If no +.I names +are given, or if the +.B \-p +option is supplied, a list +of names of all exported variables is printed. +The +.B \-n +option causes the export property to be removed from each +\fIname\fP. +If a variable name is followed by =\fIword\fP, the value of +the variable is set to \fIword\fP. +.B export +returns an exit status of 0 unless an invalid option is +encountered, +one of the \fInames\fP is not a valid shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +\fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP] +.PD 0 +.TP +\fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP] +.PD +The first form selects a range of commands from +.I first +to +.I last +from the history list and displays or edits and re-executes them. +.I First +and +.I last +may be specified as a string (to locate the last command beginning +with that string) or as a number (an index into the history list, +where a negative number is used as an offset from the current +command number). +When listing, a \fIfirst\fP or \fIlast\fP of +0 is equivalent to \-1 and \-0 is equivalent to the current +command (usually the \fBfc\fP command); otherwise 0 is equivalent to \-1 +and \-0 is invalid. +If +.I last +is not specified, it is set to +the current command for listing (so that +.if n ``fc \-l \-10'' +.if t \f(CWfc \-l \-10\fP +prints the last 10 commands) and to +.I first +otherwise. +If +.I first +is not specified, it is set to the previous +command for editing and \-16 for listing. +.sp 1 +The +.B \-n +option suppresses +the command numbers when listing. The +.B \-r +option reverses the order of +the commands. If the +.B \-l +option is given, +the commands are listed on +standard output. Otherwise, the editor given by +.I ename +is invoked +on a file containing those commands. If +.I ename +is not given, the +value of the +.SM +.B FCEDIT +variable is used, and +the value of +.SM +.B EDITOR +if +.SM +.B FCEDIT +is not set. If neither variable is set, +.FN vi +is used. When editing is complete, the edited commands are +echoed and executed. +.sp 1 +In the second form, \fIcommand\fP is re-executed after each instance +of \fIpat\fP is replaced by \fIrep\fP. +\fICommand\fP is interpreted the same as \fIfirst\fP above. +A useful alias to use with this is +.if n ``r="fc -s"'', +.if t \f(CWr='fc \-s'\fP, +so that typing +.if n ``r cc'' +.if t \f(CWr cc\fP +runs the last command beginning with +.if n ``cc'' +.if t \f(CWcc\fP +and typing +.if n ``r'' +.if t \f(CWr\fP +re-executes the last command. +.sp 1 +If the first form is used, the return value is 0 unless an invalid +option is encountered or +.I first +or +.I last +specify history lines out of range. +If the +.B \-e +option is supplied, the return value is the value of the last +command executed or failure if an error occurs with the temporary +file of commands. If the second form is used, the return status +is that of the command re-executed, unless +.I cmd +does not specify a valid history line, in which case +.B fc +returns failure. +.TP +\fBfg\fP [\fIjobspec\fP] +Resume +.I jobspec +in the foreground, and make it the current job. +If +.I jobspec +is not present, the shell's notion of the \fIcurrent job\fP is used. +The return value is that of the command placed into the foreground, +or failure if run when job control is disabled or, when run with +job control enabled, if +.I jobspec +does not specify a valid job or +.I jobspec +specifies a job that was started without job control. +.TP +\fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg ...\fP] +.B getopts +is used by shell procedures to parse positional parameters. +.I optstring +contains the option characters to be recognized; if a character +is followed by a colon, the option is expected to have an +argument, which should be separated from it by white space. +The colon and question mark characters may not be used as +option characters. +Each time it is invoked, +.B getopts +places the next option in the shell variable +.IR name , +initializing +.I name +if it does not exist, +and the index of the next argument to be processed into the +variable +.SM +.BR OPTIND . +.SM +.B OPTIND +is initialized to 1 each time the shell or a shell script +is invoked. When an option requires an argument, +.B getopts +places that argument into the variable +.SM +.BR OPTARG . +The shell does not reset +.SM +.B OPTIND +automatically; it must be manually reset between multiple +calls to +.B getopts +within the same shell invocation if a new set of parameters +is to be used. +.sp 1 +When the end of options is encountered, \fBgetopts\fP exits with a +return value greater than zero. +.SM +.B OPTIND +is set to the index of the first non-option argument, +and \fIname\fP is set to ?. +.sp 1 +.B getopts +normally parses the positional parameters, but if more arguments are +supplied as +.I arg +values, +.B getopts +parses those instead. +.sp 1 +.B getopts +can report errors in two ways. If the first character of +.I optstring +is a colon, +.I silent +error reporting is used. In normal operation, diagnostic messages +are printed when invalid options or missing option arguments are +encountered. +If the variable +.SM +.B OPTERR +is set to 0, no error messages will be displayed, even if the first +character of +.I optstring +is not a colon. +.sp 1 +If an invalid option is seen, +.B getopts +places ? into +.I name +and, if not silent, +prints an error message and unsets +.SM +.BR OPTARG . +If +.B getopts +is silent, +the option character found is placed in +.SM +.B OPTARG +and no diagnostic message is printed. +.sp 1 +If a required argument is not found, and +.B getopts +is not silent, +a question mark (\^\fB?\fP\^) is placed in +.IR name , +.SM +.B OPTARG +is unset, and a diagnostic message is printed. +If +.B getopts +is silent, then a colon (\^\fB:\fP\^) is placed in +.I name +and +.SM +.B OPTARG +is set to the option character found. +.sp 1 +.B getopts +returns true if an option, specified or unspecified, is found. +It returns false if the end of options is encountered or an +error occurs. +.TP +\fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP] +Each time \fBhash\fP is invoked, +the full pathname of the command +.I name +is determined by searching +the directories in +.B $PATH +and remembered. Any previously-remembered pathname is discarded. +If the +.B \-p +option is supplied, no path search is performed, and +.I filename +is used as the full filename of the command. +The +.B \-r +option causes the shell to forget all +remembered locations. +The +.B \-d +option causes the shell to forget the remembered location of each \fIname\fP. +If the +.B \-t +option is supplied, the full pathname to which each \fIname\fP corresponds +is printed. If multiple \fIname\fP arguments are supplied with \fB\-t\fP, +the \fIname\fP is printed before the hashed full pathname. +The +.B \-l +option causes output to be displayed in a format that may be reused as input. +If no arguments are given, or if only \fB\-l\fP is supplied, +information about remembered commands is printed. +The return status is true unless a +.I name +is not found or an invalid option is supplied. +.TP +\fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP] +Display helpful information about builtin commands. If +.I pattern +is specified, +.B help +gives detailed help on all commands matching +.IR pattern ; +otherwise help for all the builtins and shell control structures +is printed. +.RS +.PD 0 +.TP +.B \-d +Display a short description of each \fIpattern\fP +.TP +.B \-m +Display the description of each \fIpattern\fP in a manpage-like format +.TP +.B \-s +Display only a short usage synopsis for each \fIpattern\fP +.PD +.PP +The return status is 0 unless no command matches +.IR pattern . +.RE +.TP +\fBhistory [\fIn\fP] +.PD 0 +.TP +\fBhistory\fP \fB\-c\fP +.TP +\fBhistory \-d\fP \fIoffset\fP +.TP +\fBhistory \-d\fP \fIstart\fP\-\fIend\fP +.TP +\fBhistory\fP \fB\-anrw\fP [\fIfilename\fP] +.TP +\fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP] +.TP +\fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP] +.PD +With no options, display the command +history list with line numbers. Lines listed +with a +.B * +have been modified. An argument of +.I n +lists only the last +.I n +lines. +If the shell variable +.SM +.B HISTTIMEFORMAT +is set and not null, +it is used as a format string for \fIstrftime\fP(3) to display +the time stamp associated with each displayed history entry. +No intervening blank is printed between the formatted time stamp +and the history line. +If \fIfilename\fP is supplied, it is used as the +name of the history file; if not, the value of +.SM +.B HISTFILE +is used. Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-c +Clear the history list by deleting all the entries. +.TP +\fB\-d\fP \fIoffset\fP +Delete the history entry at position \fIoffset\fP. +If \fIoffset\fP is negative, it is interpreted as relative to one greater +than the last history position, so negative indices count back from the +end of the history, and an index of \-1 refers to the current +\fBhistory -d\fP command. +.TP +\fB\-d\fP \fIstart\fP\-\fIend\fP +Delete the range of history entries between positions \fIstart\fP and +\fIend\fP, inclusive. +Positive and negative values for \fIstart\fP and \fIend\fP +are interpreted as described above. +.TP +.B \-a +Append the ``new'' history lines to the history file. +These are history lines entered since the beginning of the current +\fBbash\fP session, but not already appended to the history file. +.TP +.B \-n +Read the history lines not already read from the history +file into the current history list. These are lines +appended to the history file since the beginning of the +current \fBbash\fP session. +.TP +.B \-r +Read the contents of the history file +and append them to the current history list. +.TP +.B \-w +Write the current history list to the history file, overwriting the +history file's contents. +.TP +.B \-p +Perform history substitution on the following \fIargs\fP and display +the result on the standard output. +Does not store the results in the history list. +Each \fIarg\fP must be quoted to disable normal history expansion. +.TP +.B \-s +Store the +.I args +in the history list as a single entry. The last command in the +history list is removed before the +.I args +are added. +.PD +.PP +If the +.SM +.B HISTTIMEFORMAT +variable is set, the time stamp information +associated with each history entry is written to the history file, +marked with the history comment character. +When the history file is read, lines beginning with the history +comment character followed immediately by a digit are interpreted +as timestamps for the following history entry. +The return value is 0 unless an invalid option is encountered, an +error occurs while reading or writing the history file, an invalid +\fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the +history expansion supplied as an argument to \fB\-p\fP fails. +.RE +.TP +\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ] +.PD 0 +.TP +\fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ] +.PD +The first form lists the active jobs. The options have the following +meanings: +.RS +.PD 0 +.TP +.B \-l +List process IDs +in addition to the normal information. +.TP +.B \-n +Display information only about jobs that have changed status since +the user was last notified of their status. +.TP +.B \-p +List only the process ID of the job's process group +leader. +.TP +.B \-r +Display only running jobs. +.TP +.B \-s +Display only stopped jobs. +.PD +.PP +If +.I jobspec +is given, output is restricted to information about that job. +The return status is 0 unless an invalid option is encountered +or an invalid +.I jobspec +is supplied. +.PP +If the +.B \-x +option is supplied, +.B jobs +replaces any +.I jobspec +found in +.I command +or +.I args +with the corresponding process group ID, and executes +.I command +passing it +.IR args , +returning its exit status. +.RE +.TP +\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ... +.PD 0 +.TP +\fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP] +.PD +Send the signal named by +.I sigspec +or +.I signum +to the processes named by +.I pid +or +.IR jobspec . +.I sigspec +is either a case-insensitive signal name such as +.SM +.B SIGKILL +(with or without the +.SM +.B SIG +prefix) or a signal number; +.I signum +is a signal number. +If +.I sigspec +is not present, then +.SM +.B SIGTERM +is assumed. +An argument of +.B \-l +lists the signal names. +If any arguments are supplied when +.B \-l +is given, the names of the signals corresponding to the arguments are +listed, and the return status is 0. +The \fIexit_status\fP argument to +.B \-l +is a number specifying either a signal number or the exit status of +a process terminated by a signal. +The +.B \-L +option is equivalent to \fB\-l\fP. +.B kill +returns true if at least one signal was successfully sent, or false +if an error occurs or an invalid option is encountered. +.TP +\fBlet\fP \fIarg\fP [\fIarg\fP ...] +Each +.I arg +is an arithmetic expression to be evaluated (see +.SM +.B "ARITHMETIC EVALUATION" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +If the last +.I arg +evaluates to 0, +.B let +returns 1; 0 is returned otherwise. +.TP +\fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ] +For each argument, a local variable named +.I name +is created, and assigned +.IR value . +The \fIoption\fP can be any of the options accepted by \fBdeclare\fP. +When +.B local +is used within a function, it causes the variable +.I name +to have a visible scope restricted to that function and its children. +If \fIname\fP is \-, the set of shell options is made local to the function +in which \fBlocal\fP is invoked: shell options changed using the +\fBset\fP builtin inside the function are restored to their original values +when the function returns. +The restore is effected as if a series of \fBset\fP commands were executed +to restore the values that were in place before the function. +With no operands, +.B local +writes a list of local variables to the standard output. It is +an error to use +.B local +when not within a function. The return status is 0 unless +.B local +is used outside a function, an invalid +.I name +is supplied, or +\fIname\fP is a readonly variable. +.TP +.B logout +Exit a login shell. +.TP +\fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP] +.PD 0 +.TP +\fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP] +.PD +Read lines from the standard input into the indexed array variable +.IR array , +or from file descriptor +.I fd +if the +.B \-u +option is supplied. +The variable +.SM +.B MAPFILE +is the default \fIarray\fP. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-d +The first character of \fIdelim\fP is used to terminate each input line, +rather than newline. +If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line +when it reads a NUL character. +.TP +.B \-n +Copy at most +.I count +lines. If \fIcount\fP is 0, all lines are copied. +.TP +.B \-O +Begin assigning to +.I array +at index +.IR origin . +The default index is 0. +.TP +.B \-s +Discard the first \fIcount\fP lines read. +.TP +.B \-t +Remove a trailing \fIdelim\fP (default newline) from each line read. +.TP +.B \-u +Read lines from file descriptor \fIfd\fP instead of the standard input. +.TP +.B \-C +Evaluate +.I callback +each time \fIquantum\fP lines are read. The \fB\-c\fP option specifies +.IR quantum . +.TP +.B \-c +Specify the number of lines read between each call to +.IR callback . +.PD +.PP +If +.B \-C +is specified without +.BR \-c , +the default quantum is 5000. +When \fIcallback\fP is evaluated, it is supplied the index of the next +array element to be assigned and the line to be assigned to that element +as additional arguments. +\fIcallback\fP is evaluated after the line is read but before the +array element is assigned. +.PP +If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP +before assigning to it. +.PP +\fBmapfile\fP returns successfully unless an invalid option or option +argument is supplied, \fIarray\fP is invalid or unassignable, or if +\fIarray\fP is not an indexed array. +.RE +.TP +\fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP] +Removes entries from the directory stack. +The elements are numbered from 0 starting at the first directory +listed by \fBdirs\fP. +With no arguments, \fBpopd\fP +removes the top directory from the stack, and +changes to the new top directory. +Arguments, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-n +Suppresses the normal change of directory when removing directories +from the stack, so that only the stack is manipulated. +.TP +\fB+\fP\fIn\fP +Removes the \fIn\fPth entry counting from the left of the list +shown by +.BR dirs , +starting with zero, from the stack. +For example: +.if n ``popd +0'' +.if t \f(CWpopd +0\fP +removes the first directory, +.if n ``popd +1'' +.if t \f(CWpopd +1\fP +the second. +.TP +\fB\-\fP\fIn\fP +Removes the \fIn\fPth entry counting from the right of the list +shown by +.BR dirs , +starting with zero. For example: +.if n ``popd -0'' +.if t \f(CWpopd -0\fP +removes the last directory, +.if n ``popd -1'' +.if t \f(CWpopd -1\fP +the next to last. +.PD +.PP +If the top element of the directory stack is modified, and +the \fI-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP +builtin to change to the directory at the top of the stack. +If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value. +.PP +Otherwise, +.B popd +returns false if an invalid option is encountered, the directory stack +is empty, or a non-existent directory stack entry is specified. +.PP +If the +.B popd +command is successful, +bash runs +.B dirs +to show the final contents of the directory stack, +and the return status is 0. +.RE +.TP +\fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP] +Write the formatted \fIarguments\fP to the standard output under the +control of the \fIformat\fP. +The \fB\-v\fP option causes the output to be assigned to the variable +\fIvar\fP rather than being printed to the standard output. +.sp 1 +The \fIformat\fP is a character string which contains three types of objects: +plain characters, which are simply copied to standard output, character +escape sequences, which are converted and copied to the standard output, and +format specifications, each of which causes printing of the next successive +\fIargument\fP. +In addition to the standard \fIprintf\fP(1) format specifications, +\fBprintf\fP interprets the following extensions: +.RS +.PD 0 +.TP +.B %b +causes +\fBprintf\fP to expand backslash escape sequences in the corresponding +\fIargument\fP +in the same way as \fBecho \-e\fP. +.TP +.B %q +causes \fBprintf\fP to output the corresponding +\fIargument\fP in a format that can be reused as shell input. +.TP +.B %Q +like \fB%q\fP, but applies any supplied precision to the \fIargument\fP +before quoting it. +.TP +.B %(\fIdatefmt\fP)T +causes \fBprintf\fP to output the date-time string resulting from using +\fIdatefmt\fP as a format string for \fIstrftime\fP(3). +The corresponding \fIargument\fP is an integer representing the number of +seconds since the epoch. +Two special argument values may be used: \-1 represents the current +time, and \-2 represents the time the shell was invoked. +If no argument is specified, conversion behaves as if \-1 had been given. +This is an exception to the usual \fBprintf\fP behavior. +.PD +.PP +The %b, %q, and %T directives all use the field width and precision +arguments from the format specification and write that many bytes from +(or use that wide a field for) the expanded argument, which usually +contains more characters than the original. +.PP +Arguments to non-string format specifiers are treated as C constants, +except that a leading plus or minus sign is allowed, and if the leading +character is a single or double quote, the value is the ASCII value of +the following character. +.PP +The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP. +If the \fIformat\fP requires more \fIarguments\fP than are supplied, the +extra format specifications behave as if a zero value or null string, as +appropriate, had been supplied. +The return value is zero on success, non-zero on failure. +.RE +.TP +\fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP] +.PD 0 +.TP +\fBpushd\fP [\fB\-n\fP] [\fIdir\fP] +.PD +Adds a directory to the top of the directory stack, or rotates +the stack, making the new top of the stack the current working +directory. +With no arguments, \fBpushd\fP exchanges the top two elements of +the directory stack. +Arguments, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-n +Suppresses the normal change of directory when rotating or +adding directories to the stack, so that only the stack is manipulated. +.TP +\fB+\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the left of the list shown by +.BR dirs , +starting with zero) +is at the top. +.TP +\fB\-\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the right of the list shown by +.BR dirs , +starting with zero) is at the top. +.TP +.I dir +Adds +.I dir +to the directory stack at the top +.PD +.PP +After the stack has been modified, if the \fB\-n\fP option was not +supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the +directory at the top of the stack. +If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value. +.PP +Otherwise, if no arguments are supplied, +.B pushd +returns 0 unless the directory stack is empty. +When rotating the directory stack, +.B pushd +returns 0 unless the directory stack is empty or +a non-existent directory stack element is specified. +.PP +If the +.B pushd +command is successful, +bash runs +.B dirs +to show the final contents of the directory stack. +.RE +.TP +\fBpwd\fP [\fB\-LP\fP] +Print the absolute pathname of the current working directory. +The pathname printed contains no symbolic links if the +.B \-P +option is supplied or the +.B \-o physical +option to the +.B set +builtin command is enabled. +If the +.B \-L +option is used, the pathname printed may contain symbolic links. +The return status is 0 unless an error occurs while +reading the name of the current directory or an +invalid option is supplied. +.TP +\fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...] +One line is read from the standard input, or from the file descriptor +\fIfd\fP supplied as an argument to the \fB\-u\fP option, +split into words as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under \fBWord Splitting\fP, +and the first word +is assigned to the first +.IR name , +the second word to the second +.IR name , +and so on. +If there are more words than names, the remaining words and their +intervening delimiters are assigned to the last +.IR name . +If there are fewer words read from the input stream than names, +the remaining names are assigned empty values. +The characters in +.SM +.B IFS +are used to split the line into words using the same rules the shell +uses for expansion (described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under \fBWord Splitting\fP). +The backslash character (\fB\e\fP) may be used to remove any special +meaning for the next character read and for line continuation. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-a \fIaname\fP +The words are assigned to sequential indices +of the array variable +.IR aname , +starting at 0. +.I aname +is unset before any new values are assigned. +Other \fIname\fP arguments are ignored. +.TP +.B \-d \fIdelim\fP +The first character of \fIdelim\fP is used to terminate the input line, +rather than newline. +If \fIdelim\fP is the empty string, \fBread\fP will terminate a line +when it reads a NUL character. +.TP +.B \-e +If the standard input +is coming from a terminal, +.B readline +(see +.SM +.B READLINE +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +is used to obtain the line. +Readline uses the current (or default, if line editing was not previously +active) editing settings, but uses readline's default filename completion. +.TP +.B \-i \fItext\fP +If +.B readline +is being used to read the line, \fItext\fP is placed into the editing +buffer before editing begins. +.TP +.B \-n \fInchars\fP +\fBread\fP returns after reading \fInchars\fP characters rather than +waiting for a complete line of input, but honors a delimiter if fewer +than \fInchars\fP characters are read before the delimiter. +.TP +.B \-N \fInchars\fP +\fBread\fP returns after reading exactly \fInchars\fP characters rather +than waiting for a complete line of input, unless EOF is encountered or +\fBread\fP times out. +Delimiter characters encountered in the input are +not treated specially and do not cause \fBread\fP to return until +\fInchars\fP characters are read. +The result is not split on the characters in \fBIFS\fP; the intent is +that the variable is assigned exactly the characters read +(with the exception of backslash; see the \fB\-r\fP option below). +.TP +.B \-p \fIprompt\fP +Display \fIprompt\fP on standard error, without a +trailing newline, before attempting to read any input. The prompt +is displayed only if input is coming from a terminal. +.TP +.B \-r +Backslash does not act as an escape character. +The backslash is considered to be part of the line. +In particular, a backslash-newline pair may not then be used as a line +continuation. +.TP +.B \-s +Silent mode. If input is coming from a terminal, characters are +not echoed. +.TP +.B \-t \fItimeout\fP +Cause \fBread\fP to time out and return failure if a complete line of +input (or a specified number of characters) +is not read within \fItimeout\fP seconds. +\fItimeout\fP may be a decimal number with a fractional portion following +the decimal point. +This option is only effective if \fBread\fP is reading input from a +terminal, pipe, or other special file; it has no effect when reading +from regular files. +If \fBread\fP times out, \fBread\fP saves any partial input read into +the specified variable \fIname\fP. +If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to +read any data. +The exit status is 0 if input is available on the specified file descriptor, +or the read will return EOF, +non-zero otherwise. +The exit status is greater than 128 if the timeout is exceeded. +.TP +.B \-u \fIfd\fP +Read input from file descriptor \fIfd\fP. +.PD +.PP +If no +.I names +are supplied, the line read, +without the ending delimiter but otherwise unmodified, +is assigned to the variable +.SM +.BR REPLY . +The exit status is zero, unless end-of-file is encountered, \fBread\fP +times out (in which case the status is greater than 128), +a variable assignment error (such as assigning to a readonly variable) occurs, +or an invalid file descriptor is supplied as the argument to \fB\-u\fP. +.RE +.TP +\fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...] +.PD +The given +\fInames\fP are marked readonly; the values of these +.I names +may not be changed by subsequent assignment. +If the +.B \-f +option is supplied, the functions corresponding to the +\fInames\fP are so +marked. +The +.B \-a +option restricts the variables to indexed arrays; the +.B \-A +option restricts the variables to associative arrays. +If both options are supplied, +.B \-A +takes precedence. +If no +.I name +arguments are given, or if the +.B \-p +option is supplied, a list of all readonly names is printed. +The other options may be used to restrict the output to a subset of +the set of readonly names. +The +.B \-p +option causes output to be displayed in a format that +may be reused as input. +If a variable name is followed by =\fIword\fP, the value of +the variable is set to \fIword\fP. +The return status is 0 unless an invalid option is encountered, +one of the +.I names +is not a valid shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +\fBreturn\fP [\fIn\fP] +Causes a function to stop executing and return the value specified by +.I n +to its caller. +If +.I n +is omitted, the return status is that of the last command +executed in the function body. +If \fBreturn\fP is executed by a trap handler, the last command used to +determine the status is the last command executed before the trap handler. +If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command +used to determine the status is the last command executed by the trap +handler before \fBreturn\fP was invoked. +If +.B return +is used outside a function, +but during execution of a script by the +.B . +(\fBsource\fP) command, it causes the shell to stop executing +that script and return either +.I n +or the exit status of the last command executed within the +script as the exit status of the script. +If \fIn\fP is supplied, the return value is its least significant +8 bits. +The return status is non-zero if +.B return +is supplied a non-numeric argument, or +is used outside a +function and not during execution of a script by \fB.\fP\^ or \fBsource\fP. +Any command associated with the \fBRETURN\fP trap is executed +before execution resumes after the function or script. +.TP +\fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...] +.PD 0 +.TP +\fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...] +.PD +Without options, display the name and value of each shell variable +in a format that can be reused as input +for setting or resetting the currently-set variables. +Read-only variables cannot be reset. +In \fIposix mode\fP, only shell variables are listed. +The output is sorted according to the current locale. +When options are specified, they set or unset shell attributes. +Any arguments remaining after option processing are treated +as values for the positional parameters and are assigned, in order, to +.BR $1 , +.BR $2 , +.B ... +.BR $\fIn\fP . +Options, if specified, have the following meanings: +.RS +.PD 0 +.TP 8 +.B \-a +Each variable or function that is created or modified is given the +export attribute and marked for export to the environment of +subsequent commands. +.TP 8 +.B \-b +Report the status of terminated background jobs +immediately, rather than before the next primary prompt. This is +effective only when job control is enabled. +.TP 8 +.B \-e +Exit immediately if a +\fIpipeline\fP (which may consist of a single \fIsimple command\fP), +a \fIlist\fP, +or a \fIcompound command\fP +(see +.SM +.B SHELL GRAMMAR +.ie \n(zZ=1 in \fIbash(1)\fP), +.el above), +exits with a non-zero status. +The shell does not exit if the +command that fails is part of the command list immediately following a +.B while +or +.B until +keyword, +part of the test following the +.B if +or +.B elif +reserved words, part of any command executed in a +.B && +or +.B || +list except the command following the final \fB&&\fP or \fB||\fP, +any command in a pipeline but the last, +or if the command's return value is +being inverted with +.BR ! . +If a compound command other than a subshell +returns a non-zero status because a command failed +while \fB\-e\fP was being ignored, the shell does not exit. +A trap on \fBERR\fP, if set, is executed before the shell exits. +This option applies to the shell environment and each subshell environment +separately (see +.SM +.B "COMMAND EXECUTION ENVIRONMENT" +.ie \n(zZ=1 in \fIbash(1)\fP), +.el above), +and may cause +subshells to exit before executing all the commands in the subshell. +.if t .sp 0.5 +.if n .sp 1 +If a compound command or shell function executes in a context +where \fB\-e\fP is being ignored, +none of the commands executed within the compound command or function body +will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set +and a command returns a failure status. +If a compound command or shell function sets \fB\-e\fP while executing in +a context where \fB\-e\fP is ignored, that setting will not have any +effect until the compound command or the command containing the function +call completes. +.TP 8 +.B \-f +Disable pathname expansion. +.TP 8 +.B \-h +Remember the location of commands as they are looked up for execution. +This is enabled by default. +.TP 8 +.B \-k +All arguments in the form of assignment statements +are placed in the environment for a command, not just +those that precede the command name. +.TP 8 +.B \-m +Monitor mode. Job control is enabled. This option is on +by default for interactive shells on systems that support +it (see +.SM +.B JOB CONTROL +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +All processes run in a separate process group. +When a background job completes, the shell prints a line +containing its exit status. +.TP 8 +.B \-n +Read commands but do not execute them. +This may be used to check a shell script for syntax errors. +This is ignored by interactive shells. +.TP 8 +.B \-o \fIoption\-name\fP +The \fIoption\-name\fP can be one of the following: +.RS +.TP 8 +.B allexport +Same as +.BR \-a . +.TP 8 +.B braceexpand +Same as +.BR \-B . +.TP 8 +.B emacs +Use an emacs-style command line editing interface. This is enabled +by default when the shell is interactive, unless the shell is started +with the +.B \-\-noediting +option. +This also affects the editing interface used for \fBread \-e\fP. +.TP 8 +.B errexit +Same as +.BR \-e . +.TP 8 +.B errtrace +Same as +.BR \-E . +.TP 8 +.B functrace +Same as +.BR \-T . +.TP 8 +.B hashall +Same as +.BR \-h . +.TP 8 +.B histexpand +Same as +.BR \-H . +.TP 8 +.B history +Enable command history, as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR HISTORY . +This option is on by default in interactive shells. +.TP 8 +.B ignoreeof +The effect is as if the shell command +.if t \f(CWIGNOREEOF=10\fP +.if n ``IGNOREEOF=10'' +had been executed +(see +.B Shell Variables +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP 8 +.B keyword +Same as +.BR \-k . +.TP 8 +.B monitor +Same as +.BR \-m . +.TP 8 +.B noclobber +Same as +.BR \-C . +.TP 8 +.B noexec +Same as +.BR \-n . +.TP 8 +.B noglob +Same as +.BR \-f . +.TP 8 +.B nolog +Currently ignored. +.TP 8 +.B notify +Same as +.BR \-b . +.TP 8 +.B nounset +Same as +.BR \-u . +.TP 8 +.B onecmd +Same as +.BR \-t . +.TP 8 +.B physical +Same as +.BR \-P . +.TP 8 +.B pipefail +If set, the return value of a pipeline is the value of the last +(rightmost) command to exit with a non-zero status, or zero if all +commands in the pipeline exit successfully. +This option is disabled by default. +.TP 8 +.B posix +Change the behavior of +.B bash +where the default operation differs +from the POSIX standard to match the standard (\fIposix mode\fP). +See +.SM +.B "SEE ALSO" +.ie \n(zZ=1 in \fIbash(1)\fP +.el below +for a reference to a document that details how posix mode affects +bash's behavior. +.TP 8 +.B privileged +Same as +.BR \-p . +.TP 8 +.B verbose +Same as +.BR \-v . +.TP 8 +.B vi +Use a vi-style command line editing interface. +This also affects the editing interface used for \fBread \-e\fP. +.TP 8 +.B xtrace +Same as +.BR \-x . +.sp .5 +.PP +If +.B \-o +is supplied with no \fIoption\-name\fP, the values of the current options are +printed. +If +.B +o +is supplied with no \fIoption\-name\fP, a series of +.B set +commands to recreate the current option settings is displayed on +the standard output. +.RE +.TP 8 +.B \-p +Turn on +.I privileged +mode. In this mode, the +.SM +.B $ENV +and +.SM +.B $BASH_ENV +files are not processed, shell functions are not inherited from the +environment, and the +.SM +.BR SHELLOPTS , +.SM +.BR BASHOPTS , +.SM +.BR CDPATH , +and +.SM +.B GLOBIGNORE +variables, if they appear in the environment, are ignored. +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the \fB\-p\fP option is not supplied, these actions +are taken and the effective user id is set to the real user id. +If the \fB\-p\fP option is supplied at startup, the effective user id is +not reset. +Turning this option off causes the effective user +and group ids to be set to the real user and group ids. +.TP 8 +.B \-r +Enable restricted shell mode. +This option cannot be unset once it has been set. +.TP 8 +.B \-t +Exit after reading and executing one command. +.TP 8 +.B \-u +Treat unset variables and parameters other than the special +parameters "@" and "*", +or array variables subscripted with "@" or "*", +as an error when performing +parameter expansion. If expansion is attempted on an +unset variable or parameter, the shell prints an error message, and, +if not interactive, exits with a non-zero status. +.TP 8 +.B \-v +Print shell input lines as they are read. +.TP 8 +.B \-x +After expanding each \fIsimple command\fP, +\fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or +arithmetic \fBfor\fP command, display the expanded value of +.SM +.BR PS4 , +followed by the command and its expanded arguments +or associated word list. +.TP 8 +.B \-B +The shell performs brace expansion (see +.B Brace Expansion +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This is on by default. +.TP 8 +.B \-C +If set, +.B bash +does not overwrite an existing file with the +.BR > , +.BR >& , +and +.B <> +redirection operators. This may be overridden when +creating output files by using the redirection operator +.B >| +instead of +.BR > . +.TP 8 +.B \-E +If set, any trap on \fBERR\fP is inherited by shell functions, command +substitutions, and commands executed in a subshell environment. +The \fBERR\fP trap is normally not inherited in such cases. +.TP 8 +.B \-H +Enable +.B ! +style history substitution. This option is on by +default when the shell is interactive. +.TP 8 +.B \-P +If set, the shell does not resolve symbolic links when executing +commands such as +.B cd +that change the current working directory. It uses the +physical directory structure instead. By default, +.B bash +follows the logical chain of directories when performing commands +which change the current directory. +.TP 8 +.B \-T +If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell +functions, command substitutions, and commands executed in a +subshell environment. +The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited +in such cases. +.TP 8 +.B \-\- +If no arguments follow this option, then the positional parameters are +unset. Otherwise, the positional parameters are set to the +\fIarg\fPs, even if some of them begin with a +.BR \- . +.TP 8 +.B \- +Signal the end of options, cause all remaining \fIarg\fPs to be +assigned to the positional parameters. The +.B \-x +and +.B \-v +options are turned off. +If there are no \fIarg\fPs, +the positional parameters remain unchanged. +.PD +.PP +The options are off by default unless otherwise noted. +Using + rather than \- causes these options to be turned off. +The options can also be specified as arguments to an invocation of +the shell. +The current set of options may be found in +.BR $\- . +The return status is always true unless an invalid option is encountered. +.RE +.TP +\fBshift\fP [\fIn\fP] +The positional parameters from \fIn\fP+1 ... are renamed to +.B $1 +.B .... +Parameters represented by the numbers \fB$#\fP +down to \fB$#\fP\-\fIn\fP+1 are unset. +.I n +must be a non-negative number less than or equal to \fB$#\fP. +If +.I n +is 0, no parameters are changed. +If +.I n +is not given, it is assumed to be 1. +If +.I n +is greater than \fB$#\fP, the positional parameters are not changed. +The return status is greater than zero if +.I n +is greater than +.B $# +or less than zero; otherwise 0. +.TP +\fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...] +Toggle the values of settings controlling optional shell behavior. +The settings can be either those listed below, or, if the +.B \-o +option is used, those available with the +.B \-o +option to the \fBset\fP builtin command. +With no options, or with the +.B \-p +option, a list of all settable options is displayed, with +an indication of whether or not each is set; +if \fIoptnames\fP are supplied, the output is restricted to those options. +The \fB\-p\fP option causes output to be displayed in a form that +may be reused as input. +Other options have the following meanings: +.RS +.PD 0 +.TP +.B \-s +Enable (set) each \fIoptname\fP. +.TP +.B \-u +Disable (unset) each \fIoptname\fP. +.TP +.B \-q +Suppresses normal output (quiet mode); the return status indicates +whether the \fIoptname\fP is set or unset. +If multiple \fIoptname\fP arguments are given with +.BR \-q , +the return status is zero if all \fIoptnames\fP are enabled; non-zero +otherwise. +.TP +.B \-o +Restricts the values of \fIoptname\fP to be those defined for the +.B \-o +option to the +.B set +builtin. +.PD +.PP +If either +.B \-s +or +.B \-u +is used with no \fIoptname\fP arguments, +.B shopt +shows only those options which are set or unset, respectively. +Unless otherwise noted, the \fBshopt\fP options are disabled (unset) +by default. +.PP +The return status when listing options is zero if all \fIoptnames\fP +are enabled, non-zero otherwise. When setting or unsetting options, +the return status is zero unless an \fIoptname\fP is not a valid shell +option. +.PP +The list of \fBshopt\fP options is: +.if t .sp .5v +.if n .sp 1v +.PD 0 +.TP 8 +.B assoc_expand_once +If set, the shell suppresses multiple evaluation of associative array +subscripts during arithmetic expression evaluation, while executing +builtins that can perform variable assignments, +and while executing builtins that perform array dereferencing. +.TP 8 +.B autocd +If set, a command name that is the name of a directory is executed as if +it were the argument to the \fBcd\fP command. +This option is only used by interactive shells. +.TP 8 +.B cdable_vars +If set, an argument to the +.B cd +builtin command that +is not a directory is assumed to be the name of a variable whose +value is the directory to change to. +.TP 8 +.B cdspell +If set, minor errors in the spelling of a directory component in a +.B cd +command will be corrected. +The errors checked for are transposed characters, +a missing character, and one character too many. +If a correction is found, the corrected filename is printed, +and the command proceeds. +This option is only used by interactive shells. +.TP 8 +.B checkhash +If set, \fBbash\fP checks that a command found in the hash +table exists before trying to execute it. If a hashed command no +longer exists, a normal path search is performed. +.TP 8 +.B checkjobs +If set, \fBbash\fP lists the status of any stopped and running jobs before +exiting an interactive shell. If any jobs are running, this causes +the exit to be deferred until a second exit is attempted without an +intervening command (see +.SM +.B "JOB CONTROL" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +The shell always postpones exiting if any jobs are stopped. +.TP 8 +.B checkwinsize +If set, \fBbash\fP checks the window size after each external (non-builtin) +command and, if necessary, updates the values of +.SM +.B LINES +and +.SM +.BR COLUMNS . +This option is enabled by default. +.TP 8 +.B cmdhist +If set, +.B bash +attempts to save all lines of a multiple-line +command in the same history entry. This allows +easy re-editing of multi-line commands. +This option is enabled by default, but only has an effect if command +history is enabled, as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR HISTORY . +.PD 0 +.TP 8 +.B compat31 +.TP 8 +.B compat32 +.TP 8 +.B compat40 +.TP 8 +.B compat41 +.TP 8 +.B compat42 +.TP 8 +.B compat43 +.TP 8 +.B compat44 +.TP 8 +.B compat50 +.PD +These control aspects of the shell's compatibility mode +(see +.SM +.B "SHELL COMPATIBILITY MODE" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el below). +.TP 8 +.B complete_fullquote +If set, +.B bash +quotes all shell metacharacters in filenames and directory names when +performing completion. +If not set, +.B bash +removes metacharacters such as the dollar sign from the set of +characters that will be quoted in completed filenames +when these metacharacters appear in shell variable references in words to be +completed. +This means that dollar signs in variable names that expand to directories +will not be quoted; +however, any dollar signs appearing in filenames will not be quoted, either. +This is active only when bash is using backslashes to quote completed +filenames. +This variable is set by default, which is the default bash behavior in +versions through 4.2. +.TP 8 +.B direxpand +If set, +.B bash +replaces directory names with the results of word expansion when performing +filename completion. This changes the contents of the readline editing +buffer. +If not set, +.B bash +attempts to preserve what the user typed. +.TP 8 +.B dirspell +If set, +.B bash +attempts spelling correction on directory names during word completion +if the directory name initially supplied does not exist. +.TP 8 +.B dotglob +If set, +.B bash +includes filenames beginning with a `.' in the results of pathname +expansion. +The filenames +.B ``.'' +and +.B ``..'' +must always be matched explicitly, even if +.B dotglob +is set. +.TP 8 +.B execfail +If set, a non-interactive shell will not exit if +it cannot execute the file specified as an argument to the +.B exec +builtin command. An interactive shell does not exit if +.B exec +fails. +.TP 8 +.B expand_aliases +If set, aliases are expanded as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR ALIASES . +This option is enabled by default for interactive shells. +.TP 8 +.B extdebug +If set at shell invocation, +or in a shell startup file, +arrange to execute the debugger profile +before the shell starts, identical to the \fB\-\-debugger\fP option. +If set after invocation, behavior intended for use by debuggers is enabled: +.RS +.TP +.B 1. +The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source +file name and line number corresponding to each function name supplied +as an argument. +.TP +.B 2. +If the command run by the \fBDEBUG\fP trap returns a non-zero value, the +next command is skipped and not executed. +.TP +.B 3. +If the command run by the \fBDEBUG\fP trap returns a value of 2, and the +shell is executing in a subroutine (a shell function or a shell script +executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates +a call to \fBreturn\fP. +.TP +.B 4. +.SM +.B BASH_ARGC +and +.SM +.B BASH_ARGV +are updated as described in their descriptions +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B 5. +Function tracing is enabled: command substitution, shell functions, and +subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the +\fBDEBUG\fP and \fBRETURN\fP traps. +.TP +.B 6. +Error tracing is enabled: command substitution, shell functions, and +subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the +\fBERR\fP trap. +.RE +.TP 8 +.B extglob +If set, the extended pattern matching features described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +\fBPathname Expansion\fP are enabled. +.TP 8 +.B extquote +If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is +performed within \fB${\fP\fIparameter\fP\fB}\fP expansions +enclosed in double quotes. This option is enabled by default. +.TP 8 +.B failglob +If set, patterns which fail to match filenames during pathname expansion +result in an expansion error. +.TP 8 +.B force_fignore +If set, the suffixes specified by the +.SM +.B FIGNORE +shell variable +cause words to be ignored when performing word completion even if +the ignored words are the only possible completions. +See +.SM +\fBSHELL VARIABLES\fP +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +for a description of +.SM +.BR FIGNORE . +This option is enabled by default. +.TP 8 +.B globasciiranges +If set, range expressions used in pattern matching bracket expressions (see +.SM +.B Pattern Matching +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +behave as if in the traditional C locale when performing +comparisons. That is, the current locale's collating sequence +is not taken into account, so +.B b +will not collate between +.B A +and +.BR B , +and upper-case and lower-case ASCII characters will collate together. +.TP 8 +.B globskipdots +If set, pathname expansion will never match the filenames +.B ``.'' +and +.BR ``..'' , +even if the pattern begins with a +.BR ``.'' . +This option is enabled by default. +.TP 8 +.B globstar +If set, the pattern \fB**\fP used in a pathname expansion context will +match all files and zero or more directories and subdirectories. +If the pattern is followed by a \fB/\fP, only directories and +subdirectories match. +.TP 8 +.B gnu_errfmt +If set, shell error messages are written in the standard GNU error +message format. +.TP 8 +.B histappend +If set, the history list is appended to the file named by the value +of the +.SM +.B HISTFILE +variable when the shell exits, rather than overwriting the file. +.TP 8 +.B histreedit +If set, and +.B readline +is being used, a user is given the opportunity to re-edit a +failed history substitution. +.TP 8 +.B histverify +If set, and +.B readline +is being used, the results of history substitution are not immediately +passed to the shell parser. Instead, the resulting line is loaded into +the \fBreadline\fP editing buffer, allowing further modification. +.TP 8 +.B hostcomplete +If set, and +.B readline +is being used, \fBbash\fP will attempt to perform hostname completion when a +word containing a \fB@\fP is being completed (see +.B Completing +under +.SM +.B READLINE +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This is enabled by default. +.TP 8 +.B huponexit +If set, \fBbash\fP will send +.SM +.B SIGHUP +to all jobs when an interactive login shell exits. +.TP 8 +.B inherit_errexit +If set, command substitution inherits the value of the \fBerrexit\fP option, +instead of unsetting it in the subshell environment. +This option is enabled when \fIposix mode\fP is enabled. +.TP 8 +.B interactive_comments +If set, allow a word beginning with +.B # +to cause that word and all remaining characters on that +line to be ignored in an interactive shell (see +.SM +.B COMMENTS +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This option is enabled by default. +.TP 8 +.B lastpipe +If set, and job control is not active, the shell runs the last command of +a pipeline not executed in the background in the current shell environment. +.TP 8 +.B lithist +If set, and the +.B cmdhist +option is enabled, multi-line commands are saved to the history with +embedded newlines rather than using semicolon separators where possible. +.TP 8 +.B localvar_inherit +If set, local variables inherit the value and attributes of a variable of +the same name that exists at a previous scope before any new value is +assigned. The nameref attribute is not inherited. +.TP 8 +.B localvar_unset +If set, calling \fBunset\fP on local variables in previous function scopes +marks them so subsequent lookups find them unset until that function +returns. This is identical to the behavior of unsetting local variables +at the current function scope. +.TP 8 +.B login_shell +The shell sets this option if it is started as a login shell (see +.SM +.B "INVOCATION" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +The value may not be changed. +.TP 8 +.B mailwarn +If set, and a file that \fBbash\fP is checking for mail has been +accessed since the last time it was checked, the message ``The mail in +\fImailfile\fP has been read'' is displayed. +.TP 8 +.B no_empty_cmd_completion +If set, and +.B readline +is being used, +.B bash +will not attempt to search the +.SM +.B PATH +for possible completions when +completion is attempted on an empty line. +.TP 8 +.B nocaseglob +If set, +.B bash +matches filenames in a case\-insensitive fashion when performing pathname +expansion (see +.B Pathname Expansion +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP 8 +.B nocasematch +If set, +.B bash +matches patterns in a case\-insensitive fashion when performing matching +while executing \fBcase\fP or \fB[[\fP conditional commands, +when performing pattern substitution word expansions, +or when filtering possible completions as part of programmable completion. +.TP 8 +.B noexpand_translation +If set, +.B bash +encloses the translated results of $"..." quoting in single quotes +instead of double quotes. +If the string is not translated, this has no effect. +.TP 8 +.B nullglob +If set, +.B bash +allows patterns which match no +files (see +.B Pathname Expansion +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +to expand to a null string, rather than themselves. +.TP 8 +.B patsub_replacement +If set, \fBbash\fP +expands occurrences of \fB&\fP in the replacement string of pattern +substitution to the text matched by the pattern, as described +under \fBParameter Expansion\fP +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +This option is enabled by default. +.TP 8 +.B progcomp +If set, the programmable completion facilities (see +\fBProgrammable Completion\fP +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +are enabled. +This option is enabled by default. +.TP 8 +.B progcomp_alias +If set, and programmable completion is enabled, \fBbash\fP treats a command +name that doesn't have any completions as a possible alias and attempts +alias expansion. If it has an alias, \fBbash\fP attempts programmable +completion using the command word resulting from the expanded alias. +.TP 8 +.B promptvars +If set, prompt strings undergo +parameter expansion, command substitution, arithmetic +expansion, and quote removal after being expanded as described in +.SM +.B PROMPTING +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +This option is enabled by default. +.TP 8 +.B restricted_shell +The shell sets this option if it is started in restricted mode +(see +.SM +.B "RESTRICTED SHELL" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el below). +The value may not be changed. +This is not reset when the startup files are executed, allowing +the startup files to discover whether or not a shell is restricted. +.TP 8 +.B shift_verbose +If set, the +.B shift +builtin prints an error message when the shift count exceeds the +number of positional parameters. +.TP 8 +.B sourcepath +If set, the +\fB.\fP (\fBsource\fP) builtin uses the value of +.SM +.B PATH +to find the directory containing the file supplied as an argument. +This option is enabled by default. +.TP 8 +.B varredir_close +If set, the shell automatically closes file descriptors assigned using the +\fI{varname}\fP redirection syntax (see +.SM +.B REDIRECTION +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +instead of leaving them open when the command completes. +.TP 8 +.B xpg_echo +If set, the \fBecho\fP builtin expands backslash-escape sequences +by default. +.RE +.PD +.TP +\fBsuspend\fP [\fB\-f\fP] +Suspend the execution of this shell until it receives a +.SM +.B SIGCONT +signal. A login shell, +or a shell without job control enabled, +cannot be suspended; the +.B \-f +option can be used to override this and force the suspension. +The return status is 0 unless the shell is a login shell +or job control is not enabled +and +.B \-f +is not supplied. +.TP +\fBtest\fP \fIexpr\fP +.PD 0 +.TP +\fB[\fP \fIexpr\fP \fB]\fP +Return a status of 0 (true) or 1 (false) depending on +the evaluation of the conditional expression +.IR expr . +Each operator and operand must be a separate argument. +Expressions are composed of the primaries described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" . +\fBtest\fP does not accept any options, nor does it accept and ignore +an argument of \fB\-\-\fP as signifying the end of options. +.if t .sp 0.5 +.if n .sp 1 +Expressions may be combined using the following operators, listed +in decreasing order of precedence. +The evaluation depends on the number of arguments; see below. +Operator precedence is used when there are five or more arguments. +.RS +.PD 0 +.TP +.B ! \fIexpr\fP +True if +.I expr +is false. +.TP +.B ( \fIexpr\fP ) +Returns the value of \fIexpr\fP. +This may be used to override the normal precedence of operators. +.TP +\fIexpr1\fP \-\fBa\fP \fIexpr2\fP +True if both +.I expr1 +and +.I expr2 +are true. +.TP +\fIexpr1\fP \-\fBo\fP \fIexpr2\fP +True if either +.I expr1 +or +.I expr2 +is true. +.PD +.PP +\fBtest\fP and \fB[\fP evaluate conditional +expressions using a set of rules based on the number of arguments. +.if t .sp 0.5 +.if n .sp 1 +.PD 0 +.TP +0 arguments +The expression is false. +.TP +1 argument +The expression is true if and only if the argument is not null. +.TP +2 arguments +If the first argument is \fB!\fP, the expression is true if and +only if the second argument is null. +If the first argument is one of the unary conditional operators listed +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" , +the expression is true if the unary test is true. +If the first argument is not a valid unary conditional operator, the expression +is false. +.TP +3 arguments +The following conditions are applied in the order listed. +If the second argument is one of the binary conditional operators listed +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" , +the result of the expression is the result of the binary test using +the first and third arguments as operands. +The \fB\-a\fP and \fB\-o\fP operators are considered binary operators +when there are three arguments. +If the first argument is \fB!\fP, the value is the negation of +the two-argument test using the second and third arguments. +If the first argument is exactly \fB(\fP and the third argument is +exactly \fB)\fP, the result is the one-argument test of the second +argument. +Otherwise, the expression is false. +.TP +4 arguments +The following conditions are applied in the order listed. +If the first argument is \fB!\fP, the result is the negation of +the three-argument expression composed of the remaining arguments. +the two-argument test using the second and third arguments. +If the first argument is exactly \fB(\fP and the fourth argument is +exactly \fB)\fP, the result is the two-argument test of the second +and third arguments. +Otherwise, the expression is parsed and evaluated according to +precedence using the rules listed above. +.TP +5 or more arguments +The expression is parsed and evaluated according to precedence +using the rules listed above. +.if t .sp 0.5 +.if n .sp 1 +.LP +When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators +sort lexicographically using ASCII ordering. +.RE +.PD +.TP +.B times +Print the accumulated user and system times for the shell and +for processes run from the shell. The return status is 0. +.TP +\fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...] +The command +.I arg +is to be read and executed when the shell receives +signal(s) +.IR sigspec . +If +.I arg +is absent (and there is a single \fIsigspec\fP) or +.BR \- , +each specified signal is +reset to its original disposition (the value it had +upon entrance to the shell). +If +.I arg +is the null string the signal specified by each +.I sigspec +is ignored by the shell and by the commands it invokes. +If +.I arg +is not present and +.B \-p +has been supplied, then the trap commands associated with each +.I sigspec +are displayed. +If no arguments are supplied or if only +.B \-p +is given, +.B trap +prints the list of commands associated with each signal. +The +.B \-l +option causes the shell to print a list of signal names and +their corresponding numbers. +Each +.I sigspec +is either +a signal name defined in <\fIsignal.h\fP>, or a signal number. +Signal names are case insensitive and the +.SM +.B SIG +prefix is optional. +.if t .sp 0.5 +.if n .sp 1 +If a +.I sigspec +is +.SM +.B EXIT +(0) the command +.I arg +is executed on exit from the shell. +If a +.I sigspec +is +.SM +.BR DEBUG , +the command +.I arg +is executed before every \fIsimple command\fP, \fIfor\fP command, +\fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP +command, and before the first command executes in a shell function (see +.SM +.B SHELL GRAMMAR +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +Refer to the description of the \fBextdebug\fP option to the +\fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap. +If a +.I sigspec +is +.SM +.BR RETURN , +the command +.I arg +is executed each time a shell function or a script executed with +the \fB.\fP or \fBsource\fP builtins finishes executing. +.if t .sp 0.5 +.if n .sp 1 +If a +.I sigspec +is +.SM +.BR ERR , +the command +.I arg +is executed whenever +a pipeline (which may consist of a single simple +command), a list, or a compound command returns a +non\-zero exit status, +subject to the following conditions. +The +.SM +.B ERR +trap is not executed if the failed +command is part of the command list immediately following a +.B while +or +.B until +keyword, +part of the test in an +.I if +statement, part of a command executed in a +.B && +or +.B || +list except the command following the final \fB&&\fP or \fB||\fP, +any command in a pipeline but the last, +or if the command's return value is +being inverted using +.BR ! . +These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option. +.if t .sp 0.5 +.if n .sp 1 +Signals ignored upon entry to the shell cannot be trapped or reset. +Trapped signals that are not being ignored are reset to their original +values in a subshell or subshell environment when one is created. +The return status is false if any +.I sigspec +is invalid; otherwise +.B trap +returns true. +.TP +\fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...] +With no options, +indicate how each +.I name +would be interpreted if used as a command name. +If the +.B \-t +option is used, +.B type +prints a string which is one of +.IR alias , +.IR keyword , +.IR function , +.IR builtin , +or +.I file +if +.I name +is an alias, shell reserved word, function, builtin, or disk file, +respectively. +If the +.I name +is not found, then nothing is printed, and an exit status of false +is returned. +If the +.B \-p +option is used, +.B type +either returns the name of the disk file +that would be executed if +.I name +were specified as a command name, +or nothing if +.if t \f(CWtype -t name\fP +.if n ``type -t name'' +would not return +.IR file . +The +.B \-P +option forces a +.SM +.B PATH +search for each \fIname\fP, even if +.if t \f(CWtype -t name\fP +.if n ``type -t name'' +would not return +.IR file . +If a command is hashed, +.B \-p +and +.B \-P +print the hashed value, which is not necessarily the file that appears +first in +.SM +.BR PATH . +If the +.B \-a +option is used, +.B type +prints all of the places that contain +an executable named +.IR name . +This includes aliases and functions, +if and only if the +.B \-p +option is not also used. +The table of hashed commands is not consulted +when using +.BR \-a . +The +.B \-f +option suppresses shell function lookup, as with the \fBcommand\fP builtin. +.B type +returns true if all of the arguments are found, false if +any are not found. +.TP +\fBulimit\fP [\fB\-HS\fP] \fB\-a\fP +.PD 0 +.TP +\fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]] +.PD +Provides control over the resources available to the shell and to +processes started by it, on systems that allow such control. +The \fB\-H\fP and \fB\-S\fP options specify that the hard or soft limit is +set for the given resource. +A hard limit cannot be increased by a non-root user once it is set; +a soft limit may be increased up to the value of the hard limit. +If neither \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard +limits are set. +The value of +.I limit +can be a number in the unit specified for the resource +or one of the special values +.BR hard , +.BR soft , +or +.BR unlimited , +which stand for the current hard limit, the current soft limit, and +no limit, respectively. +If +.I limit +is omitted, the current value of the soft limit of the resource is +printed, unless the \fB\-H\fP option is given. When more than one +resource is specified, the limit name and unit, if appropriate, +are printed before the value. +Other options are interpreted as follows: +.RS +.PD 0 +.TP +.B \-a +All current limits are reported; no limits are set +.TP +.B \-b +The maximum socket buffer size +.TP +.B \-c +The maximum size of core files created +.TP +.B \-d +The maximum size of a process's data segment +.TP +.B \-e +The maximum scheduling priority ("nice") +.TP +.B \-f +The maximum size of files written by the shell and its children +.TP +.B \-i +The maximum number of pending signals +.TP +.B \-k +The maximum number of kqueues that may be allocated +.TP +.B \-l +The maximum size that may be locked into memory +.TP +.B \-m +The maximum resident set size (many systems do not honor this limit) +.TP +.B \-n +The maximum number of open file descriptors (most systems do not +allow this value to be set) +.TP +.B \-p +The pipe size in 512-byte blocks (this may not be set) +.TP +.B \-q +The maximum number of bytes in POSIX message queues +.TP +.B \-r +The maximum real-time scheduling priority +.TP +.B \-s +The maximum stack size +.TP +.B \-t +The maximum amount of cpu time in seconds +.TP +.B \-u +The maximum number of processes available to a single user +.TP +.B \-v +The maximum amount of virtual memory available to the shell and, on +some systems, to its children +.TP +.B \-x +The maximum number of file locks +.TP +.B \-P +The maximum number of pseudoterminals +.TP +.B \-R +The maximum time a real-time process can run before blocking, in microseconds +.TP +.B \-T +The maximum number of threads +.PD +.PP +If +.I limit +is given, and the +.B \-a +option is not used, +\fIlimit\fP is the new value of the specified resource. +If no option is given, then +.B \-f +is assumed. Values are in 1024-byte increments, except for +.BR \-t , +which is in seconds; +.BR \-R , +which is in microseconds; +.BR \-p , +which is in units of 512-byte blocks; +.BR \-P , +.BR \-T , +.BR \-b , +.BR \-k , +.BR \-n , +and +.BR \-u , +which are unscaled values; +and, when in posix mode, +.B \-c +and +.BR \-f , +which are in 512-byte increments. +The return status is 0 unless an invalid option or argument is supplied, +or an error occurs while setting a new limit. +.RE +.TP +\fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP] +The user file-creation mask is set to +.IR mode . +If +.I mode +begins with a digit, it +is interpreted as an octal number; otherwise +it is interpreted as a symbolic mode mask similar +to that accepted by +.IR chmod (1). +If +.I mode +is omitted, the current value of the mask is printed. +The +.B \-S +option causes the mask to be printed in symbolic form; the +default output is an octal number. +If the +.B \-p +option is supplied, and +.I mode +is omitted, the output is in a form that may be reused as input. +The return status is 0 if the mode was successfully changed or if +no \fImode\fP argument was supplied, and false otherwise. +.TP +\fBunalias\fP [\-\fBa\fP] [\fIname\fP ...] +Remove each \fIname\fP from the list of defined aliases. If +.B \-a +is supplied, all alias definitions are removed. The return +value is true unless a supplied +.I name +is not a defined alias. +.TP +\fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...] +For each +.IR name , +remove the corresponding variable or function. +If the +.B \-v +option is given, each +.I name +refers to a shell variable, and that variable is removed. +Read-only variables may not be unset. +If +.B \-f +is specified, each +.I name +refers to a shell function, and the function definition +is removed. +If the +.B \-n +option is supplied, and \fIname\fP is a variable with the \fInameref\fP +attribute, \fIname\fP will be unset rather than the variable it +references. +\fB\-n\fP has no effect if the \fB\-f\fP option is supplied. +If no options are supplied, each \fIname\fP refers to a variable; if +there is no variable by that name, a function with that name, if any, is +unset. +Each unset variable or function is removed from the environment +passed to subsequent commands. +If any of +.SM +.BR BASH_ALIASES , +.SM +.BR BASH_ARGV0 , +.SM +.BR BASH_CMDS , +.SM +.BR BASH_COMMAND , +.SM +.BR BASH_SUBSHELL , +.SM +.BR BASHPID , +.SM +.BR COMP_WORDBREAKS , +.SM +.BR DIRSTACK , +.SM +.BR EPOCHREALTIME , +.SM +.BR EPOCHSECONDS , +.SM +.BR FUNCNAME , +.SM +.BR GROUPS , +.SM +.BR HISTCMD , +.SM +.BR LINENO , +.SM +.BR RANDOM , +.SM +.BR SECONDS , +or +.SM +.B SRANDOM +are unset, they lose their special properties, even if they are +subsequently reset. The exit status is true unless a +.I name +is readonly or may not be unset. +.TP +\fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid ...\fP] +Wait for each specified child process and return its termination status. +Each +.I id +may be a process +ID or a job specification; if a job spec is given, all processes +in that job's pipeline are waited for. If +.I id +is not given, +\fBwait\fP waits for all running background jobs and +the last-executed process substitution, if its process id is the same as +\fB$!\fP, +and the return status is zero. +If the \fB\-n\fP option is supplied, +\fBwait\fP waits for a single job +from the list of \fIid\fPs or, if no \fIid\fPs are supplied, any job, +to complete and returns its exit status. +If none of the supplied arguments is a child of the shell, or if no arguments +are supplied and the shell has no unwaited-for children, the exit status +is 127. +If the \fB\-p\fP option is supplied, the process or job identifier of the job +for which the exit status is returned is assigned to the variable +\fIvarname\fP named by the option argument. +The variable will be unset initially, before any assignment. +This is useful only when the \fB\-n\fP option is supplied. +Supplying the \fB\-f\fP option, when job control is enabled, +forces \fBwait\fP to wait for \fIid\fP to terminate before returning +its status, instead of returning when it changes status. +If +.I id +specifies a non-existent process or job, the return status is 127. +If \fBwait\fP is interrupted by a signal, the return status will be greater +than 128, as described under +.B SIGNALS +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +Otherwise, the return status is the exit status of the last +process or job waited for. +.SH "SHELL COMPATIBILITY MODE" +Bash-4.0 introduced the concept of a \fIshell compatibility level\fP, +specified as a set of options to the shopt builtin ( +.BR compat31 , +.BR compat32 , +.BR compat40 , +.BR compat41 , +and so on). +There is only one current +compatibility level -- each option is mutually exclusive. +The compatibility level is intended to allow users to select behavior +from previous versions that is incompatible with newer versions +while they migrate scripts to use current features and +behavior. It's intended to be a temporary solution. +.PP +This section does not mention behavior that is standard for a particular +version (e.g., setting \fBcompat32\fP means that quoting the rhs of the regexp +matching operator quotes special regexp characters in the word, which is +default behavior in bash-3.2 and subsequent versions). +.PP +If a user enables, say, \fBcompat32\fP, it may affect the behavior of other +compatibility levels up to and including the current compatibility level. +The idea is that each compatibility level controls behavior that changed +in that version of \fBbash\fP, +but that behavior may have been present in earlier versions. +For instance, the change to use locale-based comparisons with the \fB[[\fP +command came in bash-4.1, and earlier versions used ASCII-based comparisons, +so enabling \fBcompat32\fP will enable ASCII-based comparisons as well. +That granularity may not be sufficient for +all uses, and as a result users should employ compatibility levels carefully. +Read the documentation for a particular feature to find out the +current behavior. +.PP +Bash-4.3 introduced a new shell variable: +.SM +.BR BASH_COMPAT . +The value assigned +to this variable (a decimal version number like 4.2, or an integer +corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the +compatibility level. +.PP +Starting with bash-4.4, Bash has begun deprecating older compatibility +levels. +Eventually, the options will be removed in favor of +.SM +.BR BASH_COMPAT . +.PP +Bash-5.0 is the final version for which there will be an individual shopt +option for the previous version. Users should use +.SM +.B BASH_COMPAT +on bash-5.0 and later versions. +.PP +The following table describes the behavior changes controlled by each +compatibility level setting. +The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the +compatibility level +to \fINN\fP using one of the following mechanisms. +For versions prior to bash-5.0, the compatibility level may be set using +the corresponding \fBcompat\fP\fINN\fP shopt option. +For bash-4.3 and later versions, the +.SM +.B BASH_COMPAT +variable is preferred, +and it is required for bash-5.1 and later versions. +.TP +\fBcompat31\fP +.PD 0 +.RS +.IP \(bu +quoting the rhs of the \fB[[\fP command's regexp matching operator (=~) +has no special effect +.RE +.PD +.TP +\fBcompat32\fP +.PD 0 +.RS +.IP \(bu +interrupting a command list such as "a ; b ; c" causes the execution +of the next command in the list (in bash-4.0 and later versions, +the shell acts as if it received the interrupt, so +interrupting one command in a list aborts the execution of the +entire list) +.RE +.PD +.TP +\fBcompat40\fP +.PD 0 +.RS +.IP \(bu +the \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not +consider the current locale when comparing strings; they use ASCII +ordering. +Bash versions prior to bash-4.1 use ASCII collation and +.IR strcmp (3); +bash-4.1 and later use the current locale's collation sequence and +.IR strcoll (3). +.RE +.PD +.TP +\fBcompat41\fP +.PD 0 +.RS +.IP \(bu +in \fIposix\fP mode, \fBtime\fP may be followed by options and still be +recognized as a reserved word (this is POSIX interpretation 267) +.IP \(bu +in \fIposix\fP mode, the parser requires that an even number of single +quotes occur in the \fIword\fP portion of a double-quoted +parameter expansion and treats them specially, so that characters within +the single quotes are considered quoted +(this is POSIX interpretation 221) +.RE +.PD +.TP +\fBcompat42\fP +.PD 0 +.RS +.IP \(bu +the replacement string in double-quoted pattern substitution does not +undergo quote removal, as it does in versions after bash-4.2 +.IP \(bu +in posix mode, single quotes are considered special when expanding +the \fIword\fP portion of a double-quoted parameter expansion +and can be used to quote a closing brace or other special character +(this is part of POSIX interpretation 221); +in later versions, single quotes +are not special within double-quoted word expansions +.RE +.PD +.TP +\fBcompat43\fP +.PD 0 +.RS +.IP \(bu +the shell does not print a warning message if an attempt is made to +use a quoted compound assignment as an argument to declare +(e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage is +deprecated +.IP \(bu +word expansion errors are considered non-fatal errors that cause the +current command to fail, even in posix mode +(the default behavior is to make them fatal errors that cause the shell +to exit) +.IP \(bu +when executing a shell function, the loop state (while/until/etc.) +is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break +or continue loops in the calling context. Bash-4.4 and later reset +the loop state to prevent this +.RE +.PD +.TP +\fBcompat44\fP +.PD 0 +.RS +.IP \(bu +the shell sets up the values used by +.SM +.B BASH_ARGV +and +.SM +.B BASH_ARGC +so they can expand to the shell's positional parameters even if extended +debugging mode is not enabled +.IP \(bu +a subshell inherits loops from its parent context, so \fBbreak\fP +or \fBcontinue\fP will cause the subshell to exit. +Bash-5.0 and later reset the loop state to prevent the exit +.IP \(bu +variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP +that set attributes continue to affect variables with the same +name in the calling environment even if the shell is not in posix +mode +.RE +.PD +.TP +\fBcompat50\fP +.PD 0 +.RS +.IP \(bu +Bash-5.1 changed the way +.SM +.B $RANDOM +is generated to introduce slightly +more randomness. If the shell compatibility level is set to 50 or +lower, it reverts to the method from bash-5.0 and previous versions, +so seeding the random number generator by assigning a value to +.SM +.B RANDOM +will produce the same sequence as in bash-5.0 +.IP \(bu +If the command hash table is empty, bash versions prior to bash-5.1 +printed an informational message to that effect, even when producing +output that can be reused as input. Bash-5.1 suppresses that message +when the \fB\-l\fP option is supplied. +.RE +.PD +.TP +\fBcompat51\fP +.PD 0 +.RS +.IP \(bu +The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP +and \fB*\fP differently depending on whether the array is indexed or +associative, and differently than in previous versions. +.RE +.PD +.\" bash_builtins +.if \n(zZ=1 .ig zZ +.SH "RESTRICTED SHELL" +.\" rbash.1 +.zY +.PP +If +.B bash +is started with the name +.BR rbash , +or the +.B \-r +option is supplied at invocation, +the shell becomes restricted. +A restricted shell is used to +set up an environment more controlled than the standard shell. +It behaves identically to +.B bash +with the exception that the following are disallowed or not performed: +.IP \(bu +changing directories with \fBcd\fP +.IP \(bu +setting or unsetting the values of +.SM +.BR SHELL , +.SM +.BR PATH , +.SM +.BR HISTFILE , +.SM +.BR ENV , +or +.SM +.B BASH_ENV +.IP \(bu +specifying command names containing +.B / +.IP \(bu +specifying a filename containing a +.B / +as an argument to the +.B . +builtin command +.IP \(bu +specifying a filename containing a slash as an argument to the +.B history +builtin command +.IP \(bu +specifying a filename containing a slash as an argument to the +.B \-p +option to the +.B hash +builtin command +.IP \(bu +importing function definitions from the shell environment at startup +.IP \(bu +parsing the value of +.SM +.B SHELLOPTS +from the shell environment at startup +.IP \(bu +redirecting output using the >, >|, <>, >&, &>, and >> redirection operators +.IP \(bu +using the +.B exec +builtin command to replace the shell with another command +.IP \(bu +adding or deleting builtin commands with the +.B \-f +and +.B \-d +options to the +.B enable +builtin command +.IP \(bu +using the \fBenable\fP builtin command to enable disabled shell builtins +.IP \(bu +specifying the +.B \-p +option to the +.B command +builtin command +.IP \(bu +turning off restricted mode with +\fBset +r\fP or \fBshopt -u restricted_shell\fP. +.PP +These restrictions are enforced after any startup files are read. +.PP +.ie \n(zY=1 When a command that is found to be a shell script is executed, +.el \{ When a command that is found to be a shell script is executed +(see +.SM +.B "COMMAND EXECUTION" +above), +\} +.B rbash +turns off any restrictions in the shell spawned to execute the +script. +.\" end of rbash.1 +.if \n(zY=1 .ig zY +.SH "SEE ALSO" +.PD 0 +.TP +\fIBash Reference Manual\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey +.TP +\fIThe Gnu History Library\fP, Brian Fox and Chet Ramey +.TP +\fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, IEEE -- +http://pubs.opengroup.org/onlinepubs/9699919799/ +.TP +http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode +.TP +\fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1) +.TP +\fIemacs\fP(1), \fIvi\fP(1) +.TP +\fIreadline\fP(3) +.PD +.SH FILES +.PD 0 +.TP +.FN /bin/bash +The \fBbash\fP executable +.TP +.FN /etc/profile +The systemwide initialization file, executed for login shells +.TP +.FN ~/.bash_profile +The personal initialization file, executed for login shells +.TP +.FN ~/.bashrc +The individual per-interactive-shell startup file +.TP +.FN ~/.bash_logout +The individual login shell cleanup file, executed when a login shell exits +.TP +.FN ~/.bash_history +The default value of \fBHISTFILE\fP, the file in which bash saves the +command history +.TP +.FN ~/.inputrc +Individual \fIreadline\fP initialization file +.PD +.SH AUTHORS +Brian Fox, Free Software Foundation +.br +bfox@gnu.org +.PP +Chet Ramey, Case Western Reserve University +.br +chet.ramey@case.edu +.SH BUG REPORTS +If you find a bug in +.B bash, +you should report it. But first, you should +make sure that it really is a bug, and that it appears in the latest +version of +.BR bash . +The latest version is always available from +\fIftp://ftp.gnu.org/pub/gnu/bash/\fP and +\fIhttp://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz\fP. +.PP +Once you have determined that a bug actually exists, use the +.I bashbug +command to submit a bug report. +If you have a fix, you are encouraged to mail that as well! +Suggestions and `philosophical' bug reports may be mailed +to \fIbug-bash@gnu.org\fP or posted to the Usenet +newsgroup +.BR gnu.bash.bug . +.PP +ALL bug reports should include: +.PP +.PD 0 +.TP 20 +The version number of \fBbash\fR +.TP +The hardware and operating system +.TP +The compiler used to compile +.TP +A description of the bug behaviour +.TP +A short script or `recipe' which exercises the bug +.PD +.PP +.I bashbug +inserts the first three items automatically into the template +it provides for filing a bug report. +.PP +Comments and bug reports concerning +this manual page should be directed to +.IR chet.ramey@case.edu . +.SH BUGS +It's too big and too slow. +.PP +There are some subtle differences between +.B bash +and traditional versions of +.BR sh , +mostly because of the +.SM +.B POSIX +specification. +.PP +Aliases are confusing in some uses. +.PP +Shell builtin commands and functions are not stoppable/restartable. +.PP +Compound commands and command sequences of the form `a ; b ; c' +are not handled gracefully when process suspension is attempted. +When a process is stopped, the shell immediately executes the next +command in the sequence. +It suffices to place the sequence of commands between +parentheses to force it into a subshell, which may be stopped as +a unit. +.PP +Array variables may not (yet) be exported. +.PP +There may be only one active coprocess at a time. +.zZ +.zY |