From: Chet Ramey Date: Thu, 4 Sep 2025 16:29:57 +0000 (-0400) Subject: declare builtin changes to reject -i when used with -n; readline changes to make... X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=refs%2Fheads%2Fdevel;p=thirdparty%2Fbash.git declare builtin changes to reject -i when used with -n; readline changes to make control characters visible in search strings; readline signal handling changes to avoid data corruption and UAF; documentation updates for more consistent quoting --- diff --git a/.gitignore b/.gitignore index ae4383fb..f334b795 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,11 @@ # don't push out -i -i +tests/-i +builtins/-i +CWRU/-i +CWRU/old-changelogs/-i +lib/readline/-i +doc/-i *.save .DS_Store diff --git a/CWRU/CWRU.chlog b/CWRU/CWRU.chlog index e0484010..7cb586b1 100644 --- a/CWRU/CWRU.chlog +++ b/CWRU/CWRU.chlog @@ -11650,3 +11650,36 @@ bashline.c Otherwise, it's a prefix and likely doesn't exist, so we'll stick with the default backslash completion quoting style. Fixes completion quoting issue from Aaron Laws + + 8/29 + ---- +builtins/declare.def + - declare_invalid_opts: reject attempts to use -n with -i, since you + can't have nameref variables referring to positional parameters + +lib/readline/isearch.c + - rl_display_search: if the search string contains a control char, + display it using the same translation (^C) as in other places + Report and patch from Grisha Levit + + 9/4 + --- +lib/readline/input.c + - rl_getc: add RL_STATE_MOREINPUT to the list of states that cause + a received SIGINT to call _rl_abort_internal + +lib/readline/display.c + - rl_redisplay: put setting RL_STATE_REDISPLAYING outside the calls + to _rl_block_sigint and _rl_release_sigint + +lib/readline/text.c + - _rl_readstr_init: set RL_STATE_READSTR before calling rl_message + to prompt for the command name so we know we're in readstr if we + get a SIGINT + +lib/readline/signals.c + - _rl_release_sigint: after calling RL_CHECK_SIGNALS, call _rl_abort_internal + if the state indicates that we are in one of the places that can + call rl_message. That takes care of the case where redisplay gets a + SIGINT while `blocking' it. + Report from Grisha Levit diff --git a/bash.0 b/bash.0 new file mode 100644 index 00000000..573c1721 --- /dev/null +++ b/bash.0 @@ -0,0 +1,7519 @@ +_B_A_S_H(1) General Commands Manual _B_A_S_H(1) + +NNAAMMEE + bash - GNU Bourne-Again SHell + +SSYYNNOOPPSSIISS + bbaasshh [options] [command_string | file] + +CCOOPPYYRRIIGGHHTT + Bash is Copyright (C) 1989-2025 by the Free Software Foundation, Inc. + +DDEESSCCRRIIPPTTIIOONN + BBaasshh is a command language interpreter that executes commands read from + the standard input, from a string, or from a file. It is a reimplemen- + tation and extension of the Bourne shell, the historical Unix command + language interpreter. BBaasshh also incorporates useful features from the + _K_o_r_n and _C shells (kksshh and ccsshh). + + POSIX is the name for a family of computing standards based on Unix. + BBaasshh is intended to be a conformant implementation of the Shell and + Utilities portion of the IEEE POSIX specification (IEEE Standard + 1003.1). BBaasshh POSIX mode (hereafter referred to as _p_o_s_i_x _m_o_d_e) changes + the shell's behavior where its default operation differs from the stan- + dard to strictly conform to the standard. See SSEEEE AALLSSOO below for a + reference to a document that details how posix mode affects bbaasshh's be- + havior. BBaasshh can be configured to be POSIX-conformant by default. + +OOPPTTIIOONNSS + All of the single-character shell options documented in the description + of the sseett builtin command, including --oo, can be used as options when + the shell is invoked. In addition, bbaasshh interprets the following op- + tions when it is invoked: + + --cc If the --cc option is present, then commands are read from the + first non-option argument _c_o_m_m_a_n_d___s_t_r_i_n_g. If there are argu- + ments after the _c_o_m_m_a_n_d___s_t_r_i_n_g, the first argument is as- + signed to $$00 and any remaining arguments are assigned to the + positional parameters. The assignment to $$00 sets the name of + the shell, which is used in warning and error messages. + + --ii If the --ii option is present, the shell is _i_n_t_e_r_a_c_t_i_v_e. + + --ll Make bbaasshh act as if it had been invoked as a login shell (see + IINNVVOOCCAATTIIOONN below). + + --rr If the --rr option is present, the shell becomes _r_e_s_t_r_i_c_t_e_d + (see RREESSTTRRIICCTTEEDD SSHHEELLLL below). + + --ss If the --ss option is present, or if no arguments remain after + option processing, the shell reads commands 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. + + --DD Print a list of all double-quoted strings preceded by $$ on + the standard output. These are the strings that are subject + to language translation when the current locale is not CC or + PPOOSSIIXX. This implies the --nn option; no commands will be exe- + cuted. + + [[--++]]OO [[_s_h_o_p_t___o_p_t_i_o_n]] + _s_h_o_p_t___o_p_t_i_o_n is one of the shell options accepted by the + sshhoopptt builtin (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). If + _s_h_o_p_t___o_p_t_i_o_n is present, --OO sets the value of that option; ++OO + unsets it. If _s_h_o_p_t___o_p_t_i_o_n is not supplied, bbaasshh prints the + names and values of the shell options accepted by sshhoopptt on + the standard output. If the invocation option is ++OO, the + output is displayed in a format that may be reused as input. + + ---- A ---- signals the end of options and disables further option + processing. Any arguments after the ---- are treated as a + shell script filename (see below) and arguments passed to + that script. An argument of -- is equivalent to ----. + + BBaasshh also interprets a number of multi-character options. These op- + tions must appear on the command line before the single-character op- + tions to be recognized. + + ----ddeebbuuggggeerr + Arrange for the debugger profile to be executed before the shell + starts. Turns on extended debugging mode (see the description + of the eexxttddeebbuugg option to the sshhoopptt builtin below). + + ----dduummpp--ppoo--ssttrriinnggss + Equivalent to --DD, but the output is in the GNU _g_e_t_t_e_x_t "po" + (portable object) file format. + + ----dduummpp--ssttrriinnggss + Equivalent to --DD. + + ----hheellpp Display a usage message on standard output and exit success- + fully. + + ----iinniitt--ffiillee _f_i_l_e + ----rrccffiillee _f_i_l_e + Execute commands from _f_i_l_e instead of the standard personal ini- + tialization file _~_/_._b_a_s_h_r_c if the shell is interactive (see IINN-- + VVOOCCAATTIIOONN below). + + ----llooggiinn + Equivalent to --ll. + + ----nnooeeddiittiinngg + Do not use the GNU rreeaaddlliinnee library to read command lines when + the shell is interactive. + + ----nnoopprrooffiillee + Do not read either the system-wide startup file _/_e_t_c_/_p_r_o_f_i_l_e or + any of the personal initialization files _~_/_._b_a_s_h___p_r_o_f_i_l_e, + _~_/_._b_a_s_h___l_o_g_i_n, or _~_/_._p_r_o_f_i_l_e. By default, bbaasshh reads these + files when it is invoked as a login shell (see IINNVVOOCCAATTIIOONN be- + low). + + ----nnoorrcc Do not read and execute the personal initialization file + _~_/_._b_a_s_h_r_c if the shell is interactive. This option is on by de- + fault if the shell is invoked as sshh. + + ----ppoossiixx + Enable posix mode; change the behavior of bbaasshh where the default + operation differs from the POSIX standard to match the standard. + + ----rreessttrriicctteedd + The shell becomes restricted (see RREESSTTRRIICCTTEEDD SSHHEELLLL below). + + ----vveerrbboossee + Equivalent to --vv. + + ----vveerrssiioonn + Show version information for this instance of bbaasshh on the stan- + dard output and exit successfully. + +AARRGGUUMMEENNTTSS + If arguments remain after option processing, and neither the --cc nor the + --ss option has been supplied, the first argument is treated as the name + of a file containing shell commands (a _s_h_e_l_l _s_c_r_i_p_t). When bbaasshh is in- + voked in this fashion, $$00 is set to the name of the file, and the posi- + tional parameters are set to the remaining arguments. BBaasshh reads and + executes commands from this file, then exits. BBaasshh's exit status is + the exit status of the last command executed in the script. If no com- + mands are executed, the exit status is 0. BBaasshh first attempts to open + the file in the current directory, and, if no file is found, searches + the directories in PPAATTHH for the script. + +IINNVVOOCCAATTIIOONN + A _l_o_g_i_n _s_h_e_l_l is one whose first character of argument zero is a --, or + one started with the ----llooggiinn option. + + An _i_n_t_e_r_a_c_t_i_v_e _s_h_e_l_l is one started without non-option arguments (un- + less --ss is specified) and without the --cc option, and whose standard in- + put and standard error are both connected to terminals (as determined + by _i_s_a_t_t_y(3)), or one started with the --ii option. BBaasshh sets PPSS11 and $$-- + includes ii if the shell is interactive, so a shell script or a startup + file can test this state. + + The following paragraphs describe how bbaasshh executes its startup files. + If any of the files exist but cannot be read, bbaasshh reports an error. + Tildes are expanded in filenames as described below under TTiillddee EExxppaann-- + ssiioonn in the EEXXPPAANNSSIIOONN section. + + When bbaasshh is invoked as an interactive login shell, or as a non-inter- + active shell with the ----llooggiinn option, it first reads and executes com- + mands from the file _/_e_t_c_/_p_r_o_f_i_l_e, if that file exists. After reading + that file, it looks for _~_/_._b_a_s_h___p_r_o_f_i_l_e, _~_/_._b_a_s_h___l_o_g_i_n, and _~_/_._p_r_o_f_i_l_e, + in that order, and reads and executes commands from the first one that + exists and is readable. The ----nnoopprrooffiillee option may be used when the + shell is started to inhibit this behavior. + + When an interactive login shell exits, or a non-interactive login shell + executes the eexxiitt builtin command, bbaasshh reads and executes commands + from the file _~_/_._b_a_s_h___l_o_g_o_u_t, if it exists. + + When an interactive shell that is not a login shell is started, bbaasshh + reads and executes commands from _~_/_._b_a_s_h_r_c, if that file exists. The + ----nnoorrcc option inhibits this behavior. The ----rrccffiillee _f_i_l_e option causes + bbaasshh to use _f_i_l_e instead of _~_/_._b_a_s_h_r_c. + + When bbaasshh is started non-interactively, to run a shell script, for ex- + ample, it looks for the variable BBAASSHH__EENNVV 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. BBaasshh behaves as if the following com- + mand were executed: + + if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi + + but does not use the value of the PPAATTHH variable to search for the file- + name. + + If bbaasshh is invoked with the name sshh, it tries to mimic the startup be- + havior of historical versions of sshh as closely as possible, while con- + forming to the POSIX standard as well. When invoked as an interactive + login shell, or a non-interactive shell with the ----llooggiinn option, it + first attempts to read and execute commands from _/_e_t_c_/_p_r_o_f_i_l_e and + _~_/_._p_r_o_f_i_l_e, in that order. The ----nnoopprrooffiillee option inhibits this behav- + ior. When invoked as an interactive shell with the name sshh, bbaasshh looks + for the variable EENNVV, 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 sshh does not attempt to read and execute commands from + any other startup files, the ----rrccffiillee option has no effect. A non-in- + teractive shell invoked with the name sshh does not attempt to read any + other startup files. + + When invoked as sshh, bbaasshh enters posix mode after reading the startup + files. + + When bbaasshh is started in posix mode, as with the ----ppoossiixx command line + option, it follows the POSIX standard for startup files. In this mode, + interactive shells expand the EENNVV variable and read and execute com- + mands from the file whose name is the expanded value. No other startup + files are read. + + BBaasshh attempts to determine when it is being run with its standard input + connected to a network connection, as when executed by the historical + and rarely-seen remote shell daemon, usually _r_s_h_d, or the secure shell + daemon _s_s_h_d. If bbaasshh determines it is being run non-interactively in + this fashion, it reads and executes commands from _~_/_._b_a_s_h_r_c, if that + file exists and is readable. BBaasshh does not read this file if invoked + as sshh. The ----nnoorrcc option inhibits this behavior, and the ----rrccffiillee op- + tion makes bbaasshh use a different file instead of _~_/_._b_a_s_h_r_c, but neither + _r_s_h_d nor _s_s_h_d generally invoke the shell with those options or allow + them to be specified. + + If the shell is started with the effective user (group) id not equal to + the real user (group) id, and the --pp option is not supplied, no startup + files are read, shell functions are not inherited from the environment, + the SSHHEELLLLOOPPTTSS, BBAASSHHOOPPTTSS, CCDDPPAATTHH, and GGLLOOBBIIGGNNOORREE variables, if they ap- + pear in the environment, are ignored, and the effective user id is set + to the real user id. If the --pp option is supplied at invocation, the + startup behavior is the same, but the effective user id is not reset. + +DDEEFFIINNIITTIIOONNSS + The following definitions are used throughout the rest of this docu- + ment. + bbllaannkk A space or tab. + wwhhiitteessppaaccee + A character belonging to the ssppaaccee character class in the cur- + rent locale, or for which _i_s_s_p_a_c_e(3) returns true. + wwoorrdd A sequence of characters considered as a single unit by the + shell. Also known as a ttookkeenn. + nnaammee A _w_o_r_d consisting only of alphanumeric characters and under- + scores, and beginning with an alphabetic character or an under- + score. Also referred to as an iiddeennttiiffiieerr. + mmeettaacchhaarraacctteerr + A character that, when unquoted, separates words. One of the + following: + || && ;; (( )) << >> ssppaaccee ttaabb nneewwlliinnee + ccoonnttrrooll ooppeerraattoorr + A _t_o_k_e_n that performs a control function. It is one of the fol- + lowing symbols: + |||| && &&&& ;; ;;;; ;;&& ;;;;&& (( )) || ||&& <> + +RREESSEERRVVEEDD WWOORRDDSS + _R_e_s_e_r_v_e_d _w_o_r_d_s 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 SSHHEELLLL GGRRAAMMMMAARR below), the third word of a + ccaassee or sseelleecctt command (only iinn is valid), or the third word of a ffoorr + command (only iinn and ddoo are valid): + + !! ccaassee ccoopprroocc ddoo ddoonnee eelliiff eellssee eessaacc ffii ffoorr ffuunnccttiioonn iiff iinn sseelleecctt + tthheenn uunnttiill wwhhiillee {{ }} ttiimmee [[[[ ]]]] + +SSHHEELLLL GGRRAAMMMMAARR + This section describes the syntax of the various forms of shell com- + mands. + + SSiimmppllee CCoommmmaannddss + A _s_i_m_p_l_e _c_o_m_m_a_n_d is a sequence of optional variable assignments fol- + lowed by bbllaannkk-separated words and redirections, and terminated by a + _c_o_n_t_r_o_l _o_p_e_r_a_t_o_r. The first word specifies the command to be executed, + and is passed as argument zero. The remaining words are passed as ar- + guments to the invoked command. + + The return value of a _s_i_m_p_l_e _c_o_m_m_a_n_d is its exit status, or 128+_n if + the command is terminated by signal _n. + + PPiippeelliinneess + A _p_i_p_e_l_i_n_e is a sequence of one or more commands separated by one of + the control operators || or ||&&. The format for a pipeline is: + + [ttiimmee [--pp]] [ ! ] _c_o_m_m_a_n_d_1 [ [|||||&&] _c_o_m_m_a_n_d_2 ... ] + + The standard output of _c_o_m_m_a_n_d_1 is connected via a pipe to the standard + input of _c_o_m_m_a_n_d_2. This connection is performed before any redirec- + tions specified by the _c_o_m_m_a_n_d_1(see RREEDDIIRREECCTTIIOONN below). If ||&& is the + pipeline operator, _c_o_m_m_a_n_d_1's standard error, in addition to its stan- + dard output, is connected to _c_o_m_m_a_n_d_2's standard input through the + pipe; it is shorthand for 22>>&&11 ||. This implicit redirection of the + standard error to the standard output is performed after any redirec- + tions specified by _c_o_m_m_a_n_d_1. + + The return status of a pipeline is the exit status of the last command, + unless the ppiippeeffaaiill option is enabled. If ppiippeeffaaiill 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 success- + fully. If the reserved word !! precedes a pipeline, the exit status of + that pipeline is the logical negation of the exit status as described + above. If a pipeline is executed synchronously, the shell waits for + all commands in the pipeline to terminate before returning a value. + + If the ttiimmee reserved word precedes a pipeline, the shell reports the + elapsed as well as user and system time consumed by its execution when + the pipeline terminates. The --pp option changes the output format to + that specified by POSIX. When the shell is in posix mode, it does not + recognize ttiimmee as a reserved word if the next token begins with a "-". + The value of the TTIIMMEEFFOORRMMAATT variable is a format string that specifies + how the timing information should be displayed; see the description of + TTIIMMEEFFOORRMMAATT below under SShheellll VVaarriiaabblleess. + + When the shell is in posix mode, ttiimmee may appear by itself as the only + word in a simple command. In this case, the shell displays the total + user and system time consumed by the shell and its children. The TTIIMMEE-- + FFOORRMMAATT variable specifies the format of the time information. + + Each command in a multi-command pipeline, where pipes are created, is + executed in a _s_u_b_s_h_e_l_l, which is a separate process. See CCOOMMMMAANNDD EEXXEE-- + CCUUTTIIOONN EENNVVIIRROONNMMEENNTT for a description of subshells and a subshell envi- + ronment. If the llaassttppiippee option is enabled using the sshhoopptt builtin + (see the description of sshhoopptt below), and job control is not active, + the last element of a pipeline may be run by the shell process. + + LLiissttss + A _l_i_s_t is a sequence of one or more pipelines separated by one of the + operators ;;, &&, &&&&, or ||||, and optionally terminated by one of ;;, &&, or + <>. + + Of these list operators, &&&& and |||| have equal precedence, followed by ;; + and &&, which have equal precedence. + + A sequence of one or more newlines may appear in a _l_i_s_t instead of a + semicolon to delimit commands. + + If a command is terminated by the control operator &&, the shell exe- + cutes the command in the _b_a_c_k_g_r_o_u_n_d in a subshell. The shell does not + wait for the command to finish, and the return status is 0. These are + referred to as _a_s_y_n_c_h_r_o_n_o_u_s commands. Commands separated by a ;; are + executed sequentially; the shell waits for each command to terminate in + turn. The return status is the exit status of the last command exe- + cuted. + + AND and OR lists are sequences of one or more pipelines separated by + the &&&& and |||| control operators, respectively. AND and OR lists are + executed with left associativity. An AND list has the form + + _c_o_m_m_a_n_d_1 &&&& _c_o_m_m_a_n_d_2 + + _c_o_m_m_a_n_d_2 is executed if, and only if, _c_o_m_m_a_n_d_1 returns an exit status + of zero (success). + + An OR list has the form + + _c_o_m_m_a_n_d_1 |||| _c_o_m_m_a_n_d_2 + + _c_o_m_m_a_n_d_2 is executed if, and only if, _c_o_m_m_a_n_d_1 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. + + CCoommppoouunndd CCoommmmaannddss + A _c_o_m_p_o_u_n_d _c_o_m_m_a_n_d is one of the following. In most cases a _l_i_s_t 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. + + (_l_i_s_t) _l_i_s_t is executed in a subshell (see CCOOMMMMAANNDD EEXXEECCUUTTIIOONN EENNVVIIRROONN-- + MMEENNTT below for a description of a subshell environment). Vari- + able 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 _l_i_s_t. + + { _l_i_s_t; } + _l_i_s_t is executed in the current shell environment. _l_i_s_t must be + terminated with a newline or semicolon. This is known as a + _g_r_o_u_p _c_o_m_m_a_n_d. The return status is the exit status of _l_i_s_t. + + Note that unlike the metacharacters (( and )), {{ and }} are _r_e_- + _s_e_r_v_e_d _w_o_r_d_s 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 _l_i_s_t by whitespace or another shell + metacharacter. + + ((_e_x_p_r_e_s_s_i_o_n)) + The arithmetic _e_x_p_r_e_s_s_i_o_n is evaluated according to the rules + described below under AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN. If the value of + the expression is non-zero, the return status is 0; otherwise + the return status is 1. The _e_x_p_r_e_s_s_i_o_n undergoes the same ex- + pansions as if it were within double quotes, but unescaped dou- + ble quote characters in _e_x_p_r_e_s_s_i_o_n are not treated specially and + are removed. Since this can potentially result in empty + strings, this command treats those as expressions that evaluate + to 0. + + [[[[ _e_x_p_r_e_s_s_i_o_n ]]]] + Evaluate the conditional expression _e_x_p_r_e_s_s_i_o_n and return a sta- + tus of zero (true) or non-zero (false). Expressions are com- + posed of the primaries described below under CCOONNDDIITTIIOONNAALL EEXXPPRREESS-- + SSIIOONNSS. The words between the [[[[ and ]]]] do not undergo word + splitting and pathname expansion. The shell performs tilde ex- + pansion, parameter and variable expansion, arithmetic expansion, + command substitution, process substitution, and quote removal on + those words. Conditional operators such as --ff must be unquoted + to be recognized as primaries. + + When used with [[[[, the << and >> operators sort lexicographically + using the current locale. + + When the ==== and !!== operators are used, the string to the right + of the operator is considered a pattern and matched according to + the rules described below under PPaatttteerrnn MMaattcchhiinngg, as if the eexxtt-- + gglloobb shell option were enabled. The == operator is equivalent to + ====. If the nnooccaasseemmaattcchh 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 (====) or does not + match (!!==) the pattern, and 1 otherwise. If any part of the + pattern is quoted, the quoted portion is matched as a string: + every character in the quoted portion matches itself, instead of + having any special pattern matching meaning. + + An additional binary operator, ==~~, is available, with the same + precedence as ==== and !!==. When it is used, the string to the + right of the operator is considered a POSIX extended regular ex- + pression and matched accordingly (using the POSIX _r_e_g_c_o_m_p and + _r_e_g_e_x_e_c interfaces usually described in _r_e_g_e_x(3)). The return + value is 0 if the string matches the pattern, and 1 otherwise. + If the regular expression is syntactically incorrect, the condi- + tional expression's return value is 2. If the nnooccaasseemmaattcchh 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, as above. 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. + + The match succeeds if the pattern matches any part of the + string. Anchor the pattern using the ^^ and $$ regular expression + operators to force it to match the entire string. + + The array variable BBAASSHH__RREEMMAATTCCHH records which parts of the + string matched the pattern. The element of BBAASSHH__RREEMMAATTCCHH with + index 0 contains the portion of the string matching the entire + regular expression. Substrings matched by parenthesized subex- + pressions within the regular expression are saved in the remain- + ing BBAASSHH__RREEMMAATTCCHH indices. The element of BBAASSHH__RREEMMAATTCCHH with in- + dex _n is the portion of the string matching the _nth parenthe- + sized subexpression. BBaasshh sets BBAASSHH__RREEMMAATTCCHH in the global + scope; declaring it as a local variable will lead to unexpected + results. + + Expressions may be combined using the following operators, + listed in decreasing order of precedence: + + (( _e_x_p_r_e_s_s_i_o_n )) + Returns the value of _e_x_p_r_e_s_s_i_o_n. This may be used to + override the normal precedence of operators. + !! _e_x_p_r_e_s_s_i_o_n + True if _e_x_p_r_e_s_s_i_o_n is false. + _e_x_p_r_e_s_s_i_o_n_1 &&&& _e_x_p_r_e_s_s_i_o_n_2 + True if both _e_x_p_r_e_s_s_i_o_n_1 and _e_x_p_r_e_s_s_i_o_n_2 are true. + _e_x_p_r_e_s_s_i_o_n_1 |||| _e_x_p_r_e_s_s_i_o_n_2 + True if either _e_x_p_r_e_s_s_i_o_n_1 or _e_x_p_r_e_s_s_i_o_n_2 is true. + + The &&&& and |||| operators do not evaluate _e_x_p_r_e_s_s_i_o_n_2 if the value + of _e_x_p_r_e_s_s_i_o_n_1 is sufficient to determine the return value of + the entire conditional expression. + + ffoorr _n_a_m_e [ [ iinn _w_o_r_d _._._. ] ; ] ddoo _l_i_s_t ; ddoonnee + First, expand The list of words following iinn, generating a list + of items. Then, the variable _n_a_m_e is set to each element of + this list in turn, and _l_i_s_t is executed each time. If the iinn + _w_o_r_d is omitted, the ffoorr command executes _l_i_s_t once for each po- + sitional parameter that is set (see PPAARRAAMMEETTEERRSS below). The re- + turn status is the exit status of the last command that exe- + cutes. If the expansion of the items following iinn results in an + empty list, no commands are executed, and the return status is + 0. + + ffoorr (( _e_x_p_r_1 ; _e_x_p_r_2 ; _e_x_p_r_3 )) [;] ddoo _l_i_s_t ; ddoonnee + First, evaluate the arithmetic expression _e_x_p_r_1 according to the + rules described below under AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN. Then, re- + peatedly evaluate the arithmetic expression _e_x_p_r_2 until it eval- + uates to zero. Each time _e_x_p_r_2 evaluates to a non-zero value, + execute _l_i_s_t and evaluate the arithmetic expression _e_x_p_r_3. 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 _l_i_s_t + that is executed, or non-zero if any of the expressions is in- + valid. + + Use the bbrreeaakk and ccoonnttiinnuuee builtins (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS + below) to control loop execution. + + sseelleecctt _n_a_m_e [ iinn _w_o_r_d ] ; ddoo _l_i_s_t ; ddoonnee + First, expand the list of words following iinn, generating a list + of items, and print the set of expanded words the standard er- + ror, each preceded by a number. If the iinn _w_o_r_d is omitted, + print the positional parameters (see PPAARRAAMMEETTEERRSS below). sseelleecctt + then displays the PPSS33 prompt and reads a line from the standard + input. If the line consists of a number corresponding to one of + the displayed words, then sseelleecctt sets the value of _n_a_m_e to that + word. If the line is empty, sseelleecctt displays the words and + prompt again. If EOF is read, sseelleecctt completes and returns 1. + Any other value sets _n_a_m_e to null. The line read is saved in + the variable RREEPPLLYY. The _l_i_s_t is executed after each selection + until a bbrreeaakk command is executed. The exit status of sseelleecctt is + the exit status of the last command executed in _l_i_s_t, or zero if + no commands were executed. + + ccaassee _w_o_r_d iinn [ [(] _p_a_t_t_e_r_n [ || _p_a_t_t_e_r_n ] ... ) _l_i_s_t ;; ] ... eessaacc + A ccaassee command first expands _w_o_r_d, and tries to match it against + each _p_a_t_t_e_r_n in turn, proceeding from first to last, using the + matching rules described under PPaatttteerrnn MMaattcchhiinngg below. A pat- + tern list is a set of one or more patterns separated by , and + the ) operator terminates the pattern list. The _w_o_r_d is ex- + panded using tilde expansion, parameter and variable expansion, + arithmetic expansion, command substitution, process substitution + and quote removal. Each _p_a_t_t_e_r_n examined is expanded using + tilde expansion, parameter and variable expansion, arithmetic + expansion, command substitution, process substitution, and quote + removal. If the nnooccaasseemmaattcchh shell option is enabled, the match + is performed without regard to the case of alphabetic charac- + ters. A _c_l_a_u_s_e is a pattern list and an associated _l_i_s_t. + + When a match is found, ccaassee executes the corresponding _l_i_s_t. If + the ;;;; operator terminates the case clause, the ccaassee command + completes after the first match. Using ;;&& in place of ;;;; causes + execution to continue with the _l_i_s_t associated with the next + pattern list. Using ;;;;&& in place of ;;;; causes the shell to test + the next pattern list in the statement, if any, and execute any + associated _l_i_s_t if the match succeeds, 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 + the last _l_i_s_t executed. + + iiff _l_i_s_t; tthheenn _l_i_s_t; [ eelliiff _l_i_s_t; tthheenn _l_i_s_t; ] ... [ eellssee _l_i_s_t; ] ffii + The iiff _l_i_s_t is executed. If its exit status is zero, the tthheenn + _l_i_s_t is executed. Otherwise, each eelliiff _l_i_s_t is executed in + turn, and if its exit status is zero, the corresponding tthheenn + _l_i_s_t is executed and the command completes. Otherwise, the eellssee + _l_i_s_t is executed, if present. The exit status is the exit sta- + tus of the last command executed, or zero if no condition tested + true. + + wwhhiillee _l_i_s_t_-_1; ddoo _l_i_s_t_-_2; ddoonnee + uunnttiill _l_i_s_t_-_1; ddoo _l_i_s_t_-_2; ddoonnee + The wwhhiillee command continuously executes the list _l_i_s_t_-_2 as long + as the last command in the list _l_i_s_t_-_1 returns an exit status of + zero. The uunnttiill command is identical to the wwhhiillee command, ex- + cept that the test is negated: _l_i_s_t_-_2 is executed as long as the + last command in _l_i_s_t_-_1 returns a non-zero exit status. The exit + status of the wwhhiillee and uunnttiill commands is the exit status of the + last command executed in _l_i_s_t_-_2, or zero if none was executed. + + CCoopprroocceesssseess + A _c_o_p_r_o_c_e_s_s is a shell command preceded by the ccoopprroocc reserved word. A + coprocess is executed asynchronously in a subshell, as if the command + had been terminated with the && control operator, with a two-way pipe + established between the executing shell and the coprocess. + + The syntax for a coprocess is: + + ccoopprroocc [_N_A_M_E] _c_o_m_m_a_n_d [_r_e_d_i_r_e_c_t_i_o_n_s] + + This creates a coprocess named _N_A_M_E. _c_o_m_m_a_n_d may be either a simple + command or a compound command (see above). _N_A_M_E is a shell variable + name. If _N_A_M_E is not supplied, the default name is CCOOPPRROOCC. + + The recommended form to use for a coprocess is + + ccoopprroocc _N_A_M_E { _c_o_m_m_a_n_d [_r_e_d_i_r_e_c_t_i_o_n_s]; } + + This form is preferred because simple commands result in the coprocess + always being named CCOOPPRROOCC, and it is simpler to use and more complete + than the other compound commands. + + If _c_o_m_m_a_n_d is a compound command, _N_A_M_E is optional. The word following + ccoopprroocc determines whether that word is interpreted as a variable name: + it is interpreted as _N_A_M_E if it is not a reserved word that introduces + a compound command. If _c_o_m_m_a_n_d is a simple command, _N_A_M_E is not al- + lowed; this is to avoid confusion between _N_A_M_E and the first word of + the simple command. + + When the coprocess is executed, the shell creates an array variable + (see AArrrraayyss below) named _N_A_M_E in the context of the executing shell. + The standard output of _c_o_m_m_a_n_d is connected via a pipe to a file de- + scriptor in the executing shell, and that file descriptor is assigned + to _N_A_M_E[0]. The standard input of _c_o_m_m_a_n_d is connected via a pipe to a + file descriptor in the executing shell, and that file descriptor is as- + signed to _N_A_M_E[1]. This pipe is established before any redirections + specified by the command (see RREEDDIIRREECCTTIIOONN 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. + + The process ID of the shell spawned to execute the coprocess is avail- + able as the value of the variable _N_A_M_E_PID. The wwaaiitt builtin may be + used to wait for the coprocess to terminate. + + Since the coprocess is created as an asynchronous command, the ccoopprroocc + command always returns success. The return status of a coprocess is + the exit status of _c_o_m_m_a_n_d. + + SShheellll FFuunnccttiioonn DDeeffiinniittiioonnss + 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: + + _f_n_a_m_e () _c_o_m_p_o_u_n_d_-_c_o_m_m_a_n_d [_r_e_d_i_r_e_c_t_i_o_n] + ffuunnccttiioonn _f_n_a_m_e [()] _c_o_m_p_o_u_n_d_-_c_o_m_m_a_n_d [_r_e_d_i_r_e_c_t_i_o_n] + This defines a function named _f_n_a_m_e. The reserved word ffuunnccttiioonn + is optional. If the ffuunnccttiioonn reserved word is supplied, the + parentheses are optional. The _b_o_d_y of the function is the com- + pound command _c_o_m_p_o_u_n_d_-_c_o_m_m_a_n_d (see CCoommppoouunndd CCoommmmaannddss above). + That command is usually a _l_i_s_t of commands between { and }, but + may be any command listed under CCoommppoouunndd CCoommmmaannddss above. If the + ffuunnccttiioonn reserved word is used, but the parentheses are not sup- + plied, the braces are recommended. _c_o_m_p_o_u_n_d_-_c_o_m_m_a_n_d is executed + whenever _f_n_a_m_e is specified as the name of a simple command. + When in posix mode, _f_n_a_m_e must be a valid shell _n_a_m_e and may not + be the name of one of the POSIX _s_p_e_c_i_a_l _b_u_i_l_t_i_n_s. In default + mode, a function name can be any unquoted shell word that does + not contain $$. + + Any redirections (see RREEDDIIRREECCTTIIOONN 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 FFUUNNCCTTIIOONNSS below.) + +CCOOMMMMEENNTTSS + In a non-interactive shell, or an interactive shell in which the iinntteerr-- + aaccttiivvee__ccoommmmeennttss option to the sshhoopptt builtin is enabled (see SSHHEELLLL + BBUUIILLTTIINN CCOOMMMMAANNDDSS below), a word beginning with ## introduces a comment. + A word begins at the beginning of a line, after unquoted whitespace, or + after an operator. The comment causes that word and all remaining + characters on that line to be ignored. An interactive shell without + the iinntteerraaccttiivvee__ccoommmmeennttss option enabled does not allow comments. The + iinntteerraaccttiivvee__ccoommmmeennttss option is enabled by default in interactive + shells. + +QQUUOOTTIINNGG + _Q_u_o_t_i_n_g 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. + + Each of the _m_e_t_a_c_h_a_r_a_c_t_e_r_s listed above under DDEEFFIINNIITTIIOONNSS has special + meaning to the shell and must be quoted if it is to represent itself. + + When the command history expansion facilities are being used (see HHIISS-- + TTOORRYY EEXXPPAANNSSIIOONN below), the _h_i_s_t_o_r_y _e_x_p_a_n_s_i_o_n character, usually !!, must + be quoted to prevent history expansion. + + There are four quoting mechanisms: the _e_s_c_a_p_e _c_h_a_r_a_c_t_e_r, single quotes, + double quotes, and dollar-single quotes. + + A non-quoted backslash (\\) is the _e_s_c_a_p_e _c_h_a_r_a_c_t_e_r. It preserves the + literal value of the next character that follows, removing any special + meaning it has, with the exception of . If a \\ pair + appears, and the backslash is not itself quoted, the \\ is + treated as a line continuation (that is, it is removed from the input + stream and effectively ignored). + + 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. + + Enclosing characters in double quotes preserves the literal value of + all characters within the quotes, with the exception of $$, ``, \\, and, + when history expansion is enabled, !!. When the shell is in posix mode, + the !! has no special meaning within double quotes, even when history + expansion is enabled. The characters $$ and `` retain their special + meaning within double quotes. The backslash retains its special mean- + ing only when followed by one of the following characters: $$, ``, "", \\, + or <>. Backslashes preceding characters without a special mean- + ing are left unmodified. + + A double quote may be quoted within double quotes by preceding it with + a backslash. If enabled, history expansion will be performed unless an + !! appearing in double quotes is escaped using a backslash. The back- + slash preceding the !! is not removed. + + The special parameters ** and @@ have special meaning when in double + quotes (see PPAARRAAMMEETTEERRSS below). + + Character sequences of the form $$'_s_t_r_i_n_g' are treated as a special + variant of single quotes. The sequence expands to _s_t_r_i_n_g, with back- + slash-escaped characters in _s_t_r_i_n_g replaced as specified by the ANSI C + standard. Backslash escape sequences, if present, are decoded as fol- + lows: + \\aa alert (bell) + \\bb backspace + \\ee + \\EE an escape character + \\ff form feed + \\nn new line + \\rr carriage return + \\tt horizontal tab + \\vv vertical tab + \\\\ backslash + \\'' single quote + \\"" double quote + \\?? question mark + \\_n_n_n The eight-bit character whose value is the octal value + _n_n_n (one to three octal digits). + \\xx_H_H The eight-bit character whose value is the hexadecimal + value _H_H (one or two hex digits). + \\uu_H_H_H_H The Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value _H_H_H_H (one to four hex digits). + \\UU_H_H_H_H_H_H_H_H + The Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value _H_H_H_H_H_H_H_H (one to eight hex digits). + \\cc_x A control-_x character. + + The expanded result is single-quoted, as if the dollar sign had not + been present. + + TTrraannssllaattiinngg SSttrriinnggss + A double-quoted string preceded by a dollar sign ($$"_s_t_r_i_n_g") causes the + string to be translated according to the current locale. The _g_e_t_t_e_x_t + infrastructure performs the lookup and translation, using the LLCC__MMEESS-- + SSAAGGEESS, TTEEXXTTDDOOMMAAIINNDDIIRR, and TTEEXXTTDDOOMMAAIINN shell variables. If the current + locale is CC or PPOOSSIIXX, if there are no translations available, or if the + string is not translated, the dollar sign is ignored, and the string is + treated as double-quoted as described above. 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 nnooeexxppaanndd__ttrraannssllaattiioonn option is + enabled using the sshhoopptt builtin, translated strings are single-quoted + instead of double-quoted. See the description of sshhoopptt below under + SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS. + +PPAARRAAMMEETTEERRSS + A _p_a_r_a_m_e_t_e_r is an entity that stores values. It can be a _n_a_m_e, a num- + ber, or one of the special characters listed below under SSppeecciiaall PPaarraa-- + mmeetteerrss. A _v_a_r_i_a_b_l_e is a parameter denoted by a _n_a_m_e. A variable has a + _v_a_l_u_e and zero or more _a_t_t_r_i_b_u_t_e_s. Attributes are assigned using the + ddeeccllaarree builtin command (see ddeeccllaarree below in SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS). + The eexxppoorrtt and rreeaaddoonnllyy builtins assign specific attributes. + + 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 uunnsseett builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + + A _v_a_r_i_a_b_l_e is assigned to using a statement of the form + + _n_a_m_e=[_v_a_l_u_e] + + If _v_a_l_u_e is not given, the variable is assigned the null string. All + _v_a_l_u_e_s undergo tilde expansion, parameter and variable expansion, com- + mand substitution, arithmetic expansion, and quote removal (see EEXXPPAANN-- + SSIIOONN below). If the variable has its iinntteeggeerr attribute set, then _v_a_l_u_e + is evaluated as an arithmetic expression even if the $$((((...)))) expansion + is not used (see AArriitthhmmeettiicc EExxppaannssiioonn below). Word splitting and path- + name expansion are not performed. Assignment statements may also ap- + pear as arguments to the aalliiaass, ddeeccllaarree, ttyyppeesseett, eexxppoorrtt, rreeaaddoonnllyy, and + llooccaall builtin commands (_d_e_c_l_a_r_a_t_i_o_n commands). When in posix mode, + these builtins may appear in a command after one or more instances of + the ccoommmmaanndd builtin and retain these assignment statement properties. + + In the context where an assignment statement is assigning a value to a + shell variable or array index, the "+=" operator appends to or adds to + the variable's previous value. This includes arguments to _d_e_c_l_a_r_a_t_i_o_n + commands such as ddeeccllaarree that accept assignment statements. When "+=" + is applied to a variable for which the iinntteeggeerr attribute has been set, + the variable's current value and _v_a_l_u_e are each evaluated as arithmetic + expressions, and the sum of the results is assigned as the variable's + value. The current value is usually an integer constant, but may be an + expression. When "+=" is applied to an array variable using compound + assignment (see AArrrraayyss 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 ap- + plied to a string-valued variable, _v_a_l_u_e is expanded and appended to + the variable's value. + + A variable can be assigned the _n_a_m_e_r_e_f attribute using the --nn option to + the ddeeccllaarree or llooccaall builtin commands (see the descriptions of ddeeccllaarree + and llooccaall below) to create a _n_a_m_e_r_e_f, or a reference to another vari- + able. This allows variables to be manipulated indirectly. Whenever + the nameref variable is referenced, assigned to, unset, or has its at- + tributes modified (other than using or changing the _n_a_m_e_r_e_f 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 argu- + ment to the function. For instance, if a variable name is passed to a + shell function as its first argument, running + + declare -n ref=$1 + + inside the function creates a local nameref variable rreeff whose value is + the variable name passed as the first argument. References and assign- + ments to rreeff, and changes to its attributes, are treated as references, + assignments, and attribute modifications to the variable whose name was + passed as $$11. If the control variable in a ffoorr loop has the nameref + attribute, the list of words can be a list of shell variables, and a + name reference is established for each word in the list, in turn, when + the loop is executed. Array variables cannot be given the nnaammeerreeff at- + tribute. However, nameref variables can reference array variables and + subscripted array variables. Namerefs can be unset using the --nn option + to the uunnsseett builtin. Otherwise, if uunnsseett is executed with the name of + a nameref variable as an argument, the variable referenced by the + nameref variable is unset. + + When the shell starts, it reads its environment and creates a shell + variable from each environment variable that has a valid name, as de- + scribed below (see EENNVVIIRROONNMMEENNTT). + + PPoossiittiioonnaall PPaarraammeetteerrss + A _p_o_s_i_t_i_o_n_a_l _p_a_r_a_m_e_t_e_r 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 sseett 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 FFUUNNCCTTIIOONNSS below). + + When a positional parameter consisting of more than a single digit is + expanded, it must be enclosed in braces (see EEXXPPAANNSSIIOONN below). Without + braces, a digit following $ can only refer to one of the first nine po- + sitional parameters ($$11--$$99) or the special parameter $$00 (see the next + section). + + SSppeecciiaall PPaarraammeetteerrss + The shell treats several parameters specially. These parameters may + only be referenced; assignment to them is not allowed. Special parame- + ters are denoted by one of the following characters. + + ** ($$**) 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 word + expansions are performed, those words are subject to further + word splitting and pathname expansion. When the expansion oc- + curs within double quotes, it expands to a single word with the + value of each parameter separated by the first character of the + IIFFSS variable. That is, ""$$**"" is equivalent to ""$$11_c$$22_c......"", where + _c is the first character of the value of the IIFFSS variable. If + IIFFSS is unset, the parameters are separated by spaces. If IIFFSS is + null, the parameters are joined without intervening separators. + @@ ($$@@) 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, such as the value portion + of an assignment statement, this expands to a single word with + each positional parameter separated by a space. When the expan- + sion occurs within double quotes, and word splitting is per- + formed, each parameter expands to a separate word. That is, + ""$$@@"" is equivalent to ""$$11"" ""$$22"" ...... If the double-quoted expan- + sion occurs within a word, the expansion of the first parameter + is joined with the expansion of the beginning part of the origi- + nal word, and the expansion of the last parameter is joined with + the expansion of the last part of the original word. When there + are no positional parameters, ""$$@@"" and $$@@ expand to nothing + (i.e., they are removed). + ## ($$##) Expands to the number of positional parameters in decimal. + ?? ($$??) Expands to the exit status of the most recently executed + command. + -- ($$--) Expands to the current option flags as specified upon invo- + cation, by the sseett builtin command, or those set by the shell + itself (such as the --ii option). + $$ ($$$$) Expands to the process ID of the shell. In a subshell, it + expands to the process ID of the parent shell, not the subshell. + !! ($$!!)Expands to the process ID of the job most recently placed + into the background, whether executed as an asynchronous command + or using the bbgg builtin (see JJOOBB CCOONNTTRROOLL below). + 00 ($$00) Expands to the name of the shell or shell script. This is + set at shell initialization. If bbaasshh is invoked with a file of + commands, $$00 is set to the name of that file. If bbaasshh is + started with the --cc option, then $$00 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 bbaasshh, as given by argu- + ment zero. + + SShheellll VVaarriiaabblleess + The shell sets following variables: + + __ ($$__, an underscore) This has a number of meanings depending on + context. At shell startup, __ is set to the pathname used to in- + voke the shell or shell script being executed as passed in the + environment or argument list. Subsequently, it expands to the + last argument to the previous simple command executed in the + foreground, after expansion. It is also set to the full path- + name used to invoke each command executed and placed in the en- + vironment exported to that command. When checking mail, $$__ ex- + pands to the name of the mail file currently being checked. + BBAASSHH Expands to the full filename used to invoke this instance of + bbaasshh. + BBAASSHHOOPPTTSS + A colon-separated list of enabled shell options. Each word in + the list is a valid argument for the --ss option to the sshhoopptt + builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). The options + appearing in BBAASSHHOOPPTTSS are those reported as _o_n by sshhoopptt. If + this variable is in the environment when bbaasshh starts up, the + shell enables each option in the list before reading any startup + files. If this variable is exported, child shells will enable + each option in the list. This variable is read-only. + BBAASSHHPPIIDD + Expands to the process ID of the current bbaasshh process. This + differs from $$$$ under certain circumstances, such as subshells + that do not require bbaasshh to be re-initialized. Assignments to + BBAASSHHPPIIDD have no effect. If BBAASSHHPPIIDD is unset, it loses its spe- + cial properties, even if it is subsequently reset. + BBAASSHH__AALLIIAASSEESS + An associative array variable whose members correspond to the + internal list of aliases as maintained by the aalliiaass builtin. + Elements added to this array appear in the alias list; however, + unsetting array elements currently does not remove aliases from + the alias list. If BBAASSHH__AALLIIAASSEESS is unset, it loses its special + properties, even if it is subsequently reset. + BBAASSHH__AARRGGCC + An array variable whose values are the number of parameters in + each frame of the current bbaasshh execution call stack. The number + of parameters to the current subroutine (shell function or + script executed with .. or ssoouurrccee) is at the top of the stack. + When a subroutine is executed, the number of parameters passed + is pushed onto BBAASSHH__AARRGGCC. The shell sets BBAASSHH__AARRGGCC only when in + extended debugging mode (see the description of the eexxttddeebbuugg op- + tion to the sshhoopptt builtin below). Setting eexxttddeebbuugg after the + shell has started to execute a script, or referencing this vari- + able when eexxttddeebbuugg is not set, may result in inconsistent val- + ues. Assignments to BBAASSHH__AARRGGCC have no effect, and it may not be + unset. + BBAASSHH__AARRGGVV + An array variable containing all of the parameters in the cur- + rent bbaasshh 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 exe- + cuted, the shell pushes the supplied parameters onto BBAASSHH__AARRGGVV. + The shell sets BBAASSHH__AARRGGVV only when in extended debugging mode + (see the description of the eexxttddeebbuugg option to the sshhoopptt builtin + below). Setting eexxttddeebbuugg after the shell has started to execute + a script, or referencing this variable when eexxttddeebbuugg is not set, + may result in inconsistent values. Assignments to BBAASSHH__AARRGGVV + have no effect, and it may not be unset. + BBAASSHH__AARRGGVV00 + When referenced, this variable expands to the name of the shell + or shell script (identical to $$00; see the description of special + parameter 0 above). Assigning a value to BBAASSHH__AARRGGVV00 sets $$00 to + the same value. If BBAASSHH__AARRGGVV00 is unset, it loses its special + properties, even if it is subsequently reset. + BBAASSHH__CCMMDDSS + An associative array variable whose members correspond to the + internal hash table of commands as maintained by the hhaasshh + builtin. Adding elements to this array makes them appear in the + hash table; however, unsetting array elements currently does not + remove command names from the hash table. If BBAASSHH__CCMMDDSS is un- + set, it loses its special properties, even if it is subsequently + reset. + BBAASSHH__CCOOMMMMAANNDD + Expands to 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 BBAASSHH__CCOOMMMMAANNDD is unset, it loses its special + properties, even if it is subsequently reset. + BBAASSHH__EEXXEECCUUTTIIOONN__SSTTRRIINNGG + The command argument to the --cc invocation option. + BBAASSHH__LLIINNEENNOO + An array variable whose members are the line numbers in source + files where each corresponding member of FFUUNNCCNNAAMMEE was invoked. + $${{BBAASSHH__LLIINNEENNOO[[_$_i]]}} is the line number in the source file + ($${{BBAASSHH__SSOOUURRCCEE[[_$_i_+_1]]}}) where $${{FFUUNNCCNNAAMMEE[[_$_i]]}} was called (or + $${{BBAASSHH__LLIINNEENNOO[[_$_i_-_1]]}} if referenced within another shell func- + tion). Use LLIINNEENNOO to obtain the current line number. Assign- + ments to BBAASSHH__LLIINNEENNOO have no effect, and it may not be unset. + BBAASSHH__LLOOAADDAABBLLEESS__PPAATTHH + A colon-separated list of directories in which the eennaabbllee com- + mand looks for dynamically loadable builtins. + BBAASSHH__MMOONNOOSSEECCOONNDDSS + Each time this variable is referenced, it expands to the value + returned by the system's monotonic clock, if one is available. + If there is no monotonic clock, this is equivalent to EEPPOOCCHHSSEECC-- + OONNDDSS. If BBAASSHH__MMOONNOOSSEECCOONNDDSS is unset, it loses its special prop- + erties, even if it is subsequently reset. + BBAASSHH__RREEMMAATTCCHH + An array variable whose members are assigned by the ==~~ binary + operator to the [[[[ conditional command. The element with index + 0 is the portion of the string matching the entire regular ex- + pression. The element with index _n is the portion of the string + matching the _nth parenthesized subexpression. + BBAASSHH__SSOOUURRCCEE + An array variable whose members are the source filenames where + the corresponding shell function names in the FFUUNNCCNNAAMMEE array + variable are defined. The shell function $${{FFUUNNCCNNAAMMEE[[_$_i]]}} is de- + fined in the file $${{BBAASSHH__SSOOUURRCCEE[[_$_i]]}} and called from + $${{BBAASSHH__SSOOUURRCCEE[[_$_i_+_1]]}}. Assignments to BBAASSHH__SSOOUURRCCEE have no ef- + fect, and it may not be unset. + BBAASSHH__SSUUBBSSHHEELLLL + Incremented by one within each subshell or subshell environment + when the shell begins executing in that environment. The ini- + tial value is 0. If BBAASSHH__SSUUBBSSHHEELLLL is unset, it loses its spe- + cial properties, even if it is subsequently reset. + BBAASSHH__TTRRAAPPSSIIGG + Set to the signal number corresponding to the trap action being + executed during its execution. See the description of ttrraapp un- + der SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below for information about signal + numbers and trap execution. + BBAASSHH__VVEERRSSIINNFFOO + A readonly array variable whose members hold version information + for this instance of bbaasshh. The values assigned to the array + members are as follows: + BBAASSHH__VVEERRSSIINNFFOO[[0]] The major version number (the _r_e_l_e_a_s_e). + BBAASSHH__VVEERRSSIINNFFOO[[1]] The minor version number (the _v_e_r_s_i_o_n). + BBAASSHH__VVEERRSSIINNFFOO[[2]] The patch level. + BBAASSHH__VVEERRSSIINNFFOO[[3]] The build version. + BBAASSHH__VVEERRSSIINNFFOO[[4]] The release status (e.g., _b_e_t_a). + BBAASSHH__VVEERRSSIINNFFOO[[5]] The value of MMAACCHHTTYYPPEE. + BBAASSHH__VVEERRSSIIOONN + Expands to a string describing the version of this instance of + bbaasshh (e.g., 5.2.37(3)-release). + CCOOMMPP__CCWWOORRDD + An index into $${{CCOOMMPP__WWOORRDDSS}} of the word containing the current + cursor position. This variable is available only in shell func- + tions invoked by the programmable completion facilities (see + PPrrooggrraammmmaabbllee CCoommpplleettiioonn below). + CCOOMMPP__KKEEYY + The key (or final key of a key sequence) used to invoke the cur- + rent completion function. This variable is available only in + shell functions and external commands invoked by the programma- + ble completion facilities (see PPrrooggrraammmmaabbllee CCoommpplleettiioonn below). + CCOOMMPP__LLIINNEE + The current command line. This variable is available only in + shell functions and external commands invoked by the programma- + ble completion facilities (see PPrrooggrraammmmaabbllee CCoommpplleettiioonn below). + CCOOMMPP__PPOOIINNTT + The index of the current cursor position relative to the begin- + ning 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 $${{##CCOOMMPP__LLIINNEE}}. This variable is available only in + shell functions and external commands invoked by the programma- + ble completion facilities (see PPrrooggrraammmmaabbllee CCoommpplleettiioonn below). + CCOOMMPP__TTYYPPEE + Set to an integer value corresponding to the type of attempted + completion that caused a completion function to be called: _T_A_B, + for normal completion, _?, for listing completions after succes- + sive tabs, _!, for listing alternatives on partial word comple- + tion, _@, to list completions if the word is not unmodified, or + _%, for menu completion. This variable is available only in + shell functions and external commands invoked by the programma- + ble completion facilities (see PPrrooggrraammmmaabbllee CCoommpplleettiioonn below). + CCOOMMPP__WWOORRDDBBRREEAAKKSS + The set of characters that the rreeaaddlliinnee library treats as word + separators when performing word completion. If CCOOMMPP__WWOORRDDBBRREEAAKKSS + is unset, it loses its special properties, even if it is subse- + quently reset. + CCOOMMPP__WWOORRDDSS + An array variable (see AArrrraayyss below) consisting of the individ- + ual words in the current command line. The line is split into + words as rreeaaddlliinnee would split it, using CCOOMMPP__WWOORRDDBBRREEAAKKSS as de- + scribed above. This variable is available only in shell func- + tions invoked by the programmable completion facilities (see + PPrrooggrraammmmaabbllee CCoommpplleettiioonn below). + CCOOPPRROOCC An array variable (see AArrrraayyss below) created to hold the file + descriptors for output from and input to an unnamed coprocess + (see CCoopprroocceesssseess above). + DDIIRRSSTTAACCKK + An array variable (see AArrrraayyss below) containing the current con- + tents of the directory stack. Directories appear in the stack + in the order they are displayed by the ddiirrss builtin. Assigning + to members of this array variable may be used to modify directo- + ries already in the stack, but the ppuusshhdd and ppooppdd builtins must + be used to add and remove directories. Assigning to this vari- + able does not change the current directory. If DDIIRRSSTTAACCKK is un- + set, it loses its special properties, even if it is subsequently + reset. + EEPPOOCCHHRREEAALLTTIIMMEE + Each time this parameter is referenced, it expands to the number + of seconds since the Unix Epoch (see _t_i_m_e(3)) as a floating- + point value with micro-second granularity. Assignments to + EEPPOOCCHHRREEAALLTTIIMMEE are ignored. If EEPPOOCCHHRREEAALLTTIIMMEE is unset, it loses + its special properties, even if it is subsequently reset. + EEPPOOCCHHSSEECCOONNDDSS + Each time this parameter is referenced, it expands to the number + of seconds since the Unix Epoch (see _t_i_m_e(3)). Assignments to + EEPPOOCCHHSSEECCOONNDDSS are ignored. If EEPPOOCCHHSSEECCOONNDDSS is unset, it loses + its special properties, even if it is subsequently reset. + EEUUIIDD Expands to the effective user ID of the current user, initial- + ized at shell startup. This variable is readonly. + FFUUNNCCNNAAMMEE + 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 bot- + tom-most element (the one with the highest index) is "main". + This variable exists only when a shell function is executing. + Assignments to FFUUNNCCNNAAMMEE have no effect. If FFUUNNCCNNAAMMEE is unset, + it loses its special properties, even if it is subsequently re- + set. + + This variable can be used with BBAASSHH__LLIINNEENNOO and BBAASSHH__SSOOUURRCCEE. + Each element of FFUUNNCCNNAAMMEE has corresponding elements in + BBAASSHH__LLIINNEENNOO and BBAASSHH__SSOOUURRCCEE to describe the call stack. For in- + stance, $${{FFUUNNCCNNAAMMEE[[_$_i]]}} was called from the file + $${{BBAASSHH__SSOOUURRCCEE[[_$_i_+_1]]}} at line number $${{BBAASSHH__LLIINNEENNOO[[_$_i]]}}. The + ccaalllleerr builtin displays the current call stack using this infor- + mation. + GGRROOUUPPSS An array variable containing the list of groups of which the + current user is a member. Assignments to GGRROOUUPPSS have no effect. + If GGRROOUUPPSS is unset, it loses its special properties, even if it + is subsequently reset. + HHIISSTTCCMMDD + The history number, or index in the history list, of the current + command. Assignments to HHIISSTTCCMMDD have no effect. If HHIISSTTCCMMDD is + unset, it loses its special properties, even if it is subse- + quently reset. + HHOOSSTTNNAAMMEE + Automatically set to the name of the current host. + HHOOSSTTTTYYPPEE + Automatically set to a string that uniquely describes the type + of machine on which bbaasshh is executing. The default is system- + dependent. + LLIINNEENNOO 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 LLIINNEENNOO is unset, it loses its special proper- + ties, even if it is subsequently reset. + MMAACCHHTTYYPPEE + Automatically set to a string that fully describes the system + type on which bbaasshh is executing, in the standard GNU _c_p_u_-_c_o_m_- + _p_a_n_y_-_s_y_s_t_e_m format. The default is system-dependent. + MMAAPPFFIILLEE + An array variable (see AArrrraayyss below) created to hold the text + read by the mmaappffiillee builtin when no variable name is supplied. + OOLLDDPPWWDD The previous working directory as set by the ccdd command. + OOPPTTAARRGG The value of the last option argument processed by the ggeettooppttss + builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + OOPPTTIINNDD The index of the next argument to be processed by the ggeettooppttss + builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + OOSSTTYYPPEE Automatically set to a string that describes the operating sys- + tem on which bbaasshh is executing. The default is system-depen- + dent. + PPIIPPEESSTTAATTUUSS + An array variable (see AArrrraayyss below) containing a list of exit + status values from the commands in the most-recently-executed + foreground pipeline, which may consist of only a simple command + (see SSHHEELLLL GGRRAAMMMMAARR above). BBaasshh sets PPIIPPEESSTTAATTUUSS after executing + multi-element pipelines, timed and negated pipelines, simple + commands, subshells created with the ( operator, the [[[[ and (((( + compound commands, and after error conditions that result in the + shell aborting command execution. + PPPPIIDD The process ID of the shell's parent. This variable is read- + only. + PPWWDD The current working directory as set by the ccdd command. + RRAANNDDOOMM Each time this parameter is referenced, it expands to a random + integer between 0 and 32767. Assigning a value to RRAANNDDOOMM ini- + tializes (seeds) the sequence of random numbers. Seeding the + random number generator with the same constant value produces + the same sequence of values. If RRAANNDDOOMM is unset, it loses its + special properties, even if it is subsequently reset. + RREEAADDLLIINNEE__AARRGGUUMMEENNTT + Any numeric argument given to a rreeaaddlliinnee command that was de- + fined using "bind -x" (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below) when it + was invoked. + RREEAADDLLIINNEE__LLIINNEE + The contents of the rreeaaddlliinnee line buffer, for use with "bind -x" + (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + RREEAADDLLIINNEE__MMAARRKK + The position of the mark (saved insertion point) in the rreeaaddlliinnee + line buffer, for use with "bind -x" (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS + below). The characters between the insertion point and the mark + are often called the _r_e_g_i_o_n. + RREEAADDLLIINNEE__PPOOIINNTT + The position of the insertion point in the rreeaaddlliinnee line buffer, + for use with "bind -x" (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + RREEPPLLYY Set to the line of input read by the rreeaadd builtin command when + no arguments are supplied. + SSEECCOONNDDSS + Each time this parameter is referenced, it expands to the number + of seconds since shell invocation. If a value is assigned to + SSEECCOONNDDSS, 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 at one-second + resolution. If SSEECCOONNDDSS is unset, it loses its special proper- + ties, even if it is subsequently reset. + SSHHEELLLLOOPPTTSS + A colon-separated list of enabled shell options. Each word in + the list is a valid argument for the --oo option to the sseett + builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). The options + appearing in SSHHEELLLLOOPPTTSS are those reported as _o_n by sseett --oo. If + this variable is in the environment when bbaasshh starts up, the + shell enables each option in the list before reading any startup + files. If this variable is exported, child shells will enable + each option in the list. This variable is read-only. + SSHHLLVVLL Incremented by one each time an instance of bbaasshh is started. + SSRRAANNDDOOMM + Each time it is referenced, this variable expands to a 32-bit + pseudo-random number. The random number generator is not linear + on systems that support _/_d_e_v_/_u_r_a_n_d_o_m or _a_r_c_4_r_a_n_d_o_m(3), 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 SSRRAANNDDOOMM is unset, it loses its + special properties, even if it is subsequently reset. + UUIIDD Expands to the user ID of the current user, initialized at shell + startup. This variable is readonly. + + The shell uses the following variables. In some cases, bbaasshh assigns a + default value to a variable; these cases are noted below. + + BBAASSHH__CCOOMMPPAATT + The value is used to set the shell's compatibility level. See + SSHHEELLLL CCOOMMPPAATTIIBBIILLIITTYY MMOODDEE below for a description of the various + compatibility levels and their effects. The value may be a dec- + imal number (e.g., 4.2) or an integer (e.g., 42) corresponding + to the desired compatibility level. If BBAASSHH__CCOOMMPPAATT is unset or + set to the empty string, the compatibility level is set to the + default for the current version. If BBAASSHH__CCOOMMPPAATT 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. A subset of the valid + values correspond to the compatibility levels described below + under SSHHEELLLL CCOOMMPPAATTIIBBIILLIITTYY MMOODDEE. For example, 4.2 and 42 are + valid values that correspond to the ccoommppaatt4422 sshhoopptt option and + set the compatibility level to 42. The current version is also + a valid value. + BBAASSHH__EENNVV + If this parameter is set when bbaasshh is executing a shell script, + its expanded value is interpreted as a filename containing com- + mands to initialize the shell before it reads and executes com- + mands from the script. The value of BBAASSHH__EENNVV is subjected to + parameter expansion, command substitution, and arithmetic expan- + sion before being interpreted as a filename. PPAATTHH is not used + to search for the resultant filename. + BBAASSHH__XXTTRRAACCEEFFDD + If set to an integer corresponding to a valid file descriptor, + bbaasshh writes the trace output generated when "set -x" is enabled + to that file descriptor, instead of the standard error. The + file descriptor is closed when BBAASSHH__XXTTRRAACCEEFFDD is unset or as- + signed a new value. Unsetting BBAASSHH__XXTTRRAACCEEFFDD or assigning it the + empty string causes the trace output to be sent to the standard + error. Note that setting BBAASSHH__XXTTRRAACCEEFFDD to 2 (the standard error + file descriptor) and then unsetting it will result in the stan- + dard error being closed. + CCDDPPAATTHH The search path for the ccdd command. This is a colon-separated + list of directories where the shell looks for directories speci- + fied as arguments to the ccdd command. A sample value is + ".:~:/usr". + CCHHIILLDD__MMAAXX + Set the number of exited child status values for the shell to + remember. BBaasshh will not allow this value to be decreased below + a POSIX-mandated minimum, and there is a maximum value (cur- + rently 8192) that this may not exceed. The minimum value is + system-dependent. + CCOOLLUUMMNNSS + Used by the sseelleecctt compound command to determine the terminal + width when printing selection lists. Automatically set if the + cchheecckkwwiinnssiizzee option is enabled or in an interactive shell upon + receipt of a SSIIGGWWIINNCCHH. + CCOOMMPPRREEPPLLYY + An array variable from which bbaasshh reads the possible completions + generated by a shell function invoked by the programmable com- + pletion facility (see PPrrooggrraammmmaabbllee CCoommpplleettiioonn below). Each ar- + ray element contains one possible completion. + EEMMAACCSS If bbaasshh finds this variable in the environment when the shell + starts with value "t", it assumes that the shell is running in + an Emacs shell buffer and disables line editing. + EENNVV Expanded and executed similarly to BBAASSHH__EENNVV (see IINNVVOOCCAATTIIOONN + above) when an interactive shell is invoked in posix mode. + EEXXEECCIIGGNNOORREE + A colon-separated list of shell patterns (see PPaatttteerrnn MMaattcchhiinngg) + defining the set of filenames to be ignored by command search + using PPAATTHH. Files whose full pathnames match one of these pat- + terns are not considered executable files for the purposes of + completion and command execution via PPAATTHH lookup. This does not + affect the behavior of the [[, tteesstt, and [[[[ commands. Full path- + names in the command hash table are not subject to EEXXEECCIIGGNNOORREE. + 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 eexxttgglloobb shell option. + FFCCEEDDIITT The default editor for the ffcc builtin command. + FFIIGGNNOORREE + A colon-separated list of suffixes to ignore when performing + filename completion (see RREEAADDLLIINNEE below). A filename whose suf- + fix matches one of the entries in FFIIGGNNOORREE is excluded from the + list of matched filenames. A sample value is ".o:~". + FFUUNNCCNNEESSTT + If set to a numeric value greater than 0, defines a maximum + function nesting level. Function invocations that exceed this + nesting level cause the current command to abort. + GGLLOOBBIIGGNNOORREE + 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 GGLLOOBBIIGGNNOORREE, it is removed from the list of matches. + The pattern matching honors the setting of the eexxttgglloobb shell op- + tion. + GGLLOOBBSSOORRTT + Controls how the results of pathname expansion are sorted. The + value of this variable specifies the sort criteria and sort or- + der for the results of pathname expansion. If this variable is + unset or set to the null string, pathname expansion uses the + historical behavior of sorting by name, in ascending lexico- + graphic order as determined by the LLCC__CCOOLLLLAATTEE shell variable. + + If set, a valid value begins with an optional _+, which is ig- + nored, or _-, which reverses the sort order from ascending to de- + scending, followed by a sort specifier. The valid sort speci- + fiers are _n_a_m_e, _n_u_m_e_r_i_c, _s_i_z_e, _m_t_i_m_e, _a_t_i_m_e, _c_t_i_m_e, and _b_l_o_c_k_s, + which sort the files on name, names in numeric rather than lexi- + cographic order, file size, modification time, access time, in- + ode change time, and number of blocks, respectively. If any of + the non-name keys compare as equal (e.g., if two files are the + same size), sorting uses the name as a secondary sort key. + + For example, a value of _-_m_t_i_m_e sorts the results in descending + order by modification time (newest first). + + The _n_u_m_e_r_i_c specifier treats names consisting solely of digits + as numbers and sorts them using their numeric value (so "2" + sorts before "10", for example). When using _n_u_m_e_r_i_c, names con- + taining non-digits sort after all the all-digit names and are + sorted by name using the traditional behavior. + + A sort specifier of _n_o_s_o_r_t disables sorting completely; bbaasshh re- + turns the results in the order they are read from the file sys- + tem, ignoring any leading _-. + + If the sort specifier is missing, it defaults to _n_a_m_e, so a + value of _+ is equivalent to the null string, and a value of _- + sorts by name in descending order. Any invalid value restores + the historical sorting behavior. + HHIISSTTCCOONNTTRROOLL + A colon-separated list of values controlling how commands are + saved on the history list. If the list of values includes + _i_g_n_o_r_e_s_p_a_c_e, lines which begin with a ssppaaccee character are not + saved in the history list. A value of _i_g_n_o_r_e_d_u_p_s causes lines + matching the previous history entry not to be saved. A value of + _i_g_n_o_r_e_b_o_t_h is shorthand for _i_g_n_o_r_e_s_p_a_c_e and _i_g_n_o_r_e_d_u_p_s. A value + of _e_r_a_s_e_d_u_p_s 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 HHIISSTTCCOONNTTRROOLL is + unset, or does not include a valid value, bbaasshh saves all lines + read by the shell parser on the history list, subject to the + value of HHIISSTTIIGGNNOORREE. If the first line of a multi-line compound + command was saved, the second and subsequent lines are not + tested, and are added to the history regardless of the value of + HHIISSTTCCOONNTTRROOLL. If the first line was not saved, the second and + subsequent lines of the command are not saved either. + HHIISSTTFFIILLEE + The name of the file in which command history is saved (see HHIISS-- + TTOORRYY below). BBaasshh assigns a default value of _~_/_._b_a_s_h___h_i_s_t_o_r_y. + If HHIISSTTFFIILLEE is unset or null, the shell does not save the com- + mand history when it exits. + HHIISSTTFFIILLEESSIIZZEE + The maximum number of lines contained in the history file. When + this variable is assigned a value, the history file is trun- + cated, if necessary, to contain no more than the number of his- + tory entries that total no more than that number of lines by re- + moving the oldest entries. If the history list contains multi- + line entries, the history file may contain more lines than this + maximum to avoid leaving partial history entries. The history + file is also truncated to this size after writing it when a + shell exits or by the hhiissttoorryy builtin. 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 HHIISSTTSSIIZZEE after reading + any startup files. + HHIISSTTIIGGNNOORREE + A colon-separated list of patterns used to decide which command + lines should be saved on the history list. If a command line + matches one of the patterns in the value of HHIISSTTIIGGNNOORREE, it is + not saved on the history list. Each pattern is anchored at the + beginning of the line and must match the complete line (bbaasshh + does not implicitly append a "**"). Each pattern is tested + against the line after the checks specified by HHIISSTTCCOONNTTRROOLL are + applied. In addition to the normal shell pattern matching char- + acters, "&&" matches the previous history line. A backslash es- + capes the "&&"; the backslash is removed before attempting a + match. If the first line of a multi-line compound command was + saved, the second and subsequent lines are not tested, and are + added to the history regardless of the value of HHIISSTTIIGGNNOORREE. If + the first line was not saved, the second and subsequent lines of + the command are not saved either. The pattern matching honors + the setting of the eexxttgglloobb shell option. + HHIISSTTIIGGNNOORREE subsumes some of the function of HHIISSTTCCOONNTTRROOLL. A pat- + tern of "&" is identical to "ignoredups", and a pattern of "[ + ]*" is identical to "ignorespace". Combining these two pat- + terns, separating them with a colon, provides the functionality + of "ignoreboth". + HHIISSTTSSIIZZEE + The number of commands to remember in the command history (see + HHIISSTTOORRYY 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. + HHIISSTTTTIIMMEEFFOORRMMAATT + If this variable is set and not null, its value is used as a + format string for _s_t_r_f_t_i_m_e(3) to print the time stamp associated + with each history entry displayed by the hhiissttoorryy builtin. If + this variable is set, the shell writes time stamps to the his- + tory file so they may be preserved across shell sessions. This + uses the history comment character to distinguish timestamps + from other history lines. + HHOOMMEE The home directory of the current user; the default argument for + the ccdd builtin command. The value of this variable is also used + when performing tilde expansion. + HHOOSSTTFFIILLEE + Contains the name of a file in the same format as _/_e_t_c_/_h_o_s_t_s + 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 at- + tempted after the value is changed, bbaasshh adds the contents of + the new file to the existing list. If HHOOSSTTFFIILLEE is set, but has + no value, or does not name a readable file, bbaasshh attempts to + read _/_e_t_c_/_h_o_s_t_s to obtain the list of possible hostname comple- + tions. When HHOOSSTTFFIILLEE is unset, bbaasshh clears the hostname list. + IIFFSS The _I_n_t_e_r_n_a_l _F_i_e_l_d _S_e_p_a_r_a_t_o_r that is used for word splitting af- + ter expansion and to split lines into words with the rreeaadd + builtin command. Word splitting is described below under EEXXPPAANN-- + SSIIOONN. The default value is "". + IIGGNNOORREEEEOOFF + Controls the action of an interactive shell on receipt of an EEOOFF + character as the sole input. If set, the value is the number of + consecutive EEOOFF characters which must be typed as the first + characters on an input line before bbaasshh exits. If the variable + is set but does not have a numeric value, or the value is null, + the default value is 10. If it is unset, EEOOFF signifies the end + of input to the shell. + IINNPPUUTTRRCC + The filename for the rreeaaddlliinnee startup file, overriding the de- + fault of _~_/_._i_n_p_u_t_r_c (see RREEAADDLLIINNEE below). + IINNSSIIDDEE__EEMMAACCSS + If this variable appears in the environment when the shell + starts, bbaasshh assumes that it is running inside an Emacs shell + buffer and may disable line editing, depending on the value of + TTEERRMM. + LLAANNGG Used to determine the locale category for any category not + specifically selected with a variable starting with LLCC__. + LLCC__AALLLL This variable overrides the value of LLAANNGG and any other LLCC__ + variable specifying a locale category. + LLCC__CCOOLLLLAATTEE + 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 se- + quences within pathname expansion and pattern matching. + LLCC__CCTTYYPPEE + This variable determines the interpretation of characters and + the behavior of character classes within pathname expansion and + pattern matching. + LLCC__MMEESSSSAAGGEESS + This variable determines the locale used to translate double- + quoted strings preceded by a $$. + LLCC__NNUUMMEERRIICC + This variable determines the locale category used for number + formatting. + LLCC__TTIIMMEE + This variable determines the locale category used for data and + time formatting. + LLIINNEESS Used by the sseelleecctt compound command to determine the column + length for printing selection lists. Automatically set if the + cchheecckkwwiinnssiizzee option is enabled or in an interactive shell upon + receipt of a SSIIGGWWIINNCCHH. + MMAAIILL If the value is set to a file or directory name and the MMAAIILLPPAATTHH + variable is not set, bbaasshh informs the user of the arrival of + mail in the specified file or Maildir-format directory. + MMAAIILLCCHHEECCKK + Specifies how often (in seconds) bbaasshh checks for mail. The de- + fault 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. + MMAAIILLPPAATTHH + 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, $$__ expands to the + name of the current mailfile. For example: + MMAAIILLPPAATTHH='/var/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"' + BBaasshh can be configured to supply a default value for this vari- + able (there is no value by default), but the location of the + user mail files that it uses is system dependent (e.g., + /var/mail/$$UUSSEERR). + OOPPTTEERRRR If set to the value 1, bbaasshh displays error messages generated by + the ggeettooppttss builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + OOPPTTEERRRR is initialized to 1 each time the shell is invoked or a + shell script is executed. + PPAATTHH The search path for commands. It is a colon-separated list of + directories in which the shell looks for commands (see CCOOMMMMAANNDD + EEXXEECCUUTTIIOONN below). A zero-length (null) directory name in the + value of PPAATTHH 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 bbaasshh. A common value is + /usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin + PPOOSSIIXXLLYY__CCOORRRREECCTT + If this variable is in the environment when bbaasshh starts, the + shell enters posix mode before reading the startup files, as if + the ----ppoossiixx invocation option had been supplied. If it is set + while the shell is running, bbaasshh enables posix mode, as if the + command "set -o posix" had been executed. When the shell enters + posix mode, it sets this variable if it was not already set. + PPRROOMMPPTT__CCOOMMMMAANNDD + 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. + PPRROOMMPPTT__DDIIRRTTRRIIMM + If set to a number greater than zero, the value is used as the + number of trailing directory components to retain when expanding + the \\ww and \\WW prompt string escapes (see PPRROOMMPPTTIINNGG below). + Characters removed are replaced with an ellipsis. + PPSS00 The value of this parameter is expanded (see PPRROOMMPPTTIINNGG below) + and displayed by interactive shells after reading a command and + before the command is executed. + PPSS11 The value of this parameter is expanded (see PPRROOMMPPTTIINNGG below) + and used as the primary prompt string. The default value is + "\s-\v\$ ". + PPSS22 The value of this parameter is expanded as with PPSS11 and used as + the secondary prompt string. The default is "> ". + PPSS33 The value of this parameter is used as the prompt for the sseelleecctt + command (see SSHHEELLLL GGRRAAMMMMAARR above). + PPSS44 The value of this parameter is expanded as with PPSS11 and the + value is printed before each command bbaasshh displays during an ex- + ecution trace. The first character of the expanded value of PPSS44 + is replicated multiple times, as necessary, to indicate multiple + levels of indirection. The default is "+ ". + SSHHEELLLL This variable expands to the full pathname to the shell. If it + is not set when the shell starts, bbaasshh assigns to it the full + pathname of the current user's login shell. + TTIIMMEEFFOORRMMAATT + The value of this parameter is used as a format string specify- + ing how the timing information for pipelines prefixed with the + ttiimmee reserved word should be displayed. The %% character intro- + duces an escape sequence that is expanded to a time value or + other information. The escape sequences and their meanings are + as follows; the brackets denote optional portions. + %%%% A literal %%. + %%[[_p]][[ll]]RR The elapsed time in seconds. + %%[[_p]][[ll]]UU The number of CPU seconds spent in user mode. + %%[[_p]][[ll]]SS The number of CPU seconds spent in system mode. + %%PP The CPU percentage, computed as (%U + %S) / %R. + + The optional _p is a digit specifying the _p_r_e_c_i_s_i_o_n, the number + of fractional digits after a decimal point. A value of 0 causes + no decimal point or fraction to be output. ttiimmee prints at most + six digits after the decimal point; values of _p greater than 6 + are changed to 6. If _p is not specified, ttiimmee prints three dig- + its after the decimal point. + + The optional ll specifies a longer format, including minutes, of + the form _M_Mm_S_S._F_Fs. The value of _p determines whether or not + the fraction is included. + + If this variable is not set, bbaasshh acts as if it had the value + $$''\\nnrreeaall\\tt%%33llRR\\nnuusseerr\\tt%%33llUU\\nnssyyss\\tt%%33llSS''. If the value is null, + bbaasshh does not display any timing information. A trailing new- + line is added when the format string is displayed. + TTMMOOUUTT If set to a value greater than zero, the rreeaadd builtin uses the + value as its default timeout. The sseelleecctt command terminates if + input does not arrive after TTMMOOUUTT seconds when input is coming + from a terminal. In an interactive shell, the value is inter- + preted as the number of seconds to wait for a line of input af- + ter issuing the primary prompt. BBaasshh terminates after waiting + for that number of seconds if a complete line of input does not + arrive. + TTMMPPDDIIRR If set, bbaasshh uses its value as the name of a directory in which + bbaasshh creates temporary files for the shell's use. + aauuttoo__rreessuummee + This variable controls how the shell interacts with the user and + job control. If this variable is set, simple commands consist- + ing of only a single word, 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 or containing the word, this selects the most recently ac- + cessed job. The _n_a_m_e of a stopped job, in this context, is the + command line used to start it, as displayed by jjoobbss. If set to + the value _e_x_a_c_t, the word must match the name of a stopped job + exactly; if set to _s_u_b_s_t_r_i_n_g, the word needs to match a sub- + string of the name of a stopped job. The _s_u_b_s_t_r_i_n_g value pro- + vides functionality analogous to the %%?? job identifier (see JJOOBB + CCOONNTTRROOLL below). If set to any other value (e.g., _p_r_e_f_i_x), the + word must be a prefix of a stopped job's name; this provides + functionality analogous to the %%_s_t_r_i_n_g job identifier. + hhiissttcchhaarrss + The two or three characters which control history expansion, + quick substitution, and tokenization (see HHIISSTTOORRYY EEXXPPAANNSSIIOONN be- + low). The first character is the _h_i_s_t_o_r_y _e_x_p_a_n_s_i_o_n character, + the character which begins a history expansion, normally "!!". + The second character is the _q_u_i_c_k _s_u_b_s_t_i_t_u_t_i_o_n character, nor- + mally "^^". When it appears as the first character on the line, + history substitution repeats the previous command, replacing one + string with another. The optional third character is the _h_i_s_- + _t_o_r_y _c_o_m_m_e_n_t character, normally "##", which indicates that the + remainder of the line is a comment when it appears as the first + character of a word. The history comment character disables + history substitution 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. + + AArrrraayyss + BBaasshh provides one-dimensional indexed and associative array variables. + Any variable may be used as an indexed array; the ddeeccllaarree builtin ex- + plicitly declares an array. There is no maximum limit on the size of + an array, nor any requirement that members be indexed or assigned con- + tiguously. Indexed arrays are referenced using arithmetic expressions + that must expand to an integer (see AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN below) and + are zero-based; associative arrays are referenced using arbitrary + strings. Unless otherwise noted, indexed array indices must be non- + negative integers. + + The shell performs parameter and variable expansion, arithmetic expan- + sion, command substitution, and quote removal on indexed array sub- + scripts. Since this can potentially result in empty strings, subscript + indexing treats those as expressions that evaluate to 0. + + The shell performs tilde expansion, parameter and variable expansion, + arithmetic expansion, command substitution, and quote removal on asso- + ciative array subscripts. Empty strings cannot be used as associative + array keys. + + BBaasshh automatically creates an indexed array if any variable is assigned + to using the syntax + _n_a_m_e[_s_u_b_s_c_r_i_p_t]=_v_a_l_u_e . + The _s_u_b_s_c_r_i_p_t is treated as an arithmetic expression that must evaluate + to a number greater than or equal to zero. To explicitly declare an + indexed array, use + ddeeccllaarree --aa _n_a_m_e + (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + ddeeccllaarree --aa _n_a_m_e[_s_u_b_s_c_r_i_p_t] + is also accepted; the _s_u_b_s_c_r_i_p_t is ignored. + + Associative arrays are created using + ddeeccllaarree --AA _n_a_m_e + . + + Attributes may be specified for an array variable using the ddeeccllaarree and + rreeaaddoonnllyy builtins. Each attribute applies to all members of an array. + + Arrays are assigned using compound assignments of the form _n_a_m_e=((value_1 + ... value_n)), where each _v_a_l_u_e may be of the form [_s_u_b_s_c_r_i_p_t]=_s_t_r_i_n_g. + Indexed array assignments do not require anything but _s_t_r_i_n_g. Each + _v_a_l_u_e in the list is expanded using the shell expansions described be- + low under EEXXPPAANNSSIIOONN, but _v_a_l_u_es that are valid variable assignments in- + cluding the brackets and subscript do not undergo brace expansion and + word splitting, as with individual variable assignments. + + When assigning to indexed arrays, if the optional brackets and sub- + script 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. + + When assigning to an associative array, the words in a compound assign- + ment may be either assignment statements, for which the subscript is + required, or a list of words that is interpreted as a sequence of al- + ternating keys and values: _n_a_m_e=(( _k_e_y_1 _v_a_l_u_e_1 _k_e_y_2 _v_a_l_u_e_2 ...)). These + are treated identically to _n_a_m_e=(( [_k_e_y_1]=_v_a_l_u_e_1 [_k_e_y_2]=_v_a_l_u_e_2 ...)). + The first word in the list determines how the remaining words are in- + terpreted; 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. + + This syntax is also accepted by the ddeeccllaarree builtin. Individual array + elements may be assigned to using the _n_a_m_e[_s_u_b_s_c_r_i_p_t]=_v_a_l_u_e syntax in- + troduced above. + + When assigning to an indexed array, if _n_a_m_e is subscripted by a nega- + tive number, that number is interpreted as relative to one greater than + the maximum index of _n_a_m_e, so negative indices count back from the end + of the array, and an index of -1 references the last element. + + The "+=" operator appends to an array variable when assigning using the + compound assignment syntax; see PPAARRAAMMEETTEERRSS above. + + An array element is referenced using ${_n_a_m_e[_s_u_b_s_c_r_i_p_t]}. The braces + are required to avoid conflicts with pathname expansion. If _s_u_b_s_c_r_i_p_t + is @@ or **, the word expands to all members of _n_a_m_e, unless noted in the + description of a builtin or word expansion. These subscripts differ + only when the word appears within double quotes. If the word is dou- + ble-quoted, ${_n_a_m_e[*]} expands to a single word with the value of each + array member separated by the first character of the IIFFSS special vari- + able, and ${_n_a_m_e[@]} expands each element of _n_a_m_e to a separate word. + When there are no array members, ${_n_a_m_e[@]} 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 expansion of + the original word, and the expansion of the last parameter is joined + with the last part of the expansion of the original word. This is + analogous to the expansion of the special parameters ** and @@ (see SSppee-- + cciiaall PPaarraammeetteerrss above). + + ${#_n_a_m_e[_s_u_b_s_c_r_i_p_t]} expands to the length of ${_n_a_m_e[_s_u_b_s_c_r_i_p_t]}. If + _s_u_b_s_c_r_i_p_t is ** or @@, the expansion is the number of elements in the ar- + ray. + + If the _s_u_b_s_c_r_i_p_t used to reference an element of an indexed array eval- + uates 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. + + Referencing an array variable without a subscript is equivalent to ref- + erencing the array with a subscript of 0. Any reference to a variable + using a valid subscript is valid; bbaasshh creates an array if necessary. + + An array variable is considered set if a subscript has been assigned a + value. The null string is a valid value. + + It is possible to obtain the keys (indices) of an array as well as the + values. ${!!_n_a_m_e[_@]} and ${!!_n_a_m_e[_*]} expand to the indices assigned in + array variable _n_a_m_e. The treatment when in double quotes is similar to + the expansion of the special parameters _@ and _* within double quotes. + + The uunnsseett builtin is used to destroy arrays. uunnsseett _n_a_m_e[_s_u_b_s_c_r_i_p_t] un- + sets the array element at index _s_u_b_s_c_r_i_p_t, for both indexed and asso- + ciative arrays. Negative subscripts to indexed arrays are interpreted + as described above. Unsetting the last element of an array variable + does not unset the variable. uunnsseett _n_a_m_e, where _n_a_m_e is an array, re- + moves the entire array. uunnsseett _n_a_m_e[_s_u_b_s_c_r_i_p_t] behaves differently de- + pending on whether _n_a_m_e is an indexed or associative array when _s_u_b_- + _s_c_r_i_p_t is ** or @@. If _n_a_m_e is an associative array, this unsets the el- + ement with subscript ** or @@. If _n_a_m_e is an indexed array, unset re- + moves all of the elements but does not remove the array itself. + + When using a variable name with a subscript as an argument to a com- + mand, such as with uunnsseett, without using the word expansion syntax de- + scribed above, (e.g., unset a[4]), the argument is subject to pathname + expansion. Quote the argument if pathname expansion is not desired + (e.g., unset 'a[4]'). + + The ddeeccllaarree, llooccaall, and rreeaaddoonnllyy builtins each accept a --aa option to + specify an indexed array and a --AA option to specify an associative ar- + ray. If both options are supplied, --AA takes precedence. The rreeaadd + builtin accepts a --aa option to assign a list of words read from the + standard input to an array. The sseett and ddeeccllaarree builtins display array + values in a way that allows them to be reused as assignments. Other + builtins accept array name arguments as well (e.g., mmaappffiillee); see the + descriptions of individual builtins below for details. The shell pro- + vides a number of builtin array variables. + +EEXXPPAANNSSIIOONN + Expansion is performed on the command line after it has been split into + words. The shell performs these expansions: _b_r_a_c_e _e_x_p_a_n_s_i_o_n, _t_i_l_d_e _e_x_- + _p_a_n_s_i_o_n, _p_a_r_a_m_e_t_e_r _a_n_d _v_a_r_i_a_b_l_e _e_x_p_a_n_s_i_o_n, _c_o_m_m_a_n_d _s_u_b_s_t_i_t_u_t_i_o_n, _a_r_i_t_h_- + _m_e_t_i_c _e_x_p_a_n_s_i_o_n, _w_o_r_d _s_p_l_i_t_t_i_n_g, _p_a_t_h_n_a_m_e _e_x_p_a_n_s_i_o_n, and _q_u_o_t_e _r_e_m_o_v_a_l. + + 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; pathname expansion; + and quote removal. + + On systems that can support it, there is an additional expansion avail- + able: _p_r_o_c_e_s_s _s_u_b_s_t_i_t_u_t_i_o_n. This is performed at the same time as + tilde, parameter, variable, and arithmetic expansion and command sub- + stitution. + + _Q_u_o_t_e _r_e_m_o_v_a_l is always performed last. It removes quote characters + present in the original word, not ones resulting from one of the other + expansions, unless they have been quoted themselves. + + Only brace expansion, word splitting, and pathname expansion can in- + crease the number of words of the expansion; other expansions expand a + single word to a single word. The only exceptions to this are the ex- + pansions of ""$$@@"" and ""$${{_n_a_m_e[[@@]]}}"", and, in most cases, $$** and + $${{_n_a_m_e[[**]]}} as explained above (see PPAARRAAMMEETTEERRSS). + + BBrraaccee EExxppaannssiioonn + _B_r_a_c_e _e_x_p_a_n_s_i_o_n is a mechanism to generate arbitrary strings sharing a + common prefix and suffix, either of which can be empty. This mechanism + is similar to _p_a_t_h_n_a_m_e _e_x_p_a_n_s_i_o_n, but the filenames generated need not + exist. Patterns to be brace expanded are formed from an optional _p_r_e_- + _a_m_b_l_e, followed by either a series of comma-separated strings or a se- + quence expression between a pair of braces, followed by an optional + _p_o_s_t_s_c_r_i_p_t. 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. + + Brace expansions may be nested. The results of each expanded string + are not sorted; brace expansion preserves left to right order. For ex- + ample, a{{d,c,b}}e expands into "ade ace abe". + + A sequence expression takes the form _x...._y[[...._i_n_c_r]], where _x and _y are + either integers or single letters, and _i_n_c_r, an optional increment, is + an integer. When integers are supplied, the expression expands to each + number between _x and _y, inclusive. If either _x or _y begins with a + zero, each generated term will contain the same number of digits, zero- + padding where necessary. When letters are supplied, the expression ex- + pands to each character lexicographically between _x and _y, inclusive, + using the C locale. Note that both _x and _y 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 ap- + propriate. + + Brace expansion is performed before any other expansions, and any char- + acters special to other expansions are preserved in the result. It is + strictly textual. BBaasshh does not apply any syntactic interpretation to + the context of the expansion or the text between the braces. + + A correctly-formed brace expansion must contain unquoted opening and + closing braces, and at least one unquoted comma or a valid sequence ex- + pression. Any incorrectly formed brace expansion is left unchanged. + + A "{" or Q , may be quoted with a backslash to prevent its being con- + sidered part of a brace expression. To avoid conflicts with parameter + expansion, the string "${" is not considered eligible for brace expan- + sion, and inhibits brace expansion until the closing "}". + + This construct is typically used as shorthand when the common prefix of + the strings to be generated is longer than in the above example: + + mkdir /usr/local/src/bash/{old,new,dist,bugs} + or + chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} + + Brace expansion introduces a slight incompatibility with historical + versions of sshh. sshh does not treat opening or closing braces specially + when they appear as part of a word, and preserves them in the output. + BBaasshh removes braces from words as a consequence of brace expansion. + For example, a word entered to sshh as "file{1,2}" appears identically in + the output. BBaasshh outputs that word as "file1 file2" after brace expan- + sion. Start bbaasshh with the ++BB option or disable brace expansion with + the ++BB option to the sseett command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below) for + strict sshh compatibility. + + TTiillddee EExxppaannssiioonn + If a word begins with an unquoted tilde character ("~~"), all of the + characters preceding the first unquoted slash (or all characters, if + there is no unquoted slash) are considered a _t_i_l_d_e_-_p_r_e_f_i_x. 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 _l_o_g_i_n _n_a_m_e. + If this login name is the null string, the tilde is replaced with the + value of the shell parameter HHOOMMEE. If HHOOMMEE is unset, the tilde expands + to the home directory of the user executing the shell instead. Other- + wise, the tilde-prefix is replaced with the home directory associated + with the specified login name. + + If the tilde-prefix is a "~+", the value of the shell variable PPWWDD re- + places the tilde-prefix. If the tilde-prefix is a "~-", the shell sub- + stitutes the value of the shell variable OOLLDDPPWWDD, if it is set. If the + characters following the tilde in the tilde-prefix consist of a number + _N, 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 ddiirrss builtin invoked with the characters following the + tilde in the tilde-prefix as an argument. If the characters following + the tilde in the tilde-prefix consist of a number without a leading "+" + or "-", tilde expansion assumes "+". + + The results of tilde expansion are treated as if they were quoted, so + the replacement is not subject to word splitting and pathname expan- + sion. + + If the login name is invalid, or the tilde expansion fails, the tilde- + prefix is unchanged. + + BBaasshh checks each variable assignment for unquoted tilde-prefixes imme- + diately following a :: or the first ==, and performs tilde expansion in + these cases. Consequently, one may use filenames with tildes in as- + signments to PPAATTHH, MMAAIILLPPAATTHH, and CCDDPPAATTHH, and the shell assigns the ex- + panded value. + + BBaasshh also performs tilde expansion on words satisfying the conditions + of variable assignments (as described above under PPAARRAAMMEETTEERRSS) when they + appear as arguments to simple commands. BBaasshh does not do this, except + for the _d_e_c_l_a_r_a_t_i_o_n commands listed above, when in posix mode. + + PPaarraammeetteerr EExxppaannssiioonn + The "$$" 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. + + When braces are used, the matching ending brace is the first "}}" not + escaped by a backslash or within a quoted string, and not within an em- + bedded arithmetic expansion, command substitution, or parameter expan- + sion. + + The basic form of parameter expansion is + + ${_p_a_r_a_m_e_t_e_r} + + which substitutes the value of _p_a_r_a_m_e_t_e_r. The braces are required when + _p_a_r_a_m_e_t_e_r is a positional parameter with more than one digit, or when + _p_a_r_a_m_e_t_e_r is followed by a character which is not to be interpreted as + part of its name. The _p_a_r_a_m_e_t_e_r is a shell parameter as described + above PPAARRAAMMEETTEERRSS) or an array reference (AArrrraayyss). + + If the first character of _p_a_r_a_m_e_t_e_r is an exclamation point (!!), and + _p_a_r_a_m_e_t_e_r is not a _n_a_m_e_r_e_f, it introduces a level of indirection. BBaasshh + uses the value formed by expanding the rest of _p_a_r_a_m_e_t_e_r as the new _p_a_- + _r_a_m_e_t_e_r; this new parameter is then expanded and that value is used in + the rest of the expansion, rather than the expansion of the original + _p_a_r_a_m_e_t_e_r. This is known as _i_n_d_i_r_e_c_t _e_x_p_a_n_s_i_o_n. The value is subject + to tilde expansion, parameter expansion, command substitution, and + arithmetic expansion. If _p_a_r_a_m_e_t_e_r is a nameref, this expands to the + name of the parameter referenced by _p_a_r_a_m_e_t_e_r instead of performing the + complete indirect expansion, for compatibility. The exceptions to this + are the expansions of ${!!_p_r_e_f_i_x**} and ${!!_n_a_m_e[_@]} described below. The + exclamation point must immediately follow the left brace in order to + introduce indirection. + + In each of the cases below, _w_o_r_d is subject to tilde expansion, parame- + ter expansion, command substitution, and arithmetic expansion. + + When not performing substring expansion, using the forms documented be- + low (e.g., ::--), bbaasshh tests for a parameter that is unset or null. + Omitting the colon tests only for a parameter that is unset. + + ${_p_a_r_a_m_e_t_e_r::--_w_o_r_d} + UUssee DDeeffaauulltt VVaalluueess. If _p_a_r_a_m_e_t_e_r is unset or null, the expan- + sion of _w_o_r_d is substituted. Otherwise, the value of _p_a_r_a_m_e_t_e_r + is substituted. + + ${_p_a_r_a_m_e_t_e_r::==_w_o_r_d} + AAssssiiggnn DDeeffaauulltt VVaalluueess. If _p_a_r_a_m_e_t_e_r is unset or null, the ex- + pansion of _w_o_r_d is assigned to _p_a_r_a_m_e_t_e_r, and the expansion is + the final value of _p_a_r_a_m_e_t_e_r. Positional parameters and special + parameters may not be assigned in this way. + + ${_p_a_r_a_m_e_t_e_r::??_w_o_r_d} + DDiissppllaayy EErrrroorr iiff NNuullll oorr UUnnsseett. If _p_a_r_a_m_e_t_e_r is null or unset, + the shell writes the expansion of _w_o_r_d (or a message to that ef- + fect if _w_o_r_d is not present) to the standard error and, if it is + not interactive, exits with a non-zero status. An interactive + shell does not exit, but does not execute the command associated + with the expansion. Otherwise, the value of _p_a_r_a_m_e_t_e_r is sub- + stituted. + + ${_p_a_r_a_m_e_t_e_r::++_w_o_r_d} + UUssee AAlltteerrnnaattee VVaalluuee. If _p_a_r_a_m_e_t_e_r is null or unset, nothing is + substituted, otherwise the expansion of _w_o_r_d is substituted. + The value of _p_a_r_a_m_e_t_e_r is not used. + + ${_p_a_r_a_m_e_t_e_r::_o_f_f_s_e_t} + ${_p_a_r_a_m_e_t_e_r::_o_f_f_s_e_t::_l_e_n_g_t_h} + SSuubbssttrriinngg EExxppaannssiioonn. Expands to up to _l_e_n_g_t_h characters of the + value of _p_a_r_a_m_e_t_e_r starting at the character specified by _o_f_f_- + _s_e_t. If _p_a_r_a_m_e_t_e_r is @@ or **, an indexed array subscripted by @@ + or **, or an associative array name, the results differ as de- + scribed below. If ::_l_e_n_g_t_h is omitted (the first form above), + this expands to the substring of the value of _p_a_r_a_m_e_t_e_r starting + at the character specified by _o_f_f_s_e_t and extending to the end of + the value. If _o_f_f_s_e_t is omitted, it is treated as 0. If _l_e_n_g_t_h + is omitted, but the colon after _o_f_f_s_e_t is present, it is treated + as 0. _l_e_n_g_t_h and _o_f_f_s_e_t are arithmetic expressions (see AARRIITTHH-- + MMEETTIICC EEVVAALLUUAATTIIOONN below). + + If _o_f_f_s_e_t evaluates to a number less than zero, the value is + used as an offset in characters from the end of the value of _p_a_- + _r_a_m_e_t_e_r. If _l_e_n_g_t_h evaluates to a number less than zero, it is + interpreted as an offset in characters from the end of the value + of _p_a_r_a_m_e_t_e_r rather than a number of characters, and the expan- + sion is the characters between _o_f_f_s_e_t 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 ::-- expansion. + + If _p_a_r_a_m_e_t_e_r is @@ or **, the result is _l_e_n_g_t_h positional parame- + ters beginning at _o_f_f_s_e_t. A negative _o_f_f_s_e_t is taken relative + to one greater than the greatest positional parameter, so an + offset of -1 evaluates to the last positional parameter (or 0 if + there are no positional parameters). It is an expansion error + if _l_e_n_g_t_h evaluates to a number less than zero. + + If _p_a_r_a_m_e_t_e_r is an indexed array name subscripted by @ or *, the + result is the _l_e_n_g_t_h members of the array beginning with ${_p_a_r_a_- + _m_e_t_e_r[_o_f_f_s_e_t]}. A negative _o_f_f_s_e_t is taken relative to one + greater than the maximum index of the specified array. It is an + expansion error if _l_e_n_g_t_h evaluates to a number less than zero. + + Substring expansion applied to an associative array produces un- + defined results. + + Substring indexing is zero-based unless the positional parame- + ters are used, in which case the indexing starts at 1 by de- + fault. If _o_f_f_s_e_t is 0, and the positional parameters are used, + $$00 is prefixed to the list. + + ${!!_p_r_e_f_i_x**} + ${!!_p_r_e_f_i_x@@} + NNaammeess mmaattcchhiinngg pprreeffiixx. Expands to the names of variables whose + names begin with _p_r_e_f_i_x, separated by the first character of the + IIFFSS special variable. When _@ is used and the expansion appears + within double quotes, each variable name expands to a separate + word. + + ${!!_n_a_m_e[_@]} + ${!!_n_a_m_e[_*]} + LLiisstt ooff aarrrraayy kkeeyyss. If _n_a_m_e is an array variable, expands to + the list of array indices (keys) assigned in _n_a_m_e. If _n_a_m_e is + not an array, expands to 0 if _n_a_m_e is set and null otherwise. + When _@ is used and the expansion appears within double quotes, + each key expands to a separate word. + + ${##_p_a_r_a_m_e_t_e_r} + PPaarraammeetteerr lleennggtthh. Substitutes the length in characters of the + expanded value of _p_a_r_a_m_e_t_e_r. If _p_a_r_a_m_e_t_e_r is ** or @@, the value + substituted is the number of positional parameters. If _p_a_r_a_m_e_- + _t_e_r is an array name subscripted by ** or @@, the value substi- + tuted is the number of elements in the array. If _p_a_r_a_m_e_t_e_r is + an indexed array name subscripted by a negative number, that + number is interpreted as relative to one greater than the maxi- + mum index of _p_a_r_a_m_e_t_e_r, so negative indices count back from the + end of the array, and an index of -1 references the last ele- + ment. + + ${_p_a_r_a_m_e_t_e_r##_w_o_r_d} + ${_p_a_r_a_m_e_t_e_r####_w_o_r_d} + RReemmoovvee mmaattcchhiinngg pprreeffiixx ppaatttteerrnn. The _w_o_r_d is expanded to produce + a pattern just as in pathname expansion, and matched against the + expanded value of _p_a_r_a_m_e_t_e_r using the rules described under PPaatt-- + tteerrnn MMaattcchhiinngg below. If the pattern matches the beginning of + the value of _p_a_r_a_m_e_t_e_r, then the result of the expansion is the + expanded value of _p_a_r_a_m_e_t_e_r with the shortest matching pattern + (the "#" case) or the longest matching pattern (the "##" case) + deleted. If _p_a_r_a_m_e_t_e_r is @@ or **, the pattern removal operation + is applied to each positional parameter in turn, and the expan- + sion is the resultant list. If _p_a_r_a_m_e_t_e_r is an array variable + subscripted with @@ or **, the pattern removal operation is ap- + plied to each member of the array in turn, and the expansion is + the resultant list. + + ${_p_a_r_a_m_e_t_e_r%%_w_o_r_d} + ${_p_a_r_a_m_e_t_e_r%%%%_w_o_r_d} + RReemmoovvee mmaattcchhiinngg ssuuffffiixx ppaatttteerrnn. The _w_o_r_d is expanded to produce + a pattern just as in pathname expansion, and matched against the + expanded value of _p_a_r_a_m_e_t_e_r using the rules described under PPaatt-- + tteerrnn MMaattcchhiinngg below. If the pattern matches a trailing portion + of the expanded value of _p_a_r_a_m_e_t_e_r, then the result of the ex- + pansion is the expanded value of _p_a_r_a_m_e_t_e_r with the shortest + matching pattern (the "%" case) or the longest matching pattern + (the "%%" case) deleted. If _p_a_r_a_m_e_t_e_r is @@ or **, the pattern + removal operation is applied to each positional parameter in + turn, and the expansion is the resultant list. If _p_a_r_a_m_e_t_e_r is + an array variable subscripted with @@ or **, the pattern removal + operation is applied to each member of the array in turn, and + the expansion is the resultant list. + + ${_p_a_r_a_m_e_t_e_r//_p_a_t_t_e_r_n//_s_t_r_i_n_g} + ${_p_a_r_a_m_e_t_e_r////_p_a_t_t_e_r_n//_s_t_r_i_n_g} + ${_p_a_r_a_m_e_t_e_r//##_p_a_t_t_e_r_n//_s_t_r_i_n_g} + ${_p_a_r_a_m_e_t_e_r//%%_p_a_t_t_e_r_n//_s_t_r_i_n_g} + PPaatttteerrnn ssuubbssttiittuuttiioonn. The _p_a_t_t_e_r_n is expanded to produce a pat- + tern and matched against the expanded value of _p_a_r_a_m_e_t_e_r as de- + scribed under PPaatttteerrnn MMaattcchhiinngg below. The longest match of _p_a_t_- + _t_e_r_n in the expanded value is replaced with _s_t_r_i_n_g. _s_t_r_i_n_g un- + dergoes tilde expansion, parameter and variable expansion, + arithmetic expansion, command and process substitution, and + quote removal. + + In the first form above, only the first match is replaced. If + there are two slashes separating _p_a_r_a_m_e_t_e_r and _p_a_t_t_e_r_n (the sec- + ond form above), all matches of _p_a_t_t_e_r_n are replaced with + _s_t_r_i_n_g. If _p_a_t_t_e_r_n is preceded by ## (the third form above), it + must match at the beginning of the expanded value of _p_a_r_a_m_e_t_e_r. + If _p_a_t_t_e_r_n is preceded by %% (the fourth form above), it must + match at the end of the expanded value of _p_a_r_a_m_e_t_e_r. + + If the expansion of _s_t_r_i_n_g is null, matches of _p_a_t_t_e_r_n are + deleted and the // following _p_a_t_t_e_r_n may be omitted. + + If the ppaattssuubb__rreeppllaacceemmeenntt shell option is enabled using sshhoopptt, + any unquoted instances of && in _s_t_r_i_n_g are replaced with the + matching portion of _p_a_t_t_e_r_n. + + Quoting any part of _s_t_r_i_n_g inhibits replacement in the expansion + of the quoted portion, including replacement strings stored in + shell variables. Backslash escapes && in _s_t_r_i_n_g; the backslash + is removed in order to permit a literal && in the replacement + string. Backslash can also be used to escape a backslash; \\\\ + results in a literal backslash in the replacement. Users should + take care if _s_t_r_i_n_g is double-quoted to avoid unwanted interac- + tions between the backslash and double-quoting, since backslash + has special meaning within double quotes. Pattern substitution + performs the check for unquoted && after expanding _s_t_r_i_n_g; shell + programmers should quote any occurrences of && they want to be + taken literally in the replacement and ensure any instances of && + they want to be replaced are unquoted. + + Like the pattern removal operators, double quotes surrounding + the replacement string quote the expanded characters, while dou- + ble quotes enclosing the entire parameter substitution do not, + since the expansion is performed in a context that doesn't take + any enclosing double quotes into account. + + If the nnooccaasseemmaattcchh shell option is enabled, the match is per- + formed without regard to the case of alphabetic characters. + + If _p_a_r_a_m_e_t_e_r is @@ or **, the substitution operation is applied to + each positional parameter in turn, and the expansion is the re- + sultant list. If _p_a_r_a_m_e_t_e_r is an array variable subscripted + with @@ or **, the substitution operation is applied to each mem- + ber of the array in turn, and the expansion is the resultant + list. + + ${_p_a_r_a_m_e_t_e_r^^_p_a_t_t_e_r_n} + ${_p_a_r_a_m_e_t_e_r^^^^_p_a_t_t_e_r_n} + ${_p_a_r_a_m_e_t_e_r,,_p_a_t_t_e_r_n} + ${_p_a_r_a_m_e_t_e_r,,,,_p_a_t_t_e_r_n} + CCaassee mmooddiiffiiccaattiioonn. This expansion modifies the case of alpha- + betic characters in _p_a_r_a_m_e_t_e_r. First, the _p_a_t_t_e_r_n is expanded + to produce a pattern as described below under PPaatttteerrnn MMaattcchhiinngg. + BBaasshh then examines characters in the expanded value of _p_a_r_a_m_e_t_e_r + against _p_a_t_t_e_r_n as described below. If a character matches the + pattern, its case is converted. The pattern should not attempt + to match more than one character. + + Using "^" converts lowercase letters matching _p_a_t_t_e_r_n to upper- + case; "," converts matching uppercase letters to lowercase. The + ^^ and ,, variants examine the first character in the expanded + value and convert its case if it matches _p_a_t_t_e_r_n; the ^^^^ and ,,,, + variants examine all characters in the expanded value and con- + vert each one that matches _p_a_t_t_e_r_n. If _p_a_t_t_e_r_n is omitted, it + is treated like a ??, which matches every character. + + If _p_a_r_a_m_e_t_e_r is @@ or **, the case modification operation is ap- + plied to each positional parameter in turn, and the expansion is + the resultant list. If _p_a_r_a_m_e_t_e_r is an array variable sub- + scripted with @@ or **, the case modification operation is applied + to each member of the array in turn, and the expansion is the + resultant list. + + ${_p_a_r_a_m_e_t_e_r@@_o_p_e_r_a_t_o_r} + PPaarraammeetteerr ttrraannssffoorrmmaattiioonn. The expansion is either a transforma- + tion of the value of _p_a_r_a_m_e_t_e_r or information about _p_a_r_a_m_e_t_e_r + itself, depending on the value of _o_p_e_r_a_t_o_r. Each _o_p_e_r_a_t_o_r is a + single letter: + UU The expansion is a string that is the value of _p_a_r_a_m_e_t_e_r + with lowercase alphabetic characters converted to upper- + case. + uu The expansion is a string that is the value of _p_a_r_a_m_e_t_e_r + with the first character converted to uppercase, if it is + alphabetic. + LL The expansion is a string that is the value of _p_a_r_a_m_e_t_e_r + with uppercase alphabetic characters converted to lower- + case. + QQ The expansion is a string that is the value of _p_a_r_a_m_e_t_e_r + quoted in a format that can be reused as input. + EE The expansion is a string that is the value of _p_a_r_a_m_e_t_e_r + with backslash escape sequences expanded as with the + $$''...'' quoting mechanism. + PP The expansion is a string that is the result of expanding + the value of _p_a_r_a_m_e_t_e_r as if it were a prompt string (see + PPRROOMMPPTTIINNGG below). + AA The expansion is a string in the form of an assignment + statement or ddeeccllaarree command that, if evaluated, recre- + ates _p_a_r_a_m_e_t_e_r with its attributes and value. + KK Produces a possibly-quoted version of the value of _p_a_r_a_- + _m_e_t_e_r, except that it prints the values of indexed and + associative arrays as a sequence of quoted key-value + pairs (see AArrrraayyss above). The keys and values are quoted + in a format that can be reused as input. + aa The expansion is a string consisting of flag values rep- + resenting _p_a_r_a_m_e_t_e_r's attributes. + kk Like the K transformation, but expands the keys and val- + ues of indexed and associative arrays to separate words + after word splitting. + + If _p_a_r_a_m_e_t_e_r is @@ or **, the operation is applied to each posi- + tional parameter in turn, and the expansion is the resultant + list. If _p_a_r_a_m_e_t_e_r is an array variable subscripted with @@ or + **, the operation is applied to each member of the array in turn, + and the expansion is the resultant list. + + The result of the expansion is subject to word splitting and + pathname expansion as described below. + + CCoommmmaanndd SSuubbssttiittuuttiioonn + _C_o_m_m_a_n_d _s_u_b_s_t_i_t_u_t_i_o_n allows the output of a command to replace the com- + mand itself. There are two standard forms: + + $$((_c_o_m_m_a_n_d)) + or (deprecated) + ``_c_o_m_m_a_n_d``. + + BBaasshh performs the expansion by executing _c_o_m_m_a_n_d in a subshell environ- + ment 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 com- + mand substitution $$((ccaatt _f_i_l_e)) can be replaced by the equivalent but + faster $$((<< _f_i_l_e)). + + With the old-style backquote form of substitution, backslash retains + its literal meaning except when followed by $$, ``, or \\. The first + backquote not preceded by a backslash terminates the command substitu- + tion. When using the $(_c_o_m_m_a_n_d) form, all characters between the + parentheses make up the command; none are treated specially. + + There is an alternate form of command substitution: + + $${{_c _c_o_m_m_a_n_d;;}} + + which executes _c_o_m_m_a_n_d in the current execution environment and cap- + tures its output, again with trailing newlines removed. + + The character _c following the open brace must be a space, tab, newline, + or ||, and the close brace must be in a position where a reserved word + may appear (i.e., preceded by a command terminator such as semicolon). + BBaasshh allows the close brace to be joined to the remaining characters in + the word without being followed by a shell metacharacter as a reserved + word would usually require. + + Any side effects of _c_o_m_m_a_n_d take effect immediately in the current exe- + cution environment and persist in the current environment after the + command completes (e.g., the eexxiitt builtin exits the shell). + + This type of command substitution superficially resembles executing an + unnamed shell function: local variables are created as when a shell + function is executing, and the rreettuurrnn builtin forces _c_o_m_m_a_n_d to com- + plete; however, the rest of the execution environment, including the + positional parameters, is shared with the caller. + + If the first character following the open brace is a ||, the construct + expands to the value of the RREEPPLLYY shell variable after _c_o_m_m_a_n_d exe- + cutes, without removing any trailing newlines, and the standard output + of _c_o_m_m_a_n_d remains the same as in the calling shell. BBaasshh creates RREE-- + PPLLYY as an initially-unset local variable when _c_o_m_m_a_n_d executes, and re- + stores RREEPPLLYY to the value it had before the command substitution after + _c_o_m_m_a_n_d completes, as with any local variable. + + Command substitutions may be nested. To nest when using the backquoted + form, escape the inner backquotes with backslashes. + + If the substitution appears within double quotes, bbaasshh does not perform + word splitting and pathname expansion on the results. + + AArriitthhmmeettiicc EExxppaannssiioonn + Arithmetic expansion evaluates an arithmetic expression and substitutes + the result. The format for arithmetic expansion is: + + $$((((_e_x_p_r_e_s_s_i_o_n)))) + + The _e_x_p_r_e_s_s_i_o_n undergoes the same expansions as if it were within dou- + ble quotes, but unescaped double quote characters in _e_x_p_r_e_s_s_i_o_n are not + treated specially and are removed. All tokens in the expression un- + dergo parameter and variable expansion, command substitution, and quote + removal. The result is treated as the arithmetic expression to be + evaluated. Since the way Bash handles double quotes can potentially + result in empty strings, arithmetic expansion treats those as expres- + sions that evaluate to 0. Arithmetic expansions may be nested. + + The evaluation is performed according to the rules listed below under + AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN. If _e_x_p_r_e_s_s_i_o_n is invalid, bbaasshh prints a message + to standard error indicating failure, does not perform the substitu- + tion, and does not execute the command associated with the expansion. + + PPrroocceessss SSuubbssttiittuuttiioonn + _P_r_o_c_e_s_s _s_u_b_s_t_i_t_u_t_i_o_n allows a process's input or output to be referred + to using a filename. It takes the form of <<((_l_i_s_t)) or >>((_l_i_s_t)). The + process _l_i_s_t is run asynchronously, and its input or output appears as + a filename. This filename is passed as an argument to the current com- + mand as the result of the expansion. + + If the >>((_l_i_s_t)) form is used, writing to the file provides input for + _l_i_s_t. If the <<((_l_i_s_t)) form is used, reading the file obtains the output + of _l_i_s_t. No space may appear between the << or >> and the left parenthe- + sis, otherwise the construct would be interpreted as a redirection. + + Process substitution is supported on systems that support named pipes + (_F_I_F_O_s) or the _/_d_e_v_/_f_d method of naming open files. + + When available, process substitution is performed simultaneously with + parameter and variable expansion, command substitution, and arithmetic + expansion. + + WWoorrdd SSpplliittttiinngg + The shell scans the results of parameter expansion, command substitu- + tion, and arithmetic expansion that did not occur within double quotes + for _w_o_r_d _s_p_l_i_t_t_i_n_g. Words that were not expanded are not split. + + The shell treats each character of IIFFSS as a delimiter, and splits the + results of the other expansions into words using these characters as + field terminators. + + An _I_F_S _w_h_i_t_e_s_p_a_c_e character is whitespace as defined above (see DDeeffiinnii-- + ttiioonnss) that appears in the value of IIFFSS. Space, tab, and newline are + always considered IFS whitespace, even if they don't appear in the lo- + cale's ssppaaccee category. + + If IIFFSS is unset, field splitting acts as if its value were + <><><>, and treats these characters as IFS whitespace. + If the value of IIFFSS is null, no word splitting occurs, but implicit + null arguments (see below) are still removed. + + Word splitting begins by removing sequences of IFS whitespace charac- + ters from the beginning and end of the results of the previous expan- + sions, then splits the remaining words. + + If the value of IIFFSS consists solely of IFS whitespace, any sequence of + IFS whitespace characters delimits a field, so a field consists of + characters that are not unquoted IFS whitespace, and null fields result + only from quoting. + + If IIFFSS contains a non-whitespace character, then any character in the + value of IIFFSS that is not IFS whitespace, along with any adjacent IFS + whitespace characters, delimits a field. This means that adjacent non- + IFS-whitespace delimiters produce a null field. A sequence of IFS + whitespace characters also delimits a field. + + Explicit null arguments ("""" or '''') 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. Expanding a + parameter with no value within double quotes produces a null field, + which 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, word splitting removes the null argument portion, leaving + the non-null expansion. That is, the word "-d''" becomes "-d" after + word splitting and null argument removal. + + PPaatthhnnaammee EExxppaannssiioonn + After word splitting, unless the --ff option has been set, bbaasshh scans + each word for the characters **, ??, and [[. If one of these characters + appears, and is not quoted, then the word is regarded as a _p_a_t_t_e_r_n, and + replaced with a sorted list of filenames matching the pattern (see PPaatt-- + tteerrnn MMaattcchhiinngg below) subject to the value of the GGLLOOBBSSOORRTT shell vari- + able. + + If no matching filenames are found, and the shell option nnuullllgglloobb is + not enabled, the word is left unchanged. If the nnuullllgglloobb option is + set, and no matches are found, the word is removed. If the ffaaiillgglloobb + shell option is set, and no matches are found, bbaasshh prints an error + message and does not execute the command. If the shell option nnooccaassee-- + gglloobb is enabled, the match is performed without regard to the case of + alphabetic characters. + + When a pattern is used for pathname expansion, the character "." at the + start of a name or immediately following a slash must be matched ex- + plicitly, unless the shell option ddoottgglloobb is set. In order to match + the filenames _. and _._., the pattern must begin with "." (for example, + ".?"), even if ddoottgglloobb is set. If the gglloobbsskkiippddoottss shell option is en- + abled, the filenames _. and _._. never match, even if the pattern begins + with a ".". When not matching pathnames, the "." 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 + PPaatttteerrnn MMaattcchhiinngg. + + See the description of sshhoopptt below under SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS for a + description of the nnooccaasseegglloobb, nnuullllgglloobb, gglloobbsskkiippddoottss, ffaaiillgglloobb, and + ddoottgglloobb shell options. + + The GGLLOOBBIIGGNNOORREE shell variable may be used to restrict the set of file + names matching a _p_a_t_t_e_r_n. If GGLLOOBBIIGGNNOORREE is set, each matching file + name that also matches one of the patterns in GGLLOOBBIIGGNNOORREE is removed + from the list of matches. If the nnooccaasseegglloobb option is set, the match- + ing against the patterns in GGLLOOBBIIGGNNOORREE is performed without regard to + case. The filenames _. and _._. are always ignored when GGLLOOBBIIGGNNOORREE is set + and not null. However, setting GGLLOOBBIIGGNNOORREE to a non-null value has the + effect of enabling the ddoottgglloobb shell option, so all other filenames be- + ginning with a "." match. To get the old behavior of ignoring file- + names beginning with a ".", make ".*" one of the patterns in GGLLOOBBIIGG-- + NNOORREE. The ddoottgglloobb option is disabled when GGLLOOBBIIGGNNOORREE is unset. The + GGLLOOBBIIGGNNOORREE pattern matching honors the setting of the eexxttgglloobb shell op- + tion. + + The value of the GGLLOOBBSSOORRTT shell variable controls how the results of + pathname expansion are sorted, as described above under SShheellll VVaarrii-- + aabblleess. + + PPaatttteerrnn MMaattcchhiinngg + + 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. + + The special pattern characters have the following meanings: + + ** Matches any string, including the null string. When the + gglloobbssttaarr shell option is enabled, and ** is used in a + pathname expansion context, two adjacent **s used as a + single pattern match all files and zero or more directo- + ries and subdirectories. If followed by a //, two adja- + cent **s match only directories and subdirectories. + ?? Matches any single character. + [[...]] Matches any one of the characters enclosed between the + brackets. This is known as a _b_r_a_c_k_e_t _e_x_p_r_e_s_s_i_o_n and + matches a single character. A pair of characters sepa- + rated by a hyphen denotes a _r_a_n_g_e _e_x_p_r_e_s_s_i_o_n; any charac- + ter that falls between those two characters, inclusive, + using the current locale's collating sequence and charac- + ter set, matches. If the first character following the [[ + is a !! or a ^^ then any character not within the range + matches. To match a --, include it as the first or last + character in the set. To match a ]], include it as the + first character in the set. + + 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 LLCC__CCOOLLLLAATTEE or + LLCC__AALLLL shell variables, if set. To obtain the tradi- + tional interpretation of range expressions, where [[aa--dd]] + is equivalent to [[aabbccdd]], set the value of the LLCC__CCOOLLLLAATTEE + or LLCC__AALLLL shell variables to CC, or enable the gglloobbaassccii-- + iirraannggeess shell option. + + Within a bracket expression, _c_h_a_r_a_c_t_e_r _c_l_a_s_s_e_s can be + specified using the syntax [[::_c_l_a_s_s::]], where _c_l_a_s_s is one + of the following classes defined in the POSIX standard: + + aallnnuumm aallpphhaa aasscciiii bbllaannkk ccnnttrrll ddiiggiitt ggrraapphh lloowweerr pprriinntt + ppuunncctt ssppaaccee uuppppeerr wwoorrdd xxddiiggiitt + + A character class matches any character belonging to that + class. The wwoorrdd character class matches letters, digits, + and the character _. + + Within a bracket expression, an _e_q_u_i_v_a_l_e_n_c_e _c_l_a_s_s can be + specified using the syntax [[==_c==]], which matches all char- + acters with the same collation weight (as defined by the + current locale) as the character _c. + + Within a bracket expression, the syntax [[.._s_y_m_b_o_l..]] + matches the collating symbol _s_y_m_b_o_l. + + If the eexxttgglloobb shell option is enabled using the sshhoopptt builtin, the + shell recognizes several extended pattern matching operators. In the + following description, a _p_a_t_t_e_r_n_-_l_i_s_t is a list of one or more patterns + separated by a ||. Composite patterns may be formed using one or more + of the following sub-patterns: + + ??((_p_a_t_t_e_r_n_-_l_i_s_t)) + Matches zero or one occurrence of the given patterns. + **((_p_a_t_t_e_r_n_-_l_i_s_t)) + Matches zero or more occurrences of the given patterns. + ++((_p_a_t_t_e_r_n_-_l_i_s_t)) + Matches one or more occurrences of the given patterns. + @@((_p_a_t_t_e_r_n_-_l_i_s_t)) + Matches one of the given patterns. + !!((_p_a_t_t_e_r_n_-_l_i_s_t)) + Matches anything except one of the given patterns. + + The eexxttgglloobb option changes the behavior of the parser, since the paren- + theses are normally treated as operators with syntactic meaning. To + ensure that extended matching patterns are parsed correctly, make sure + that eexxttgglloobb is enabled before parsing constructs containing the pat- + terns, including shell functions and command substitutions. + + When matching filenames, the ddoottgglloobb shell option determines the set of + filenames that are tested: when ddoottgglloobb is enabled, the set of file- + names 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 "." un- + less the pattern or sub-pattern begins with a ".". If the gglloobbsskkiippddoottss + shell option is enabled, the filenames _. and _._. never appear in the + set. As above, "." only has a special meaning when matching filenames. + + Complicated extended pattern matching against long strings is slow, es- + pecially 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. + + QQuuoottee RReemmoovvaall + After the preceding expansions, all unquoted occurrences of the charac- + ters \\, '', and "" that did not result from one of the above expansions + are removed. + +RREEDDIIRREECCTTIIOONN + Before a command is executed, its input and output may be _r_e_d_i_r_e_c_t_e_d + using a special notation interpreted by the shell. _R_e_d_i_r_e_c_t_i_o_n 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. When used with the eexxeecc builtin, redirections modify file + handles in the current shell execution environment. The following + redirection operators may precede or appear anywhere within a _s_i_m_p_l_e + _c_o_m_m_a_n_d or may follow a _c_o_m_m_a_n_d. Redirections are processed in the or- + der they appear, from left to right. + + Each redirection that may be preceded by a file descriptor number may + instead be preceded by a word of the form {_v_a_r_n_a_m_e}. In this case, for + each redirection operator except >>&&-- and <<&&--, the shell allocates a + file descriptor greater than or equal to 10 and assigns it to _v_a_r_n_a_m_e. + If {_v_a_r_n_a_m_e} precedes >>&&-- or <<&&--, the value of _v_a_r_n_a_m_e defines the file + descriptor to close. If {_v_a_r_n_a_m_e} is supplied, the redirection per- + sists beyond the scope of the command, which allows the shell program- + mer to manage the file descriptor's lifetime manually without using the + eexxeecc builtin. The vvaarrrreeddiirr__cclloossee shell option manages this behavior. + + In the following descriptions, if the file descriptor number is omit- + ted, and the first character of the redirection operator is "<", the + redirection refers to the standard input (file descriptor 0). If the + first character of the redirection operator is ">", the redirection + refers to the standard output (file descriptor 1). + + The _w_o_r_d following the redirection operator in the following descrip- + tions, 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, bbaasshh reports an error. + + The order of redirections is significant. For example, the command + + ls >> dirlist 2>>&&1 + + directs both standard output and standard error to the file _d_i_r_l_i_s_t, + while the command + + ls 2>>&&1 >> dirlist + + directs only the standard output to file _d_i_r_l_i_s_t, because the standard + error was directed to the standard output before the standard output + was redirected to _d_i_r_l_i_s_t. + + BBaasshh handles several filenames specially when they are used in redirec- + tions, as described in the following table. If the operating system on + which bbaasshh is running provides these special files, bbaasshh uses them; + otherwise it emulates them internally with the behavior described be- + low. + + //ddeevv//ffdd//_f_d + If _f_d is a valid integer, duplicate file descriptor _f_d. + //ddeevv//ssttddiinn + File descriptor 0 is duplicated. + //ddeevv//ssttddoouutt + File descriptor 1 is duplicated. + //ddeevv//ssttddeerrrr + File descriptor 2 is duplicated. + //ddeevv//ttccpp//_h_o_s_t//_p_o_r_t + If _h_o_s_t is a valid hostname or Internet address, and _p_o_r_t + is an integer port number or service name, bbaasshh attempts + to open the corresponding TCP socket. + //ddeevv//uuddpp//_h_o_s_t//_p_o_r_t + If _h_o_s_t is a valid hostname or Internet address, and _p_o_r_t + is an integer port number or service name, bbaasshh attempts + to open the corresponding UDP socket. + + A failure to open or create a file causes the redirection to fail. + + Redirections using file descriptors greater than 9 should be used with + care, as they may conflict with file descriptors the shell uses inter- + nally. + + RReeddiirreeccttiinngg IInnppuutt + Redirecting input opens the file whose name results from the expansion + of _w_o_r_d for reading on file descriptor _n, or the standard input (file + descriptor 0) if _n is not specified. + + The general format for redirecting input is: + + [_n]<<_w_o_r_d + + RReeddiirreeccttiinngg OOuuttppuutt + Redirecting output opens the file whose name results from the expansion + of _w_o_r_d for writing on file descriptor _n, or the standard output (file + descriptor 1) if _n is not specified. If the file does not exist it is + created; if it does exist it is truncated to zero size. + + The general format for redirecting output is: + + [_n]>>_w_o_r_d + + If the redirection operator is >>, and the nnoocclloobbbbeerr option to the sseett + builtin command has been enabled, the redirection fails if the file + whose name results from the expansion of _w_o_r_d exists and is a regular + file. If the redirection operator is >>||, or the redirection operator + is >> and the nnoocclloobbbbeerr option to the sseett builtin is not enabled, bbaasshh + attempts the redirection even if the file named by _w_o_r_d exists. + + AAppppeennddiinngg RReeddiirreecctteedd OOuuttppuutt + Redirecting output in this fashion opens the file whose name results + from the expansion of _w_o_r_d for appending on file descriptor _n, or the + standard output (file descriptor 1) if _n is not specified. If the file + does not exist it is created. + + The general format for appending output is: + + [_n]>>>>_w_o_r_d + + RReeddiirreeccttiinngg SSttaannddaarrdd OOuuttppuutt aanndd SSttaannddaarrdd EErrrroorr + This construct redirects both the standard output (file descriptor 1) + and the standard error output (file descriptor 2) to the file whose + name is the expansion of _w_o_r_d. + + There are two formats for redirecting standard output and standard er- + ror: + + &&>>_w_o_r_d + and + >>&&_w_o_r_d + + Of the two forms, the first is preferred. This is semantically equiva- + lent to + + >>_w_o_r_d 2>>&&1 + + When using the second form, _w_o_r_d may not expand to a number or --. If + it does, other redirection operators apply (see DDuupplliiccaattiinngg FFiillee DDee-- + ssccrriippttoorrss below) for compatibility reasons. + + AAppppeennddiinngg SSttaannddaarrdd OOuuttppuutt aanndd SSttaannddaarrdd EErrrroorr + This construct appends both the standard output (file descriptor 1) and + the standard error output (file descriptor 2) to the file whose name is + the expansion of _w_o_r_d. + + The format for appending standard output and standard error is: + + &&>>>>_w_o_r_d + + This is semantically equivalent to + + >>>>_w_o_r_d 2>>&&1 + + (see DDuupplliiccaattiinngg FFiillee DDeessccrriippttoorrss below). + + HHeerree DDooccuummeennttss + This type of redirection instructs the shell to read input from the + current source until it reads a line containing only _d_e_l_i_m_i_t_e_r (with no + trailing blanks). All of the lines read up to that point then become + the standard input (or file descriptor _n if _n is specified) for a com- + mand. + + The format of here-documents is: + + [_n]<<<<[--]_w_o_r_d + _h_e_r_e_-_d_o_c_u_m_e_n_t + _d_e_l_i_m_i_t_e_r + + The shell does not perform parameter and variable expansion, command + substitution, arithmetic expansion, or pathname expansion on _w_o_r_d. + + If any part of _w_o_r_d is quoted, the _d_e_l_i_m_i_t_e_r is the result of quote re- + moval on _w_o_r_d, and the lines in the here-document are not expanded. If + _w_o_r_d is unquoted, the _d_e_l_i_m_i_t_e_r is _w_o_r_d itself, and the here-document + text is treated similarly to a double-quoted string: all lines of the + here-document are subjected to parameter expansion, command substitu- + tion, and arithmetic expansion, the character sequence \\<> is + treated literally, and \\ must be used to quote the characters \\, $$, and + ``; however, double quote characters have no special meaning. + + If the redirection operator is <<<<--, then the shell strips all leading + tab characters from input lines and the line containing _d_e_l_i_m_i_t_e_r. + This allows here-documents within shell scripts to be indented in a + natural fashion. + + If the delimiter is not quoted, the shell treats the \\<> se- + quence as a line continuation: the two lines are joined and the back- + slash-newline is removed. This happens while reading the here-docu- + ment, before the check for the ending delimiter, so joined lines can + form the end delimiter. + + HHeerree SSttrriinnggss + A variant of here documents, the format is: + + [_n]<<<<<<_w_o_r_d + + The _w_o_r_d undergoes tilde expansion, parameter and variable expansion, + command substitution, arithmetic expansion, and quote removal. Path- + name 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 _n if _n is specified). + + DDuupplliiccaattiinngg FFiillee DDeessccrriippttoorrss + The redirection operator + + [_n]<<&&_w_o_r_d + + is used to duplicate input file descriptors. If _w_o_r_d expands to one or + more digits, file descriptor _n is made to be a copy of that file de- + scriptor. It is a redirection error if the digits in _w_o_r_d do not spec- + ify a file descriptor open for input. If _w_o_r_d evaluates to --, file de- + scriptor _n is closed. If _n is not specified, this uses the standard + input (file descriptor 0). + + The operator + + [_n]>>&&_w_o_r_d + + is used similarly to duplicate output file descriptors. If _n is not + specified, this uses the standard output (file descriptor 1). It is a + redirection error if the digits in _w_o_r_d do not specify a file descrip- + tor open for output. If _w_o_r_d evaluates to --, file descriptor _n is + closed. As a special case, if _n is omitted, and _w_o_r_d does not expand + to one or more digits or --, this redirects the standard output and + standard error as described previously. + + MMoovviinngg FFiillee DDeessccrriippttoorrss + The redirection operator + + [_n]<<&&_d_i_g_i_t-- + + moves the file descriptor _d_i_g_i_t to file descriptor _n, or the standard + input (file descriptor 0) if _n is not specified. _d_i_g_i_t is closed after + being duplicated to _n. + + Similarly, the redirection operator + + [_n]>>&&_d_i_g_i_t-- + + moves the file descriptor _d_i_g_i_t to file descriptor _n, or the standard + output (file descriptor 1) if _n is not specified. + + OOppeenniinngg FFiillee DDeessccrriippttoorrss ffoorr RReeaaddiinngg aanndd WWrriittiinngg + The redirection operator + + [_n]<<>>_w_o_r_d + + opens the file whose name is the expansion of _w_o_r_d for both reading and + writing on file descriptor _n, or on file descriptor 0 if _n is not spec- + ified. If the file does not exist, it is created. + +AALLIIAASSEESS + _A_l_i_a_s_e_s allow a string to be substituted for a word that is in a posi- + tion in the input where it can be the first word of a simple command. + Aliases have names and corresponding values that are set and unset us- + ing the aalliiaass and uunnaalliiaass builtin commands (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS + below). + + If the shell reads an unquoted word in the right position, it checks + the word to see if it matches an alias name. If it matches, the shell + replaces the word with the alias value, and reads that value as if it + had been read instead of the word. The shell doesn't look at any char- + acters following the word before attempting alias substitution. + + The characters //, $$, ``, and == and any of the shell _m_e_t_a_c_h_a_r_a_c_t_e_r_s 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 llss to llss --FF, for + instance, and bbaasshh does not try to recursively expand the replacement + text. + + If the last character of the alias value is a _b_l_a_n_k, the shell checks + the next command word following the alias for alias expansion. + + Aliases are created and listed with the aalliiaass command, and removed with + the uunnaalliiaass command. + + There is no mechanism for using arguments in the replacement text. If + arguments are needed, use a shell function (see FFUUNNCCTTIIOONNSS below) in- + stead. + + Aliases are not expanded when the shell is not interactive, unless the + eexxppaanndd__aalliiaasseess shell option is set using sshhoopptt (see the description of + sshhoopptt under SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + + The rules concerning the definition and use of aliases are somewhat + confusing. BBaasshh 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 shell reads the next line of input, and an alias defi- + nition in a compound command does not take effect until the shell + parses and executes the entire compound command. The commands follow- + ing the alias definition on that line, or in the rest of a compound + command, are not affected by the new alias. This behavior is also an + issue when functions are executed. Aliases are expanded when a func- + tion definition is read, not when the function is executed, because a + function definition is itself a command. As a consequence, aliases de- + fined in a function are not available until after that function is exe- + cuted. To be safe, always put alias definitions on a separate line, + and do not use aalliiaass in compound commands. + + For almost every purpose, shell functions are preferable to aliases. + +FFUUNNCCTTIIOONNSS + A shell function, defined as described above under SSHHEELLLL GGRRAAMMMMAARR, + stores a series of commands for later execution. When the name of a + shell function is used as a simple command name, the shell executes the + list of commands associated with that function name. Functions are ex- + ecuted in the context of the calling shell; there is no new process + 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 ## is + updated to reflect the new positional parameters. Special parameter 00 + is unchanged. The first element of the FFUUNNCCNNAAMMEE variable is set to the + name of the function while the function is executing. + + All other aspects of the shell execution environment are identical be- + tween a function and its caller with these exceptions: the DDEEBBUUGG and + RREETTUURRNN traps (see the description of the ttrraapp builtin under SSHHEELLLL + BBUUIILLTTIINN CCOOMMMMAANNDDSS below) are not inherited unless the function has been + given the ttrraaccee attribute (see the description of the ddeeccllaarree builtin + below) or the --oo ffuunnccttrraaccee shell option has been enabled with the sseett + builtin (in which case all functions inherit the DDEEBBUUGG and RREETTUURRNN + traps), and the EERRRR trap is not inherited unless the --oo eerrrrttrraaccee shell + option has been enabled. + + Variables local to the function are declared with the llooccaall builtin + command (_l_o_c_a_l _v_a_r_i_a_b_l_e_s). Ordinarily, variables and their values are + shared between the function and its caller. If a variable is declared + llooccaall, the variable's visible scope is restricted to that function and + its children (including the functions it calls). + + In the following description, the _c_u_r_r_e_n_t _s_c_o_p_e is a currently- execut- + ing 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. A local variable at the current scope is a variable + declared using the llooccaall or ddeeccllaarree builtins in the function that is + currently executing. + + Local variables "shadow" variables with the same name declared at pre- + vious scopes. For instance, a local variable declared in a function + hides variables with the same name declared at previous scopes, includ- + ing global variables: references and assignments refer to the local + variable, leaving the variables at previous scopes unmodified. When + the function returns, the global variable is once again visible. + + The shell uses _d_y_n_a_m_i_c _s_c_o_p_i_n_g 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 exe- + cution 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. + + For example, if a variable _v_a_r is declared as local in function _f_u_n_c_1, + and _f_u_n_c_1 calls another function _f_u_n_c_2, references to _v_a_r made from + within _f_u_n_c_2 resolve to the local variable _v_a_r from _f_u_n_c_1, shadowing + any global variable named _v_a_r. + + The uunnsseett builtin also acts using the same dynamic scope: if a variable + is local to the current scope, uunnsseett unsets 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 remains + so (appearing as unset) until it is reset in that scope or until the + function returns. Once the function returns, any instance of the vari- + able at a previous scope becomes visible. If the unset acts on a vari- + able at a previous scope, any instance of a variable with that name + that had been shadowed becomes visible (see below how the llooccaallvvaarr__uunn-- + sseett shell option changes this behavior). + + The FFUUNNCCNNEESSTT variable, if set to a numeric value greater than 0, de- + fines a maximum function nesting level. Function invocations that ex- + ceed the limit cause the entire command to abort. + + If the builtin command rreettuurrnn is executed in a function, the function + completes and execution resumes with the next command after the func- + tion call. If rreettuurrnn is supplied a numeric argument, that is the func- + tion's return status; otherwise the function's return status is the + exit status of the last command executed before the rreettuurrnn. Any com- + mand associated with the RREETTUURRNN trap is executed before execution re- + sumes. When a function completes, the values of the positional parame- + ters and the special parameter ## are restored to the values they had + prior to the function's execution. + + The --ff option to the ddeeccllaarree or ttyyppeesseett builtin commands lists function + names and definitions. The --FF option to ddeeccllaarree or ttyyppeesseett lists the + function names only (and optionally the source file and line number, if + the eexxttddeebbuugg 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 --ff option to + the eexxppoorrtt builtin. The --ff option to the uunnsseett builtin deletes a func- + tion definition. + + Functions may be recursive. The FFUUNNCCNNEESSTT variable may be used to limit + the depth of the function call stack and restrict the number of func- + tion invocations. By default, bbaasshh imposes no limit on the number of + recursive calls. + +AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN + The shell allows arithmetic expressions to be evaluated, under certain + circumstances (see the lleett and ddeeccllaarree builtin commands, the (((( com- + pound command, the arithmetic ffoorr command, the [[[[ conditional command, + and AArriitthhmmeettiicc EExxppaannssiioonn). + + Evaluation is done in the largest fixed-width integers available, with + no check for overflow, though division by 0 is trapped and flagged as + an error. The operators and their precedence, associativity, and val- + ues 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. + + _i_d++++ _i_d---- + variable post-increment and post-decrement + ++++_i_d ----_i_d + variable pre-increment and pre-decrement + -- ++ unary minus and plus + !! ~~ logical and bitwise negation + **** exponentiation + ** // %% multiplication, division, remainder + ++ -- addition, subtraction + <<<< >>>> left and right bitwise shifts + <<== >>== << >> + comparison + ==== !!== equality and inequality + && bitwise AND + ^^ bitwise exclusive OR + || bitwise OR + &&&& logical AND + |||| logical OR + _e_x_p_r??_e_x_p_r::_e_x_p_r + conditional operator + == **== //== %%== ++== --== <<<<== >>>>== &&== ^^== ||== + assignment + _e_x_p_r_1 ,, _e_x_p_r_2 + comma + + Shell variables are allowed as operands; parameter expansion is per- + formed before the expression is evaluated. Within an expression, shell + variables may also be referenced by name without using the parameter + expansion syntax. This means you can use "x", where _x is a shell vari- + able name, in an arithmetic expression, and the shell will evaluate its + value as an expression and use the result. A shell variable that is + null or unset evaluates to 0 when referenced by name in an expression. + + The value of a variable is evaluated as an arithmetic expression when + it is referenced, or when a variable which has been given the _i_n_t_e_g_e_r + attribute using ddeeccllaarree --ii is assigned a value. A null value evaluates + to 0. A shell variable need not have its _i_n_t_e_g_e_r attribute enabled to + be used in an expression. + + Integer constants follow the C language definition, without suffixes or + character constants. Constants with a leading 0 are interpreted as oc- + tal numbers. A leading 0x or 0X denotes hexadecimal. Otherwise, num- + bers take the form [_b_a_s_e_#]n, where the optional _b_a_s_e is a decimal num- + ber between 2 and 64 representing the arithmetic base, and _n is a num- + ber in that base. If _b_a_s_e_# is omitted, then base 10 is used. When + specifying _n, 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 _b_a_s_e is less than or equal to 36, lowercase and up- + percase letters may be used interchangeably to represent numbers be- + tween 10 and 35. + + Operators are evaluated in precedence order. Sub-expressions in paren- + theses are evaluated first and may override the precedence rules above. + +CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS + Conditional expressions are used by the [[[[ compound command and the + tteesstt and [[ builtin commands to test file attributes and perform string + and arithmetic comparisons. The tteesstt and [[ commands determine their + behavior based on the number of arguments; see the descriptions of + those commands for any other command-specific actions. + + Expressions are formed from the unary or binary primaries listed below. + Unary expressions are often used to examine the status of a file or + shell variable. Binary operators are used for string, numeric, and + file attribute comparisons. + + BBaasshh handles several filenames specially when they are used in expres- + sions. If the operating system on which bbaasshh is running provides these + special files, bash will use them; otherwise it will emulate them in- + ternally with this behavior: If any _f_i_l_e argument to one of the pri- + maries is of the form _/_d_e_v_/_f_d_/_n, then bbaasshh checks file descriptor _n. + If the _f_i_l_e argument to one of the primaries is one of _/_d_e_v_/_s_t_d_i_n, + _/_d_e_v_/_s_t_d_o_u_t, or _/_d_e_v_/_s_t_d_e_r_r, bbaasshh checks file descriptor 0, 1, or 2, + respectively. + + Unless otherwise specified, primaries that operate on files follow sym- + bolic links and operate on the target of the link, rather than the link + itself. + + When used with [[[[, or when the shell is in posix mode, the << and >> op- + erators sort lexicographically using the current locale. When the + shell is not in posix mode, the tteesstt command sorts using ASCII order- + ing. + + --aa _f_i_l_e + True if _f_i_l_e exists. + --bb _f_i_l_e + True if _f_i_l_e exists and is a block special file. + --cc _f_i_l_e + True if _f_i_l_e exists and is a character special file. + --dd _f_i_l_e + True if _f_i_l_e exists and is a directory. + --ee _f_i_l_e + True if _f_i_l_e exists. + --ff _f_i_l_e + True if _f_i_l_e exists and is a regular file. + --gg _f_i_l_e + True if _f_i_l_e exists and is set-group-id. + --hh _f_i_l_e + True if _f_i_l_e exists and is a symbolic link. + --kk _f_i_l_e + True if _f_i_l_e exists and its "sticky" bit is set. + --pp _f_i_l_e + True if _f_i_l_e exists and is a named pipe (FIFO). + --rr _f_i_l_e + True if _f_i_l_e exists and is readable. + --ss _f_i_l_e + True if _f_i_l_e exists and has a size greater than zero. + --tt _f_d True if file descriptor _f_d is open and refers to a terminal. + --uu _f_i_l_e + True if _f_i_l_e exists and its set-user-id bit is set. + --ww _f_i_l_e + True if _f_i_l_e exists and is writable. + --xx _f_i_l_e + True if _f_i_l_e exists and is executable. + --GG _f_i_l_e + True if _f_i_l_e exists and is owned by the effective group id. + --LL _f_i_l_e + True if _f_i_l_e exists and is a symbolic link. + --NN _f_i_l_e + True if _f_i_l_e exists and has been modified since it was last ac- + cessed. + --OO _f_i_l_e + True if _f_i_l_e exists and is owned by the effective user id. + --SS _f_i_l_e + True if _f_i_l_e exists and is a socket. + --oo _o_p_t_n_a_m_e + True if the shell option _o_p_t_n_a_m_e is enabled. See the list of + options under the description of the --oo option to the sseett + builtin below. + --vv _v_a_r_n_a_m_e + True if the shell variable _v_a_r_n_a_m_e is set (has been assigned a + value). If _v_a_r_n_a_m_e is an indexed array variable name sub- + scripted by _@ or _*, this returns true if the array has any set + elements. If _v_a_r_n_a_m_e is an associative array variable name sub- + scripted by _@ or _*, this returns true if an element with that + key is set. + --RR _v_a_r_n_a_m_e + True if the shell variable _v_a_r_n_a_m_e is set and is a name refer- + ence. + --zz _s_t_r_i_n_g + True if the length of _s_t_r_i_n_g is zero. + _s_t_r_i_n_g + --nn _s_t_r_i_n_g + True if the length of _s_t_r_i_n_g is non-zero. + + _s_t_r_i_n_g_1 ==== _s_t_r_i_n_g_2 + _s_t_r_i_n_g_1 == _s_t_r_i_n_g_2 + True if the strings are equal. == should be used with the tteesstt + command for POSIX conformance. When used with the [[[[ command, + this performs pattern matching as described above (CCoommppoouunndd CCoomm-- + mmaannddss). + _s_t_r_i_n_g_1 !!== _s_t_r_i_n_g_2 + True if the strings are not equal. + _s_t_r_i_n_g_1 << _s_t_r_i_n_g_2 + True if _s_t_r_i_n_g_1 sorts before _s_t_r_i_n_g_2 lexicographically. + _s_t_r_i_n_g_1 >> _s_t_r_i_n_g_2 + True if _s_t_r_i_n_g_1 sorts after _s_t_r_i_n_g_2 lexicographically. + + _f_i_l_e_1 --eeff _f_i_l_e_2 + True if _f_i_l_e_1 and _f_i_l_e_2 refer to the same device and inode num- + bers. + _f_i_l_e_1 -nntt _f_i_l_e_2 + True if _f_i_l_e_1 is newer (according to modification date) than + _f_i_l_e_2, or if _f_i_l_e_1 exists and _f_i_l_e_2 does not. + _f_i_l_e_1 -oott _f_i_l_e_2 + True if _f_i_l_e_1 is older than _f_i_l_e_2, or if _f_i_l_e_2 exists and _f_i_l_e_1 + does not. + + _a_r_g_1 OOPP _a_r_g_2 + OOPP is one of --eeqq, --nnee, --lltt, --llee, --ggtt, or --ggee. These arithmetic + binary operators return true if _a_r_g_1 is equal to, not equal to, + less than, less than or equal to, greater than, or greater than + or equal to _a_r_g_2, respectively. _a_r_g_1 and _a_r_g_2 may be positive + or negative integers. When used with the [[[[ command, _a_r_g_1 and + _a_r_g_2 are evaluated as arithmetic expressions (see AARRIITTHHMMEETTIICC + EEVVAALLUUAATTIIOONN above). Since the expansions the [[[[ command performs + on _a_r_g_1 and _a_r_g_2 can potentially result in empty strings, arith- + metic expression evaluation treats those as expressions that + evaluate to 0. + +SSIIMMPPLLEE CCOOMMMMAANNDD EEXXPPAANNSSIIOONN + When the shell executes a simple command, it performs the following ex- + pansions, assignments, and redirections, from left to right, in the + following order. + + 1. The words that the parser has marked as variable assignments + (those preceding the command name) and redirections are saved + for later processing. + + 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. + + 3. Redirections are performed as described above under RREEDDIIRREECCTTIIOONN. + + 4. The text after the == in each variable assignment undergoes tilde + expansion, parameter expansion, command substitution, arithmetic + expansion, and quote removal before being assigned to the vari- + able. + + 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 cur- + rent 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. + + If no command name results, redirections are performed, but do not af- + fect the current shell environment. A redirection error causes the + command to exit with a non-zero status. + + If there is a command name left after expansion, execution proceeds as + described below. Otherwise, the command exits. If one of the expan- + sions 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 zero sta- + tus. + +CCOOMMMMAANNDD EEXXEECCUUTTIIOONN + After a command has been split into words, if it results in a simple + command and an optional list of arguments, the shell performs the fol- + lowing actions. + + 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 FFUUNNCCTTIIOONNSS. 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. + + If the name is neither a shell function nor a builtin, and contains no + slashes, bbaasshh searches each element of the PPAATTHH for a directory con- + taining an executable file by that name. BBaasshh uses a hash table to re- + member the full pathnames of executable files (see hhaasshh under SSHHEELLLL + BBUUIILLTTIINN CCOOMMMMAANNDDSS below). Bash performs a full search of the directo- + ries in PPAATTHH 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 ccoommmmaanndd__nnoott__ffoouunndd__hhaannddllee. If that function exists, it + is invoked in a separate execution environment with the original com- + mand 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 re- + turns an exit status of 127. + + If the search is successful, or if the command name contains one or + more slashes, the shell executes the named program in a separate execu- + tion environment. Argument 0 is set to the name given, and the remain- + ing arguments to the command are set to the arguments given, if any. + + 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 _s_h_e_l_l _s_c_r_i_p_t, a + file containing shell commands, and the shell creates a new instance of + itself to execute it. Bash tries to determine whether the file is a + text file or a binary, and will not execute files it determines to be + binaries. This subshell reinitializes itself, so that the effect is as + if a new shell had been invoked to handle the script, with the excep- + tion that the locations of commands remembered by the parent (see hhaasshh + below under SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS are retained by the child. + + If the program is a file beginning with ##!!, 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 exe- + cutable 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. + +CCOOMMMMAANNDD EEXXEECCUUTTIIOONN EENNVVIIRROONNMMEENNTT + The shell has an _e_x_e_c_u_t_i_o_n _e_n_v_i_r_o_n_m_e_n_t, which consists of the follow- + ing: + + +o Open files inherited by the shell at invocation, as modified by + redirections supplied to the eexxeecc builtin. + + +o The current working directory as set by ccdd, ppuusshhdd, or ppooppdd, or + inherited by the shell at invocation. + + +o The file creation mode mask as set by uummaasskk or inherited from + the shell's parent. + + +o Current traps set by ttrraapp. + + +o Shell parameters that are set by variable assignment or with sseett + or inherited from the shell's parent in the environment. + + +o Shell functions defined during execution or inherited from the + shell's parent in the environment. + + +o Options enabled at invocation (either by default or with com- + mand-line arguments) or by sseett. + + +o Options enabled by sshhoopptt. + + +o Shell aliases defined with aalliiaass. + + +o Various process IDs, including those of background jobs, the + value of $$$$, and the value of PPPPIIDD. + + When a simple command other than a builtin or shell function is to be + executed, it is invoked in a separate execution environment that con- + sists of the following. Unless otherwise noted, the values are inher- + ited from the shell. + + +o The shell's open files, plus any modifications and additions + specified by redirections to the command. + + +o The current working directory. + + +o The file creation mode mask. + + +o Shell variables and functions marked for export, along with + variables exported for the command, passed in the environment. + + +o Traps caught by the shell are reset to the values inherited from + the shell's parent, and traps ignored by the shell are ignored. + + A command invoked in this separate environment cannot affect the + shell's execution environment. + + A _s_u_b_s_h_e_l_l is a copy of the shell process. + + Command substitution, commands grouped with parentheses, and asynchro- + nous commands are invoked in a subshell environment that is a duplicate + of the shell environment, except that traps caught by the shell are re- + set to the values that the shell inherited from its parent at invoca- + tion. Builtin commands that are invoked as part of a pipeline, except + possibly in the last element depending on the value of the llaassttppiippee + shell option, are also executed in a subshell environment. Changes + made to the subshell environment cannot affect the shell's execution + environment. + + When the shell is in posix mode, subshells spawned to execute command + substitutions inherit the value of the --ee option from their parent + shell. When not in posix mode, bbaasshh clears the --ee option in such sub- + shells. See the description of the iinnhheerriitt__eerrrreexxiitt shell option below + for how to control this behavior when not in posix mode. + + If a command is followed by a && and job control is not active, the de- + fault standard input for the command is the empty file _/_d_e_v_/_n_u_l_l. Oth- + erwise, the invoked command inherits the file descriptors of the call- + ing shell as modified by redirections. + +EENNVVIIRROONNMMEENNTT + When a program is invoked it is given an array of strings called the + _e_n_v_i_r_o_n_m_e_n_t. This is a list of _n_a_m_e-_v_a_l_u_e pairs, of the form + _n_a_m_e=_v_a_l_u_e. + + The shell provides several ways to manipulate the environment. On in- + vocation, the shell scans its own environment and creates a parameter + for each name found, automatically marking it for _e_x_p_o_r_t to child + processes. Executed commands inherit the environment. The eexxppoorrtt, ddee-- + ccllaarree --xx, and uunnsseett commands modify the environment by adding and + deleting parameters and functions. If the value of a parameter in the + environment is modified, the new value automatically 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 uunn-- + sseett or eexxppoorrtt --nn commands, plus any additions via the eexxppoorrtt and ddee-- + ccllaarree --xx commands. + + If any parameter assignments, as described above in PPAARRAAMMEETTEERRSS, appear + before a _s_i_m_p_l_e _c_o_m_m_a_n_d, the variable assignments are part of that com- + mand's environment for as long as it executes. These assignment state- + ments affect only the environment seen by that command. If these as- + signments precede a call to a shell function, the variables are local + to the function and exported to that function's children. + + If the --kk option is set (see the sseett builtin command below), then _a_l_l + parameter assignments are placed in the environment for a command, not + just those that precede the command name. + + When bbaasshh invokes an external command, the variable __ is set to the + full pathname of the command and passed to that command in its environ- + ment. + +EEXXIITT SSTTAATTUUSS + The exit status of an executed command is the value returned by the + _w_a_i_t_p_i_d 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. + + For the shell's purposes, a command which exits with a zero exit status + has succeeded. So while an exit status of zero indicates success, a + non-zero exit status indicates failure. + + When a command terminates on a fatal signal _N, bbaasshh uses the value of + 128+_N as the exit status. + + If a command is not found, the child process created to execute it re- + turns a status of 127. If a command is found but is not executable, + the return status is 126. + + If a command fails because of an error during expansion or redirection, + the exit status is greater than zero. + + Shell builtin commands return a status of 0 (_t_r_u_e) if successful, and + non-zero (_f_a_l_s_e) if an error occurs while they execute. All builtins + return an exit status of 2 to indicate incorrect usage, generally in- + valid options or missing arguments. + + The exit status of the last command is available in the special parame- + ter $?. + + BBaasshh itself returns the exit status of the last command executed, un- + less a syntax error occurs, in which case it exits with a non-zero + value. See also the eexxiitt builtin command below. + +SSIIGGNNAALLSS + When bbaasshh is interactive, in the absence of any traps, it ignores + SSIIGGTTEERRMM (so that kkiillll 00 does not kill an interactive shell), and + catches and handles SSIIGGIINNTT (so that the wwaaiitt builtin is interruptible). + When bbaasshh receives SSIIGGIINNTT, it breaks out of any executing loops. In + all cases, bbaasshh ignores SSIIGGQQUUIITT. If job control is in effect, bbaasshh ig- + nores SSIIGGTTTTIINN, SSIIGGTTTTOOUU, and SSIIGGTTSSTTPP. + + The ttrraapp builtin modifies the shell's signal handling, as described be- + low. + + Non-builtin commands bbaasshh executes have signal handlers set to the val- + ues inherited by the shell from its parent, unless ttrraapp sets them to be + ignored, in which case the child process will ignore them as well. + When job control is not in effect, asynchronous commands ignore SSIIGGIINNTT + and SSIIGGQQUUIITT in addition to these inherited handlers. Commands run as a + result of command substitution ignore the keyboard-generated job con- + trol signals SSIIGGTTTTIINN, SSIIGGTTTTOOUU, and SSIIGGTTSSTTPP. + + The shell exits by default upon receipt of a SSIIGGHHUUPP. Before exiting, + an interactive shell resends the SSIIGGHHUUPP to all jobs, running or + stopped. The shell sends SSIIGGCCOONNTT to stopped jobs to ensure that they + receive the SSIIGGHHUUPP (see JJOOBB CCOONNTTRROOLL below for more information about + running and stopped jobs). To prevent the shell from sending the sig- + nal to a particular job, remove it from the jobs table with the ddiissoowwnn + builtin (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below) or mark it not to receive + SSIIGGHHUUPP using ddiissoowwnn --hh. + + If the hhuuppoonneexxiitt shell option has been set using sshhoopptt, bbaasshh sends a + SSIIGGHHUUPP to all jobs when an interactive login shell exits. + + If bbaasshh is waiting for a command to complete and receives a signal for + which a trap has been set, it will not execute the trap until the com- + mand completes. If bbaasshh is waiting for an asynchronous command via the + wwaaiitt builtin, and it receives a signal for which a trap has been set, + the wwaaiitt builtin will return immediately with an exit status greater + than 128, immediately after which the shell executes the trap. + + When job control is not enabled, and bbaasshh is waiting for a foreground + command to complete, the shell receives keyboard-generated signals such + as SSIIGGIINNTT (usually generated by ^^CC) 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 ^^CC sends SSIIGGIINNTT to all + processes in that process group. Since bbaasshh does not enable job con- + trol by default when the shell is not interactive, this scenario is + most common in non-interactive shells. + + When job control is enabled, and bbaasshh is waiting for a foreground com- + mand to complete, the shell does not receive keyboard-generated sig- + nals, because it is not in the same process group as the terminal. + This scenario is most common in interactive shells, where bbaasshh attempts + to enable job control by default. See JJOOBB CCOONNTTRROOLL below for more in- + formation about process groups. + + When job control is not enabled, and bbaasshh receives SSIIGGIINNTT while waiting + for a foreground command, it waits until that foreground command termi- + nates and then decides what to do about the SSIIGGIINNTT: + + 1. If the command terminates due to the SSIIGGIINNTT, bbaasshh concludes that + the user meant to send the SSIIGGIINNTT to the shell as well, and acts + on the SSIIGGIINNTT (e.g., by running a SSIIGGIINNTT trap, exiting a non-in- + teractive shell, or returning to the top level to read a new + command). + + 2. If the command does not terminate due to SSIIGGIINNTT, the program + handled the SSIIGGIINNTT itself and did not treat it as a fatal sig- + nal. In that case, bbaasshh does not treat SSIIGGIINNTT as a fatal sig- + nal, either, instead assuming that the SSIIGGIINNTT was used as part + of the program's normal operation (e.g., emacs uses it to abort + editing commands) or deliberately discarded. However, bbaasshh will + run any trap set on SSIIGGIINNTT, as it does with any other trapped + signal it receives while it is waiting for the foreground com- + mand to complete, for compatibility. + + When job control is enabled, bbaasshh does not receive keyboard-generated + signals such as SSIIGGIINNTT while it is waiting for a foreground command. + An interactive shell does not pay attention to the SSIIGGIINNTT, even if the + foreground command terminates as a result, other than noting its exit + status. If the shell is not interactive, and the foreground command + terminates due to the SSIIGGIINNTT, bbaasshh pretends it received the SSIIGGIINNTT it- + self (scenario 1 above), for compatibility. + +JJOOBB CCOONNTTRROOLL + _J_o_b _c_o_n_t_r_o_l refers to the ability to selectively stop (_s_u_s_p_e_n_d) the ex- + ecution of processes and continue (_r_e_s_u_m_e) their execution at a later + point. A user typically employs this facility via an interactive in- + terface supplied jointly by the operating system kernel's terminal dri- + ver and bbaasshh. + + The shell associates a _j_o_b with each pipeline. It keeps a table of + currently executing jobs, which the jjoobbss command will display. Each + job has a _j_o_b _n_u_m_b_e_r, which jjoobbss displays between brackets. Job num- + bers start at 1. When bbaasshh starts a job asynchronously (in the _b_a_c_k_- + _g_r_o_u_n_d), it prints a line that looks like: + + [1] 25647 + + 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. BBaasshh + uses the _j_o_b abstraction as the basis for job control. + + To facilitate the implementation of the user interface to job control, + each process has a _p_r_o_c_e_s_s _g_r_o_u_p _I_D, and the operating system maintains + the notion of a _c_u_r_r_e_n_t _t_e_r_m_i_n_a_l _p_r_o_c_e_s_s _g_r_o_u_p _I_D. This terminal + process group ID is associated with the _c_o_n_t_r_o_l_l_i_n_g _t_e_r_m_i_n_a_l. + + Processes that have the same process group ID are said to be part of + the same _p_r_o_c_e_s_s _g_r_o_u_p. Members of the _f_o_r_e_g_r_o_u_n_d process group + (processes whose process group ID is equal to the current terminal + process group ID) receive keyboard-generated signals such as SSIIGGIINNTT. + Processes in the foreground process group are said to be _f_o_r_e_g_r_o_u_n_d + processes. _B_a_c_k_g_r_o_u_n_d processes are those whose process group ID dif- + fers from the controlling terminal's; such processes are immune to key- + board-generated signals. Only foreground processes are allowed to read + from or, if the user so specifies with "stty tostop", write to the con- + trolling terminal. The system sends a SSIIGGTTTTIINN ((SSIIGGTTTTOOUU)) signal to + background processes which attempt to read from (write to when "tostop" + is in effect) the terminal, which, unless caught, suspends the process. + + If the operating system on which bbaasshh is running supports job control, + bbaasshh contains facilities to use it. Typing the _s_u_s_p_e_n_d character (typ- + ically ^^ZZ, Control-Z) while a process is running stops that process and + returns control to bbaasshh. Typing the _d_e_l_a_y_e_d _s_u_s_p_e_n_d character (typi- + cally ^^YY, Control-Y) causes the process stop when it attempts to read + input from the terminal, and returns control to bbaasshh. The user then + manipulates the state of this job, using the bbgg command to continue it + in the background, the ffgg command to continue it in the foreground, or + the kkiillll command to kill it. The suspend character takes effect imme- + diately, and has the additional side effect of discarding any pending + output and typeahead. To force a background process to stop, or stop a + process that's not associated with the current terminal session, send + it the SSIIGGSSTTOOPP signal using kkiillll. + + There are a number of ways to refer to a job in the shell. The %% char- + acter introduces a job specification (jobspec). + + Job number _n may be referred to as %%nn. 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, %%ccee refers to a job whose + command name begins with ccee. Using %%??ccee, on the other hand, refers to + any job containing the string ccee in its command line. If the prefix or + substring matches more than one job, bbaasshh reports an error. + + The symbols %%%% and %%++ refer to the shell's notion of the _c_u_r_r_e_n_t _j_o_b. + A single % (with no accompanying job specification) also refers to the + current job. %%-- refers to the _p_r_e_v_i_o_u_s _j_o_b. When a job starts in the + background, a job stops while in the foreground, or a job is resumed in + the background, it becomes the current job. The job that was the cur- + rent job becomes the previous job. When the current job terminates, + the previous job becomes the current job. If there is only a single + job, %%++ and %%-- can both be used to refer to that job. In output per- + taining to jobs (e.g., the output of the jjoobbss command), the current job + is always marked with a ++, and the previous job with a --. + + Simply naming a job can be used to bring it into the foreground: %%11 is + a synonym for "fg %1", bringing job 1 from the background into the + foreground. Similarly, "%1 &" resumes job 1 in the background, equiva- + lent to "bg %1". + + The shell learns immediately whenever a job changes state. Normally, + bbaasshh waits until it is about to print a prompt before notifying the + user about changes in a job's status so as to not interrupt any other + output, though it will notify of changes in a job's status after a + foreground command in a list completes, before executing the next com- + mand in the list. If the --bb option to the sseett builtin command is en- + abled, bbaasshh reports status changes immediately. BBaasshh executes any trap + on SSIIGGCCHHLLDD for each child that terminates. + + When a job terminates and bbaasshh notifies the user about it, bbaasshh removes + the job from the table. It will not appear in jjoobbss output, but wwaaiitt + will report its exit status, as long as it's supplied the process ID + associated with the job as an argument. When the table is empty, job + numbers start over at 1. + + If a user attempts to exit bbaasshh while jobs are stopped (or, if the + cchheecckkjjoobbss shell option has been enabled using the sshhoopptt builtin, run- + ning), the shell prints a warning message, and, if the cchheecckkjjoobbss option + is enabled, lists the jobs and their statuses. The jjoobbss command may + then be used to inspect their status. If the user immediately attempts + to exit again, without an intervening command, bbaasshh does not print an- + other warning, and terminates any stopped jobs. + + When the shell is waiting for a job or process using the wwaaiitt builtin, + and job control is enabled, wwaaiitt will return when the job changes + state. The --ff option causes wwaaiitt to wait until the job or process ter- + minates before returning. + +PPRROOMMPPTTIINNGG + When executing interactively, bbaasshh displays the primary prompt PPSS11 when + it is ready to read a command, and the secondary prompt PPSS22 when it + needs more input to complete a command. + + BBaasshh examines the value of the array variable PPRROOMMPPTT__CCOOMMMMAANNDD just be- + fore printing each primary prompt. If any elements in PPRROOMMPPTT__CCOOMMMMAANNDD + are set and non-null, Bash executes each value, in numeric order, just + as if it had been typed on the command line. BBaasshh displays PPSS00 after + it reads a command but before executing it. + + BBaasshh displays PPSS44 as described above before tracing each command when + the --xx option is enabled. + + BBaasshh allows the prompt strings PPSS00, PPSS11, PPSS22, and PPSS44, to be customized + by inserting a number of backslash-escaped special characters that are + decoded as follows: + + \\aa An ASCII bell character (07). + \\dd The date in "Weekday Month Date" format (e.g., "Tue May + 26"). + \\DD{{_f_o_r_m_a_t}} + The _f_o_r_m_a_t is passed to _s_t_r_f_t_i_m_e(3) and the result is in- + serted into the prompt string; an empty _f_o_r_m_a_t results in + a locale-specific time representation. The braces are + required. + \\ee An ASCII escape character (033). + \\hh The hostname up to the first ".". + \\HH The hostname. + \\jj The number of jobs currently managed by the shell. + \\ll The basename of the shell's terminal device name (e.g., + "ttys0"). + \\nn A newline. + \\rr A carriage return. + \\ss The name of the shell: the basename of $$00 (the portion + following the final slash). + \\tt The current time in 24-hour HH:MM:SS format. + \\TT The current time in 12-hour HH:MM:SS format. + \\@@ The current time in 12-hour am/pm format. + \\AA The current time in 24-hour HH:MM format. + \\uu The username of the current user. + \\vv The bbaasshh version (e.g., 2.00). + \\VV The bbaasshh release, version + patch level (e.g., 2.00.0) + \\ww The value of the PPWWDD shell variable ($$PPWWDD), with $$HHOOMMEE + abbreviated with a tilde (uses the value of the + PPRROOMMPPTT__DDIIRRTTRRIIMM variable). + \\WW The basename of $$PPWWDD, with $$HHOOMMEE abbreviated with a + tilde. + \\!! The history number of this command. + \\## The command number of this command. + \\$$ If the effective UID is 0, a ##, otherwise a $$. + \\_n_n_n The character corresponding to the octal number _n_n_n. + \\\\ A backslash. + \\[[ Begin a sequence of non-printing characters, which could + be used to embed a terminal control sequence into the + prompt. + \\]] End a sequence of non-printing characters. + + 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 HHIISSTTOORRYY be- + low), while the command number is the position in the sequence of com- + mands 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 + pprroommppttvvaarrss shell option (see the description of the sshhoopptt command under + SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). This can have unwanted side effects if + escaped portions of the string appear within command substitution or + contain characters special to word expansion. + +RREEAADDLLIINNEE + This is the library that handles reading input when using an interac- + tive shell, unless the ----nnooeeddiittiinngg option is supplied at shell invoca- + tion. Line editing is also used when using the --ee option to the rreeaadd + builtin. By default, the line editing commands are similar to those of + emacs; a vi-style line editing interface is also available. Line edit- + ing can be enabled at any time using the --oo eemmaaccss or --oo vvii options to + the sseett builtin (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). To turn off line + editing after the shell is running, use the ++oo eemmaaccss or ++oo vvii options + to the sseett builtin. + + RReeaaddlliinnee NNoottaattiioonn + This section uses Emacs-style editing concepts and uses its notation + for keystrokes. Control keys are denoted by C-_k_e_y, e.g., C-n means + Control-N. Similarly, _m_e_t_a keys are denoted by M-_k_e_y, so M-x means + Meta-X. The Meta key is often labeled "Alt" or "Option". + + On keyboards without a _M_e_t_a key, M-_x means ESC _x, i.e., press and re- + lease the Escape key, then press and release the _x key, in sequence. + This makes ESC the _m_e_t_a _p_r_e_f_i_x. The combination M-C-_x means ESC Con- + trol-_x: press and release the Escape key, then press and hold the Con- + trol key while pressing the _x key, then release both. + + On some keyboards, the Meta key modifier produces characters with the + eighth bit (0200) set. You can use the eennaabbllee--mmeettaa--kkeeyy variable to + control whether or not it does this, if the keyboard allows it. On + many others, the terminal or terminal emulator converts the metafied + key to a key sequence beginning with ESC as described in the preceding + paragraph. + + If your _M_e_t_a key produces a key sequence with the ESC meta prefix, you + can make M-_k_e_y key bindings you specify (see RReeaaddlliinnee KKeeyy BBiinnddiinnggss be- + low) do the same thing by setting the ffoorrccee--mmeettaa--pprreeffiixx variable. + + RReeaaddlliinnee commands may be given numeric _a_r_g_u_m_e_n_t_s, 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., kkiillll--lliinnee) makes that command act + in a backward direction. Commands whose behavior with arguments devi- + ates from this are noted below. + + The _p_o_i_n_t is the current cursor position, and _m_a_r_k refers to a saved + cursor position. The text between the point and mark is referred to as + the _r_e_g_i_o_n. RReeaaddlliinnee has the concept of an _a_c_t_i_v_e _r_e_g_i_o_n: when the re- + gion is active, rreeaaddlliinnee redisplay highlights the region using the + value of the aaccttiivvee--rreeggiioonn--ssttaarrtt--ccoolloorr variable. The eennaabbllee--aaccttiivvee--rree-- + ggiioonn variable turns this on and off. Several commands set the region + to active; those are noted below. + + When a command is described as _k_i_l_l_i_n_g text, the text deleted is saved + for possible future retrieval (_y_a_n_k_i_n_g). The killed text is saved in a + _k_i_l_l _r_i_n_g. Consecutive kills accumulate the deleted text 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. + + RReeaaddlliinnee IInniittiiaalliizzaattiioonn + RReeaaddlliinnee is customized by putting commands in an initialization file + (the _i_n_p_u_t_r_c file). The name of this file is taken from the value of + the IINNPPUUTTRRCC shell variable. If that variable is unset, the default is + _~_/_._i_n_p_u_t_r_c. If that file does not exist or cannot be read, rreeaaddlliinnee + looks for _/_e_t_c_/_i_n_p_u_t_r_c. When a program that uses the rreeaaddlliinnee library + starts up, rreeaaddlliinnee reads the initialization file and sets the key + bindings and variables found there, before reading any user input. + + There are only a few basic constructs allowed in the inputrc file. + Blank lines are ignored. Lines beginning with a ## are comments. Lines + beginning with a $$ indicate conditional constructs. Other lines denote + key bindings and variable settings. + + The default key-bindings in this section may be changed using key bind- + ing commands in the _i_n_p_u_t_r_c file. Programs that use the rreeaaddlliinnee li- + brary, including bbaasshh, may add their own commands and bindings. + + For example, placing + + M-Control-u: universal-argument + or + C-Meta-u: universal-argument + + into the _i_n_p_u_t_r_c would make M-C-u execute the rreeaaddlliinnee command _u_n_i_v_e_r_- + _s_a_l_-_a_r_g_u_m_e_n_t. + + Key bindings may contain the following symbolic character names: _D_E_L, + _E_S_C, _E_S_C_A_P_E, _L_F_D, _N_E_W_L_I_N_E, _R_E_T, _R_E_T_U_R_N, _R_U_B_O_U_T (a destructive back- + space), _S_P_A_C_E, _S_P_C, and _T_A_B. + + In addition to command names, rreeaaddlliinnee allows keys to be bound to a + string that is inserted when the key is pressed (a _m_a_c_r_o). The differ- + ence between a macro and a command is that a macro is enclosed in sin- + gle or double quotes. + + RReeaaddlliinnee KKeeyy BBiinnddiinnggss + The syntax for controlling key bindings in the _i_n_p_u_t_r_c 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 key sequence may + be specified in one of two ways: as a symbolic key name, possibly with + _M_e_t_a_- or _C_o_n_t_r_o_l_- prefixes, or as a key sequence composed of one or + more characters enclosed in double quotes. The key sequence and name + are separated by a colon. There can be no whitespace between the name + and the colon. + + When using the form kkeeyynnaammee:_f_u_n_c_t_i_o_n_-_n_a_m_e or _m_a_c_r_o, _k_e_y_n_a_m_e is the name + of a key spelled out in English. For example: + + Control-u: universal-argument + Meta-Rubout: backward-kill-word + Control-o: "> output" + + In the above example, _C_-_u is bound to the function uunniivveerrssaall--aarrgguummeenntt, + _M_-_D_E_L is bound to the function bbaacckkwwaarrdd--kkiillll--wwoorrdd, and _C_-_o is bound to + run the macro expressed on the right hand side (that is, to insert the + text "> output" into the line). + + In the second form, ""kkeeyysseeqq"":_f_u_n_c_t_i_o_n_-_n_a_m_e or _m_a_c_r_o, kkeeyysseeqq differs + from kkeeyynnaammee 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 + none of the symbolic character names are recognized. + + "\C-u": universal-argument + "\C-x\C-r": re-read-init-file + "\e[11~": "Function Key 1" + + In this example, _C_-_u is again bound to the function uunniivveerrssaall--aarrgguummeenntt. + _C_-_x _C_-_r is bound to the function rree--rreeaadd--iinniitt--ffiillee, and _E_S_C _[ _1 _1 _~ is + bound to insert the text "Function Key 1". + + The full set of GNU Emacs style escape sequences available when speci- + fying key sequences is + \\CC-- A control prefix. + \\MM-- Adding the meta prefix or converting the following char- + acter to a meta character, as described below under + ffoorrccee--mmeettaa--pprreeffiixx. + \\ee An escape character. + \\\\ Backslash. + \\"" Literal ", a double quote. + \\'' Literal ', a single quote. + + In addition to the GNU Emacs style escape sequences, a second set of + backslash escapes is available: + \\aa alert (bell) + \\bb backspace + \\dd delete + \\ff form feed + \\nn newline + \\rr carriage return + \\tt horizontal tab + \\vv vertical tab + \\_n_n_n The eight-bit character whose value is the octal value + _n_n_n (one to three digits). + \\xx_H_H The eight-bit character whose value is the hexadecimal + value _H_H (one or two hex digits). + + 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 func- + tion name. The backslash escapes described above are expanded in the + macro body. Backslash quotes any other character in the macro text, + including " and '. + + BBaasshh will display or modify the current rreeaaddlliinnee key bindings with the + bbiinndd builtin command. The --oo eemmaaccss or --oo vvii options to the sseett builtin + (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below) change the editing mode during in- + teractive use. + + RReeaaddlliinnee VVaarriiaabblleess + RReeaaddlliinnee has variables that can be used to further customize its behav- + ior. A variable may be set in the _i_n_p_u_t_r_c file with a statement of the + form + + sseett _v_a_r_i_a_b_l_e_-_n_a_m_e _v_a_l_u_e + or using the bbiinndd builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + + Except where noted, rreeaaddlliinnee variables can take the values OOnn or OOffff + (without regard to case). Unrecognized variable names are ignored. + When rreeaaddlliinnee reads a variable value, empty or null values, "on" (case- + insensitive), and "1" are equivalent to OOnn. All other values are + equivalent to OOffff. + + The bbiinndd --VV command lists the current rreeaaddlliinnee variable names and val- + ues (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). + + The variables and their default values are: + + aaccttiivvee--rreeggiioonn--ssttaarrtt--ccoolloorr + A string variable that controls the text color and background + when displaying the text in the active region (see the descrip- + tion of eennaabbllee--aaccttiivvee--rreeggiioonn 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 ter- + minfo description. A sample value might be "\e[01;33m". + aaccttiivvee--rreeggiioonn--eenndd--ccoolloorr + A string variable that "undoes" the effects of aaccttiivvee--rree-- + ggiioonn--ssttaarrtt--ccoolloorr and restores "normal" terminal display appear- + ance after displaying text in the active region. This string + must not take up any physical character positions on the dis- + play, 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 ob- + tained from the terminal's terminfo description. A sample value + might be "\e[0m". + bbeellll--ssttyyllee ((aauuddiibbllee)) + Controls what happens when rreeaaddlliinnee wants to ring the terminal + bell. If set to nnoonnee, rreeaaddlliinnee never rings the bell. If set to + vviissiibbllee, rreeaaddlliinnee uses a visible bell if one is available. If + set to aauuddiibbllee, rreeaaddlliinnee attempts to ring the terminal's bell. + bbiinndd--ttttyy--ssppeecciiaall--cchhaarrss ((OOnn)) + If set to OOnn, rreeaaddlliinnee attempts to bind the control characters + that are treated specially by the kernel's terminal driver to + their rreeaaddlliinnee equivalents. These override the default rreeaaddlliinnee + bindings described here. Type "stty -a" at a bbaasshh prompt to see + your current terminal settings, including the special control + characters (usually cccchhaarrss). This binding takes place on each + call to rreeaaddlliinnee, so changes made by "stty" can take effect. + bblliinnkk--mmaattcchhiinngg--ppaarreenn ((OOffff)) + If set to OOnn, rreeaaddlliinnee attempts to briefly move the cursor to an + opening parenthesis when a closing parenthesis is inserted. + ccoolloorreedd--ccoommpplleettiioonn--pprreeffiixx ((OOffff)) + If set to OOnn, when listing completions, rreeaaddlliinnee displays the + common prefix of the set of possible completions using a differ- + ent color. The color definitions are taken from the value of + the LLSS__CCOOLLOORRSS environment variable. If there is a color defini- + tion in $$LLSS__CCOOLLOORRSS for the custom suffix ".readline-colored-com- + pletion-prefix", rreeaaddlliinnee uses this color for the common prefix + instead of its default. + ccoolloorreedd--ssttaattss ((OOffff)) + If set to OOnn, rreeaaddlliinnee displays possible completions using dif- + ferent colors to indicate their file type. The color defini- + tions are taken from the value of the LLSS__CCOOLLOORRSS environment + variable. + ccoommmmeenntt--bbeeggiinn (("##")) + The string that the rreeaaddlliinnee iinnsseerrtt--ccoommmmeenntt command inserts. + This command is bound to MM--## in emacs mode and to ## in vi com- + mand mode. + ccoommpplleettiioonn--ddiissppllaayy--wwiiddtthh ((--11)) + 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 + causes matches to be displayed one per line. The default value + is -1. + ccoommpplleettiioonn--iiggnnoorree--ccaassee ((OOffff)) + If set to OOnn, rreeaaddlliinnee performs filename matching and completion + in a case-insensitive fashion. + ccoommpplleettiioonn--mmaapp--ccaassee ((OOffff)) + If set to OOnn, and ccoommpplleettiioonn--iiggnnoorree--ccaassee is enabled, rreeaaddlliinnee + treats hyphens (_-) and underscores (__) as equivalent when per- + forming case-insensitive filename matching and completion. + ccoommpplleettiioonn--pprreeffiixx--ddiissppllaayy--lleennggtthh ((00)) + The maximum 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, rreeaaddlliinnee replaces common + prefixes longer than this value with an ellipsis when displaying + possible completions. If a completion begins with a period, and + eeaaddlliinnee is completing filenames, it uses three underscores in- + stead of an ellipsis. + ccoommpplleettiioonn--qquueerryy--iitteemmss ((110000)) + This determines when the user is queried about viewing the num- + ber of possible completions generated by the ppoossssiibbllee--ccoommppllee-- + ttiioonnss 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, rreeaaddlliinnee + asks whether or not the user wishes to view them; otherwise + rreeaaddlliinnee simply lists them on the terminal. A zero value means + rreeaaddlliinnee should never ask; negative values are treated as zero. + ccoonnvveerrtt--mmeettaa ((OOnn)) + If set to OOnn, rreeaaddlliinnee converts characters it reads that have + the eighth bit set to an ASCII key sequence by clearing the + eighth bit and prefixing it with an escape character (converting + the character to have the meta prefix). The default is _O_n, but + rreeaaddlliinnee sets it to _O_f_f if the locale contains characters whose + encodings may include bytes with the eighth bit set. This vari- + able is dependent on the LLCC__CCTTYYPPEE locale category, and may + change if the locale changes. This variable also affects key + bindings; see the description of ffoorrccee--mmeettaa--pprreeffiixx below. + ddiissaabbllee--ccoommpplleettiioonn ((OOffff)) + If set to OOnn, rreeaaddlliinnee inhibits word completion. Completion + characters are inserted into the line as if they had been mapped + to sseellff--iinnsseerrtt. + eecchhoo--ccoonnttrrooll--cchhaarraacctteerrss ((OOnn)) + When set to OOnn, on operating systems that indicate they support + it, rreeaaddlliinnee echoes a character corresponding to a signal gener- + ated from the keyboard. + eeddiittiinngg--mmooddee ((eemmaaccss)) + Controls whether rreeaaddlliinnee uses a set of key bindings similar to + _E_m_a_c_s or _v_i. eeddiittiinngg--mmooddee can be set to either eemmaaccss or vvii. + eemmaaccss--mmooddee--ssttrriinngg ((@@)) + If the _s_h_o_w_-_m_o_d_e_-_i_n_-_p_r_o_m_p_t 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. The \1 and \2 es- + capes begin and end sequences of non-printing characters, which + can be used to embed a terminal control sequence into the mode + string. + eennaabbllee--aaccttiivvee--rreeggiioonn ((OOnn)) + When this variable is set to _O_n, rreeaaddlliinnee allows certain com- + mands to designate the region as _a_c_t_i_v_e. When the region is ac- + tive, rreeaaddlliinnee highlights the text in the region using the value + of the aaccttiivvee--rreeggiioonn--ssttaarrtt--ccoolloorr variable, which defaults to the + string that enables the terminal's standout mode. The active + region shows the text inserted by bracketed-paste and any match- + ing text found by incremental and non-incremental history + searches. + eennaabbllee--bbrraacckkeetteedd--ppaassttee ((OOnn)) + When set to OOnn, rreeaaddlliinnee 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 is called _b_r_a_c_k_e_t_e_d_-_p_a_s_t_e _m_o_d_e; it prevents + rreeaaddlliinnee from executing any editing commands bound to key se- + quences appearing in the pasted text. + eennaabbllee--kkeeyyppaadd ((OOffff)) + When set to OOnn, rreeaaddlliinnee tries to enable the application keypad + when it is called. Some systems need this to enable the arrow + keys. + eennaabbllee--mmeettaa--kkeeyy ((OOnn)) + When set to OOnn, rreeaaddlliinnee tries to enable any meta modifier key + the terminal claims to support. On many terminals, the Meta key + is used to send eight-bit characters; this variable checks for + the terminal capability that indicates the terminal can enable + and disable a mode that sets the eighth bit of a character + (0200) if the Meta key is held down when the character is typed + (a meta character). + eexxppaanndd--ttiillddee ((OOffff)) + If set to OOnn, rreeaaddlliinnee performs tilde expansion when it attempts + word completion. + ffoorrccee--mmeettaa--pprreeffiixx ((OOffff)) + If set to OOnn, rreeaaddlliinnee modifies its behavior when binding key + sequences containing \M- or Meta- (see KKeeyy BBiinnddiinnggss above) by + converting a key sequence of the form \M-_C or Meta-_C to the two- + character sequence EESSCC _C (adding the meta prefix). If + ffoorrccee--mmeettaa--pprreeffiixx is set to OOffff (the default), rreeaaddlliinnee uses the + value of the ccoonnvveerrtt--mmeettaa variable to determine whether to per- + form this conversion: if ccoonnvveerrtt--mmeettaa is OOnn, rreeaaddlliinnee performs + the conversion described above; if it is OOffff, rreeaaddlliinnee converts + _C to a meta character by setting the eighth bit (0200). + hhiissttoorryy--pprreesseerrvvee--ppooiinntt ((OOffff)) + If set to OOnn, the history code attempts to place point at the + same location on each history line retrieved with pprreevviioouuss--hhiiss-- + ttoorryy or nneexxtt--hhiissttoorryy. + hhiissttoorryy--ssiizzee ((uunnsseett)) + 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, bbaasshh + sets the maximum number of history entries to the value of the + HHIISSTTSSIIZZEE shell variable. Setting _h_i_s_t_o_r_y_-_s_i_z_e to a non-numeric + value will set the maximum number of history entries to 500. + hhoorriizzoonnttaall--ssccrroollll--mmooddee ((OOffff)) + Setting this variable to OOnn makes rreeaaddlliinnee 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. + iinnppuutt--mmeettaa ((OOffff)) + If set to OOnn, rreeaaddlliinnee enables eight-bit input (that is, it does + not clear the eighth bit in the characters it reads), regardless + of what the terminal claims it can support. The default is _O_f_f, + but rreeaaddlliinnee sets it to _O_n if the locale contains characters + whose encodings may include bytes with the eighth bit set. This + variable is dependent on the LLCC__CCTTYYPPEE locale category, and its + value may change if the locale changes. The name mmeettaa--ffllaagg is a + synonym for iinnppuutt--mmeettaa. + iisseeaarrcchh--tteerrmmiinnaattoorrss (("CC--[[CC--jj")) + The string of characters that should terminate an incremental + search without subsequently executing the character as a com- + mand. If this variable has not been given a value, the charac- + ters _E_S_C and CC--jj terminate an incremental search. + kkeeyymmaapp ((eemmaaccss)) + Set the current rreeaaddlliinnee keymap. The set of valid keymap names + is _e_m_a_c_s_, _e_m_a_c_s_-_s_t_a_n_d_a_r_d_, _e_m_a_c_s_-_m_e_t_a_, _e_m_a_c_s_-_c_t_l_x_, _v_i_, _v_i_-_c_o_m_- + _m_a_n_d, and _v_i_-_i_n_s_e_r_t. _v_i is equivalent to _v_i_-_c_o_m_m_a_n_d; _e_m_a_c_s is + equivalent to _e_m_a_c_s_-_s_t_a_n_d_a_r_d. The default value is _e_m_a_c_s; the + value of eeddiittiinngg--mmooddee also affects the default keymap. + kkeeyysseeqq--ttiimmeeoouutt ((550000)) + Specifies the duration rreeaaddlliinnee 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 rreeaaddlliinnee does not + receive any input within the timeout, it uses the shorter but + complete key sequence. The value is specified in milliseconds, + so a value of 1000 means that rreeaaddlliinnee 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, rreeaaddlliinnee waits un- + til another key is pressed to decide which key sequence to com- + plete. + mmaarrkk--ddiirreeccttoorriieess ((OOnn)) + If set to OOnn, completed directory names have a slash appended. + mmaarrkk--mmooddiiffiieedd--lliinneess ((OOffff)) + If set to OOnn, rreeaaddlliinnee displays history lines that have been + modified with a preceding asterisk (**). + mmaarrkk--ssyymmlliinnkkeedd--ddiirreeccttoorriieess ((OOffff)) + If set to OOnn, completed names which are symbolic links to direc- + tories have a slash appended, subject to the value of mmaarrkk--ddii-- + rreeccttoorriieess. + mmaattcchh--hhiiddddeenn--ffiilleess ((OOnn)) + This variable, when set to OOnn, forces rreeaaddlliinnee to match files + whose names begin with a "." (hidden files) when performing + filename completion. If set to OOffff, the user must include the + leading "." in the filename to be completed. + mmeennuu--ccoommpplleettee--ddiissppllaayy--pprreeffiixx ((OOffff)) + If set to OOnn, menu completion displays the common prefix of the + list of possible completions (which may be empty) before cycling + through the list. + oouuttppuutt--mmeettaa ((OOffff)) + If set to OOnn, rreeaaddlliinnee displays characters with the eighth bit + set directly rather than as a meta-prefixed escape sequence. + The default is _O_f_f, but rreeaaddlliinnee sets it to _O_n if the locale + contains characters whose encodings may include bytes with the + eighth bit set. This variable is dependent on the LLCC__CCTTYYPPEE lo- + cale category, and its value may change if the locale changes. + ppaaggee--ccoommpplleettiioonnss ((OOnn)) + If set to OOnn, rreeaaddlliinnee uses an internal pager resembling _m_o_r_e(1) + to display a screenful of possible completions at a time. + pprreeffeerr--vviissiibbllee--bbeellll + See bbeellll--ssttyyllee. + pprriinntt--ccoommpplleettiioonnss--hhoorriizzoonnttaallllyy ((OOffff)) + If set to OOnn, rreeaaddlliinnee displays completions with matches sorted + horizontally in alphabetical order, rather than down the screen. + rreevveerrtt--aallll--aatt--nneewwlliinnee ((OOffff)) + If set to OOnn, rreeaaddlliinnee will undo all changes to history lines + before returning when executing aacccceepptt--lliinnee. By default, his- + tory lines may be modified and retain individual undo lists + across calls to rreeaaddlliinnee. + sseeaarrcchh--iiggnnoorree--ccaassee ((OOffff)) + If set to OOnn, rreeaaddlliinnee performs incremental and non-incremental + history list searches in a case-insensitive fashion. + sshhooww--aallll--iiff--aammbbiigguuoouuss ((OOffff)) + This alters the default behavior of the completion functions. + If set to OOnn, words which have more than one possible completion + cause the matches to be listed immediately instead of ringing + the bell. + sshhooww--aallll--iiff--uunnmmooddiiffiieedd ((OOffff)) + This alters the default behavior of the completion functions in + a fashion similar to sshhooww--aallll--iiff--aammbbiigguuoouuss. If set to OOnn, words + which have more than one possible completion without any possi- + ble partial completion (the possible completions don't share a + common prefix) cause the matches to be listed immediately in- + stead of ringing the bell. + sshhooww--mmooddee--iinn--pprroommpptt ((OOffff)) + If set to OOnn, add a string to the beginning of the prompt indi- + cating the editing mode: emacs, vi command, or vi insertion. + The mode strings are user-settable (e.g., _e_m_a_c_s_-_m_o_d_e_-_s_t_r_i_n_g). + sskkiipp--ccoommpplleetteedd--tteexxtt ((OOffff)) + If set to OOnn, 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, + rreeaaddlliinnee 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. + vvii--ccmmdd--mmooddee--ssttrriinngg ((((ccmmdd)))) + If the _s_h_o_w_-_m_o_d_e_-_i_n_-_p_r_o_m_p_t 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. + The \1 and \2 escapes begin and end sequences of non-printing + characters, which can be used to embed a terminal control se- + quence into the mode string. + vvii--iinnss--mmooddee--ssttrriinngg ((((iinnss)))) + If the _s_h_o_w_-_m_o_d_e_-_i_n_-_p_r_o_m_p_t 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. + The \1 and \2 escapes begin and end sequences of non-printing + characters, which can be used to embed a terminal control se- + quence into the mode string. + vviissiibbllee--ssttaattss ((OOffff)) + If set to OOnn, a character denoting a file's type as reported by + _s_t_a_t(2) is appended to the filename when listing possible com- + pletions. + + RReeaaddlliinnee CCoonnddiittiioonnaall CCoonnssttrruuccttss + RReeaaddlliinnee 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 available. + + $$iiff The $$iiff construct allows bindings to be made based on the edit- + ing mode, the terminal being used, or the application using + rreeaaddlliinnee. The text of the test, after any comparison operator, + extends to the end of the line; unless otherwise noted, no char- + acters are required to isolate it. + + mmooddee The mmooddee== form of the $$iiff directive is used to test + whether rreeaaddlliinnee is in emacs or vi mode. This may be + used in conjunction with the sseett kkeeyymmaapp command, for in- + stance, to set bindings in the _e_m_a_c_s_-_s_t_a_n_d_a_r_d and + _e_m_a_c_s_-_c_t_l_x keymaps only if rreeaaddlliinnee is starting out in + emacs mode. + + tteerrmm The tteerrmm== 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 == is tested against both the full name of the ter- + minal and the portion of the terminal name before the + first --. This allows _x_t_e_r_m to match both _x_t_e_r_m and + _x_t_e_r_m_-_2_5_6_c_o_l_o_r, for instance. + + vveerrssiioonn + The vveerrssiioonn test may be used to perform comparisons + against specific rreeaaddlliinnee versions. The vveerrssiioonn expands + to the current rreeaaddlliinnee version. The set of comparison + operators includes ==, (and ====), !!==, <<==, >>==, <<, and >>. + The version number supplied on the right side of the op- + erator consists of a major version number, an optional + decimal point, and an optional minor version (e.g., 77..11). + If the minor version is omitted, it defaults to 00. The + operator may be separated from the string vveerrssiioonn and + from the version number argument by whitespace. + + _a_p_p_l_i_c_a_t_i_o_n + The _a_p_p_l_i_c_a_t_i_o_n construct is used to include application- + specific settings. Each program using the rreeaaddlliinnee li- + brary sets the _a_p_p_l_i_c_a_t_i_o_n _n_a_m_e, 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 + bbaasshh: + + $$iiff Bash + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + $$eennddiiff + + _v_a_r_i_a_b_l_e + The _v_a_r_i_a_b_l_e construct provides simple equality tests for + rreeaaddlliinnee variables and values. The permitted comparison + operators are _=, _=_=, and _!_=. 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. String and boolean variables + may be tested. Boolean variables must be tested against + the values _o_n and _o_f_f. + + $$eellssee Commands in this branch of the $$iiff directive are executed if the + test fails. + + $$eennddiiff This command, as seen in the previous example, terminates an $$iiff + command. + + $$iinncclluuddee + This directive takes a single filename as an argument and reads + commands and key bindings from that file. For example, the fol- + lowing directive would read _/_e_t_c_/_i_n_p_u_t_r_c: + + $$iinncclluuddee _/_e_t_c_/_i_n_p_u_t_r_c + + SSeeaarrcchhiinngg + RReeaaddlliinnee provides commands for searching through the command history + (see HHIISSTTOORRYY below) for lines containing a specified string. There are + two search modes: _i_n_c_r_e_m_e_n_t_a_l and _n_o_n_-_i_n_c_r_e_m_e_n_t_a_l. + + Incremental searches begin before the user has finished typing the + search string. As each character of the search string is typed, rreeaadd-- + lliinnee 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. When using emacs editing + mode, type CC--rr to search backward in the history for a particular + string. Typing CC--ss searches forward through the history. The charac- + ters present in the value of the iisseeaarrcchh--tteerrmmiinnaattoorrss variable are used + to terminate an incremental search. If that variable has not been as- + signed a value, _E_S_C and CC--jj terminate an incremental search. CC--gg + aborts an incremental search and restores the original line. When the + search is terminated, the history entry containing the search string + becomes the current line. + + To find other matching entries in the history list, type CC--rr or CC--ss as + appropriate. This searches backward or forward in the history for the + next entry matching the search string typed so far. Any other key se- + quence bound to a rreeaaddlliinnee command terminates the search and executes + that command. For instance, a newline terminates the search and ac- + cepts the line, thereby executing the command from the history list. A + movement command will terminate the search, make the last line found + the current line, and begin editing. + + RReeaaddlliinnee remembers the last incremental search string. If two CC--rrs are + typed without any intervening characters defining a new search string, + rreeaaddlliinnee uses any remembered search string. + + Non-incremental searches read the entire search string before starting + to search for matching history entries. The search string may be typed + by the user or be part of the contents of the current line. + + RReeaaddlliinnee CCoommmmaanndd NNaammeess + 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 accom- + panying key sequence are unbound by default. + + In the following descriptions, _p_o_i_n_t refers to the current cursor posi- + tion, and _m_a_r_k refers to a cursor position saved by the sseett--mmaarrkk com- + mand. The text between the point and mark is referred to as the _r_e_- + _g_i_o_n. RReeaaddlliinnee has the concept of an _a_c_t_i_v_e _r_e_g_i_o_n: when the region is + active, rreeaaddlliinnee redisplay highlights the region using the value of the + aaccttiivvee--rreeggiioonn--ssttaarrtt--ccoolloorr variable. The eennaabbllee--aaccttiivvee--rreeggiioonn rreeaaddlliinnee + variable turns this on and off. Several commands set the region to ac- + tive; those are noted below. + + CCoommmmaannddss ffoorr MMoovviinngg + bbeeggiinnnniinngg--ooff--lliinnee ((CC--aa)) + Move to the start of the current line. This may also be bound + to the Home key on some keyboards. + eenndd--ooff--lliinnee ((CC--ee)) + Move to the end of the line. This may also be bound to the End + key on some keyboards. + ffoorrwwaarrdd--cchhaarr ((CC--ff)) + Move forward a character. This may also be bound to the right + arrow key on some keyboards. + bbaacckkwwaarrdd--cchhaarr ((CC--bb)) + Move back a character. This may also be bound to the left arrow + key on some keyboards. + ffoorrwwaarrdd--wwoorrdd ((MM--ff)) + Move forward to the end of the next word. Words are composed of + alphanumeric characters (letters and digits). + bbaacckkwwaarrdd--wwoorrdd ((MM--bb)) + Move back to the start of the current or previous word. Words + are composed of alphanumeric characters (letters and digits). + sshheellll--ffoorrwwaarrdd--wwoorrdd ((MM--CC--ff)) + Move forward to the end of the next word. Words are delimited + by non-quoted shell metacharacters. + sshheellll--bbaacckkwwaarrdd--wwoorrdd ((MM--CC--bb)) + Move back to the start of the current or previous word. Words + are delimited by non-quoted shell metacharacters. + pprreevviioouuss--ssccrreeeenn--lliinnee + 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 rreeaaddlliinnee 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. + nneexxtt--ssccrreeeenn--lliinnee + Attempt to move point to the same physical screen column on the + next physical screen line. This will not have the desired ef- + fect if the current rreeaaddlliinnee line does not take up more than one + physical line or if the length of the current rreeaaddlliinnee line is + not greater than the length of the prompt plus the screen width. + cclleeaarr--ddiissppllaayy ((MM--CC--ll)) + 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. + cclleeaarr--ssccrreeeenn ((CC--ll)) + Clear the screen, then redraw the current line, leaving the cur- + rent line at the top of the screen. With a numeric argument, + refresh the current line without clearing the screen. + rreeddrraaww--ccuurrrreenntt--lliinnee + Refresh the current line. + + CCoommmmaannddss ffoorr MMaanniippuullaattiinngg tthhee HHiissttoorryy + aacccceepptt--lliinnee ((NNeewwlliinnee,, RReettuurrnn)) + 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 HHIISSTTCCOONNTTRROOLL and HHIISSTTIIGGNNOORREE variables. If the line is a + modified history line, restore the history line to its original + state. + pprreevviioouuss--hhiissttoorryy ((CC--pp)) + Fetch the previous command from the history list, moving back in + the list. This may also be bound to the up arrow key on some + keyboards. + nneexxtt--hhiissttoorryy ((CC--nn)) + Fetch the next command from the history list, moving forward in + the list. This may also be bound to the down arrow key on some + keyboards. + bbeeggiinnnniinngg--ooff--hhiissttoorryy ((MM--<<)) + Move to the first line in the history. + eenndd--ooff--hhiissttoorryy ((MM-->>)) + Move to the end of the input history, i.e., the line currently + being entered. + ooppeerraattee--aanndd--ggeett--nneexxtt ((CC--oo)) + Accept the current line for execution as if a newline had been + entered, 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. + ffeettcchh--hhiissttoorryy + 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. + rreevveerrssee--sseeaarrcchh--hhiissttoorryy ((CC--rr)) + Search backward starting at the current line and moving "up" + through the history as necessary. This is an incremental + search. This command sets the region to the matched text and + activates the region. + ffoorrwwaarrdd--sseeaarrcchh--hhiissttoorryy ((CC--ss)) + Search forward starting at the current line and moving "down" + through the history as necessary. This is an incremental + search. This command sets the region to the matched text and + activates the region. + nnoonn--iinnccrreemmeennttaall--rreevveerrssee--sseeaarrcchh--hhiissttoorryy ((MM--pp)) + Search backward through the history starting at the current line + using a non-incremental search for a string supplied by the + user. The search string may match anywhere in a history line. + nnoonn--iinnccrreemmeennttaall--ffoorrwwaarrdd--sseeaarrcchh--hhiissttoorryy ((MM--nn)) + Search forward through the history using a non-incremental + search for a string supplied by the user. The search string may + match anywhere in a history line. + hhiissttoorryy--sseeaarrcchh--bbaacckkwwaarrdd + Search backward through the history for the string of characters + between the start of the current line and the point. The search + string must match at the beginning of a history line. This is a + non-incremental search. This may be bound to the Page Up key on + some keyboards. + hhiissttoorryy--sseeaarrcchh--ffoorrwwaarrdd + Search forward through the history for the string of characters + between the start of the current line and the point. The search + string must match at the beginning of a history line. This is a + non-incremental search. This may be bound to the Page Down key + on some keyboards. + hhiissttoorryy--ssuubbssttrriinngg--sseeaarrcchh--bbaacckkwwaarrdd + Search backward 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-in- + cremental search. + hhiissttoorryy--ssuubbssttrriinngg--sseeaarrcchh--ffoorrwwaarrdd + 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-in- + cremental search. + yyaannkk--nntthh--aarrgg ((MM--CC--yy)) + Insert the first argument to the previous command (usually the + second word on the previous line) at point. With an argument _n, + insert the _nth word from the previous command (the words in the + previous command begin with word 0). A negative argument in- + serts the _nth word from the end of the previous command. Once + the argument _n is computed, this uses the history expansion fa- + cilities to extract the _nth word, as if the "!_n" history expan- + sion had been specified. + yyaannkk--llaasstt--aarrgg ((MM--..,, MM--__)) + Insert the last argument to the previous command (the last word + of the previous history entry). With a numeric argument, behave + exactly like yyaannkk--nntthh--aarrgg. Successive calls to yyaannkk--llaasstt--aarrgg + 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). This uses the history expansion facilities + to extract the last word, as if the "!$" history expansion had + been specified. + sshheellll--eexxppaanndd--lliinnee ((MM--CC--ee)) + Expand the line by performing shell word expansions. This per- + forms alias and history expansion, $$'_s_t_r_i_n_g' and $$"_s_t_r_i_n_g" quot- + ing, tilde expansion, parameter and variable expansion, arith- + metic expansion, command and process substitution, word split- + ting, and quote removal. An explicit argument suppresses com- + mand and process substitution. See HHIISSTTOORRYY EEXXPPAANNSSIIOONN below for + a description of history expansion. + hhiissttoorryy--eexxppaanndd--lliinnee ((MM--^^)) + Perform history expansion on the current line. See HHIISSTTOORRYY EEXX-- + PPAANNSSIIOONN below for a description of history expansion. + mmaaggiicc--ssppaaccee + Perform history expansion on the current line and insert a + space. See HHIISSTTOORRYY EEXXPPAANNSSIIOONN below for a description of history + expansion. + aalliiaass--eexxppaanndd--lliinnee + Perform alias expansion on the current line. See AALLIIAASSEESS above + for a description of alias expansion. + hhiissttoorryy--aanndd--aalliiaass--eexxppaanndd--lliinnee + Perform history and alias expansion on the current line. + iinnsseerrtt--llaasstt--aarrgguummeenntt ((MM--..,, MM--__)) + A synonym for yyaannkk--llaasstt--aarrgg. + eeddiitt--aanndd--eexxeeccuuttee--ccoommmmaanndd ((CC--xx CC--ee)) + Invoke an editor on the current command line, and execute the + result as shell commands. BBaasshh attempts to invoke $$VVIISSUUAALL, $$EEDD-- + IITTOORR, and _e_m_a_c_s as the editor, in that order. + + CCoommmmaannddss ffoorr CChhaannggiinngg TTeexxtt + _e_n_d_-_o_f_-_f_i_l_e ((uussuuaallllyy CC--dd)) + The character indicating end-of-file as set, for example, by + _s_t_t_y(1). If this character is read when there are no characters + on the line, and point is at the beginning of the line, rreeaaddlliinnee + interprets it as the end of input and returns EEOOFF. + ddeelleettee--cchhaarr ((CC--dd)) + Delete the character at point. If this function is bound to the + same character as the tty EEOOFF character, as CC--dd commonly is, see + above for the effects. This may also be bound to the Delete key + on some keyboards. + bbaacckkwwaarrdd--ddeelleettee--cchhaarr ((RRuubboouutt)) + Delete the character behind the cursor. When given a numeric + argument, save the deleted text on the kill ring. + ffoorrwwaarrdd--bbaacckkwwaarrdd--ddeelleettee--cchhaarr + Delete the character under the cursor, unless the cursor is at + the end of the line, in which case the character behind the cur- + sor is deleted. + qquuootteedd--iinnsseerrtt ((CC--qq,, CC--vv)) + Add the next character typed to the line verbatim. This is how + to insert characters like CC--qq, for example. + ttaabb--iinnsseerrtt ((CC--vv TTAABB)) + Insert a tab character. + sseellff--iinnsseerrtt ((aa,, bb,, AA,, 11,, !!,, ...)) + Insert the character typed. + bbrraacckkeetteedd--ppaassttee--bbeeggiinn + This function is intended to be bound to the "bracketed paste" + escape sequence sent by some terminals, and such a binding is + assigned by default. It allows rreeaaddlliinnee to insert the pasted + text as a single unit without treating each character as if it + had been read from the keyboard. The pasted characters are in- + serted as if each one was bound to sseellff--iinnsseerrtt instead of exe- + cuting any editing commands. + Bracketed paste sets the region to the inserted text and acti- + vates the region. + ttrraannssppoossee--cchhaarrss ((CC--tt)) + 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. + ttrraannssppoossee--wwoorrddss ((MM--tt)) + Drag the word before point past the word after point, moving + point past that word as well. If point is at the end of the + line, this transposes the last two words on the line. + sshheellll--ttrraannssppoossee--wwoorrddss ((MM--CC--tt)) + Drag the word before point past the word after point, moving + point past that word as well. If the insertion point is at the + end of the line, this transposes the last two words on the line. + Word boundaries are the same as sshheellll--ffoorrwwaarrdd--wwoorrdd and + sshheellll--bbaacckkwwaarrdd--wwoorrdd. + uuppccaassee--wwoorrdd ((MM--uu)) + Uppercase the current (or following) word. With a negative ar- + gument, uppercase the previous word, but do not move point. + ddoowwnnccaassee--wwoorrdd ((MM--ll)) + Lowercase the current (or following) word. With a negative ar- + gument, lowercase the previous word, but do not move point. + ccaappiittaalliizzee--wwoorrdd ((MM--cc)) + Capitalize the current (or following) word. With a negative ar- + gument, capitalize the previous word, but do not move point. + oovveerrwwrriittee--mmooddee + Toggle overwrite mode. With an explicit positive numeric argu- + ment, switches to overwrite mode. With an explicit non-positive + numeric argument, switches to insert mode. This command affects + only eemmaaccss mode; vvii mode does overwrite differently. Each call + to _r_e_a_d_l_i_n_e_(_) starts in insert mode. + In overwrite mode, characters bound to sseellff--iinnsseerrtt replace the + text at point rather than pushing the text to the right. Char- + acters bound to bbaacckkwwaarrdd--ddeelleettee--cchhaarr replace the character be- + fore point with a space. By default, this command is unbound, + but may be bound to the Insert key on some keyboards. + + KKiilllliinngg aanndd YYaannkkiinngg + kkiillll--lliinnee ((CC--kk)) + Kill the text from point to the end of the current line. With a + negative numeric argument, kill backward from the cursor to the + beginning of the line. + bbaacckkwwaarrdd--kkiillll--lliinnee ((CC--xx RRuubboouutt)) + Kill backward to the beginning of the current line. With a neg- + ative numeric argument, kill forward from the cursor to the end + of the line. + uunniixx--lliinnee--ddiissccaarrdd ((CC--uu)) + Kill backward from point to the beginning of the line, saving + the killed text on the kill-ring. + kkiillll--wwhhoollee--lliinnee + Kill all characters on the current line, no matter where point + is. + kkiillll--wwoorrdd ((MM--dd)) + 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 ffoorrwwaarrdd--wwoorrdd. + bbaacckkwwaarrdd--kkiillll--wwoorrdd ((MM--RRuubboouutt)) + Kill the word behind point. Word boundaries are the same as + those used by bbaacckkwwaarrdd--wwoorrdd. + sshheellll--kkiillll--wwoorrdd ((MM--CC--dd)) + 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 sshheellll--ffoorrwwaarrdd--wwoorrdd. + sshheellll--bbaacckkwwaarrdd--kkiillll--wwoorrdd + Kill the word behind point. Word boundaries are the same as + those used by sshheellll--bbaacckkwwaarrdd--wwoorrdd. + uunniixx--wwoorrdd--rruubboouutt ((CC--ww)) + Kill the word behind point, using white space as a word bound- + ary, saving the killed text on the kill-ring. + uunniixx--ffiilleennaammee--rruubboouutt + Kill the word behind point, using white space and the slash + character as the word boundaries, saving the killed text on the + kill-ring. + ddeelleettee--hhoorriizzoonnttaall--ssppaaccee ((MM--\\)) + Delete all spaces and tabs around point. + kkiillll--rreeggiioonn + Kill the text in the current region. + ccooppyy--rreeggiioonn--aass--kkiillll + Copy the text in the region to the kill buffer, so it can be + yanked immediately. + ccooppyy--bbaacckkwwaarrdd--wwoorrdd + Copy the word before point to the kill buffer. The word bound- + aries are the same as bbaacckkwwaarrdd--wwoorrdd. + ccooppyy--ffoorrwwaarrdd--wwoorrdd + Copy the word following point to the kill buffer. The word + boundaries are the same as ffoorrwwaarrdd--wwoorrdd. + yyaannkk ((CC--yy)) + Yank the top of the kill ring into the buffer at point. + yyaannkk--ppoopp ((MM--yy)) + Rotate the kill ring, and yank the new top. Only works follow- + ing yyaannkk or yyaannkk--ppoopp. + + NNuummeerriicc AArrgguummeennttss + ddiiggiitt--aarrgguummeenntt ((MM--00,, MM--11,, ...,, MM----)) + Add this digit to the argument already accumulating, or start a + new argument. M-- starts a negative argument. + uunniivveerrssaall--aarrgguummeenntt + 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 fol- + lowed by digits, executing uunniivveerrssaall--aarrgguummeenntt again ends the nu- + meric argument, but is otherwise ignored. As a special case, if + this command is immediately followed by a character that is nei- + ther 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 argu- + ment count four, a second time makes the argument count sixteen, + and so on. + + CCoommpplleettiinngg + ccoommpplleettee ((TTAABB)) + Attempt to perform completion on the text before point. BBaasshh + attempts completion by first checking for any programmable com- + pletions for the command word (see PPrrooggrraammmmaabbllee CCoommpplleettiioonn be- + low), otherwise treating the text as a variable (if the text be- + gins with $$), username (if the text begins with ~~), hostname (if + the text begins with @@), or command (including aliases, func- + tions, and builtins) in turn. If none of these produces a + match, it falls back to filename completion. + ppoossssiibbllee--ccoommpplleettiioonnss ((MM--??)) + List the possible completions of the text before point. When + displaying completions, rreeaaddlliinnee sets the number of columns used + for display to the value of ccoommpplleettiioonn--ddiissppllaayy--wwiiddtthh, the value + of the shell variable CCOOLLUUMMNNSS, or the screen width, in that or- + der. + iinnsseerrtt--ccoommpplleettiioonnss ((MM--**)) + Insert all completions of the text before point that would have + been generated by ppoossssiibbllee--ccoommpplleettiioonnss, separated by a space. + mmeennuu--ccoommpplleettee + Similar to ccoommpplleettee, but replaces the word to be completed with + a single match from the list of possible completions. Repeat- + edly executing mmeennuu--ccoommpplleettee steps through the list of possible + completions, inserting each match in turn. At the end of the + list of completions, mmeennuu--ccoommpplleettee rings the bell (subject to + the setting of bbeellll--ssttyyllee) and restores the original text. An + argument of _n moves _n positions forward in the list of matches; + a negative argument moves backward through the list. This com- + mand is intended to be bound to TTAABB, but is unbound by default. + mmeennuu--ccoommpplleettee--bbaacckkwwaarrdd + Identical to mmeennuu--ccoommpplleettee, but moves backward through the list + of possible completions, as if mmeennuu--ccoommpplleettee had been given a + negative argument. This command is unbound by default. + eexxppoorrtt--ccoommpplleettiioonnss + Perform completion on the word before point as described above + and write the list of possible completions to rreeaaddlliinnee's output + stream using the following format, writing information on sepa- + rate lines: + + +o the number of matches _N; + +o the word being completed; + +o _S:_E, where _S and _E are the start and end offsets of the + word in the rreeaaddlliinnee line buffer; then + +o each match, one per line + + If there are no matches, the first line will be "0", and this + command does not print any output after the _S:_E. If there is + only a single match, this prints a single line containing it. + If there is more than one match, this prints the common prefix + of the matches, which may be empty, on the first line after the + _S:_E, then the matches on subsequent lines. In this case, _N will + include the first line with the common prefix. + + The user or application should be able to accommodate the possi- + bility of a blank line. The intent is that the user or applica- + tion reads _N lines after the line containing _S:_E to obtain the + match list. This command is unbound by default. + + ddeelleettee--cchhaarr--oorr--lliisstt + Deletes the character under the cursor if not at the beginning + or end of the line (like ddeelleettee--cchhaarr). At the end of the line, + it behaves identically to ppoossssiibbllee--ccoommpplleettiioonnss. This command is + unbound by default. + + ccoommpplleettee--ffiilleennaammee ((MM--//)) + Attempt filename completion on the text before point. + + ppoossssiibbllee--ffiilleennaammee--ccoommpplleettiioonnss ((CC--xx //)) + List the possible completions of the text before point, treating + it as a filename. + + ccoommpplleettee--uusseerrnnaammee ((MM--~~)) + Attempt completion on the text before point, treating it as a + username. + + ppoossssiibbllee--uusseerrnnaammee--ccoommpplleettiioonnss ((CC--xx ~~)) + List the possible completions of the text before point, treating + it as a username. + + ccoommpplleettee--vvaarriiaabbllee ((MM--$$)) + Attempt completion on the text before point, treating it as a + shell variable. + + ppoossssiibbllee--vvaarriiaabbllee--ccoommpplleettiioonnss ((CC--xx $$)) + List the possible completions of the text before point, treating + it as a shell variable. + + ccoommpplleettee--hhoossttnnaammee ((MM--@@)) + Attempt completion on the text before point, treating it as a + hostname. + + ppoossssiibbllee--hhoossttnnaammee--ccoommpplleettiioonnss ((CC--xx @@)) + List the possible completions of the text before point, treating + it as a hostname. + + ccoommpplleettee--ccoommmmaanndd ((MM--!!)) + 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. + + ppoossssiibbllee--ccoommmmaanndd--ccoommpplleettiioonnss ((CC--xx !!)) + List the possible completions of the text before point, treating + it as a command name. + + ddyynnaammiicc--ccoommpplleettee--hhiissttoorryy ((MM--TTAABB)) + Attempt completion on the text before point, comparing the text + against history list entries for possible completion matches. + + ddaabbbbrreevv--eexxppaanndd + Attempt menu completion on the text before point, comparing the + text against lines from the history list for possible completion + matches. + + ccoommpplleettee--iinnttoo--bbrraacceess ((MM--{{)) + Perform filename completion and insert the list of possible com- + pletions enclosed within braces so the list is available to the + shell (see BBrraaccee EExxppaannssiioonn above). + + KKeeyybbooaarrdd MMaaccrrooss + ssttaarrtt--kkbbdd--mmaaccrroo ((CC--xx (()) + Begin saving the characters typed into the current keyboard + macro. + eenndd--kkbbdd--mmaaccrroo ((CC--xx )))) + Stop saving the characters typed into the current keyboard macro + and store the definition. + ccaallll--llaasstt--kkbbdd--mmaaccrroo ((CC--xx ee)) + Re-execute the last keyboard macro defined, by making the char- + acters in the macro appear as if typed at the keyboard. + pprriinntt--llaasstt--kkbbdd--mmaaccrroo (()) + Print the last keyboard macro defined in a format suitable for + the _i_n_p_u_t_r_c file. + + MMiisscceellllaanneeoouuss + rree--rreeaadd--iinniitt--ffiillee ((CC--xx CC--rr)) + Read in the contents of the _i_n_p_u_t_r_c file, and incorporate any + bindings or variable assignments found there. + aabboorrtt ((CC--gg)) + Abort the current editing command and ring the terminal's bell + (subject to the setting of bbeellll--ssttyyllee). + ddoo--lloowweerrccaassee--vveerrssiioonn ((MM--AA,, MM--BB,, MM--_x,, ...)) + If the metafied character _x is uppercase, run the command that + is bound to the corresponding metafied lowercase character. The + behavior is undefined if _x is already lowercase. + pprreeffiixx--mmeettaa ((EESSCC)) + Metafy the next character typed. EESSCC ff is equivalent to MMeettaa--ff. + uunnddoo ((CC--__,, CC--xx CC--uu)) + Incremental undo, separately remembered for each line. + rreevveerrtt--lliinnee ((MM--rr)) + Undo all changes made to this line. This is like executing the + uunnddoo command enough times to return the line to its initial + state. + ttiillddee--eexxppaanndd ((MM--&&)) + Perform tilde expansion on the current word. + sseett--mmaarrkk ((CC--@@,, MM--<>)) + Set the mark to the point. If a numeric argument is supplied, + set the mark to that position. + eexxcchhaannggee--ppooiinntt--aanndd--mmaarrkk ((CC--xx CC--xx)) + Swap the point with the mark. Set the current cursor position + to the saved position, then set the mark to the old cursor posi- + tion. + cchhaarraacctteerr--sseeaarrcchh ((CC--]])) + Read a character and move point to the next occurrence of that + character. A negative argument searches for previous occur- + rences. + cchhaarraacctteerr--sseeaarrcchh--bbaacckkwwaarrdd ((MM--CC--]])) + Read a character and move point to the previous occurrence of + that character. A negative argument searches for subsequent oc- + currences. + sskkiipp--ccssii--sseeqquueennccee + Read enough characters to consume a multi-key sequence such as + those defined for keys like Home and End. CSI sequences begin + with a Control Sequence Indicator (CSI), usually _E_S_C _[. If this + sequence is bound to "\e[", keys producing CSI sequences have no + effect unless explicitly bound to a rreeaaddlliinnee command, instead of + inserting stray characters into the editing buffer. This is un- + bound by default, but usually bound to _E_S_C _[. + iinnsseerrtt--ccoommmmeenntt ((MM--##)) + Without a numeric argument, insert the value of the rreeaaddlliinnee + ccoommmmeenntt--bbeeggiinn variable 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 ccoommmmeenntt--bbeeggiinn, insert the value; otherwise delete the + characters in ccoommmmeenntt--bbeeggiinn from the beginning of the line. In + either case, the line is accepted as if a newline had been + typed. The default value of ccoommmmeenntt--bbeeggiinn 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 ex- + ecuted by the shell. + ssppeellll--ccoorrrreecctt--wwoorrdd ((CC--xx ss)) + Perform spelling correction on the current word, treating it as + a directory or filename, in the same way as the ccddssppeellll shell + option. Word boundaries are the same as those used by + sshheellll--ffoorrwwaarrdd--wwoorrdd. + gglloobb--ccoommpplleettee--wwoorrdd ((MM--gg)) + Treat the word before point as a pattern for pathname expansion, + with an asterisk implicitly appended, then use the pattern to + generate a list of matching file names for possible completions. + gglloobb--eexxppaanndd--wwoorrdd ((CC--xx **)) + Treat the word before point as a pattern for pathname expansion, + and insert the list of matching file names, replacing the word. + If a numeric argument is supplied, append a ** before pathname + expansion. + gglloobb--lliisstt--eexxppaannssiioonnss ((CC--xx gg)) + Display the list of expansions that would have been generated by + gglloobb--eexxppaanndd--wwoorrdd and redisplay the line. If a numeric argument + is supplied, append a ** before pathname expansion. + dduummpp--ffuunnccttiioonnss + Print all of the functions and their key bindings to the rreeaadd-- + lliinnee output stream. If a numeric argument is supplied, the out- + put is formatted in such a way that it can be made part of an + _i_n_p_u_t_r_c file. + dduummpp--vvaarriiaabblleess + Print all of the settable rreeaaddlliinnee variables and their values to + the rreeaaddlliinnee output stream. If a numeric argument is supplied, + the output is formatted in such a way that it can be made part + of an _i_n_p_u_t_r_c file. + dduummpp--mmaaccrrooss + Print all of the rreeaaddlliinnee key sequences bound to macros and the + strings they output to the rreeaaddlliinnee output stream. If a numeric + argument is supplied, the output is formatted in such a way that + it can be made part of an _i_n_p_u_t_r_c file. + eexxeeccuuttee--nnaammeedd--ccoommmmaanndd ((MM--xx)) + Read a bindable rreeaaddlliinnee command name from the input and execute + the function to which it's bound, as if the key sequence to + which it was bound appeared in the input. If this function is + supplied with a numeric argument, it passes that argument to the + function it executes. + ddiissppllaayy--sshheellll--vveerrssiioonn ((CC--xx CC--vv)) + Display version information about the current instance of bbaasshh. + + PPrrooggrraammmmaabbllee CCoommpplleettiioonn + When a user attempts word completion for a command or an argument to a + command for which a completion specification (a _c_o_m_p_s_p_e_c) has been de- + fined using the ccoommpplleettee builtin (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below), + rreeaaddlliinnee invokes the programmable completion facilities. + + First, bbaasshh identifies the command name. If a compspec has been de- + fined for that command, the compspec is used to generate the list of + possible completions for the word. If the command word is the empty + string (completion attempted at the beginning of an empty line), bbaasshh + uses any compspec defined with the --EE option to ccoommpplleettee. The --II op- + tion to ccoommpplleettee indicates that the command word is the first non-as- + signment word on the line, or after a command delimiter such as ;; or ||. + This usually indicates command name completion. + + If the command word is a full pathname, bbaasshh searches for a compspec + for the full pathname first. If there is no compspec for the full + pathname, bbaasshh attempts to find a compspec for the portion following + the final slash. If those searches do not result in a compspec, or if + there is no compspec for the command word, bbaasshh uses any compspec de- + fined with the --DD option to ccoommpplleettee as the default. If there is no + default compspec, bbaasshh performs alias expansion on the command word as + a final resort, and attempts to find a compspec for the command word + resulting from any successful expansion. + + If a compspec is not found, bbaasshh performs its default completion as de- + scribed above under CCoommpplleettiinngg. Otherwise, once a compspec has been + found, bbaasshh uses it to generate the list of matching words. + + First, bbaasshh performs the _a_c_t_i_o_n_s specified by the compspec. This only + returns matches which are prefixes of the word being completed. When + the --ff or --dd option is used for filename or directory name completion, + bbaasshh uses the shell variable FFIIGGNNOORREE to filter the matches. + + Next, programmable completion generates matches specified by a pathname + expansion pattern supplied as an argument to the --GG option. The words + generated by the pattern need not match the word being completed. BBaasshh + uses the FFIIGGNNOORREE variable to filter the matches, but does not use the + GGLLOOBBIIGGNNOORREE shell variable. + + Next, completion considers the string specified as the argument to the + --WW option. The string is first split using the characters in the IIFFSS + special variable as delimiters. This honors shell quoting within the + string, in order to provide a mechanism for the words to contain shell + metacharacters or characters in the value of IIFFSS. Each word is then + expanded using brace expansion, tilde expansion, parameter and variable + expansion, command substitution, and arithmetic expansion, as described + above under EEXXPPAANNSSIIOONN. The results are split using the rules described + above under WWoorrdd SSpplliittttiinngg. The results of the expansion are prefix- + matched against the word being completed, and the matching words become + possible completions. + + After these matches have been generated, bbaasshh executes any shell func- + tion or command specified with the --FF and --CC options. When the command + or function is invoked, bbaasshh assigns values to the CCOOMMPP__LLIINNEE, + CCOOMMPP__PPOOIINNTT, CCOOMMPP__KKEEYY, and CCOOMMPP__TTYYPPEE variables as described above under + SShheellll VVaarriiaabblleess. If a shell function is being invoked, bbaasshh also sets + the CCOOMMPP__WWOORRDDSS and CCOOMMPP__CCWWOORRDD variables. When the function or command + is invoked, the first argument ($$11) is the name of the command whose + arguments are being completed, the second argument ($$22) is the word be- + ing completed, and the third argument ($$33) is the word preceding the + word being completed on the current command line. There is no filter- + ing of the generated completions against the word being completed; the + function or command has complete freedom in generating the matches and + they do not need to match a prefix of the word. + + Any function specified with --FF is invoked first. The function may use + any of the shell facilities, including the ccoommppggeenn and ccoommppoopptt builtins + described below, to generate the matches. It must put the possible + completions in the CCOOMMPPRREEPPLLYY array variable, one per array element. + + Next, any command specified with the --CC option is invoked in an envi- + ronment equivalent to command substitution. It should print a list of + completions, one per line, to the standard output. Backslash will es- + cape a newline, if necessary. These are added to the set of possible + completions. + + External commands that are invoked to generate completions ( "external + completers") receive the word preceding the completion word as an argu- + ment, as described above. This provides context that is sometimes use- + ful, but may include information that is considered sensitive or part + of a word expansion that will not appear in the command line after ex- + pansion. That word may be visible in process listings or in audit + logs. This may be a concern to users and completion specification au- + thors if there is sensitive information on the command line before ex- + pansion, since completion takes place before words are expanded. If + this is an issue, completion authors should use functions as wrappers + around external commands and pass context information to the external + command in a different way. External completers can infer context from + the CCOOMMPP__LLIINNEE and CCOOMMPP__PPOOIINNTT environment variables, but they need to + ensure they break words in the same way rreeaaddlliinnee does, using the + CCOOMMPP__WWOORRDDBBRREEAAKKSS variable. + + After generating all of the possible completions, bbaasshh applies any fil- + ter specified with the --XX option to the completions in the list. The + filter is a pattern as used for pathname expansion; a && in the pattern + is replaced with the text of the word being completed. A literal && may + be escaped with a backslash; the backslash is removed before attempting + a match. Any completion that matches the pattern is removed from the + list. A leading !! negates the pattern; in this case bbaasshh removes any + completion that does not match the pattern. If the nnooccaasseemmaattcchh shell + option is enabled, bbaasshh performs the match without regard to the case + of alphabetic characters. + + Finally, programmable completion adds any prefix and suffix specified + with the --PP and --SS options, respectively, to each completion, and re- + turns the result to rreeaaddlliinnee as the list of possible completions. + + If the previously-applied actions do not generate any matches, and the + --oo ddiirrnnaammeess option was supplied to ccoommpplleettee when the compspec was de- + fined, bbaasshh attempts directory name completion. + + If the --oo pplluussddiirrss option was supplied to ccoommpplleettee when the compspec + was defined, bbaasshh attempts directory name completion and adds any + matches to the set of possible completions. + + 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 bbaasshh completions and the rreeaaddlliinnee default of filename comple- + tion are disabled. If the --oo bbaasshhddeeffaauulltt option was supplied to ccoomm-- + pplleettee when the compspec was defined, and the compspec generates no + matches, bbaasshh attempts its default completions. If the compspec and, + if attempted, the default bbaasshh completions generate no matches, and the + --oo ddeeffaauulltt option was supplied to ccoommpplleettee when the compspec was de- + fined, programmable completion performs rreeaaddlliinnee's default completion. + + The options supplied to ccoommpplleettee and ccoommppoopptt can control how rreeaaddlliinnee + treats the completions. For instance, the _-_o _f_u_l_l_q_u_o_t_e option tells + rreeaaddlliinnee to quote the matches as if they were filenames. See the de- + scription of ccoommpplleettee below for details. + + When a compspec indicates that it wants directory name completion, the + programmable completion functions force rreeaaddlliinnee to append a slash to + completed names which are symbolic links to directories, subject to the + value of the mmaarrkk--ddiirreeccttoorriieess rreeaaddlliinnee variable, regardless of the set- + ting of the mmaarrkk--ssyymmlliinnkkeedd--ddiirreeccttoorriieess rreeaaddlliinnee variable. + + There is some support for dynamically modifying completions. This is + most useful when used in combination with a default completion speci- + fied with ccoommpplleettee --DD. It's possible for shell functions executed as + completion functions 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 can be used to + build a set of completions dynamically as completion is attempted, + rather than loading them all at once. + + For instance, assuming that there is a library of compspecs, each kept + in a file corresponding to the name of the command, the following de- + fault completion function would load completions dynamically: + _completion_loader() + { + . "/etc/bash_completion.d/$1.sh" \ + >/dev/null 2>&1 && return 124 + } + complete -D -F _completion_loader \ + -o bashdefault -o default + +HHIISSTTOORRYY + When the --oo hhiissttoorryy option to the sseett builtin is enabled, the shell + provides access to the _c_o_m_m_a_n_d _h_i_s_t_o_r_y, the list of commands previously + typed. The value of the HHIISSTTSSIIZZEE variable is used as the number of + commands to save in a history list: the shell saves the text of the + last HHIISSTTSSIIZZEE commands (default 500). The shell stores each command in + the history list prior to parameter and variable expansion (see EEXXPPAANN-- + SSIIOONN above) but after history expansion is performed, subject to the + values of the shell variables HHIISSTTIIGGNNOORREE and HHIISSTTCCOONNTTRROOLL. + + On startup, bbaasshh initializes the history list by reading history en- + tries from the file named by the HHIISSTTFFIILLEE variable (default + _~_/_._b_a_s_h___h_i_s_t_o_r_y). That file is referred to as the _h_i_s_t_o_r_y _f_i_l_e. The + history file is truncated, if necessary, to contain no more than the + number of history entries specified by the value of the HHIISSTTFFIILLEESSIIZZEE + variable. If HHIISSTTFFIILLEESSIIZZEE is unset, or set to null, a non-numeric + value, or a numeric value less than zero, the history file is not trun- + cated. + + 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 dis- + played depending on the value of the HHIISSTTTTIIMMEEFFOORRMMAATT variable. When + present, history timestamps delimit history entries, making multi-line + entries possible. + + When a shell with history enabled exits, bbaasshh copies the last $$HHIISSTTSSIIZZEE + entries from the history list to $$HHIISSTTFFIILLEE. If the hhiissttaappppeenndd shell + option is enabled (see the description of sshhoopptt under SSHHEELLLL BBUUIILLTTIINN + CCOOMMMMAANNDDSS below), bbaasshh appends the entries to the history file, other- + wise it overwrites the history file. If HHIISSTTFFIILLEE is unset or null, or + if the history file is unwritable, the history is not saved. After + saving the history, bbaasshh truncates the history file to contain no more + than HHIISSTTFFIILLEESSIIZZEE lines as described above. + + If the HHIISSTTTTIIMMEEFFOORRMMAATT variable is set, the shell writes the timestamp + information associated with each history entry to the history file, + marked with the history comment character, so timestamps are preserved + across shell sessions. This uses the history comment character to dis- + tinguish timestamps from other history lines. As above, when using + HHIISSTTTTIIMMEEFFOORRMMAATT, the timestamps delimit multi-line history entries. + + The ffcc builtin command (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below) will list or + edit and re-execute a portion of the history list. The hhiissttoorryy builtin + can 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. + + The shell allows control over which commands are saved on the history + list. The HHIISSTTCCOONNTTRROOLL and HHIISSTTIIGGNNOORREE variables are used to save only a + subset of the commands entered. If the ccmmddhhiisstt shell option is en- + abled, the shell attempts to save each line of a multi-line command in + the same history entry, adding semicolons where necessary to preserve + syntactic correctness. The lliitthhiisstt shell option modifies ccmmddhhiisstt by + saving the command with embedded newlines instead of semicolons. See + the description of the sshhoopptt builtin below under SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS + for information on setting and unsetting shell options. + +HHIISSTTOORRYY EEXXPPAANNSSIIOONN + The shell supports a history expansion feature that is similar to the + history expansion in ccsshh. This section describes what syntax features + are available. + + History expansion is enabled by default for interactive shells, and can + be disabled using the ++HH option to the sseett builtin command (see SSHHEELLLL + BBUUIILLTTIINN CCOOMMMMAANNDDSS below). Non-interactive shells do not perform history + expansion by default, but it can be enabled with "set -H". + + 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. + + 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. The shell attempts to inform the history expansion + functions about quoting still in effect from previous lines. + + It takes place in two parts. The first is to determine which history + list entry to use during substitution. The second is to select por- + tions of that entry to include into the current one. + + The entry selected from the history is the _e_v_e_n_t, and the portions of + that entry that are acted upon are _w_o_r_d_s. Various _m_o_d_i_f_i_e_r_s are avail- + able to manipulate the selected words. The entry is split into words + in the same fashion as when reading input, so that several _m_e_t_a_c_h_a_r_a_c_- + _t_e_r-separated words surrounded by quotes are considered one word. The + _e_v_e_n_t _d_e_s_i_g_n_a_t_o_r selects the event, the optional _w_o_r_d _d_e_s_i_g_n_a_t_o_r se- + lects words from the event, and various optional _m_o_d_i_f_i_e_r_s are avail- + able to manipulate the selected words. + + History expansions are introduced by the appearance of the history ex- + pansion character, which is !! by default. History expansions may ap- + pear anywhere in the input, but do not nest. + + Only backslash (\\) 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. + + Several characters inhibit history expansion if found immediately fol- + lowing the history expansion character, even if it is unquoted: space, + tab, newline, carriage return, ==, and the other shell metacharacters + defined above. + + There is a special abbreviation for substitution, active when the _q_u_i_c_k + _s_u_b_s_t_i_t_u_t_i_o_n character (described above under hhiissttcchhaarrss) is the first + character on the line. It selects the previous history list entry, us- + ing an event designator equivalent to !!!!, and substitutes one string + for another in that entry. It is described below under EEvveenntt DDeessiiggnnaa-- + ttoorrss. This is the only history expansion that does not begin with the + history expansion character. + + Several shell options settable with the sshhoopptt builtin will modify his- + tory expansion behavior (see the description of the sshhoopptt builtin be- + low).and If the hhiissttvveerriiffyy shell option is enabled, and rreeaaddlliinnee is be- + ing used, history substitutions are not immediately passed to the shell + parser. Instead, the expanded line is reloaded into the rreeaaddlliinnee edit- + ing buffer for further modification. If rreeaaddlliinnee is being used, and + the hhiissttrreeeeddiitt shell option is enabled, a failed history substitution + is reloaded into the rreeaaddlliinnee editing buffer for correction. + + The --pp option to the hhiissttoorryy builtin command shows what a history ex- + pansion will do before using it. The --ss option to the hhiissttoorryy builtin + will add commands to the end of the history list without actually exe- + cuting them, so that they are available for subsequent recall. + + The shell allows control of the various characters used by the history + expansion mechanism (see the description of hhiissttcchhaarrss above under SShheellll + VVaarriiaabblleess). The shell uses the history comment character to mark his- + tory timestamps when writing the history file. + + EEvveenntt DDeessiiggnnaattoorrss + An event designator is a reference to an entry in the history list. + The event designator consists of the portion of the word beginning with + the history expansion character and ending with the word designator if + present, or the end of the word. Unless the reference is absolute, + events are relative to the current position in the history list. + + !! Start a history substitution, except when followed by a bbllaannkk, + newline, carriage return, =, or, when the eexxttgglloobb shell option + is enabled using the sshhoopptt builtin, (. + !!_n Refer to history list entry _n. + !!--_n Refer to the current entry minus _n. + !!!! Refer to the previous entry. This is a synonym for "!-1". + !!_s_t_r_i_n_g + Refer to the most recent command preceding the current position + in the history list starting with _s_t_r_i_n_g. + !!??_s_t_r_i_n_g[[??]] + Refer to the most recent command preceding the current position + in the history list containing _s_t_r_i_n_g. The trailing ?? may be + omitted if _s_t_r_i_n_g is followed immediately by a newline. If + _s_t_r_i_n_g is missing, this uses the string from the most recent + search; it is an error if there is no previous search string. + ^^_s_t_r_i_n_g_1^^_s_t_r_i_n_g_2^^ + Quick substitution. Repeat the previous command, replacing + _s_t_r_i_n_g_1 with _s_t_r_i_n_g_2. Equivalent to "!!:s^_s_t_r_i_n_g_1^_s_t_r_i_n_g_2^" + (see MMooddiiffiieerrss below). + !!## The entire command line typed so far. + + WWoorrdd DDeessiiggnnaattoorrss + Word designators are used to select desired words from the event. They + are optional; if the word designator isn't supplied, the history expan- + sion uses the entire event. A :: separates the event specification from + the word designator. It may be omitted if the word designator begins + with a ^^, $$, **, --, or %%. Words are numbered from the beginning of the + line, with the first word being denoted by 0 (zero). Words are in- + serted into the current line separated by single spaces. + + 00 ((zzeerroo)) + The zeroth word. For the shell, this is the command word. + _n The _nth word. + ^^ The first argument: word 1. + $$ The last word. This is usually the last argument, but will ex- + pand to the zeroth word if there is only one word in the line. + %% The first word matched by the most recent "?_s_t_r_i_n_g?" search, if + the search string begins with a character that is part of a + word. By default, searches begin at the end of each line and + proceed to the beginning, so the first word matched is the one + closest to the end of the line. + _x--_y A range of words; "-_y" abbreviates "0-_y". + ** All of the words but the zeroth. This is a synonym for "_1_-_$". + It is not an error to use ** if there is just one word in the + event; it expands to the empty string in that case. + xx** Abbreviates _x_-_$. + xx-- Abbreviates _x_-_$ like xx**, but omits the last word. If xx is miss- + ing, it defaults to 0. + + If a word designator is supplied without an event specification, the + previous command is used as the event, equivalent to !!!!. + + MMooddiiffiieerrss + After the optional word designator, the expansion may include a se- + quence of one or more of the following modifiers, each preceded by a + ":". These modify, or edit, the word or words selected from the his- + tory event. + + hh Remove a trailing pathname component, leaving only the head. + tt Remove all leading pathname components, leaving the tail. + rr Remove a trailing suffix of the form _._x_x_x, leaving the basename. + ee Remove all but the trailing suffix. + pp Print the new command but do not execute it. + qq Quote the substituted words, escaping further substitutions. + xx Quote the substituted words as with qq, but break into words at + bbllaannkkss and newlines. The qq and xx modifiers are mutually exclu- + sive; expansion uses the last one supplied. + ss//_o_l_d//_n_e_w// + Substitute _n_e_w for the first occurrence of _o_l_d 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. A single backslash quotes the delimiter in _o_l_d + and _n_e_w. If & appears in _n_e_w, it is replaced with _o_l_d. A sin- + gle backslash quotes the &. If _o_l_d is null, it is set to the + last _o_l_d substituted, or, if no previous history substitutions + took place, the last _s_t_r_i_n_g in a !!??_s_t_r_i_n_g[[??]] search. If _n_e_w is + null, each matching _o_l_d is deleted. + && Repeat the previous substitution. + gg Cause changes to be applied over the entire event line. This is + used in conjunction with "::ss" (e.g., "::ggss//_o_l_d//_n_e_w//") or "::&&". + If used with "::ss", 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 aa may be used as a synonym for gg. + GG Apply the following "ss" or "&&" modifier once to each word in the + event line. + +SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS + Unless otherwise noted, each builtin command documented in this section + as accepting options preceded by -- accepts ---- to signify the end of the + options. The ::, ttrruuee, ffaallssee, and tteesstt/[[ builtins do not accept options + and do not treat ---- specially. The eexxiitt, llooggoouutt, rreettuurrnn, bbrreeaakk, ccoonn-- + ttiinnuuee, lleett, and sshhiifftt builtins accept and process arguments beginning + with -- without requiring ----. Other builtins that accept arguments but + are not specified as accepting options interpret arguments beginning + with -- as invalid options and require ---- to prevent this interpreta- + tion. + + :: [_a_r_g_u_m_e_n_t_s] + No effect; the command does nothing beyond expanding _a_r_g_u_m_e_n_t_s + and performing any specified redirections. The return status is + zero. + + .. [--pp _p_a_t_h] _f_i_l_e_n_a_m_e [_a_r_g_u_m_e_n_t_s] + ssoouurrccee [--pp _p_a_t_h] _f_i_l_e_n_a_m_e [_a_r_g_u_m_e_n_t_s] + The .. command (ssoouurrccee) reads and execute commands from _f_i_l_e_n_a_m_e + in the current shell environment and returns the exit status of + the last command executed from _f_i_l_e_n_a_m_e. + + If _f_i_l_e_n_a_m_e does not contain a slash, .. searches for it. If the + --pp option is supplied, .. treats _p_a_t_h as a colon-separated list + of directories in which to find _f_i_l_e_n_a_m_e; otherwise, .. uses the + entries in PPAATTHH to find the directory containing _f_i_l_e_n_a_m_e. + _f_i_l_e_n_a_m_e does not need to be executable. When bbaasshh is not in + posix mode, it searches the current directory if _f_i_l_e_n_a_m_e is not + found in PPAATTHH, but does not search the current directory if --pp + is supplied. If the ssoouurrcceeppaatthh option to the sshhoopptt builtin com- + mand is turned off, .. does not search PPAATTHH. + + If any _a_r_g_u_m_e_n_t_s are supplied, they become the positional para- + meters when _f_i_l_e_n_a_m_e is executed. Otherwise the positional pa- + rameters are unchanged. + + If the --TT option is enabled, .. inherits any trap on DDEEBBUUGG; if it + is not, any DDEEBBUUGG trap string is saved and restored around the + call to .., and .. unsets the DDEEBBUUGG trap while it executes. If --TT + is not set, and the sourced file changes the DDEEBBUUGG trap, the new + value persists after .. completes. The return status is the sta- + tus of the last command executed from _f_i_l_e_n_a_m_e (0 if no commands + are executed), and non-zero if _f_i_l_e_n_a_m_e is not found or cannot + be read. + + aalliiaass [--pp] [_n_a_m_e[=_v_a_l_u_e] ...] + With no arguments or with the --pp option, aalliiaass prints the list + of aliases in the form aalliiaass _n_a_m_e=_v_a_l_u_e on standard output. + When arguments are supplied, define an alias for each _n_a_m_e whose + _v_a_l_u_e is given. A trailing space in _v_a_l_u_e causes the next word + to be checked for alias substitution when the alias is expanded + during command parsing. For each _n_a_m_e in the argument list for + which no _v_a_l_u_e is supplied, print the name and value of the + alias _n_a_m_e. aalliiaass returns true unless a _n_a_m_e is given (without + a corresponding =_v_a_l_u_e) for which no alias has been defined. + + bbgg [_j_o_b_s_p_e_c ...] + Resume each suspended job _j_o_b_s_p_e_c in the background, as if it + had been started with &&. If _j_o_b_s_p_e_c is not present, the shell + uses its notion of the _c_u_r_r_e_n_t _j_o_b. bbgg _j_o_b_s_p_e_c returns 0 unless + run when job control is disabled or, when run with job control + enabled, any specified _j_o_b_s_p_e_c was not found or was started + without job control. + + bbiinndd [--mm _k_e_y_m_a_p] [--llssvvSSVVXX] + bbiinndd [--mm _k_e_y_m_a_p] [--qq _f_u_n_c_t_i_o_n] [--uu _f_u_n_c_t_i_o_n] [--rr _k_e_y_s_e_q] + bbiinndd [--mm _k_e_y_m_a_p] --ff _f_i_l_e_n_a_m_e + bbiinndd [--mm _k_e_y_m_a_p] --xx _k_e_y_s_e_q[:] _s_h_e_l_l_-_c_o_m_m_a_n_d + bbiinndd [--mm _k_e_y_m_a_p] _k_e_y_s_e_q:_f_u_n_c_t_i_o_n_-_n_a_m_e + bbiinndd [--mm _k_e_y_m_a_p] --pp|--PP [_r_e_a_d_l_i_n_e_-_c_o_m_m_a_n_d] + bbiinndd [--mm _k_e_y_m_a_p] _k_e_y_s_e_q:_r_e_a_d_l_i_n_e_-_c_o_m_m_a_n_d + bbiinndd _r_e_a_d_l_i_n_e_-_c_o_m_m_a_n_d_-_l_i_n_e + Display current rreeaaddlliinnee key and function bindings, bind a key + sequence to a rreeaaddlliinnee function or macro or to a shell command, + or set a rreeaaddlliinnee variable. Each non-option argument is a key + binding or command as it would appear in a rreeaaddlliinnee initializa- + tion file such as _._i_n_p_u_t_r_c, but each binding or command must be + passed as a separate argument; e.g., '"\C-x\C-r": + re-read-init-file'. In the following descriptions, output + available to be re-read is formatted as commands that would ap- + pear in a rreeaaddlliinnee initialization file or that would be supplied + as individual arguments to a bbiinndd command. Options, if sup- + plied, have the following meanings: + --mm _k_e_y_m_a_p + Use _k_e_y_m_a_p as the keymap to be affected by the subsequent + bindings. Acceptable _k_e_y_m_a_p names are _e_m_a_c_s_, _e_m_a_c_s_-_s_t_a_n_- + _d_a_r_d_, _e_m_a_c_s_-_m_e_t_a_, _e_m_a_c_s_-_c_t_l_x_, _v_i_, _v_i_-_m_o_v_e_, _v_i_-_c_o_m_m_a_n_d, + and _v_i_-_i_n_s_e_r_t. _v_i is equivalent to _v_i_-_c_o_m_m_a_n_d (_v_i_-_m_o_v_e + is also a synonym); _e_m_a_c_s is equivalent to _e_m_a_c_s_-_s_t_a_n_- + _d_a_r_d. + --ll List the names of all rreeaaddlliinnee functions. + --pp Display rreeaaddlliinnee function names and bindings in such a + way that they can be used as an argument to a subsequent + bbiinndd command or in a rreeaaddlliinnee initialization file. If + arguments remain after option processing, bbiinndd treats + them as rreeaaddlliinnee command names and restricts output to + those names. + --PP List current rreeaaddlliinnee function names and bindings. If + arguments remain after option processing, bbiinndd treats + them as rreeaaddlliinnee command names and restricts output to + those names. + --ss Display rreeaaddlliinnee key sequences bound to macros and the + strings they output in such a way that they can be used + as an argument to a subsequent bbiinndd command or in a rreeaadd-- + lliinnee initialization file. + --SS Display rreeaaddlliinnee key sequences bound to macros and the + strings they output. + --vv Display rreeaaddlliinnee variable names and values in such a way + that they can be used as an argument to a subsequent bbiinndd + command or in a rreeaaddlliinnee initialization file. + --VV List current rreeaaddlliinnee variable names and values. + --ff _f_i_l_e_n_a_m_e + Read key bindings from _f_i_l_e_n_a_m_e. + --qq _f_u_n_c_t_i_o_n + Display key sequences that invoke the named rreeaaddlliinnee + _f_u_n_c_t_i_o_n. + --uu _f_u_n_c_t_i_o_n + Unbind all key sequences bound to the named rreeaaddlliinnee + _f_u_n_c_t_i_o_n. + --rr _k_e_y_s_e_q + Remove any current binding for _k_e_y_s_e_q. + --xx _k_e_y_s_e_q[[:: ]]_s_h_e_l_l_-_c_o_m_m_a_n_d + Cause _s_h_e_l_l_-_c_o_m_m_a_n_d to be executed whenever _k_e_y_s_e_q is en- + tered. The separator between _k_e_y_s_e_q and _s_h_e_l_l_-_c_o_m_m_a_n_d is + either whitespace or a colon optionally followed by + whitespace. If the separator is whitespace, _s_h_e_l_l_-_c_o_m_- + _m_a_n_d must be enclosed in double quotes and rreeaaddlliinnee ex- + pands any of its special backslash-escapes in _s_h_e_l_l_-_c_o_m_- + _m_a_n_d before saving it. If the separator is a colon, any + enclosing double quotes are optional, and rreeaaddlliinnee does + not expand the command string before saving it. Since + the entire key binding expression must be a single argu- + ment, it should be enclosed in single quotes. When + _s_h_e_l_l_-_c_o_m_m_a_n_d is executed, the shell sets the RREEAADD-- + LLIINNEE__LLIINNEE variable to the contents of the rreeaaddlliinnee line + buffer and the RREEAADDLLIINNEE__PPOOIINNTT and RREEAADDLLIINNEE__MMAARRKK 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 RREEAADDLLIINNEE__AARRGGUUMMEENNTT variable. If there was no argu- + ment, that variable is not set. If the executed command + changes the value of any of RREEAADDLLIINNEE__LLIINNEE, RREEAADD-- + LLIINNEE__PPOOIINNTT, or RREEAADDLLIINNEE__MMAARRKK, those new values will be + reflected in the editing state. + --XX List all key sequences bound to shell commands and the + associated commands in a format that can be reused as an + argument to a subsequent bbiinndd command. + + The return value is 0 unless an unrecognized option is supplied + or an error occurred. + + bbrreeaakk [_n] + Exit from within a ffoorr, wwhhiillee, uunnttiill, or sseelleecctt loop. If _n is + specified, bbrreeaakk exits _n enclosing loops. _n must be >= 1. If _n + is greater than the number of enclosing loops, all enclosing + loops are exited. The return value is 0 unless _n is not greater + than or equal to 1. + + bbuuiillttiinn _s_h_e_l_l_-_b_u_i_l_t_i_n [_a_r_g_u_m_e_n_t_s] + Execute the specified shell builtin _s_h_e_l_l_-_b_u_i_l_t_i_n, passing it + _a_r_g_u_m_e_n_t_s, 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 ccdd builtin is commonly redefined this way. The return sta- + tus is false if _s_h_e_l_l_-_b_u_i_l_t_i_n is not a shell builtin command. + + ccaalllleerr [_e_x_p_r] + Returns the context of any active subroutine call (a shell func- + tion or a script executed with the .. or ssoouurrccee builtins). + + Without _e_x_p_r, ccaalllleerr displays the line number and source file- + name of the current subroutine call. If a non-negative integer + is supplied as _e_x_p_r, ccaalllleerr displays the line number, subroutine + name, and source file corresponding to that position in the cur- + rent 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 sub- + routine call or _e_x_p_r does not correspond to a valid position in + the call stack. + + ccdd [--LL] [--@@] [_d_i_r] + ccdd --PP [--ee] [--@@] [_d_i_r] + Change the current directory to _d_i_r. if _d_i_r is not supplied, + the value of the HHOOMMEE shell variable is used as _d_i_r. If _d_i_r is + the empty string, ccdd treats it as an error. The variable CCDDPPAATTHH + exists, and _d_i_r does not begin with a slash (/), ccdd uses it as a + search path: the shell searches each directory name in CCDDPPAATTHH + for _d_i_r. Alternative directory names in CCDDPPAATTHH are separated by + a colon (:). A null directory name in CCDDPPAATTHH is the same as the + current directory, i.e., ".". + + The --PP option causes ccdd to use the physical directory structure + by resolving symbolic links while traversing _d_i_r and before pro- + cessing instances of _._. in _d_i_r (see also the --PP option to the + sseett builtin command). + + The --LL option forces ccdd to follow symbolic links by resolving + the link after processing instances of _._. in _d_i_r. If _._. appears + in _d_i_r, ccdd processes it by removing the immediately previous + pathname component from _d_i_r, back to a slash or the beginning of + _d_i_r, and verifying that the portion of _d_i_r it has processed to + that point is still a valid directory name after removing the + pathname component. If it is not a valid directory name, ccdd re- + turns a non-zero status. If neither --LL nor --PP is supplied, ccdd + behaves as if --LL had been supplied. + + If the --ee option is supplied with --PP, and ccdd cannot successfully + determine the current working directory after a successful di- + rectory change, it returns a non-zero status. + + On systems that support it, the --@@ option presents the extended + attributes associated with a file as a directory. + + An argument of -- is converted to $$OOLLDDPPWWDD before attempting the + directory change. + + If ccdd uses a non-empty directory name from CCDDPPAATTHH, or if -- is + the first argument, and the directory change is successful, ccdd + writes the absolute pathname of the new working directory to the + standard output. + + If the directory change is successful, ccdd sets the value of the + PPWWDD environment variable to the new directory name, and sets the + OOLLDDPPWWDD 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. + + ccoommmmaanndd [--ppVVvv] _c_o_m_m_a_n_d [_a_r_g ...] + The ccoommmmaanndd builtin runs _c_o_m_m_a_n_d with _a_r_g_s suppressing the nor- + mal shell function lookup for _c_o_m_m_a_n_d. Only builtin commands or + commands found in the PPAATTHH named _c_o_m_m_a_n_d are executed. If the + --pp option is supplied, the search for _c_o_m_m_a_n_d is performed using + a default value for PPAATTHH that is guaranteed to find all of the + standard utilities. + + If either the --VV or --vv option is supplied, ccoommmmaanndd prints a de- + scription of _c_o_m_m_a_n_d. The --vv option displays a single word in- + dicating the command or filename used to invoke _c_o_m_m_a_n_d; the --VV + option produces a more verbose description. + + If the --VV or --vv option is supplied, the exit status is zero if + _c_o_m_m_a_n_d was found, and non-zero if not. If neither option is + supplied and an error occurred or _c_o_m_m_a_n_d cannot be found, the + exit status is 127. Otherwise, the exit status of the ccoommmmaanndd + builtin is the exit status of _c_o_m_m_a_n_d. + + ccoommppggeenn [--VV _v_a_r_n_a_m_e] [_o_p_t_i_o_n] [_w_o_r_d] + Generate possible completion matches for _w_o_r_d according to the + _o_p_t_i_o_ns, which may be any option accepted by the ccoommpplleettee + builtin with the exceptions of --pp, --rr, --DD, --EE, and --II, and write + the matches to the standard output. + + If the --VV option is supplied, ccoommppggeenn stores the generated com- + pletions into the indexed array variable _v_a_r_n_a_m_e instead of + writing them to the standard output. + + When using the --FF or --CC options, the various shell variables set + by the programmable completion facilities, while available, will + not have useful values. + + The matches will be generated in the same way as if the program- + mable completion code had generated them directly from a comple- + tion specification with the same flags. If _w_o_r_d is specified, + only those completions matching _w_o_r_d will be displayed or + stored. + + The return value is true unless an invalid option is supplied, + or no matches were generated. + + ccoommpplleettee [--aabbccddeeffggjjkkssuuvv] [--oo _c_o_m_p_-_o_p_t_i_o_n] [--DDEEII] [--AA _a_c_t_i_o_n] + [--GG _g_l_o_b_p_a_t] [--WW _w_o_r_d_l_i_s_t] [--FF _f_u_n_c_t_i_o_n] [--CC _c_o_m_m_a_n_d] + [--XX _f_i_l_t_e_r_p_a_t] [--PP _p_r_e_f_i_x] [--SS _s_u_f_f_i_x] _n_a_m_e [_n_a_m_e ...] + ccoommpplleettee --pprr [--DDEEII] [_n_a_m_e ...] + Specify how arguments to each _n_a_m_e should be completed. + + If the --pp option is supplied, or if no options or _n_a_m_es are sup- + plied, print existing completion specifications in a way that + allows them to be reused as input. The --rr option removes a com- + pletion specification for each _n_a_m_e, or, if no _n_a_m_es are sup- + plied, all completion specifications. + + The --DD option indicates that other supplied options and actions + should apply to the "default" command completion; that is, com- + pletion attempted on a command for which no completion has pre- + viously been defined. The --EE option indicates that other sup- + plied options and actions should apply to "empty" command com- + pletion; that is, completion attempted on a blank line. The --II + 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 ;; or ||, which is usu- + ally command name completion. If multiple options are supplied, + the --DD option takes precedence over --EE, and both take precedence + over --II. If any of --DD, --EE, or --II are supplied, any other _n_a_m_e + arguments are ignored; these completions only apply to the case + specified by the option. + + The process of applying these completion specifications when at- + tempting word completion is described above under PPrrooggrraammmmaabbllee + CCoommpplleettiioonn. + + Other options, if specified, have the following meanings. The + arguments to the --GG, --WW, and --XX options (and, if necessary, the + --PP and --SS options) should be quoted to protect them from expan- + sion before the ccoommpplleettee builtin is invoked. + + --oo _c_o_m_p_-_o_p_t_i_o_n + The _c_o_m_p_-_o_p_t_i_o_n controls several aspects of the comp- + spec's behavior beyond the simple generation of comple- + tions. _c_o_m_p_-_o_p_t_i_o_n may be one of: + bbaasshhddeeffaauulltt + Perform the rest of the default bbaasshh completions + if the compspec generates no matches. + ddeeffaauulltt Use rreeaaddlliinnee's default filename completion if + the compspec generates no matches. + ddiirrnnaammeess + Perform directory name completion if the comp- + spec generates no matches. + ffiilleennaammeess + Tell rreeaaddlliinnee that the compspec generates file- + names, so it can perform any filename-specific + processing (such as adding a slash to directory + names, quoting special characters, or suppress- + ing trailing spaces). This is intended to be + used with shell functions. + ffuullllqquuoottee + Tell rreeaaddlliinnee to quote all the completed words + even if they are not filenames. + nnooqquuoottee Tell rreeaaddlliinnee not to quote the completed words + if they are filenames (quoting filenames is the + default). + nnoossoorrtt Tell rreeaaddlliinnee not to sort the list of possible + completions alphabetically. + nnoossppaaccee Tell rreeaaddlliinnee not to append a space (the de- + fault) to words completed at the end of the + line. + pplluussddiirrss + After generating any matches defined by the + compspec, attempt directory name completion and + add any matches to the results of the other ac- + tions. + --AA _a_c_t_i_o_n + The _a_c_t_i_o_n may be one of the following to generate a + list of possible completions: + aalliiaass Alias names. May also be specified as --aa. + aarrrraayyvvaarr + Array variable names. + bbiinnddiinngg RReeaaddlliinnee key binding names. + bbuuiillttiinn Names of shell builtin commands. May also be + specified as --bb. + ccoommmmaanndd Command names. May also be specified as --cc. + ddiirreeccttoorryy + Directory names. May also be specified as --dd. + ddiissaabblleedd + Names of disabled shell builtins. + eennaabblleedd Names of enabled shell builtins. + eexxppoorrtt Names of exported shell variables. May also be + specified as --ee. + ffiillee File and directory names, similar to rreeaaddlliinnee's + filename completion. May also be specified as + --ff. + ffuunnccttiioonn + Names of shell functions. + ggrroouupp Group names. May also be specified as --gg. + hheellppttooppiicc + Help topics as accepted by the hheellpp builtin. + hhoossttnnaammee + Hostnames, as taken from the file specified by + the HHOOSSTTFFIILLEE shell variable. + jjoobb Job names, if job control is active. May also + be specified as --jj. + kkeeyywwoorrdd Shell reserved words. May also be specified as + --kk. + rruunnnniinngg Names of running jobs, if job control is active. + sseerrvviiccee Service names. May also be specified as --ss. + sseettoopptt Valid arguments for the --oo option to the sseett + builtin. + sshhoopptt Shell option names as accepted by the sshhoopptt + builtin. + ssiiggnnaall Signal names. + ssttooppppeedd Names of stopped jobs, if job control is active. + uusseerr User names. May also be specified as --uu. + vvaarriiaabbllee + Names of all shell variables. May also be spec- + ified as --vv. + --CC _c_o_m_m_a_n_d + _c_o_m_m_a_n_d is executed in a subshell environment, and its + output is used as the possible completions. Arguments + are passed as with the --FF option. + --FF _f_u_n_c_t_i_o_n + The shell function _f_u_n_c_t_i_o_n is executed in the current + shell environment. When the function is executed, the + first argument ($$11) is the name of the command whose ar- + guments are being completed, the second argument ($$22) is + the word being completed, and the third argument ($$33) is + the word preceding the word being completed on the cur- + rent command line. When _f_u_n_c_t_i_o_n finishes, programmable + completion retrieves the possible completions from the + value of the CCOOMMPPRREEPPLLYY array variable. + --GG _g_l_o_b_p_a_t + Expand the pathname expansion pattern _g_l_o_b_p_a_t to gener- + ate the possible completions. + --PP _p_r_e_f_i_x + Add _p_r_e_f_i_x to the beginning of each possible completion + after all other options have been applied. + --SS _s_u_f_f_i_x + Append _s_u_f_f_i_x to each possible completion after all + other options have been applied. + --WW _w_o_r_d_l_i_s_t + Split the _w_o_r_d_l_i_s_t using the characters in the IIFFSS spe- + cial variable as delimiters, and expand each resulting + word. Shell quoting is honored within _w_o_r_d_l_i_s_t, in or- + der to provide a mechanism for the words to contain + shell metacharacters or characters in the value of IIFFSS. + The possible completions are the members of the resul- + tant list which match a prefix of the word being com- + pleted. + --XX _f_i_l_t_e_r_p_a_t + _f_i_l_t_e_r_p_a_t is a pattern as used for pathname expansion. + It is applied to the list of possible completions gener- + ated by the preceding options and arguments, and each + completion matching _f_i_l_t_e_r_p_a_t is removed from the list. + A leading !! in _f_i_l_t_e_r_p_a_t negates the pattern; in this + case, any completion not matching _f_i_l_t_e_r_p_a_t is removed. + + The return value is true unless an invalid option is supplied, + an option other than --pp, --rr, --DD, --EE, or --II is supplied without a + _n_a_m_e argument, an attempt is made to remove a completion speci- + fication for a _n_a_m_e for which no specification exists, or an er- + ror occurs adding a completion specification. + + ccoommppoopptt [--oo _o_p_t_i_o_n] [--DDEEII] [++oo _o_p_t_i_o_n] [_n_a_m_e] + Modify completion options for each _n_a_m_e according to the _o_p_- + _t_i_o_ns, or for the currently-executing completion if no _n_a_m_es are + supplied. If no _o_p_t_i_o_ns are supplied, display the completion + options for each _n_a_m_e or the current completion. The possible + values of _o_p_t_i_o_n are those valid for the ccoommpplleettee builtin de- + scribed above. + + The --DD option indicates that other supplied options should apply + to the "default" command completion; the --EE option indicates + that other supplied options should apply to "empty" command com- + pletion; and the --II option indicates that other supplied options + should apply to completion on the initial word on the line. + These are determined in the same way as the ccoommpplleettee builtin. + + If multiple options are supplied, the --DD option takes precedence + over --EE, and both take precedence over --II. + + The return value is true unless an invalid option is supplied, + an attempt is made to modify the options for a _n_a_m_e for which no + completion specification exists, or an output error occurs. + + ccoonnttiinnuuee [_n] + ccoonnttiinnuuee resumes the next iteration of the enclosing ffoorr, wwhhiillee, + uunnttiill, or sseelleecctt loop. If _n is specified, bbaasshh resumes the _nth + enclosing loop. _n must be >= 1. If _n is greater than the num- + ber of enclosing loops, the shell resumes the last enclosing + loop (the "top-level" loop). The return value is 0 unless _n is + not greater than or equal to 1. + + ddeeccllaarree [--aaAAffFFggiiIIllnnrrttuuxx] [--pp] [_n_a_m_e[=_v_a_l_u_e] ...] + ttyyppeesseett [--aaAAffFFggiiIIllnnrrttuuxx] [--pp] [_n_a_m_e[=_v_a_l_u_e] ...] + Declare variables and/or give them attributes. If no _n_a_m_es are + given then display the values of variables or functions. The --pp + option will display the attributes and values of each _n_a_m_e. + When --pp is used with _n_a_m_e arguments, additional options, other + than --ff and --FF, are ignored. + + When --pp is supplied without _n_a_m_e arguments, ddeeccllaarree will display + the attributes and values of all variables having the attributes + specified by the additional options. If no other options are + supplied with --pp, ddeeccllaarree will display the attributes and values + of all shell variables. The --ff option restricts the display to + shell functions. + + The --FF option inhibits the display of function definitions; only + the function name and attributes are printed. If the eexxttddeebbuugg + shell option is enabled using sshhoopptt, the source file name and + line number where each _n_a_m_e is defined are displayed as well. + The --FF option implies --ff. + + The --gg option forces variables to be created or modified at the + global scope, even when ddeeccllaarree is executed in a shell function. + It is ignored when ddeeccllaarree is not executed in a shell function. + + The --II option causes local variables to inherit the attributes + (except the _n_a_m_e_r_e_f attribute) and value of any existing vari- + able with the same _n_a_m_e 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 vari- + ables with the specified attribute or to give variables attrib- + utes: + --aa Each _n_a_m_e is an indexed array variable (see AArrrraayyss + above). + --AA Each _n_a_m_e is an associative array variable (see AArrrraayyss + above). + --ff Each _n_a_m_e refers to a shell function. + --ii The variable is treated as an integer; arithmetic evalua- + tion (see AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN above) is performed when + the variable is assigned a value. + --ll When the variable is assigned a value, all upper-case + characters are converted to lower-case. The upper-case + attribute is disabled. + --nn Give each _n_a_m_e the _n_a_m_e_r_e_f attribute, making it a name + reference to another variable. That other variable is + defined by the value of _n_a_m_e. All references, assign- + ments, and attribute modifications to _n_a_m_e, except those + using or changing the --nn attribute itself, are performed + on the variable referenced by _n_a_m_e's value. The nameref + attribute cannot be applied to array variables. + --rr Make _n_a_m_es readonly. These names cannot then be assigned + values by subsequent assignment statements or unset. + --tt Give each _n_a_m_e the _t_r_a_c_e attribute. Traced functions in- + herit the DDEEBBUUGG and RREETTUURRNN traps from the calling shell. + The trace attribute has no special meaning for variables. + --uu When the variable is assigned a value, all lower-case + characters are converted to upper-case. The lower-case + attribute is disabled. + --xx Mark each _n_a_m_e for export to subsequent commands via the + environment. + + Using "+" instead of "-" turns off the specified attribute in- + stead, with the exceptions that ++aa and ++AA may not be used to de- + stroy array variables and ++rr will not remove the readonly at- + tribute. + + When used in a function, ddeeccllaarree and ttyyppeesseett make each _n_a_m_e lo- + cal, as with the llooccaall command, unless the --gg option is sup- + plied. If a variable name is followed by =_v_a_l_u_e, the value of + the variable is set to _v_a_l_u_e. When using --aa or --AA and the com- + pound 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 "-f foo=bar", an + attempt is made to assign a value to a readonly variable, an at- + tempt is made to assign a value to an array variable without us- + ing the compound assignment syntax (see AArrrraayyss above), one of + the _n_a_m_e_s 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 --ff. + + ddiirrss [[--ccllppvv]] [[++_n]] [[--_n]] + Without options, display the list of currently remembered direc- + tories. The default display is on a single line with directory + names separated by spaces. Directories are added to the list + with the ppuusshhdd command; the ppooppdd command removes entries from + the list. The current directory is always the first directory + in the stack. + + Options, if supplied, have the following meanings: + --cc Clears the directory stack by deleting all of the en- + tries. + --ll Produces a listing using full pathnames; the default + listing format uses a tilde to denote the home directory. + --pp Print the directory stack with one entry per line. + --vv Print the directory stack with one entry per line, pre- + fixing each entry with its index in the stack. + ++_n Displays the _nth entry counting from the left of the list + shown by ddiirrss when invoked without options, starting with + zero. + --_n Displays the _nth entry counting from the right of the + list shown by ddiirrss when invoked without options, starting + with zero. + + The return value is 0 unless an invalid option is supplied or _n + indexes beyond the end of the directory stack. + + ddiissoowwnn [--aarr] [--hh] [_i_d ...] + Without options, remove each _i_d from the table of active jobs. + Each _i_d may be a job specification _j_o_b_s_p_e_c or a process ID _p_i_d; + if _i_d is a _p_i_d, ddiissoowwnn uses the job containing _p_i_d as _j_o_b_s_p_e_c. + + If the --hh option is supplied, ddiissoowwnn does not remove the jobs + corresponding to each _i_d from the jobs table, but rather marks + them so the shell does not send SSIIGGHHUUPP to the job if the shell + receives a SSIIGGHHUUPP. + + If no _i_d is supplied, the --aa option means to remove or mark all + jobs; the --rr option without an _i_d argument removes or marks run- + ning jobs. If no _i_d is supplied, and neither the --aa nor the --rr + option is supplied, ddiissoowwnn removes or marks the current job. + + The return value is 0 unless an _i_d does not specify a valid job. + + eecchhoo [--nneeEE] [_a_r_g ...] + Output the _a_r_gs, separated by spaces, followed by a newline. + The return status is 0 unless a write error occurs. If --nn is + specified, the trailing newline is not printed. + + If the --ee option is given, eecchhoo interprets the following back- + slash-escaped characters. The --EE option disables interpretation + of these escape characters, even on systems where they are in- + terpreted by default. The xxppgg__eecchhoo shell option determines + whether or not eecchhoo interprets any options and expands these es- + cape characters. eecchhoo does not interpret ---- to mean the end of + options. + + eecchhoo interprets the following escape sequences: + \\aa alert (bell) + \\bb backspace + \\cc suppress further output + \\ee + \\EE an escape character + \\ff form feed + \\nn new line + \\rr carriage return + \\tt horizontal tab + \\vv vertical tab + \\\\ backslash + \\00_n_n_n The eight-bit character whose value is the octal value + _n_n_n (zero to three octal digits). + \\xx_H_H The eight-bit character whose value is the hexadecimal + value _H_H (one or two hex digits). + \\uu_H_H_H_H The Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value _H_H_H_H (one to four hex digits). + \\UU_H_H_H_H_H_H_H_H + The Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value _H_H_H_H_H_H_H_H (one to eight hex digits). + + eecchhoo writes any unrecognized backslash-escaped characters un- + changed. + + eennaabbllee [--aa] [--ddnnppss] [--ff _f_i_l_e_n_a_m_e] [_n_a_m_e ...] + Enable and disable builtin shell commands. Disabling a builtin + allows an executable file 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 files. + + If --nn is supplied, each _n_a_m_e is disabled; otherwise, _n_a_m_es are + enabled. For example, to use the tteesstt binary found using PPAATTHH + instead of the shell builtin version, run "enable -n test". + + If no _n_a_m_e arguments are supplied, or if the --pp option is sup- + plied, print a list of shell builtins. With no other option ar- + guments, the list consists of all enabled shell builtins. If --nn + is supplied, print only disabled builtins. If --aa is supplied, + the list printed includes all builtins, with an indication of + whether or not each is enabled. The --ss option means to restrict + the output to the POSIX _s_p_e_c_i_a_l builtins. + + The --ff option means to load the new builtin command _n_a_m_e from + shared object _f_i_l_e_n_a_m_e, on systems that support dynamic loading. + If _f_i_l_e_n_a_m_e does not contain a slash, BBaasshh will use the value of + the BBAASSHH__LLOOAADDAABBLLEESS__PPAATTHH variable as a colon-separated list of + directories in which to search for _f_i_l_e_n_a_m_e. The default for + BBAASSHH__LLOOAADDAABBLLEESS__PPAATTHH is system-dependent, and may include "." to + force a search of the current directory. The --dd option will + delete a builtin previously loaded with --ff. If _-_s is used with + _-_f, the new builtin becomes a POSIX special builtin. + + If no options are supplied and a _n_a_m_e is not a shell builtin, + eennaabbllee will attempt to load _n_a_m_e from a shared object named + _n_a_m_e, as if the command were "enable -f _n_a_m_e _n_a_m_e". + + The return value is 0 unless a _n_a_m_e is not a shell builtin or + there is an error loading a new builtin from a shared object. + + eevvaall [_a_r_g ...] + Concatenate the _a_r_gs together into a single command, separating + them with spaces. BBaasshh then reads and execute this command, and + returns its exit status as the return status of eevvaall. If there + are no _a_r_g_s, or only null arguments, eevvaall returns 0. + + eexxeecc [--ccll] [--aa _n_a_m_e] [_c_o_m_m_a_n_d [_a_r_g_u_m_e_n_t_s]] + If _c_o_m_m_a_n_d is specified, it replaces the shell without creating + a new process. _c_o_m_m_a_n_d cannot be a shell builtin or function. + The _a_r_g_u_m_e_n_t_s become the arguments to _c_o_m_m_a_n_d. If the --ll option + is supplied, the shell places a dash at the beginning of the ze- + roth argument passed to _c_o_m_m_a_n_d. This is what _l_o_g_i_n(1) does. + The --cc option causes _c_o_m_m_a_n_d to be executed with an empty envi- + ronment. If --aa is supplied, the shell passes _n_a_m_e as the zeroth + argument to the executed command. + + If _c_o_m_m_a_n_d cannot be executed for some reason, a non-interactive + shell exits, unless the eexxeeccffaaiill shell option is enabled. In + that case, it returns a non-zero status. An interactive shell + returns a non-zero status if the file cannot be executed. A + subshell exits unconditionally if eexxeecc fails. + + If _c_o_m_m_a_n_d is not specified, any redirections take effect in the + current shell, and the return status is 0. If there is a redi- + rection error, the return status is 1. + + eexxiitt [_n] + Cause the shell to exit with a status of _n. If _n is omitted, + the exit status is that of the last command executed. Any trap + on EEXXIITT is executed before the shell terminates. + + eexxppoorrtt [--ffnn] [_n_a_m_e[=_v_a_l_u_e]] ... + eexxppoorrtt --pp [[--ff]] + The supplied _n_a_m_e_s are marked for automatic export to the envi- + ronment of subsequently executed commands. If the --ff option is + given, the _n_a_m_e_s refer to functions. + + The --nn option unexports, or removes the export attribute, from + each _n_a_m_e. If no _n_a_m_e_s are given, or if only the --pp option is + supplied, eexxppoorrtt displays a list of names of all exported vari- + ables on the standard output. Using --pp and --ff together displays + exported functions. The --pp option displays output in a form + that may be reused as input. + + eexxppoorrtt allows the value of a variable to be set when it is ex- + ported or unexported by following the variable name with =_v_a_l_u_e. + This sets the value of the variable to _v_a_l_u_e while modifying the + export attribute. eexxppoorrtt returns an exit status of 0 unless an + invalid option is encountered, one of the _n_a_m_e_s is not a valid + shell variable name, or --ff is supplied with a _n_a_m_e that is not a + function. + + ffaallssee Does nothing; returns a non-zero status. + + ffcc [--ee _e_n_a_m_e] [--llnnrr] [_f_i_r_s_t] [_l_a_s_t] + ffcc --ss [_p_a_t=_r_e_p] [_c_m_d] + The first form selects a range of commands from _f_i_r_s_t to _l_a_s_t + from the history list and displays or edits and re-executes + them. _F_i_r_s_t and _l_a_s_t 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 _f_i_r_s_t or _l_a_s_t of 0 is equivalent to -1 and -0 is + equivalent to the current command (usually the ffcc command); oth- + erwise 0 is equivalent to -1 and -0 is invalid. If _l_a_s_t is not + specified, it is set to the current command for listing (so that + "fc -l -10" prints the last 10 commands) and to _f_i_r_s_t otherwise. + If _f_i_r_s_t is not specified, it is set to the previous command for + editing and -16 for listing. + + If the --ll option is supplied, the commands are listed on the + standard output. The --nn option suppresses the command numbers + when listing. The --rr option reverses the order of the commands. + + Otherwise, ffcc invokes the editor named by _e_n_a_m_e on a file con- + taining those commands. If _e_n_a_m_e is not supplied, ffcc uses the + value of the FFCCEEDDIITT variable, and the value of EEDDIITTOORR if FFCCEEDDIITT + is not set. If neither variable is set, ffcc uses _v_i_. When edit- + ing is complete, ffcc reads the file containing the edited com- + mands and echoes and executes them. + + In the second form, ffcc re-executes _c_o_m_m_a_n_d after replacing each + instance of _p_a_t with _r_e_p. _C_o_m_m_a_n_d is interpreted the same as + _f_i_r_s_t above. + + A useful alias to use with ffcc is "r="fc -s"", so that typing "r + cc" runs the last command beginning with "cc" and typing "r" re- + executes the last command. + + If the first form is used, the return value is zero unless an + invalid option is encountered or _f_i_r_s_t or _l_a_s_t specify history + lines out of range. When editing and re-executing a file of + commands, the return value is the value of the last command exe- + cuted or failure if an error occurs with the temporary file. If + the second form is used, the return status is that of the re-ex- + ecuted command, unless _c_m_d does not specify a valid history en- + try, in which case ffcc returns a non-zero status. + + ffgg [_j_o_b_s_p_e_c] + Resume _j_o_b_s_p_e_c in the foreground, and make it the current job. + If _j_o_b_s_p_e_c is not present, ffgg uses the shell's notion of the + _c_u_r_r_e_n_t _j_o_b. The return value is that of the command placed + into the foreground, or failure if run when job control is dis- + abled or, when run with job control enabled, if _j_o_b_s_p_e_c does not + specify a valid job or _j_o_b_s_p_e_c specifies a job that was started + without job control. + + ggeettooppttss _o_p_t_s_t_r_i_n_g _n_a_m_e [_a_r_g ...] + ggeettooppttss is used by shell scripts and functions to parse posi- + tional parameters and obtain options and their arguments. _o_p_t_- + _s_t_r_i_n_g 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, ggeettooppttss places the next option in the + shell variable _n_a_m_e, initializing _n_a_m_e if it does not exist, and + the index of the next argument to be processed into the variable + OOPPTTIINNDD. OOPPTTIINNDD is initialized to 1 each time the shell or a + shell script is invoked. When an option requires an argument, + ggeettooppttss places that argument into the variable OOPPTTAARRGG. + + The shell does not reset OOPPTTIINNDD automatically; it must be manu- + ally reset between multiple calls to ggeettooppttss within the same + shell invocation to use a new set of parameters. + + When it reaches the end of options, ggeettooppttss exits with a return + value greater than zero. OOPPTTIINNDD is set to the index of the + first non-option argument, and _n_a_m_e is set to ?. + + ggeettooppttss normally parses the positional parameters, but if more + arguments are supplied as _a_r_g values, ggeettooppttss parses those in- + stead. + + ggeettooppttss can report errors in two ways. If the first character + of _o_p_t_s_t_r_i_n_g is a colon, ggeettooppttss uses _s_i_l_e_n_t error reporting. + In normal operation, ggeettooppttss prints diagnostic messages when it + encounters invalid options or missing option arguments. If the + variable OOPPTTEERRRR is set to 0, ggeettooppttss does not display any error + messages, even if the first character of _o_p_t_s_t_r_i_n_g is not a + colon. + + If ggeettooppttss detects an invalid option, it places ? into _n_a_m_e and, + if not silent, prints an error message and unsets OOPPTTAARRGG. If + ggeettooppttss is silent, it assigns the option character found to OOPP-- + TTAARRGG and does not print a diagnostic message. + + If a required argument is not found, and ggeettooppttss is not silent, + it sets the value of _n_a_m_e to a question mark (??), unsets OOPPTTAARRGG, + and prints a diagnostic message. If ggeettooppttss is silent, it sets + the value of _n_a_m_e to a colon (::) and sets OOPPTTAARRGG to the option + character found. + + ggeettooppttss returns true if an option, specified or unspecified, is + found. It returns false if the end of options is encountered or + an error occurs. + + hhaasshh [--llrr] [--pp _f_i_l_e_n_a_m_e] [--ddtt] [_n_a_m_e] + Each time hhaasshh is invoked, it remembers the full pathname of the + command _n_a_m_e as determined by searching the directories in + $$PPAATTHH. Any previously-remembered pathname associated with _n_a_m_e + is discarded. If the --pp option is supplied, hhaasshh uses _f_i_l_e_n_a_m_e + as the full pathname of the command. + + The --rr option causes the shell to forget all remembered loca- + tions. Assigning to the PPAATTHH variable also clears all hashed + filenames. The --dd option causes the shell to forget the remem- + bered location of each _n_a_m_e. + + If the --tt option is supplied, hhaasshh prints the full pathname cor- + responding to each _n_a_m_e. If multiple _n_a_m_e arguments are sup- + plied with --tt, hhaasshh prints the _n_a_m_e before the corresponding + hashed full pathname. The --ll option displays output in a format + that may be reused as input. + + If no arguments are given, or if only --ll is supplied, hhaasshh + prints information about remembered commands. The --tt, --dd, and + --pp options (the options that act on the _n_a_m_e arguments) are mu- + tually exclusive. Only one will be active. If more than one is + supplied, --tt has higher priority than --pp, and both have higher + priority than --dd. + + The return status is zero unless a _n_a_m_e is not found or an in- + valid option is supplied. + + hheellpp [--ddmmss] [_p_a_t_t_e_r_n] + Display helpful information about builtin commands. If _p_a_t_t_e_r_n + is specified, hheellpp gives detailed help on all commands matching + _p_a_t_t_e_r_n as described below; otherwise it displays a list of all + the builtins and shell compound commands. + + Options, if supplied, have the follow meanings: + + --dd Display a short description of each _p_a_t_t_e_r_n + --mm Display the description of each _p_a_t_t_e_r_n in a manpage-like + format + --ss Display only a short usage synopsis for each _p_a_t_t_e_r_n + + If _p_a_t_t_e_r_n contains pattern matching characters (see PPaatttteerrnn + MMaattcchhiinngg above) it's treated as a shell pattern and hheellpp prints + the description of each help topic matching _p_a_t_t_e_r_n. + + If not, and _p_a_t_t_e_r_n exactly matches the name of a help topic, + hheellpp prints the description associated with that topic. Other- + wise, hheellpp performs prefix matching and prints the descriptions + of all matching help topics. + + The return status is 0 unless no command matches _p_a_t_t_e_r_n. + + hhiissttoorryy [[_n]] + hhiissttoorryy --cc + hhiissttoorryy --dd _o_f_f_s_e_t + hhiissttoorryy --dd _s_t_a_r_t-_e_n_d + hhiissttoorryy --aannrrww [_f_i_l_e_n_a_m_e] + hhiissttoorryy --pp _a_r_g [_a_r_g ...] + hhiissttoorryy --ss _a_r_g [_a_r_g ...] + With no options, display the command history list with numbers. + Entries prefixed with a ** have been modified. An argument of _n + lists only the last _n entries. If the shell variable HHIISSTTTTIIMMEE-- + FFOORRMMAATT is set and not null, it is used as a format string for + _s_t_r_f_t_i_m_e(3) to display the time stamp associated with each dis- + played history entry. If hhiissttoorryy uses HHIISSTTTTIIMMEEFFOORRMMAATT, it does + not print an intervening space between the formatted time stamp + and the history entry. + + If _f_i_l_e_n_a_m_e is supplied, hhiissttoorryy uses it as the name of the his- + tory file; if not, it uses the value of HHIISSTTFFIILLEE. If _f_i_l_e_n_a_m_e + is not supplied and HHIISSTTFFIILLEE is unset or null, the --aa,, --nn,, --rr,, + and --ww options have no effect. + + Options, if supplied, have the following meanings: + --cc Clear the history list by deleting all the entries. This + can be used with the other options to replace the history + list. + --dd _o_f_f_s_e_t + Delete the history entry at position _o_f_f_s_e_t. If _o_f_f_s_e_t + 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 hhiissttoorryy --dd command. + --dd _s_t_a_r_t-_e_n_d + Delete the range of history entries between positions + _s_t_a_r_t and _e_n_d, inclusive. Positive and negative values + for _s_t_a_r_t and _e_n_d are interpreted as described above. + --aa Append the "new" history lines to the history file. + These are history lines entered since the beginning of + the current bbaasshh session, but not already appended to the + history file. + --nn Read the history lines not already read from the history + file and add them to the current history list. These are + lines appended to the history file since the beginning of + the current bbaasshh session. + --rr Read the history file and append its contents to the cur- + rent history list. + --ww Write the current history list to the history file, over- + writing the history file. + --pp Perform history substitution on the following _a_r_g_s and + display the result on the standard output, without stor- + ing the results in the history list. Each _a_r_g must be + quoted to disable normal history expansion. + --ss Store the _a_r_g_s in the history list as a single entry. + The last command in the history list is removed before + adding the _a_r_g_s. + + If the HHIISSTTTTIIMMEEFFOORRMMAATT variable is set, hhiissttoorryy writes the time + stamp information associated with each history entry to the his- + tory file, marked with the history comment character as de- + scribed above. 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 _o_f_f_s_e_t or range is supplied as an argument to --dd, or the + history expansion supplied as an argument to --pp fails. + + jjoobbss [--llnnpprrss] [ _j_o_b_s_p_e_c ... ] + jjoobbss --xx _c_o_m_m_a_n_d [ _a_r_g_s ... ] + The first form lists the active jobs. The options have the fol- + lowing meanings: + --ll List process IDs in addition to the normal information. + --nn Display information only about jobs that have changed + status since the user was last notified of their status. + --pp List only the process ID of the job's process group + leader. + --rr Display only running jobs. + --ss Display only stopped jobs. + + If _j_o_b_s_p_e_c is supplied, jjoobbss restricts output to information + about that job. The return status is 0 unless an invalid option + is encountered or an invalid _j_o_b_s_p_e_c is supplied. + + If the --xx option is supplied, jjoobbss replaces any _j_o_b_s_p_e_c found in + _c_o_m_m_a_n_d or _a_r_g_s with the corresponding process group ID, and ex- + ecutes _c_o_m_m_a_n_d, passing it _a_r_g_s, returning its exit status. + + kkiillll [--ss _s_i_g_s_p_e_c | --nn _s_i_g_n_u_m | --_s_i_g_s_p_e_c] _i_d [ ... ] + kkiillll --ll|--LL [_s_i_g_s_p_e_c | _e_x_i_t___s_t_a_t_u_s] + Send the signal specified by _s_i_g_s_p_e_c or _s_i_g_n_u_m to the processes + named by each _i_d. Each _i_d may be a job specification _j_o_b_s_p_e_c or + a process ID _p_i_d. _s_i_g_s_p_e_c is either a case-insensitive signal + name such as SSIIGGKKIILLLL (with or without the SSIIGG prefix) or a sig- + nal number; _s_i_g_n_u_m is a signal number. If _s_i_g_s_p_e_c is not sup- + plied, then kkiillll sends SSIIGGTTEERRMM. + + The --ll option lists the signal names. If any arguments are sup- + plied when --ll is given, kkiillll lists the names of the signals cor- + responding to the arguments, and the return status is 0. The + _e_x_i_t___s_t_a_t_u_s argument to --ll is a number specifying either a sig- + nal number or the exit status of a process terminated by a sig- + nal; if it is supplied, kkiillll prints the name of the signal that + caused the process to terminate. kkiillll assumes that process exit + statuses are greater than 128; anything less than that is a sig- + nal number. The --LL option is equivalent to --ll. + + kkiillll returns true if at least one signal was successfully sent, + or false if an error occurs or an invalid option is encountered. + + lleett _a_r_g [_a_r_g ...] + Each _a_r_g is evaluated as an arithmetic expression (see AARRIITTHH-- + MMEETTIICC EEVVAALLUUAATTIIOONN above). If the last _a_r_g evaluates to 0, lleett + returns 1; otherwise lleett returns 0. + + llooccaall [_o_p_t_i_o_n] [_n_a_m_e[=_v_a_l_u_e] ... | - ] + For each argument, create a local variable named _n_a_m_e and assign + it _v_a_l_u_e. The _o_p_t_i_o_n can be any of the options accepted by ddee-- + ccllaarree. When llooccaall is used within a function, it causes the + variable _n_a_m_e to have a visible scope restricted to that func- + tion and its children. It is an error to use llooccaall when not + within a function. + + If _n_a_m_e is -, it makes the set of shell options local to the + function in which llooccaall is invoked: any shell options changed + using the sseett builtin inside the function after the call to lloo-- + ccaall are restored to their original values when the function re- + turns. The restore is performed as if a series of sseett commands + were executed to restore the values that were in place before + the function. + + With no operands, llooccaall writes a list of local variables to the + standard output. + + The return status is 0 unless llooccaall is used outside a function, + an invalid _n_a_m_e is supplied, or _n_a_m_e is a readonly variable. + + llooggoouutt [[_n]] + Exit a login shell, returning a status of _n to the shell's par- + ent. + + mmaappffiillee [--dd _d_e_l_i_m] [--nn _c_o_u_n_t] [--OO _o_r_i_g_i_n] [--ss _c_o_u_n_t] [--tt] [--uu _f_d] [--CC + _c_a_l_l_b_a_c_k] [--cc _q_u_a_n_t_u_m] [_a_r_r_a_y] + rreeaaddaarrrraayy [--dd _d_e_l_i_m] [--nn _c_o_u_n_t] [--OO _o_r_i_g_i_n] [--ss _c_o_u_n_t] [--tt] [--uu _f_d] [--CC + _c_a_l_l_b_a_c_k] [--cc _q_u_a_n_t_u_m] [_a_r_r_a_y] + Read lines from the standard input, or from file descriptor _f_d + if the --uu option is supplied, into the indexed array variable + _a_r_r_a_y. The variable MMAAPPFFIILLEE is the default _a_r_r_a_y. Options, if + supplied, have the following meanings: + --dd Use the first character of _d_e_l_i_m to terminate each input + line, rather than newline. If _d_e_l_i_m is the empty string, + mmaappffiillee will terminate a line when it reads a NUL charac- + ter. + --nn Copy at most _c_o_u_n_t lines. If _c_o_u_n_t is 0, copy all lines. + --OO Begin assigning to _a_r_r_a_y at index _o_r_i_g_i_n. The default + index is 0. + --ss Discard the first _c_o_u_n_t lines read. + --tt Remove a trailing _d_e_l_i_m (default newline) from each line + read. + --uu Read lines from file descriptor _f_d instead of the stan- + dard input. + --CC Evaluate _c_a_l_l_b_a_c_k each time _q_u_a_n_t_u_m lines are read. The + --cc option specifies _q_u_a_n_t_u_m. + --cc Specify the number of lines read between each call to + _c_a_l_l_b_a_c_k. + + If --CC is specified without --cc, the default quantum is 5000. + When _c_a_l_l_b_a_c_k 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. _c_a_l_l_b_a_c_k is evaluated after + the line is read but before the array element is assigned. + + If not supplied with an explicit origin, mmaappffiillee will clear _a_r_- + _r_a_y before assigning to it. + + mmaappffiillee returns zero unless an invalid option or option argument + is supplied, _a_r_r_a_y is invalid or unassignable, or if _a_r_r_a_y is + not an indexed array. + + ppooppdd [-nn] [+_n] [-_n] + Remove entries from the directory stack. The elements are num- + bered from 0 starting at the first directory listed by ddiirrss, so + ppooppdd is equivalent to "popd +0." With no arguments, ppooppdd re- + moves the top directory from the stack, and changes to the new + top directory. Arguments, if supplied, have the following mean- + ings: + --nn Suppress the normal change of directory when removing di- + rectories from the stack, only manipulate the stack. + ++_n Remove the _nth entry counting from the left of the list + shown by ddiirrss, starting with zero, from the stack. For + example: "popd +0" removes the first directory, "popd +1" + the second. + --_n Remove the _nth entry counting from the right of the list + shown by ddiirrss, starting with zero. For example: "popd + -0" removes the last directory, "popd -1" the next to + last. + + If the top element of the directory stack is modified, and the + _-_n option was not supplied, ppooppdd uses the ccdd builtin to change + to the directory at the top of the stack. If the ccdd fails, ppooppdd + returns a non-zero value. + + Otherwise, ppooppdd returns false if an invalid option is supplied, + the directory stack is empty, or _n specifies a non-existent di- + rectory stack entry. + + If the ppooppdd command is successful, bbaasshh runs ddiirrss to show the + final contents of the directory stack, and the return status is + 0. + + pprriinnttff [--vv _v_a_r] _f_o_r_m_a_t [_a_r_g_u_m_e_n_t_s] + Write the formatted _a_r_g_u_m_e_n_t_s to the standard output under the + control of the _f_o_r_m_a_t. The --vv option assigns the output to the + variable _v_a_r rather than printing it to the standard output. + + The _f_o_r_m_a_t 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 _a_r_g_u_m_e_n_t. In + addition to the standard _p_r_i_n_t_f(3) format characters ccCCssSS-- + nnddiioouuxxXXeeEEffFFggGGaaAA, pprriinnttff interprets the following additional for- + mat specifiers: + %%bb causes pprriinnttff to expand backslash escape sequences in the + corresponding _a_r_g_u_m_e_n_t in the same way as eecchhoo --ee. + %%qq causes pprriinnttff to output the corresponding _a_r_g_u_m_e_n_t in a + format that can be reused as shell input. %%qq and %%QQ use + the $$'''' quoting style if any characters in the argument + string require it, and backslash quoting otherwise. If + the format string uses the _p_r_i_n_t_f alternate form, these + two formats quote the argument string using single + quotes. + %%QQ like %%qq, but applies any supplied precision to the _a_r_g_u_- + _m_e_n_t before quoting it. + %%((_d_a_t_e_f_m_t))TT + causes pprriinnttff to output the date-time string resulting + from using _d_a_t_e_f_m_t as a format string for _s_t_r_f_t_i_m_e(3). + The corresponding _a_r_g_u_m_e_n_t is an integer representing the + number of seconds since the epoch. This format specifier + recognizes two special argument values: -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 supplied. This is an exception to the + usual pprriinnttff behavior. + + The %b, %q, and %T format specifiers 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 ar- + gument, which usually contains more characters than the origi- + nal. + + The %n format specifier accepts a corresponding argument that is + treated as a shell variable name. + + The %s and %c format specifiers accept an l (long) modifier, + which forces them to convert the argument string to a wide-char- + acter string and apply any supplied field width and precision in + terms of characters, not bytes. The %S and %C format specifiers + are equivalent to %ls and %lc, respectively. + + Arguments to non-string format specifiers are treated as C con- + stants, 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 numeric value of the following character, using the cur- + rent locale. + + The _f_o_r_m_a_t is reused as necessary to consume all of the _a_r_g_u_- + _m_e_n_t_s. If the _f_o_r_m_a_t requires more _a_r_g_u_m_e_n_t_s 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 if an invalid option is sup- + plied or a write or assignment error occurs. + + ppuusshhdd [--nn] [+_n] [-_n] + ppuusshhdd [--nn] [_d_i_r] + Add a directory to the top of the directory stack, or rotate the + stack, making the new top of the stack the current working di- + rectory. With no arguments, ppuusshhdd exchanges the top two ele- + ments of the directory stack. Arguments, if supplied, have the + following meanings: + --nn Suppress the normal change of directory when rotating or + adding directories to the stack, only manipulate the + stack. + ++_n Rotate the stack so that the _nth directory (counting from + the left of the list shown by ddiirrss, starting with zero) + is at the top. + --_n Rotates the stack so that the _nth directory (counting + from the right of the list shown by ddiirrss, starting with + zero) is at the top. + _d_i_r Adds _d_i_r to the directory stack at the top. + + After the stack has been modified, if the --nn option was not sup- + plied, ppuusshhdd uses the ccdd builtin to change to the directory at + the top of the stack. If the ccdd fails, ppuusshhdd returns a non-zero + value. + + Otherwise, if no arguments are supplied, ppuusshhdd returns zero un- + less the directory stack is empty. When rotating the directory + stack, ppuusshhdd returns zero unless the directory stack is empty or + _n specifies a non-existent directory stack element. + + If the ppuusshhdd command is successful, bbaasshh runs ddiirrss to show the + final contents of the directory stack. + + ppwwdd [--LLPP] + Print the absolute pathname of the current working directory. + The pathname printed contains no symbolic links if the --PP option + is supplied or the --oo pphhyyssiiccaall option to the sseett builtin command + is enabled. If the --LL 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 in- + valid option is supplied. + + rreeaadd [--EEeerrss] [--aa _a_n_a_m_e] [--dd _d_e_l_i_m] [--ii _t_e_x_t] [--nn _n_c_h_a_r_s] [--NN _n_c_h_a_r_s] + [--pp _p_r_o_m_p_t] [--tt _t_i_m_e_o_u_t] [--uu _f_d] [_n_a_m_e ...] + Read one line from the standard input, or from the file descrip- + tor _f_d supplied as an argument to the --uu option, split it into + words as described above under WWoorrdd SSpplliittttiinngg, and assign the + first word to the first _n_a_m_e, the second word to the second + _n_a_m_e, and so on. If there are more words than names, the re- + maining words and their intervening delimiters are assigned to + the last _n_a_m_e. If there are fewer words read from the input + stream than names, the remaining names are assigned empty val- + ues. The characters in the value of the IIFFSS variable are used + to split the line into words using the same rules the shell uses + for expansion (described above under WWoorrdd SSpplliittttiinngg). The back- + slash character (\\) removes any special meaning for the next + character read and is used for line continuation. + + Options, if supplied, have the following meanings: + --aa _a_n_a_m_e + The words are assigned to sequential indices of the array + variable _a_n_a_m_e, starting at 0. _a_n_a_m_e is unset before any + new values are assigned. Other _n_a_m_e arguments are ig- + nored. + --dd _d_e_l_i_m + The first character of _d_e_l_i_m terminates the input line, + rather than newline. If _d_e_l_i_m is the empty string, rreeaadd + will terminate a line when it reads a NUL character. + --ee If the standard input is coming from a terminal, rreeaadd + uses rreeaaddlliinnee (see RREEAADDLLIINNEE above) to obtain the line. + RReeaaddlliinnee uses the current (or default, if line editing + was not previously active) editing settings, but uses + rreeaaddlliinnee's default filename completion. + --EE If the standard input is coming from a terminal, rreeaadd + uses rreeaaddlliinnee (see RREEAADDLLIINNEE above) to obtain the line. + RReeaaddlliinnee uses the current (or default, if line editing + was not previously active) editing settings, but uses + bash's default completion, including programmable comple- + tion. + --ii _t_e_x_t + If rreeaaddlliinnee is being used to read the line, rreeaadd places + _t_e_x_t into the editing buffer before editing begins. + --nn _n_c_h_a_r_s + rreeaadd returns after reading _n_c_h_a_r_s characters rather than + waiting for a complete line of input, unless it encoun- + ters EOF or rreeaadd times out, but honors a delimiter if it + reads fewer than _n_c_h_a_r_s characters before the delimiter. + --NN _n_c_h_a_r_s + rreeaadd returns after reading exactly _n_c_h_a_r_s characters + rather than waiting for a complete line of input, unless + it encounters EOF or rreeaadd times out. Any delimiter char- + acters in the input are not treated specially and do not + cause rreeaadd to return until it has read _n_c_h_a_r_s characters. + The result is not split on the characters in IIFFSS; the in- + tent is that the variable is assigned exactly the charac- + ters read (with the exception of backslash; see the --rr + option below). + --pp _p_r_o_m_p_t + Display _p_r_o_m_p_t on standard error, without a trailing new- + line, before attempting to read any input, but only if + input is coming from a terminal. + --rr Backslash does not act as an escape character. The back- + slash is considered to be part of the line. In particu- + lar, a backslash-newline pair may not then be used as a + line continuation. + --ss Silent mode. If input is coming from a terminal, charac- + ters are not echoed. + --tt _t_i_m_e_o_u_t + Cause rreeaadd to time out and return failure if it does not + read a complete line of input (or a specified number of + characters) within _t_i_m_e_o_u_t seconds. _t_i_m_e_o_u_t may be a + decimal number with a fractional portion following the + decimal point. This option is only effective if rreeaadd is + reading input from a terminal, pipe, or other special + file; it has no effect when reading from regular files. + If rreeaadd times out, it saves any partial input read into + the specified variable _n_a_m_e, and the exit status is + greater than 128. If _t_i_m_e_o_u_t is 0, rreeaadd returns immedi- + ately, without trying to read any data. In this case, + the exit status is 0 if input is available on the speci- + fied file descriptor, or the read will return EOF, non- + zero otherwise. + --uu _f_d Read input from file descriptor _f_d instead of the stan- + dard input. + + Other than the case where _d_e_l_i_m is the empty string, rreeaadd ig- + nores any NUL characters in the input. + + If no _n_a_m_e_s are supplied, rreeaadd assigns the line read, without + the ending delimiter but otherwise unmodified, to the variable + RREEPPLLYY. + + The exit status is zero, unless end-of-file is encountered, rreeaadd + times out (in which case the status is greater than 128), a + variable assignment error (such as assigning to a readonly vari- + able) occurs, or an invalid file descriptor is supplied as the + argument to --uu. + + rreeaaddoonnllyy [--aaAAff] [--pp] [_n_a_m_e[=_w_o_r_d] ...] + The given _n_a_m_e_s are marked readonly; the values of these _n_a_m_e_s + may not be changed by subsequent assignment or unset. If the --ff + option is supplied, each _n_a_m_e refers to a shell function. The + --aa option restricts the variables to indexed arrays; the --AA op- + tion restricts the variables to associative arrays. If both op- + tions are supplied, --AA takes precedence. If no _n_a_m_e arguments + are supplied, or if the --pp option is supplied, print a list of + all readonly names. The other options may be used to restrict + the output to a subset of the set of readonly names. The --pp op- + tion displays output in a format that may be reused as input. + + rreeaaddoonnllyy allows the value of a variable to be set at the same + time the readonly attribute is changed by following the variable + name with =_v_a_l_u_e. This sets the value of the variable is to + _v_a_l_u_e while modifying the readonly attribute. + + The return status is 0 unless an invalid option is encountered, + one of the _n_a_m_e_s is not a valid shell variable name, or --ff is + supplied with a _n_a_m_e that is not a function. + + rreettuurrnn [_n] + Stop executing a shell function or sourced file and return the + value specified by _n to its caller. If _n is omitted, the return + status is that of the last command executed. If rreettuurrnn is exe- + cuted by a trap handler, the last command used to determine the + status is the last command executed before the trap handler. If + rreettuurrnn is executed during a DDEEBBUUGG trap, the last command used to + determine the status is the last command executed by the trap + handler before rreettuurrnn was invoked. + + When rreettuurrnn is used to terminate execution of a script being ex- + ecuted by the .. (ssoouurrccee) command, it causes the shell to stop + executing that script and return either _n or the exit status of + the last command executed within the script as the exit status + of the script. If _n is supplied, the return value is its least + significant 8 bits. + + Any command associated with the RREETTUURRNN trap is executed before + execution resumes after the function or script. + + The return status is non-zero if rreettuurrnn is supplied a non-nu- + meric argument, or is used outside a function and not during ex- + ecution of a script by .. or ssoouurrccee. + + sseett [--aabbeeffhhkkmmnnppttuuvvxxBBCCEEHHPPTT] [--oo _o_p_t_i_o_n_-_n_a_m_e] [----] [--] [_a_r_g ...] + sseett [++aabbeeffhhkkmmnnppttuuvvxxBBCCEEHHPPTT] [++oo _o_p_t_i_o_n_-_n_a_m_e] [----] [--] [_a_r_g ...] + sseett --oo + sseett ++oo Without options, display the name and value of each shell vari- + able in a format that can be reused as input for setting or re- + setting the currently-set variables. Read-only variables cannot + be reset. In posix mode, 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 argu- + ments remaining after option processing are treated as values + for the positional parameters and are assigned, in order, to $$11, + $$22, ..., $$_n. Options, if specified, have the following mean- + ings: + --aa Each variable or function that is created or modified is + given the export attribute and marked for export to the + environment of subsequent commands. + --bb Report the status of terminated background jobs immedi- + ately, rather than before the next primary prompt or af- + ter a foreground command terminates. This is effective + only when job control is enabled. + --ee Exit immediately if a _p_i_p_e_l_i_n_e (which may consist of a + single _s_i_m_p_l_e _c_o_m_m_a_n_d), a _l_i_s_t, or a _c_o_m_p_o_u_n_d _c_o_m_m_a_n_d + (see SSHHEELLLL GGRRAAMMMMAARR 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 wwhhiillee + or uunnttiill reserved word, part of the test following the + iiff or eelliiff reserved words, part of any command executed + in a &&&& or |||| list except the command following the fi- + nal &&&& or ||||, any command in a pipeline but the last + (subject to the state of the ppiippeeffaaiill shell option), or + if the command's return value is being inverted with !!. + If a compound command other than a subshell returns a + non-zero status because a command failed while --ee was + being ignored, the shell does not exit. A trap on EERRRR, + if set, is executed before the shell exits. This option + applies to the shell environment and each subshell envi- + ronment separately (see CCOOMMMMAANNDD EEXXEECCUUTTIIOONN EENNVVIIRROONNMMEENNTT + above), and may cause subshells to exit before executing + all the commands in the subshell. + + If a compound command or shell function executes in a + context where --ee is being ignored, none of the commands + executed within the compound command or function body + will be affected by the --ee setting, even if --ee is set + and a command returns a failure status. If a compound + command or shell function sets --ee while executing in a + context where --ee is ignored, that setting will not have + any effect until the compound command or the command + containing the function call completes. + --ff Disable pathname expansion. + --hh Remember the location of commands as they are looked up + for execution. This is enabled by default. + --kk All arguments in the form of assignment statements are + placed in the environment for a command, not just those + that precede the command name. + --mm Monitor mode. Job control is enabled. This option is + on by default for interactive shells on systems that + support it (see JJOOBB CCOONNTTRROOLL above). All processes run + in a separate process group. When a background job com- + pletes, the shell prints a line containing its exit sta- + tus. + --nn Read commands but do not execute them. This may be used + to check a shell script for syntax errors. This is ig- + nored by interactive shells. + --oo _o_p_t_i_o_n_-_n_a_m_e + The _o_p_t_i_o_n_-_n_a_m_e can be one of the following: + aalllleexxppoorrtt + Same as --aa. + bbrraacceeeexxppaanndd + Same as --BB. + eemmaaccss Use an emacs-style command line editing inter- + face. This is enabled by default when the shell + is interactive, unless the shell is started with + the ----nnooeeddiittiinngg option. This also affects the + editing interface used for rreeaadd --ee. + eerrrreexxiitt Same as --ee. + eerrrrttrraaccee + Same as --EE. + ffuunnccttrraaccee + Same as --TT. + hhaasshhaallll Same as --hh. + hhiisstteexxppaanndd + Same as --HH. + hhiissttoorryy Enable command history, as described above under + HHIISSTTOORRYY. This option is on by default in inter- + active shells. + iiggnnoorreeeeooff + The effect is as if the shell command + "IGNOREEOF=10" had been executed (see SShheellll + VVaarriiaabblleess above). + kkeeyywwoorrdd Same as --kk. + mmoonniittoorr Same as --mm. + nnoocclloobbbbeerr + Same as --CC. + nnooeexxeecc Same as --nn. + nnoogglloobb Same as --ff. + nnoolloogg Currently ignored. + nnoottiiffyy Same as --bb. + nnoouunnsseett Same as --uu. + oonneeccmmdd Same as --tt. + pphhyyssiiccaall + Same as --PP. + ppiippeeffaaiill + 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. + ppoossiixx Enable posix mode; change the behavior of bbaasshh + where the default operation differs from the + POSIX standard to match the standard. See SSEEEE + AALLSSOO below for a reference to a document that + details how posix mode affects bash's behavior. + pprriivviilleeggeedd + Same as --pp. + vveerrbboossee Same as --vv. + vvii Use a vi-style command line editing interface. + This also affects the editing interface used for + rreeaadd --ee. + xxttrraaccee Same as --xx. + If --oo is supplied with no _o_p_t_i_o_n_-_n_a_m_e, sseett prints the + current shell option settings. If ++oo is supplied with + no _o_p_t_i_o_n_-_n_a_m_e, sseett prints a series of sseett commands to + recreate the current option settings on the standard + output. + --pp Turn on _p_r_i_v_i_l_e_g_e_d mode. In this mode, the shell does + not read the $$EENNVV and $$BBAASSHH__EENNVV files, shell functions + are not inherited from the environment, and the SSHHEELL-- + LLOOPPTTSS, BBAASSHHOOPPTTSS, CCDDPPAATTHH, and GGLLOOBBIIGGNNOORREE 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 --pp option is + not supplied, these actions are taken and the effective + user id is set to the real user id. If the --pp 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. + --rr Enable restricted shell mode. This option cannot be un- + set once it has been set. + --tt Exit after reading and executing one command. + --uu Treat unset variables and parameters other than the spe- + cial parameters "@" and "*", or array variables sub- + scripted 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. + --vv Print shell input lines as they are read. + --xx After expanding each _s_i_m_p_l_e _c_o_m_m_a_n_d, ffoorr command, ccaassee + command, sseelleecctt command, or arithmetic ffoorr command, dis- + play the expanded value of PPSS44, followed by the command + and its expanded arguments or associated word list, to + the standard error. + --BB The shell performs brace expansion (see BBrraaccee EExxppaannssiioonn + above). This is on by default. + --CC If set, bbaasshh does not overwrite an existing file with + the >>, >>&&, and <<>> redirection operators. Using the + redirection operator >>|| instead of >> will override this + and force the creation of an output file. + --EE If set, any trap on EERRRR is inherited by shell functions, + command substitutions, and commands executed in a sub- + shell environment. The EERRRR trap is normally not inher- + ited in such cases. + --HH Enable !! style history substitution. This option is on + by default when the shell is interactive. + --PP If set, the shell does not resolve symbolic links when + executing commands such as ccdd that change the current + working directory. It uses the physical directory + structure instead. By default, bbaasshh follows the logical + chain of directories when performing commands which + change the current directory. + --TT If set, any traps on DDEEBBUUGG and RREETTUURRNN are inherited by + shell functions, command substitutions, and commands ex- + ecuted in a subshell environment. The DDEEBBUUGG and RREETTUURRNN + traps are normally not inherited in such cases. + ---- If no arguments follow this option, unset the positional + parameters. Otherwise, set the positional parameters to + the _a_r_gs, even if some of them begin with a --. + -- Signal the end of options, and assign all remaining _a_r_gs + to the positional parameters. The --xx and --vv options are + turned off. If there are no _a_r_gs, the positional para- + meters remain unchanged. + + The options are off by default unless otherwise noted. Using + + rather than - causes these options to be turned off. The op- + tions can also be specified as arguments to an invocation of the + shell. The current set of options may be found in $$--. The re- + turn status is always zero unless an invalid option is encoun- + tered. + + sshhiifftt [_n] + Rename positional parameters from _n+1 ... to $$11 ........ Parameters + represented by the numbers $$## down to $$##-_n+1 are unset. _n must + be a non-negative number less than or equal to $$##. If _n is 0, + no parameters are changed. If _n is not given, it is assumed to + be 1. If _n is greater than $$##, the positional parameters are + not changed. The return status is greater than zero if _n is + greater than $$## or less than zero; otherwise 0. + + sshhoopptt [--ppqqssuu] [--oo] [_o_p_t_n_a_m_e ...] + Toggle the values of settings controlling optional shell behav- + ior. The settings can be either those listed below, or, if the + --oo option is used, those available with the --oo option to the sseett + builtin command. + + With no options, or with the --pp option, display a list of all + settable options, with an indication of whether or not each is + set; if any _o_p_t_n_a_m_e_s are supplied, the output is restricted to + those options. The --pp option displays output in a form that may + be reused as input. + + Other options have the following meanings: + --ss Enable (set) each _o_p_t_n_a_m_e. + --uu Disable (unset) each _o_p_t_n_a_m_e. + --qq Suppresses normal output (quiet mode); the return status + indicates whether the _o_p_t_n_a_m_e is set or unset. If multi- + ple _o_p_t_n_a_m_e arguments are supplied with --qq, the return + status is zero if all _o_p_t_n_a_m_e_s are enabled; non-zero oth- + erwise. + --oo Restricts the values of _o_p_t_n_a_m_e to be those defined for + the --oo option to the sseett builtin. + + If either --ss or --uu is used with no _o_p_t_n_a_m_e arguments, sshhoopptt + shows only those options which are set or unset, respectively. + Unless otherwise noted, the sshhoopptt options are disabled (unset) + by default. + + The return status when listing options is zero if all _o_p_t_n_a_m_e_s + are enabled, non-zero otherwise. When setting or unsetting op- + tions, the return status is zero unless an _o_p_t_n_a_m_e is not a + valid shell option. + + The list of sshhoopptt options is: + + aarrrraayy__eexxppaanndd__oonnccee + If set, the shell suppresses multiple evaluation of as- + sociative and indexed array subscripts during arithmetic + expression evaluation, while executing builtins that can + perform variable assignments, and while executing + builtins that perform array dereferencing. + aassssoocc__eexxppaanndd__oonnccee + Deprecated; a synonym for aarrrraayy__eexxppaanndd__oonnccee. + aauuttooccdd If set, a command name that is the name of a directory + is executed as if it were the argument to the ccdd com- + mand. This option is only used by interactive shells. + bbaasshh__ssoouurrccee__ffuullllppaatthh + If set, filenames added to the BBAASSHH__SSOOUURRCCEE array vari- + able are converted to full pathnames (see SShheellll VVaarrii-- + aabblleess above). + ccddaabbllee__vvaarrss + If set, an argument to the ccdd builtin command that is + not a directory is assumed to be the name of a variable + whose value is the directory to change to. + ccddssppeellll If set, the ccdd command attempts to correct minor errors + in the spelling of a directory component. Minor errors + include transposed characters, a missing character, and + one extra character. If ccdd corrects the directory name, + it prints the corrected filename, and the command pro- + ceeds. This option is only used by interactive shells. + cchheecckkhhaasshh + If set, bbaasshh checks that a command found in the hash ta- + ble exists before trying to execute it. If a hashed + command no longer exists, bbaasshh performs a normal path + search. + cchheecckkjjoobbss + If set, bbaasshh lists the status of any stopped and running + jobs before exiting an interactive shell. If any jobs + are running, bbaasshh defers the exit until a second exit is + attempted without an intervening command (see JJOOBB CCOONN-- + TTRROOLL above). The shell always postpones exiting if any + jobs are stopped. + cchheecckkwwiinnssiizzee + If set, bbaasshh checks the window size after each external + (non-builtin) command and, if necessary, updates the + values of LLIINNEESS and CCOOLLUUMMNNSS, using the file descriptor + associated with the standard error if it is a terminal. + This option is enabled by default. + ccmmddhhiisstt If set, bbaasshh 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 above under HHIISSTTOORRYY. + ccoommppaatt3311 + ccoommppaatt3322 + ccoommppaatt4400 + ccoommppaatt4411 + ccoommppaatt4422 + ccoommppaatt4433 + ccoommppaatt4444 + These control aspects of the shell's compatibility mode + (see SSHHEELLLL CCOOMMPPAATTIIBBIILLIITTYY MMOODDEE below). + ccoommpplleettee__ffuullllqquuoottee + If set, bbaasshh quotes all shell metacharacters in file- + names and directory names when performing completion. + If not set, bbaasshh removes metacharacters such as the dol- + lar 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 ex- + pand 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 back- + slashes to quote completed filenames. This variable is + set by default, which is the default bash behavior in + versions through 4.2. + ddiirreexxppaanndd + If set, bbaasshh replaces directory names with the results + of word expansion when performing filename completion. + This changes the contents of the rreeaaddlliinnee editing + buffer. If not set, bbaasshh attempts to preserve what the + user typed. + ddiirrssppeellll + If set, bbaasshh attempts spelling correction on directory + names during word completion if the directory name ini- + tially supplied does not exist. + ddoottgglloobb If set, bbaasshh includes filenames beginning with a "." in + the results of pathname expansion. The filenames _. and + _._. must always be matched explicitly, even if ddoottgglloobb is + set. + eexxeeccffaaiill + If set, a non-interactive shell will not exit if it can- + not execute the file specified as an argument to the + eexxeecc builtin. An interactive shell does not exit if + eexxeecc fails. + eexxppaanndd__aalliiaasseess + If set, aliases are expanded as described above under + AALLIIAASSEESS. This option is enabled by default for interac- + tive shells. + eexxttddeebbuugg + If set at shell invocation, or in a shell startup file, + arrange to execute the debugger profile before the shell + starts, identical to the ----ddeebbuuggggeerr option. If set af- + ter invocation, behavior intended for use by debuggers + is enabled: + 11.. The --FF option to the ddeeccllaarree builtin displays the + source file name and line number corresponding to + each function name supplied as an argument. + 22.. If the command run by the DDEEBBUUGG trap returns a + non-zero value, the next command is skipped and + not executed. + 33.. If the command run by the DDEEBBUUGG trap returns a + value of 2, and the shell is executing in a sub- + routine (a shell function or a shell script exe- + cuted by the .. or ssoouurrccee builtins), the shell + simulates a call to rreettuurrnn. + 44.. BBAASSHH__AARRGGCC and BBAASSHH__AARRGGVV are updated as described + in their descriptions above). + 55.. Function tracing is enabled: command substitu- + tion, shell functions, and subshells invoked with + (( _c_o_m_m_a_n_d )) inherit the DDEEBBUUGG and RREETTUURRNN traps. + 66.. Error tracing is enabled: command substitution, + shell functions, and subshells invoked with (( + _c_o_m_m_a_n_d )) inherit the EERRRR trap. + eexxttgglloobb If set, enable the extended pattern matching features + described above under PPaatthhnnaammee EExxppaannssiioonn. + eexxttqquuoottee + If set, $$'_s_t_r_i_n_g' and $$"_s_t_r_i_n_g" quoting is performed + within $${{_p_a_r_a_m_e_t_e_r}} expansions enclosed in double + quotes. This option is enabled by default. + ffaaiillgglloobb + If set, patterns which fail to match filenames during + pathname expansion result in an expansion error. + ffoorrccee__ffiiggnnoorree + If set, the suffixes specified by the FFIIGGNNOORREE shell + variable cause words to be ignored when performing word + completion even if the ignored words are the only possi- + ble completions. See SShheellll VVaarriiaabblleess above for a de- + scription of FFIIGGNNOORREE. This option is enabled by de- + fault. + gglloobbaasscciiiirraannggeess + If set, range expressions used in pattern matching + bracket expressions (see PPaatttteerrnn MMaattcchhiinngg above) behave + as if in the traditional C locale when performing com- + parisons. That is, pattern matching does not take the + current locale's collating sequence into account, so bb + will not collate between AA and BB, and upper-case and + lower-case ASCII characters will collate together. + gglloobbsskkiippddoottss + If set, pathname expansion will never match the file- + names _. and _._., even if the pattern begins with a ".". + This option is enabled by default. + gglloobbssttaarr + If set, the pattern **** used in a pathname expansion con- + text will match all files and zero or more directories + and subdirectories. If the pattern is followed by a //, + only directories and subdirectories match. + ggnnuu__eerrrrffmmtt + If set, shell error messages are written in the standard + GNU error message format. + hhiissttaappppeenndd + If set, the history list is appended to the file named + by the value of the HHIISSTTFFIILLEE variable when the shell ex- + its, rather than overwriting the file. + hhiissttrreeeeddiitt + If set, and rreeaaddlliinnee is being used, the user is given + the opportunity to re-edit a failed history substitu- + tion. + hhiissttvveerriiffyy + If set, and rreeaaddlliinnee is being used, the results of his- + tory substitution are not immediately passed to the + shell parser. Instead, the resulting line is loaded + into the rreeaaddlliinnee editing buffer, allowing further modi- + fication. + hhoossttccoommpplleettee + If set, and rreeaaddlliinnee is being used, bbaasshh will attempt to + perform hostname completion when a word containing a @@ + is being completed (see CCoommpplleettiinngg under RREEAADDLLIINNEE + above). This is enabled by default. + hhuuppoonneexxiitt + If set, bbaasshh will send SSIIGGHHUUPP to all jobs when an inter- + active login shell exits. + iinnhheerriitt__eerrrreexxiitt + If set, command substitution inherits the value of the + eerrrreexxiitt option, instead of unsetting it in the subshell + environment. This option is enabled when posix mode is + enabled. + iinntteerraaccttiivvee__ccoommmmeennttss + In an interactive shell, a word beginning with ## causes + that word and all remaining characters on that line to + be ignored, as in a non-interactive shell (see CCOOMMMMEENNTTSS + above). This option is enabled by default. + llaassttppiippee + If set, and job control is not active, the shell runs + the last command of a pipeline not executed in the back- + ground in the current shell environment. + lliitthhiisstt If set, and the ccmmddhhiisstt option is enabled, multi-line + commands are saved to the history with embedded newlines + rather than using semicolon separators where possible. + llooccaallvvaarr__iinnhheerriitt + 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 at- + tribute is not inherited. + llooccaallvvaarr__uunnsseett + If set, calling uunnsseett on local variables in previous + function scopes marks them so subsequent lookups find + them unset until that function returns. This is identi- + cal to the behavior of unsetting local variables at the + current function scope. + llooggiinn__sshheellll + The shell sets this option if it is started as a login + shell (see IINNVVOOCCAATTIIOONN above). The value may not be + changed. + mmaaiillwwaarrnn + If set, and a file that bbaasshh is checking for mail has + been accessed since the last time it was checked, bbaasshh + displays the message "The mail in _m_a_i_l_f_i_l_e has been + read". + nnoo__eemmppttyy__ccmmdd__ccoommpplleettiioonn + If set, and rreeaaddlliinnee is being used, bbaasshh does not search + PPAATTHH for possible completions when completion is at- + tempted on an empty line. + nnooccaasseegglloobb + If set, bbaasshh matches filenames in a case-insensitive + fashion when performing pathname expansion (see PPaatthhnnaammee + EExxppaannssiioonn above). + nnooccaasseemmaattcchh + If set, bbaasshh matches patterns in a case-insensitive + fashion when performing matching while executing ccaassee or + [[[[ conditional commands, when performing pattern substi- + tution word expansions, or when filtering possible com- + pletions as part of programmable completion. + nnooeexxppaanndd__ttrraannssllaattiioonn + If set, bbaasshh encloses the translated results of $$""..."" + quoting in single quotes instead of double quotes. If + the string is not translated, this has no effect. + nnuullllgglloobb + If set, pathname expansion patterns which match no files + (see PPaatthhnnaammee EExxppaannssiioonn above) expand to nothing and are + removed, rather than expanding to themselves. + ppaattssuubb__rreeppllaacceemmeenntt + If set, bbaasshh expands occurrences of && in the replacement + string of pattern substitution to the text matched by + the pattern, as described under PPaarraammeetteerr EExxppaannssiioonn + above. This option is enabled by default. + pprrooggccoommpp + If set, enable the programmable completion facilities + (see PPrrooggrraammmmaabbllee CCoommpplleettiioonn above). This option is en- + abled by default. + pprrooggccoommpp__aalliiaass + If set, and programmable completion is enabled, bbaasshh + treats a command name that doesn't have any completions + as a possible alias and attempts alias expansion. If it + has an alias, bbaasshh attempts programmable completion us- + ing the command word resulting from the expanded alias. + pprroommppttvvaarrss + If set, prompt strings undergo parameter expansion, com- + mand substitution, arithmetic expansion, and quote re- + moval after being expanded as described in PPRROOMMPPTTIINNGG + above. This option is enabled by default. + rreessttrriicctteedd__sshheellll + The shell sets this option if it is started in re- + stricted mode (see RREESSTTRRIICCTTEEDD SSHHEELLLL below). The value + may not be changed. This is not reset when the startup + files are executed, allowing the startup files to dis- + cover whether or not a shell is restricted. + sshhiifftt__vveerrbboossee + If set, the sshhiifftt builtin prints an error message when + the shift count exceeds the number of positional parame- + ters. + ssoouurrcceeppaatthh + If set, the .. (ssoouurrccee) builtin uses the value of PPAATTHH to + find the directory containing the file supplied as an + argument when the --pp option is not supplied. This op- + tion is enabled by default. + vvaarrrreeddiirr__cclloossee + If set, the shell automatically closes file descriptors + assigned using the _{_v_a_r_n_a_m_e_} redirection syntax (see + RREEDDIIRREECCTTIIOONN above) instead of leaving them open when the + command completes. + xxppgg__eecchhoo + If set, the eecchhoo builtin expands backslash-escape se- + quences by default. If the ppoossiixx shell option is also + enabled, eecchhoo does not interpret any options. + + ssuussppeenndd [--ff] + Suspend the execution of this shell until it receives a SSIIGGCCOONNTT + signal. A login shell, or a shell without job control enabled, + cannot be suspended; the --ff option will 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 --ff is not sup- + plied. + + tteesstt _e_x_p_r + [[ _e_x_p_r ]] + Return a status of 0 (true) or 1 (false) depending on the evalu- + ation of the conditional expression _e_x_p_r. Each operator and + operand must be a separate argument. Expressions are composed + of the primaries described above under CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS. + tteesstt does not accept any options, nor does it accept and ignore + an argument of ---- as signifying the end of options. + + Expressions may be combined using the following operators, + listed in decreasing order of precedence. The evaluation de- + pends on the number of arguments; see below. tteesstt uses operator + precedence when there are five or more arguments. + !! _e_x_p_r True if _e_x_p_r is false. + (( _e_x_p_r )) + Returns the value of _e_x_p_r. This may be used to override + normal operator precedence. + _e_x_p_r_1 -aa _e_x_p_r_2 + True if both _e_x_p_r_1 and _e_x_p_r_2 are true. + _e_x_p_r_1 -oo _e_x_p_r_2 + True if either _e_x_p_r_1 or _e_x_p_r_2 is true. + + tteesstt and [[ evaluate conditional expressions using a set of rules + based on the number of arguments. + + 0 arguments + The expression is false. + 1 argument + The expression is true if and only if the argument is not + null. + 2 arguments + If the first argument is !!, the expression is true if and + only if the second argument is null. If the first argu- + ment is one of the unary conditional operators listed + above under CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS, 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. + 3 arguments + The following conditions are applied in the order listed. + If the second argument is one of the binary conditional + operators listed above under CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS, the + result of the expression is the result of the binary test + using the first and third arguments as operands. The --aa + and --oo operators are considered binary operators when + there are three arguments. If the first argument is !!, + the value is the negation of the two-argument test using + the second and third arguments. If the first argument is + exactly (( and the third argument is exactly )), the result + is the one-argument test of the second argument. Other- + wise, the expression is false. + 4 arguments + The following conditions are applied in the order listed. + If the first argument is !!, the result is the negation of + the three-argument expression composed of the remaining + arguments. If the first argument is exactly (( and the + fourth argument is exactly )), the result is the two-argu- + ment test of the second and third arguments. Otherwise, + the expression is parsed and evaluated according to + precedence using the rules listed above. + 5 or more arguments + The expression is parsed and evaluated according to + precedence using the rules listed above. + + When the shell is in posix mode, or if the expression is part of + the [[[[ command, the << and >> operators sort using the current lo- + cale. If the shell is not in posix mode, the tteesstt and [[ com- + mands sort lexicographically using ASCII ordering. + + The historical operator-precedence parsing with 4 or more argu- + ments can lead to ambiguities when it encounters strings that + look like primaries. The POSIX standard has deprecated the --aa + and --oo primaries and enclosing expressions within parentheses. + Scripts should no longer use them. It's much more reliable to + restrict test invocations to a single primary, and to replace + uses of --aa and --oo with the shell's &&&& and |||| list operators. + + ttiimmeess Print the accumulated user and system times for the shell and + for processes run from the shell. The return status is 0. + + ttrraapp [--llppPP] [[_a_c_t_i_o_n] _s_i_g_s_p_e_c ...] + The _a_c_t_i_o_n is a command that is read and executed when the shell + receives any of the signals _s_i_g_s_p_e_c. If _a_c_t_i_o_n is absent (and + there is a single _s_i_g_s_p_e_c) or --, each specified _s_i_g_s_p_e_c is reset + to the value it had when the shell was started. If _a_c_t_i_o_n is + the null string the signal specified by each _s_i_g_s_p_e_c is ignored + by the shell and by the commands it invokes. + + If no arguments are supplied, ttrraapp displays the actions associ- + ated with each trapped signal as a set of ttrraapp commands that can + be reused as shell input to restore the current signal disposi- + tions. If --pp is given, and _a_c_t_i_o_n is not present, then ttrraapp + displays the actions associated with each _s_i_g_s_p_e_c or, if none + are supplied, for all trapped signals, as a set of ttrraapp commands + that can be reused as shell input to restore the current signal + dispositions. The --PP option behaves similarly, but displays + only the actions associated with each _s_i_g_s_p_e_c argument. --PP re- + quires at least one _s_i_g_s_p_e_c argument. The --PP or --pp options may + be used in a subshell environment (e.g., command substitution) + and, as long as they are used before ttrraapp is used to change a + signal's handling, will display the state of its parent's traps. + + The --ll option prints a list of signal names and their corre- + sponding numbers. Each _s_i_g_s_p_e_c is either a signal name defined + in <_s_i_g_n_a_l_._h>, or a signal number. Signal names are case insen- + sitive and the SSIIGG prefix is optional. If --ll is supplied with + no _s_i_g_s_p_e_c arguments, it prints a list of valid signal names. + + If a _s_i_g_s_p_e_c is EEXXIITT (0), _a_c_t_i_o_n is executed on exit from the + shell. If a _s_i_g_s_p_e_c is DDEEBBUUGG, _a_c_t_i_o_n is executed before every + _s_i_m_p_l_e _c_o_m_m_a_n_d, _f_o_r command, _c_a_s_e command, _s_e_l_e_c_t command, (( + arithmetic command, [[ conditional command, arithmetic _f_o_r com- + mand, and before the first command executes in a shell function + (see SSHHEELLLL GGRRAAMMMMAARR above). Refer to the description of the + eexxttddeebbuugg shell option (see sshhoopptt above) for details of its ef- + fect on the DDEEBBUUGG trap. If a _s_i_g_s_p_e_c is RREETTUURRNN, _a_c_t_i_o_n is exe- + cuted each time a shell function or a script executed with the .. + or ssoouurrccee builtins finishes executing. + + If a _s_i_g_s_p_e_c is EERRRR, _a_c_t_i_o_n 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 EERRRR trap is not executed if the + failed command is part of the command list immediately following + a wwhhiillee or uunnttiill reserved word, part of the test in an _i_f state- + ment, part of a command executed in a &&&& or |||| list except the + command following the final &&&& or ||||, any command in a pipeline + but the last (subject to the state of the ppiippeeffaaiill shell op- + tion), or if the command's return value is being inverted using + !!. These are the same conditions obeyed by the eerrrreexxiitt (--ee) op- + tion. + + When the shell is not interactive, signals ignored upon entry to + the shell cannot be trapped or reset. Interactive shells permit + trapping signals ignored on entry. 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 _s_i_g_s_p_e_c is invalid; otherwise ttrraapp returns true. + + ttrruuee Does nothing, returns a 0 status. + + ttyyppee [--aaffttppPP] _n_a_m_e [_n_a_m_e ...] + Indicate how each _n_a_m_e would be interpreted if used as a command + name. + + If the --tt option is used, ttyyppee prints a string which is one of + _a_l_i_a_s, _k_e_y_w_o_r_d, _f_u_n_c_t_i_o_n, _b_u_i_l_t_i_n, or _f_i_l_e if _n_a_m_e is an alias, + shell reserved word, function, builtin, or executable file, re- + spectively. If the _n_a_m_e is not found, ttyyppee prints nothing and + returns a non-zero exit status. + + If the --pp option is used, ttyyppee either returns the pathname of + the executable file that would be found by searching $$PPAATTHH for + _n_a_m_e or nothing if "type -t name" would not return _f_i_l_e. The --PP + option forces a PPAATTHH search for each _n_a_m_e, even if "type -t + name" would not return _f_i_l_e. If _n_a_m_e is present in the table of + hashed commands, --pp and --PP print the hashed value, which is not + necessarily the file that appears first in PPAATTHH. + + If the --aa option is used, ttyyppee prints all of the places that + contain a command named _n_a_m_e. This includes aliases, reserved + words, functions, and builtins, but the path search options (--pp + and --PP) can be supplied to restrict the output to executable + files. ttyyppee does not consult the table of hashed commands when + using --aa with --pp, and only performs a PPAATTHH search for _n_a_m_e. + + The --ff option suppresses shell function lookup, as with the ccoomm-- + mmaanndd builtin. ttyyppee returns true if all of the arguments are + found, false if any are not found. + + uulliimmiitt [--HHSS] --aa + uulliimmiitt [--HHSS] [--bbccddeeffiikkllmmnnppqqrrssttuuvvxxPPRRTT [_l_i_m_i_t]] + Provides control over the resources available to the shell and + to processes it starts, on systems that allow such control. + + The --HH and --SS options specify whether 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 --HH nor --SS is speci- + fied, uulliimmiitt sets both the soft and hard limits. + + The value of _l_i_m_i_t can be a number in the unit specified for the + resource or one of the special values hhaarrdd, ssoofftt, or uunnlliimmiitteedd, + which stand for the current hard limit, the current soft limit, + and no limit, respectively. If _l_i_m_i_t is omitted, uulliimmiitt prints + the current value of the soft limit of the resource, unless the + --HH 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: + --aa Report all current limits; no limits are set. + --bb The maximum socket buffer size. + --cc The maximum size of core files created. + --dd The maximum size of a process's data segment. + --ee The maximum scheduling priority ("nice"). + --ff The maximum size of files written by the shell and its + children. + --ii The maximum number of pending signals. + --kk The maximum number of kqueues that may be allocated. + --ll The maximum size that may be locked into memory. + --mm The maximum resident set size (many systems do not honor + this limit). + --nn The maximum number of open file descriptors (most systems + do not allow this value to be set). + --pp The pipe size in 512-byte blocks (this may not be set). + --qq The maximum number of bytes in POSIX message queues. + --rr The maximum real-time scheduling priority. + --ss The maximum stack size. + --tt The maximum amount of cpu time in seconds. + --uu The maximum number of processes available to a single + user. + --vv The maximum amount of virtual memory available to the + shell and, on some systems, to its children. + --xx The maximum number of file locks. + --PP The maximum number of pseudoterminals. + --RR The maximum time a real-time process can run before + blocking, in microseconds. + --TT The maximum number of threads. + + If _l_i_m_i_t is supplied, and the --aa option is not used, _l_i_m_i_t is + the new value of the specified resource. If no option is sup- + plied, then --ff is assumed. + + Values are in 1024-byte increments, except for --tt, which is in + seconds; --RR, which is in microseconds; --pp, which is in units of + 512-byte blocks; --PP, --TT, --bb, --kk, --nn, and --uu, which are unscaled + values; and, when in posix mode, --cc and --ff, 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. + + uummaasskk [--pp] [--SS] [_m_o_d_e] + Set the user file-creation mask to _m_o_d_e. If _m_o_d_e begins with a + digit, it is interpreted as an octal number; otherwise it is in- + terpreted as a symbolic mode mask similar to that accepted by + _c_h_m_o_d(1). If _m_o_d_e is omitted, uummaasskk prints the current value of + the mask. The --SS option without a _m_o_d_e argument prints the mask + in a symbolic format; the default output is an octal number. If + the --pp option is supplied, and _m_o_d_e is omitted, the output is in + a form that may be reused as input. The return status is zero + if the mode was successfully changed or if no _m_o_d_e argument was + supplied, and non-zero otherwise. + + uunnaalliiaass [-aa] [_n_a_m_e ...] + Remove each _n_a_m_e from the list of defined aliases. If --aa is + supplied, remove all alias definitions. The return value is + true unless a supplied _n_a_m_e is not a defined alias. + + uunnsseett [-ffvv] [-nn] [_n_a_m_e ...] + For each _n_a_m_e, remove the corresponding variable or function. + If the --vv option is given, each _n_a_m_e refers to a shell variable, + and that variable is removed. If --ff is specified, each _n_a_m_e + refers to a shell function, and the function definition is re- + moved. If the --nn option is supplied, and _n_a_m_e is a variable + with the _n_a_m_e_r_e_f attribute, _n_a_m_e will be unset rather than the + variable it references. --nn has no effect if the --ff option is + supplied. Read-only variables and functions may not be unset. + When variables or functions are removed, they are also removed + from the environment passed to subsequent commands. If no op- + tions are supplied, each _n_a_m_e refers to a variable; if there is + no variable by that name, a function with that name, if any, is + unset. Some shell variables may not be unset. If any of + BBAASSHH__AALLIIAASSEESS, BBAASSHH__AARRGGVV00, BBAASSHH__CCMMDDSS, BBAASSHH__CCOOMMMMAANNDD, BBAASSHH__SSUUBB-- + SSHHEELLLL, BBAASSHHPPIIDD, CCOOMMPP__WWOORRDDBBRREEAAKKSS, DDIIRRSSTTAACCKK, EEPPOOCCHHRREEAALLTTIIMMEE, + EEPPOOCCHHSSEECCOONNDDSS, FFUUNNCCNNAAMMEE, GGRROOUUPPSS, HHIISSTTCCMMDD, LLIINNEENNOO, RRAANNDDOOMM, SSEECC-- + OONNDDSS, or SSRRAANNDDOOMM are unset, they lose their special properties, + even if they are subsequently reset. The exit status is true + unless a _n_a_m_e is readonly or may not be unset. + + wwaaiitt [--ffnn] [--pp _v_a_r_n_a_m_e] [_i_d ...] + Wait for each specified child process _i_d and return the termina- + tion status of the last _i_d. Each _i_d may be a process ID _p_i_d or + a job specification _j_o_b_s_p_e_c; if a jobspec is supplied, wwaaiitt + waits for all processes in the job. + + If no options or _i_ds are supplied, wwaaiitt waits for all running + background jobs and the last-executed process substitution, if + its process id is the same as $$!!, and the return status is zero. + + If the --nn option is supplied, wwaaiitt waits for any one of the + given _i_ds or, if no _i_ds are supplied, any job or process substi- + tution, to complete and returns its exit status. If none of the + supplied _i_ds is a child of the shell, or if no _i_ds are supplied + and the shell has no unwaited-for children, the exit status is + 127. + + If the --pp option is supplied, wwaaiitt assigns the process or job + identifier of the job for which the exit status is returned to + the variable _v_a_r_n_a_m_e named by the option argument. The vari- + able, which cannot be readonly, will be unset initially, before + any assignment. This is useful only when used with the --nn op- + tion. + + Supplying the --ff option, when job control is enabled, forces + wwaaiitt to wait for each _i_d to terminate before returning its sta- + tus, instead of returning when it changes status. + + If none of the _i_ds specify one of the shell's active child + processes, the return status is 127. If wwaaiitt is interrupted by + a signal, any _v_a_r_n_a_m_e will remain unset, and the return status + will be greater than 128, as described under SSIIGGNNAALLSS above. + Otherwise, the return status is the exit status of the last _i_d. + +SSHHEELLLL CCOOMMPPAATTIIBBIILLIITTYY MMOODDEE + Bash-4.0 introduced the concept of a _s_h_e_l_l _c_o_m_p_a_t_i_b_i_l_i_t_y _l_e_v_e_l, speci- + fied as a set of options to the shopt builtin (ccoommppaatt3311, ccoommppaatt3322, ccoomm-- + ppaatt4400, ccoommppaatt4411, 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 solu- + tion. + + This section does not mention behavior that is standard for a particu- + lar version (e.g., setting ccoommppaatt3322 means that quoting the right hand + side of the regexp matching operator quotes special regexp characters + in the word, which is default behavior in bash-3.2 and subsequent ver- + sions). + + If a user enables, say, ccoommppaatt3322, 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 bbaasshh, but that behavior may have been + present in earlier versions. For instance, the change to use locale- + based comparisons with the [[[[ command came in bash-4.1, and earlier + versions used ASCII-based comparisons, so enabling ccoommppaatt3322 will enable + ASCII-based comparisons as well. That granularity may not be suffi- + cient 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. + + Bash-4.3 introduced a new shell variable: BBAASSHH__CCOOMMPPAATT. The value as- + signed to this variable (a decimal version number like 4.2, or an inte- + ger corresponding to the ccoommppaatt_N_N option, like 42) determines the com- + patibility level. + + Starting with bash-4.4, bbaasshh began deprecating older compatibility lev- + els. Eventually, the options will be removed in favor of BBAASSHH__CCOOMMPPAATT. + + Bash-5.0 was the final version for which there was an individual shopt + option for the previous version. BBAASSHH__CCOOMMPPAATT is the only mechanism to + control the compatibility level in versions newer than bash-5.0. + + The following table describes the behavior changes controlled by each + compatibility level setting. The ccoommppaatt_N_N tag is used as shorthand for + setting the compatibility level to _N_N using one of the following mecha- + nisms. For versions prior to bash-5.0, the compatibility level may be + set using the corresponding ccoommppaatt_N_N shopt option. For bash-4.3 and + later versions, the BBAASSHH__CCOOMMPPAATT variable is preferred, and it is re- + quired for bash-5.1 and later versions. + + ccoommppaatt3311 + +o Quoting the rhs of the [[[[ command's regexp matching oper- + ator (=~) has no special effect. + + ccoommppaatt3322 + +o The << and >> operators to the [[[[ command do not consider + the current locale when comparing strings; they use ASCII + ordering. + + ccoommppaatt4400 + +o The << and >> operators to the [[[[ command do not consider + the current locale when comparing strings; they use ASCII + ordering. BBaasshh versions prior to bash-4.1 use ASCII col- + lation and _s_t_r_c_m_p(3); bash-4.1 and later use the current + locale's collation sequence and _s_t_r_c_o_l_l(3). + + ccoommppaatt4411 + +o In posix mode, ttiimmee may be followed by options and still + be recognized as a reserved word (this is POSIX interpre- + tation 267). + +o In _p_o_s_i_x mode, the parser requires that an even number of + single quotes occur in the _w_o_r_d 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). + + ccoommppaatt4422 + +o The replacement string in double-quoted pattern substitu- + tion does not undergo quote removal, as it does in ver- + sions after bash-4.2. + +o In posix mode, single quotes are considered special when + expanding the _w_o_r_d 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 interpre- + tation 221); in later versions, single quotes are not + special within double-quoted word expansions. + + ccoommppaatt4433 + +o 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). + +o When executing a shell function, the loop state + (while/until/etc.) is not reset, so bbrreeaakk or ccoonnttiinnuuee in + that function will break or continue loops in the calling + context. Bash-4.4 and later reset the loop state to pre- + vent this. + + ccoommppaatt4444 + +o The shell sets up the values used by BBAASSHH__AARRGGVV and + BBAASSHH__AARRGGCC so they can expand to the shell's positional + parameters even if extended debugging mode is not en- + abled. + +o A subshell inherits loops from its parent context, so + bbrreeaakk or ccoonnttiinnuuee will cause the subshell to exit. + Bash-5.0 and later reset the loop state to prevent the + exit + +o Variable assignments preceding builtins like eexxppoorrtt and + rreeaaddoonnllyy that set attributes continue to affect variables + with the same name in the calling environment even if the + shell is not in posix mode. + + ccoommppaatt5500 + +o Bash-5.1 changed the way $$RRAANNDDOOMM is generated to intro- + duce slightly more randomness. If the shell compatibil- + ity level is set to 50 or lower, it reverts to the method + from bash-5.0 and previous versions, so seeding the ran- + dom number generator by assigning a value to RRAANNDDOOMM will + produce the same sequence as in bash-5.0. + +o If the command hash table is empty, bash versions prior + to bash-5.1 printed an informational message to that ef- + fect, even when producing output that can be reused as + input. Bash-5.1 suppresses that message when the --ll op- + tion is supplied. + + ccoommppaatt5511 + +o The uunnsseett builtin treats attempts to unset array sub- + scripts @@ and ** differently depending on whether the ar- + ray is indexed or associative, and differently than in + previous versions. + +o Arithmetic commands ( ((((...)))) ) and the expressions in an + arithmetic for statement can be expanded more than once. + +o Expressions used as arguments to arithmetic operators in + the [[[[ conditional command can be expanded more than + once. + +o The expressions in substring parameter brace expansion + can be expanded more than once. + +o The expressions in the $$((((...)))) word expansion can be ex- + panded more than once. + +o Arithmetic expressions used as indexed array subscripts + can be expanded more than once. + +o tteesstt --vv, when given an argument of AA[[@@]], where AA is an + existing associative array, will return true if the array + has any set elements. Bash-5.2 will look for and report + on a key named @@. + +o The ${_p_a_r_a_m_e_t_e_r[[::]]==_v_a_l_u_e} word expansion will return + _v_a_l_u_e, before any variable-specific transformations have + been performed (e.g., converting to lowercase). Bash-5.2 + will return the final value assigned to the variable. + +o Parsing command substitutions will behave as if extended + globbing (see the description of the sshhoopptt builtin above) + is enabled, so that parsing a command substitution con- + taining an extglob pattern (say, as part of a shell func- + tion) will not fail. This assumes the intent is to en- + able extglob before the command is executed and word ex- + pansions are performed. It will fail at word expansion + time if extglob hasn't been enabled by the time the com- + mand is executed. + + ccoommppaatt5522 + +o The tteesstt builtin uses its historical algorithm to parse + parenthesized subexpressions when given five or more ar- + guments. + +o If the --pp or --PP option is supplied to the bbiinndd builtin, + bbiinndd treats any arguments remaining after option process- + ing as bindable command names, and displays any key se- + quences bound to those commands, instead of treating the + arguments as key sequences to bind. + +RREESSTTRRIICCTTEEDD SSHHEELLLL + If bbaasshh is started with the name rrbbaasshh, or the --rr option is supplied at + invocation, the shell becomes _r_e_s_t_r_i_c_t_e_d. A restricted shell is used + to set up an environment more controlled than the standard shell. It + behaves identically to bbaasshh with the exception that the following are + disallowed or not performed: + + +o Changing directories with ccdd. + + +o Setting or unsetting the values of SSHHEELLLL, PPAATTHH, HHIISSTTFFIILLEE, EENNVV, + or BBAASSHH__EENNVV. + + +o Specifying command names containing //. + + +o Specifying a filename containing a // as an argument to the .. + builtin command. + + +o Using the --pp option to the .. builtin command to specify a + search path. + + +o Specifying a filename containing a slash as an argument to the + hhiissttoorryy builtin command. + + +o Specifying a filename containing a slash as an argument to the + --pp option to the hhaasshh builtin command. + + +o Importing function definitions from the shell environment at + startup. + + +o Parsing the values of BBAASSHHOOPPTTSS and SSHHEELLLLOOPPTTSS from the shell en- + vironment at startup. + + +o Redirecting output using the >, >|, <>, >&, &>, and >> redirec- + tion operators. + + +o Using the eexxeecc builtin command to replace the shell with another + command. + + +o Adding or deleting builtin commands with the --ff and --dd options + to the eennaabbllee builtin command. + + +o Using the eennaabbllee builtin command to enable disabled shell + builtins. + + +o Specifying the --pp option to the ccoommmmaanndd builtin command. + + +o Turning off restricted mode with sseett ++rr or sshhoopptt --uu rree-- + ssttrriicctteedd__sshheellll. + + These restrictions are enforced after any startup files are read. + + When a command that is found to be a shell script is executed (see CCOOMM-- + MMAANNDD EEXXEECCUUTTIIOONN above), rrbbaasshh turns off any restrictions in the shell + spawned to execute the script. + +SSEEEE AALLSSOO + _B_a_s_h _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, Brian Fox and Chet Ramey + _T_h_e _G_n_u _R_e_a_d_l_i_n_e _L_i_b_r_a_r_y, Brian Fox and Chet Ramey + _T_h_e _G_n_u _H_i_s_t_o_r_y _L_i_b_r_a_r_y, Brian Fox and Chet Ramey + _P_o_r_t_a_b_l_e _O_p_e_r_a_t_i_n_g _S_y_s_t_e_m _I_n_t_e_r_f_a_c_e _(_P_O_S_I_X_) _P_a_r_t _2_: _S_h_e_l_l _a_n_d _U_t_i_l_i_- + _t_i_e_s, IEEE -- + http://pubs.opengroup.org/onlinepubs/9799919799/ + http://tiswww.case.edu/~chet/bash/POSIX -- a description of posix mode + _s_h(1), _k_s_h(1), _c_s_h(1) + _e_m_a_c_s(1), _v_i(1) + _r_e_a_d_l_i_n_e(3) + +FFIILLEESS + _/_b_i_n_/_b_a_s_h + The bbaasshh executable + _/_e_t_c_/_p_r_o_f_i_l_e + The systemwide initialization file, executed for login shells + _~_/_._b_a_s_h___p_r_o_f_i_l_e + The personal initialization file, executed for login shells + _~_/_._b_a_s_h_r_c + The individual per-interactive-shell startup file + _~_/_._b_a_s_h___l_o_g_o_u_t + The individual login shell cleanup file, executed when a login + shell exits + _~_/_._b_a_s_h___h_i_s_t_o_r_y + The default value of HHIISSTTFFIILLEE, the file in which bash saves the + command history + _~_/_._i_n_p_u_t_r_c + Individual _r_e_a_d_l_i_n_e initialization file + +AAUUTTHHOORRSS + Brian Fox, Free Software Foundation + bfox@gnu.org + + Chet Ramey, Case Western Reserve University + chet.ramey@case.edu + +BBUUGG RREEPPOORRTTSS + If you find a bug in bbaasshh, 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 bbaasshh. The latest version is always available from + _f_t_p_:_/_/_f_t_p_._g_n_u_._o_r_g_/_p_u_b_/_g_n_u_/_b_a_s_h_/ and _h_t_t_p_:_/_/_g_i_t_._s_a_v_a_n_- + _n_a_h_._g_n_u_._o_r_g_/_c_g_i_t_/_b_a_s_h_._g_i_t_/_s_n_a_p_s_h_o_t_/_b_a_s_h_-_m_a_s_t_e_r_._t_a_r_._g_z. + + Once you have determined that a bug actually exists, use the _b_a_s_h_b_u_g + command to submit a bug report. If you have a fix, you are encouraged + to mail that as well! You may send suggestions and "philosophical" bug + reports to _b_u_g_-_b_a_s_h_@_g_n_u_._o_r_g or post them to the Usenet newsgroup + ggnnuu..bbaasshh..bbuugg. + + ALL bug reports should include: + + The version number of bbaasshh + The hardware and operating system + The compiler used to compile + A description of the bug behavior + A short script or "recipe" which exercises the bug + + _b_a_s_h_b_u_g inserts the first three items automatically into the template + it provides for filing a bug report. + + Comments and bug reports concerning this manual page should be directed + to _c_h_e_t_._r_a_m_e_y_@_c_a_s_e_._e_d_u. + +BBUUGGSS + It's too big and too slow. + + There are some subtle differences between bbaasshh and traditional versions + of sshh, mostly because of the POSIX specification. + + Aliases are confusing in some uses. + + Shell builtin commands and functions are not stoppable/restartable. + + Compound commands and command lists of the form "a ; b ; c" are not + handled gracefully when combined with process suspension. When a + process is stopped, the shell immediately executes the next command in + the list or breaks out of any existing loops. It suffices to enclose + the command in parentheses to force it into a subshell, which may be + stopped as a unit, or to start the command in the background and imme- + diately bring it into the foreground. + + Array variables may not (yet) be exported. + +GNU Bash 5.3 2025 August 25 _B_A_S_H(1) diff --git a/bash.info b/bash.info new file mode 100644 index 00000000..03b2ee83 --- /dev/null +++ b/bash.info @@ -0,0 +1,13778 @@ +This is bash.info, produced by makeinfo version 7.2 from bashref.texi. + +This text is a brief description of the features that are present in the +Bash shell (version 5.3, 7 August 2025). + + This is Edition 5.3, last updated 7 August 2025, of ‘The GNU Bash +Reference Manual’, for ‘Bash’, Version 5.3. + + Copyright © 1988-2025 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". +INFO-DIR-SECTION Basics +START-INFO-DIR-ENTRY +* Bash: (bash). The GNU Bourne-Again SHell. +END-INFO-DIR-ENTRY + + +File: bash.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +Bash Features +************* + +This text is a brief description of the features that are present in the +Bash shell (version 5.3, 7 August 2025). The Bash home page is +. + + This is Edition 5.3, last updated 7 August 2025, of ‘The GNU Bash +Reference Manual’, for ‘Bash’, Version 5.3. + + Bash contains features that appear in other popular shells, and some +features that only appear in Bash. Some of the shells that Bash has +borrowed concepts from are the Bourne Shell (‘sh’), the Korn Shell +(‘ksh’), and the C-shell (‘csh’ and its successor, ‘tcsh’). The +following menu breaks the features up into categories, noting which +features were inspired by other shells and which are specific to Bash. + + This manual is meant as a brief introduction to features found in +Bash. The Bash manual page should be used as the definitive reference +on shell behavior. + +* Menu: + +* Introduction:: An introduction to the shell. +* Definitions:: Some definitions used in the rest of this + manual. +* Basic Shell Features:: The shell "building blocks". +* Shell Builtin Commands:: Commands that are a part of the shell. +* Shell Variables:: Variables used or set by Bash. +* Bash Features:: Features found only in Bash. +* Job Control:: What job control is and how Bash allows you + to use it. +* Command Line Editing:: Chapter describing the command line + editing features. +* Using History Interactively:: Command History Expansion +* Installing Bash:: How to build and install Bash on your system. +* Reporting Bugs:: How to report bugs in Bash. +* Major Differences From The Bourne Shell:: A terse list of the differences + between Bash and historical + versions of /bin/sh. +* GNU Free Documentation License:: Copying and sharing this documentation. +* Indexes:: Various indexes for this manual. + + +File: bash.info, Node: Introduction, Next: Definitions, Up: Top + +1 Introduction +************** + +* Menu: + +* What is Bash?:: A short description of Bash. +* What is a shell?:: A brief introduction to shells. + + +File: bash.info, Node: What is Bash?, Next: What is a shell?, Up: Introduction + +1.1 What is Bash? +================= + +Bash is the shell, or command language interpreter, for the GNU +operating system. The name is an acronym for the ‘Bourne-Again SHell’, +a pun on Stephen Bourne, the author of the direct ancestor of the +current Unix shell ‘sh’, which appeared in the Seventh Edition Bell Labs +Research version of Unix. + + Bash is largely compatible with ‘sh’ and incorporates useful features +from the Korn shell ‘ksh’ and the C shell ‘csh’. It is intended to be a +conformant implementation of the IEEE POSIX Shell and Tools portion of +the IEEE POSIX specification (IEEE Standard 1003.1). It offers +functional improvements over ‘sh’ for both interactive and programming +use. + + While the GNU operating system provides other shells, including a +version of ‘csh’, Bash is the default shell. Like other GNU software, +Bash is quite portable. It currently runs on nearly every version of +Unix and a few other operating systems − independently-supported ports +exist for Windows and other platforms. + + +File: bash.info, Node: What is a shell?, Prev: What is Bash?, Up: Introduction + +1.2 What is a shell? +==================== + +At its base, a shell is simply a macro processor that executes commands. +The term macro processor means functionality where text and symbols are +expanded to create larger expressions. + + A Unix shell is both a command interpreter and a programming +language. As a command interpreter, the shell provides the user +interface to the rich set of GNU utilities. The programming language +features allow these utilities to be combined. Users can create files +containing commands, and these become commands themselves. These new +commands have the same status as system commands in directories such as +‘/bin’, allowing users or groups to establish custom environments to +automate their common tasks. + + Shells may be used interactively or non-interactively. In +interactive mode, they accept input typed from the keyboard. When +executing non-interactively, shells execute commands read from a file or +a string. + + A shell allows execution of GNU commands, both synchronously and +asynchronously. The shell waits for synchronous commands to complete +before accepting more input; asynchronous commands continue to execute +in parallel with the shell while it reads and executes additional +commands. The “redirection” constructs permit fine-grained control of +the input and output of those commands. Moreover, the shell allows +control over the contents of commands' environments. + + Shells also provide a small set of built-in commands (“builtins”) +implementing functionality impossible or inconvenient to obtain via +separate utilities. For example, ‘cd’, ‘break’, ‘continue’, and ‘exec’ +cannot be implemented outside of the shell because they directly +manipulate the shell itself. The ‘history’, ‘getopts’, ‘kill’, or ‘pwd’ +builtins, among others, could be implemented in separate utilities, but +they are more convenient to use as builtin commands. All of the shell +builtins are described in subsequent sections. + + While executing commands is essential, most of the power (and +complexity) of shells is due to their embedded programming languages. +Like any high-level language, the shell provides variables, flow control +constructs, quoting, and functions. + + Shells offer features geared specifically for interactive use rather +than to augment the programming language. These interactive features +include job control, command line editing, command history and aliases. +This manual describes how Bash provides all of these features. + + +File: bash.info, Node: Definitions, Next: Basic Shell Features, Prev: Introduction, Up: Top + +2 Definitions +************* + +These definitions are used throughout the remainder of this manual. + +‘POSIX’ + A family of open system standards based on Unix. Bash is primarily + concerned with the Shell and Utilities portion of the POSIX 1003.1 + standard. + +‘blank’ + A space or tab character. + +‘whitespace’ + A character belonging to the ‘space’ character class in the current + locale, or for which ‘isspace()’ returns true. + +‘builtin’ + A command that is implemented internally by the shell itself, + rather than by an executable program somewhere in the file system. + +‘control operator’ + A ‘token’ that performs a control function. It is a ‘newline’ or + one of the following: ‘||’, ‘&&’, ‘&’, ‘;’, ‘;;’, ‘;&’, ‘;;&’, ‘|’, + ‘|&’, ‘(’, or ‘)’. + +‘exit status’ + The value returned by a command to its caller. The value is + restricted to eight bits, so the maximum value is 255. + +‘field’ + A unit of text that is the result of one of the shell expansions. + After expansion, when executing a command, the resulting fields are + used as the command name and arguments. + +‘filename’ + A string of characters used to identify a file. + +‘job’ + A set of processes comprising a pipeline, and any processes + descended from it, that are all in the same process group. + +‘job control’ + A mechanism by which users can selectively stop (suspend) and + restart (resume) execution of processes. + +‘metacharacter’ + A character that, when unquoted, separates words. A metacharacter + is a ‘space’, ‘tab’, ‘newline’, or one of the following characters: + ‘|’, ‘&’, ‘;’, ‘(’, ‘)’, ‘<’, or ‘>’. + +‘name’ + A ‘word’ consisting solely of letters, numbers, and underscores, + and beginning with a letter or underscore. ‘Name’s are used as + shell variable and function names. Also referred to as an + ‘identifier’. + +‘operator’ + A ‘control operator’ or a ‘redirection operator’. *Note + Redirections::, for a list of redirection operators. Operators + contain at least one unquoted ‘metacharacter’. + +‘process group’ + A collection of related processes each having the same process + group ID. + +‘process group ID’ + A unique identifier that represents a ‘process group’ during its + lifetime. + +‘reserved word’ + A ‘word’ that has a special meaning to the shell. Most reserved + words introduce shell flow control constructs, such as ‘for’ and + ‘while’. + +‘return status’ + A synonym for ‘exit status’. + +‘signal’ + A mechanism by which a process may be notified by the kernel of an + event occurring in the system. + +‘special builtin’ + A shell builtin command that has been classified as special by the + POSIX standard. + +‘token’ + A sequence of characters considered a single unit by the shell. It + is either a ‘word’ or an ‘operator’. + +‘word’ + A sequence of characters treated as a unit by the shell. Words may + not include unquoted ‘metacharacters’. + + +File: bash.info, Node: Basic Shell Features, Next: Shell Builtin Commands, Prev: Definitions, Up: Top + +3 Basic Shell Features +********************** + +Bash is an acronym for ‘Bourne-Again SHell’. The Bourne shell is the +traditional Unix shell originally written by Stephen Bourne. All of the +Bourne shell builtin commands are available in Bash, and the rules for +evaluation and quoting are taken from the POSIX specification for the +"standard" Unix shell. + + This chapter briefly summarizes the shell's "building blocks": +commands, control structures, shell functions, shell parameters, shell +expansions, redirections, which are a way to direct input and output +from and to named files, and how the shell executes commands. + +* Menu: + +* Shell Syntax:: What your input means to the shell. +* Shell Commands:: The types of commands you can use. +* Shell Functions:: Grouping commands by name. +* Shell Parameters:: How the shell stores values. +* Shell Expansions:: How Bash expands parameters and the various + expansions available. +* Redirections:: A way to control where input and output go. +* Executing Commands:: What happens when you run a command. +* Shell Scripts:: Executing files of shell commands. + + +File: bash.info, Node: Shell Syntax, Next: Shell Commands, Up: Basic Shell Features + +3.1 Shell Syntax +================ + +* Menu: + +* Shell Operation:: The basic operation of the shell. +* Quoting:: How to remove the special meaning from characters. +* Comments:: How to specify comments. + +When the shell reads input, it proceeds through a sequence of +operations. If the input indicates the beginning of a comment, the +shell ignores the comment symbol (‘#’), and the rest of that line. + + Otherwise, roughly speaking, the shell reads its input and divides +the input into words and operators, employing the quoting rules to +select which meanings to assign various words and characters. + + The shell then parses these tokens into commands and other +constructs, removes the special meaning of certain words or characters, +expands others, redirects input and output as needed, executes the +specified command, waits for the command's exit status, and makes that +exit status available for further inspection or processing. + + +File: bash.info, Node: Shell Operation, Next: Quoting, Up: Shell Syntax + +3.1.1 Shell Operation +--------------------- + +The following is a brief description of the shell's operation when it +reads and executes a command. Basically, the shell does the following: + + 1. Reads its input from a file (*note Shell Scripts::), from a string + supplied as an argument to the ‘-c’ invocation option (*note + Invoking Bash::), or from the user's terminal. + + 2. Breaks the input into words and operators, obeying the quoting + rules described in *note Quoting::. These tokens are separated by + ‘metacharacters’. This step performs alias expansion (*note + Aliases::). + + 3. Parses the tokens into simple and compound commands (*note Shell + Commands::). + + 4. Performs the various shell expansions (*note Shell Expansions::), + breaking the expanded tokens into lists of filenames (*note + Filename Expansion::) and commands and arguments. + + 5. Performs any necessary redirections (*note Redirections::) and + removes the redirection operators and their operands from the + argument list. + + 6. Executes the command (*note Executing Commands::). + + 7. Optionally waits for the command to complete and collects its exit + status (*note Exit Status::). + + +File: bash.info, Node: Quoting, Next: Comments, Prev: Shell Operation, Up: Shell Syntax + +3.1.2 Quoting +------------- + +* Menu: + +* Escape Character:: How to remove the special meaning from a single + character. +* Single Quotes:: How to inhibit all interpretation of a sequence + of characters. +* Double Quotes:: How to suppress most of the interpretation of a + sequence of characters. +* ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. +* Locale Translation:: How to translate strings into different languages. + +Quoting 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. + + Each of the shell metacharacters (*note Definitions::) has special +meaning to the shell and must be quoted if it is to represent itself. + + When the command history expansion facilities are being used (*note +History Interaction::), the “history expansion” character, usually ‘!’, +must be quoted to prevent history expansion. *Note Bash History +Facilities::, for more details concerning history expansion. + + There are four quoting mechanisms: the “escape character”, single +quotes, double quotes, and dollar-single quotes. + + +File: bash.info, Node: Escape Character, Next: Single Quotes, Up: Quoting + +3.1.2.1 Escape Character +........................ + +A non-quoted backslash ‘\’ is the Bash escape character. It preserves +the literal value of the next character that follows, removing any +special meaning it has, with the exception of ‘newline’. If a +‘\newline’ pair appears, and the backslash itself is not quoted, the +‘\newline’ is treated as a line continuation (that is, it is removed +from the input stream and effectively ignored). + + +File: bash.info, Node: Single Quotes, Next: Double Quotes, Prev: Escape Character, Up: Quoting + +3.1.2.2 Single Quotes +..................... + +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. + + +File: bash.info, Node: Double Quotes, Next: ANSI-C Quoting, Prev: Single Quotes, Up: Quoting + +3.1.2.3 Double Quotes +..................... + +Enclosing characters in double quotes (‘"’) preserves the literal value +of all characters within the quotes, with the exception of ‘$’, ‘`’, +‘\’, and, when history expansion is enabled, ‘!’. When the shell is in +POSIX mode (*note Bash POSIX Mode::), the ‘!’ has no special meaning +within double quotes, even when history expansion is enabled. The +characters ‘$’ and ‘`’ retain their special meaning within double quotes +(*note Shell Expansions::). The backslash retains its special meaning +only when followed by one of the following characters: ‘$’, ‘`’, ‘"’, +‘\’, or ‘newline’. Within double quotes, backslashes that are followed +by one of these characters are removed. Backslashes preceding +characters without a special meaning are left unmodified. + + A double quote may be quoted within double quotes by preceding it +with a backslash. If enabled, history expansion will be performed +unless an ‘!’ appearing in double quotes is escaped using a backslash. +The backslash preceding the ‘!’ is not removed. + + The special parameters ‘*’ and ‘@’ have special meaning when in +double quotes (*note Shell Parameter Expansion::). + + +File: bash.info, Node: ANSI-C Quoting, Next: Locale Translation, Prev: Double Quotes, Up: Quoting + +3.1.2.4 ANSI-C Quoting +...................... + +Character sequences of the form ‘$'STRING'’ are treated as a special +kind of single quotes. The sequence expands to STRING, with +backslash-escaped characters in STRING replaced as specified by the ANSI +C standard. Backslash escape sequences, if present, are decoded as +follows: + +‘\a’ + alert (bell) +‘\b’ + backspace +‘\e’ +‘\E’ + An escape character (not in ANSI C). +‘\f’ + form feed +‘\n’ + newline +‘\r’ + carriage return +‘\t’ + horizontal tab +‘\v’ + vertical tab +‘\\’ + backslash +‘\'’ + single quote +‘\"’ + double quote +‘\?’ + question mark +‘\NNN’ + The eight-bit character whose value is the octal value NNN (one to + three octal digits). +‘\xHH’ + The eight-bit character whose value is the hexadecimal value HH + (one or two hex digits). +‘\uHHHH’ + The Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value HHHH (one to four hex digits). +‘\UHHHHHHHH’ + The Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value HHHHHHHH (one to eight hex digits). +‘\cX’ + A control-X character. + +The expanded result is single-quoted, as if the dollar sign had not been +present. + + +File: bash.info, Node: Locale Translation, Prev: ANSI-C Quoting, Up: Quoting + +3.1.2.5 Locale-Specific Translation +................................... + +* Menu: + +* Creating Internationalized Scripts:: How to use translations and different + languages in your scripts. + +Prefixing a double-quoted string with a dollar sign (‘$’), such as +$"hello, world", causes the string to be translated according to the +current locale. The ‘gettext’ infrastructure performs the lookup and +translation, using the ‘LC_MESSAGES’, ‘TEXTDOMAINDIR’, and ‘TEXTDOMAIN’ +shell variables, as explained below. See the gettext documentation for +additional details not covered here. If the current locale is ‘C’ or +‘POSIX’, if there are no translations available, or if the string is not +translated, the dollar sign is ignored, and the string is treated as +double-quoted as described above. Since this is a form of double +quoting, the string remains double-quoted by default, whether or not it +is translated and replaced. If the ‘noexpand_translation’ option is +enabled using the ‘shopt’ builtin (*note The Shopt Builtin::), +translated strings are single-quoted instead of double-quoted. + + The rest of this section is a brief overview of how you use gettext +to create translations for strings in a shell script named SCRIPTNAME. +There are more details in the gettext documentation. + + +File: bash.info, Node: Creating Internationalized Scripts, Up: Locale Translation + +Once you've marked the strings in your script that you want to translate +using $"...", you create a gettext "template" file using the command + + bash --dump-po-strings SCRIPTNAME > DOMAIN.pot + +The DOMAIN is your “message domain”. It's just an arbitrary string +that's used to identify the files gettext needs, like a package or +script name. It needs to be unique among all the message domains on +systems where you install the translations, so gettext knows which +translations correspond to your script. You'll use the template file to +create translations for each target language. The template file +conventionally has the suffix ‘.pot’. + + You copy this template file to a separate file for each target +language you want to support (called "PO" files, which use the suffix +‘.po’). PO files use various naming conventions, but when you are +working to translate a template file into a particular language, you +first copy the template file to a file whose name is the language you +want to target, with the ‘.po’ suffix. For instance, the Spanish +translations of your strings would be in a file named ‘es.po’, and to +get started using a message domain named "example," you would run + + cp example.pot es.po + +Ultimately, PO files are often named DOMAIN.po and installed in +directories that contain multiple translation files for a particular +language. + + Whichever naming convention you choose, you will need to translate +the strings in the PO files into the appropriate languages. This has to +be done manually. + + When you have the translations and PO files complete, you'll use the +gettext tools to produce what are called "MO" files, which are compiled +versions of the PO files the gettext tools use to look up translations +efficiently. MO files are also called "message catalog" files. You use +the ‘msgfmt’ program to do this. For instance, if you had a file with +Spanish translations, you could run + + msgfmt -o es.mo es.po + +to produce the corresponding MO file. + + Once you have the MO files, you decide where to install them and use +the ‘TEXTDOMAINDIR’ shell variable to tell the gettext tools where they +are. Make sure to use the same message domain to name the MO files as +you did for the PO files when you install them. + + Your users will use the ‘LANG’ or ‘LC_MESSAGES’ shell variables to +select the desired language. + + You set the ‘TEXTDOMAIN’ variable to the script's message domain. As +above, you use the message domain to name your translation files. + + You, or possibly your users, set the ‘TEXTDOMAINDIR’ variable to the +name of a directory where the message catalog files are stored. If you +install the message files into the system's standard message catalog +directory, you don't need to worry about this variable. + + The directory where the message catalog files are stored varies +between systems. Some use the message catalog selected by the +‘LC_MESSAGES’ shell variable. Others create the name of the message +catalog from the value of the ‘TEXTDOMAIN’ shell variable, possibly +adding the ‘.mo’ suffix. If you use the ‘TEXTDOMAIN’ variable, you may +need to set the ‘TEXTDOMAINDIR’ variable to the location of the message +catalog files, as above. It's common to use both variables in this +fashion: ‘$TEXTDOMAINDIR’/‘$LC_MESSAGES’/LC_MESSAGES/‘$TEXTDOMAIN’.mo. + + If you used that last convention, and you wanted to store the message +catalog files with Spanish (es) and Esperanto (eo) translations into a +local directory you use for custom translation files, you could run + + TEXTDOMAIN=example + TEXTDOMAINDIR=/usr/local/share/locale + + cp es.mo ${TEXTDOMAINDIR}/es/LC_MESSAGES/${TEXTDOMAIN}.mo + cp eo.mo ${TEXTDOMAINDIR}/eo/LC_MESSAGES/${TEXTDOMAIN}.mo + + When all of this is done, and the message catalog files containing +the compiled translations are installed in the correct location, your +users will be able to see translated strings in any of the supported +languages by setting the ‘LANG’ or ‘LC_MESSAGES’ environment variables +before running your script. + + +File: bash.info, Node: Comments, Prev: Quoting, Up: Shell Syntax + +3.1.3 Comments +-------------- + +In a non-interactive shell, or an interactive shell in which the +‘interactive_comments’ option to the ‘shopt’ builtin is enabled (*note +The Shopt Builtin::), a word beginning with ‘#’ introduces a comment. A +word begins at the beginning of a line, after unquoted whitespace, or +after an operator. The comment causes that word and all remaining +characters on that line to be ignored. An interactive shell without the +‘interactive_comments’ option enabled does not allow comments. The +‘interactive_comments’ option is enabled by default in interactive +shells. *Note Interactive Shells::, for a description of what makes a +shell interactive. + + +File: bash.info, Node: Shell Commands, Next: Shell Functions, Prev: Shell Syntax, Up: Basic Shell Features + +3.2 Shell Commands +================== + +A simple shell command such as ‘echo a b c’ consists of the command +itself followed by arguments, separated by spaces. + + More complex shell commands are composed of simple commands arranged +together in a variety of ways: in a pipeline in which the output of one +command becomes the input of a second, in a loop or conditional +construct, or in some other grouping. + +* Menu: + +* Reserved Words:: Words that have special meaning to the shell. +* Simple Commands:: The most common type of command. +* Pipelines:: Connecting the input and output of several + commands. +* Lists:: How to execute commands sequentially. +* Compound Commands:: Shell commands for control flow. +* Coprocesses:: Two-way communication between commands. +* GNU Parallel:: Running commands in parallel. + + +File: bash.info, Node: Reserved Words, Next: Simple Commands, Up: Shell Commands + +3.2.1 Reserved Words +-------------------- + +Reserved words are words that have special meaning to the shell. They +are used to begin and end the shell's compound commands. + + The following words are recognized as reserved when unquoted and the +first word of a command (see below for exceptions): + +‘if’ ‘then’ ‘elif’ ‘else’ ‘fi’ ‘time’ +‘for’ ‘in’ ‘until’ ‘while’ ‘do’ ‘done’ +‘case’ ‘esac’ ‘coproc’‘select’‘function’ +‘{’ ‘}’ ‘[[’ ‘]]’ ‘!’ + +‘in’ is recognized as a reserved word if it is the third word of a +‘case’ or ‘select’ command. ‘in’ and ‘do’ are recognized as reserved +words if they are the third word in a ‘for’ command. + + +File: bash.info, Node: Simple Commands, Next: Pipelines, Prev: Reserved Words, Up: Shell Commands + +3.2.2 Simple Commands +--------------------- + +A simple command is the kind of command that's executed most often. +It's just a sequence of words separated by ‘blank’s, terminated by one +of the shell's control operators (*note Definitions::). The first word +generally specifies a command to be executed, with the rest of the words +being that command's arguments. + + The return status (*note Exit Status::) of a simple command is its +exit status as provided by the POSIX 1003.1 ‘waitpid’ function, or 128+N +if the command was terminated by signal N. + + +File: bash.info, Node: Pipelines, Next: Lists, Prev: Simple Commands, Up: Shell Commands + +3.2.3 Pipelines +--------------- + +A ‘pipeline’ is a sequence of one or more commands separated by one of +the control operators ‘|’ or ‘|&’. + + The format for a pipeline is + [time [-p]] [!] COMMAND1 [ | or |& COMMAND2 ] ... + +The output of each command in the pipeline is connected via a pipe to +the input of the next command. That is, each command reads the previous +command's output. This connection is performed before any redirections +specified by COMMAND1. + + If ‘|&’ is the pipeline operator, COMMAND1's standard error, in +addition to its standard output, is connected to COMMAND2's standard +input through the pipe; it is shorthand for ‘2>&1 |’. This implicit +redirection of the standard error to the standard output is performed +after any redirections specified by COMMAND1, consistent with that +shorthand. + + If the reserved word ‘time’ precedes the pipeline, Bash prints timing +statistics for the pipeline once it finishes. The statistics currently +consist of elapsed (wall-clock) time and user and system time consumed +by the command's execution. The ‘-p’ option changes the output format +to that specified by POSIX. When the shell is in POSIX mode (*note Bash +POSIX Mode::), it does not recognize ‘time’ as a reserved word if the +next token begins with a ‘-’. The value of the ‘TIMEFORMAT’ variable is +a format string that specifies how the timing information should be +displayed. *Note Bash Variables::, for a description of the available +formats. Providing ‘time’ as a reserved word permits the timing of +shell builtins, shell functions, and pipelines. An external ‘time’ +command cannot time these easily. + + When the shell is in POSIX mode (*note Bash POSIX Mode::), you can +use ‘time’ by itself as a simple command. In this case, the shell +displays the total user and system time consumed by the shell and its +children. The ‘TIMEFORMAT’ variable specifies the format of the time +information. + + If a pipeline is not executed asynchronously (*note Lists::), the +shell waits for all commands in the pipeline to complete. + + Each command in a multi-command pipeline, where pipes are created, is +executed in its own “subshell”, which is a separate process (*note +Command Execution Environment::). If the ‘lastpipe’ option is enabled +using the ‘shopt’ builtin (*note The Shopt Builtin::), and job control +is not active, the last element of a pipeline may be run by the shell +process. + + The exit status of a pipeline is the exit status of the last command +in the pipeline, unless the ‘pipefail’ option is enabled (*note The Set +Builtin::). If ‘pipefail’ 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 +‘!’ precedes the pipeline, the exit status is the logical negation of +the exit status as described above. If a pipeline is not executed +asynchronously (*note Lists::), the shell waits for all commands in the +pipeline to terminate before returning a value. The return status of an +asynchronous pipeline is 0. + + +File: bash.info, Node: Lists, Next: Compound Commands, Prev: Pipelines, Up: Shell Commands + +3.2.4 Lists of Commands +----------------------- + +A ‘list’ is a sequence of one or more pipelines separated by one of the +operators ‘;’, ‘&’, ‘&&’, or ‘||’, and optionally terminated by one of +‘;’, ‘&’, or a ‘newline’. + + Of these list operators, ‘&&’ and ‘||’ have equal precedence, +followed by ‘;’ and ‘&’, which have equal precedence. + + A sequence of one or more newlines may appear in a ‘list’ to delimit +commands, equivalent to a semicolon. + + If a command is terminated by the control operator ‘&’, the shell +executes the command asynchronously in a subshell. This is known as +executing the command in the “background”, and these are referred to as +“asynchronous” commands. The shell does not wait for the command to +finish, and the return status is 0 (true). When job control is not +active (*note Job Control::), the standard input for asynchronous +commands, in the absence of any explicit redirections, is redirected +from ‘/dev/null’. + + Commands separated by a ‘;’ 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. + + AND and OR lists are sequences of one or more pipelines separated by +the control operators ‘&&’ and ‘||’, respectively. AND and OR lists are +executed with left associativity. + + An AND list has the form + COMMAND1 && COMMAND2 + +COMMAND2 is executed if, and only if, COMMAND1 returns an exit status of +zero (success). + + An OR list has the form + COMMAND1 || COMMAND2 + +COMMAND2 is executed if, and only if, 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. + + +File: bash.info, Node: Compound Commands, Next: Coprocesses, Prev: Lists, Up: Shell Commands + +3.2.5 Compound Commands +----------------------- + +* Menu: + +* Looping Constructs:: Shell commands for iterative action. +* Conditional Constructs:: Shell commands for conditional execution. +* Command Grouping:: Ways to group commands. + +Compound commands are the shell programming language constructs. Each +construct begins with a reserved word or control operator and is +terminated by a corresponding reserved word or operator. Any +redirections (*note Redirections::) associated with a compound command +apply to all commands within that compound command unless explicitly +overridden. + + In most cases a list of commands in a compound 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. + + Bash provides looping constructs, conditional commands, and +mechanisms to group commands and execute them as a unit. + + +File: bash.info, Node: Looping Constructs, Next: Conditional Constructs, Up: Compound Commands + +3.2.5.1 Looping Constructs +.......................... + +Bash supports the following looping constructs. + + Note that wherever a ‘;’ appears in the description of a command's +syntax, it may be replaced with one or more newlines. + +‘until’ + The syntax of the ‘until’ command is: + + until TEST-COMMANDS; do CONSEQUENT-COMMANDS; done + + Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit + status which is not zero. The return status is the exit status of + the last command executed in CONSEQUENT-COMMANDS, or zero if none + was executed. + +‘while’ + The syntax of the ‘while’ command is: + + while TEST-COMMANDS; do CONSEQUENT-COMMANDS; done + + Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit + status of zero. The return status is the exit status of the last + command executed in CONSEQUENT-COMMANDS, or zero if none was + executed. + +‘for’ + The syntax of the ‘for’ command is: + + for NAME [ [in WORDS ...] ; ] do COMMANDS; done + + Expand WORDS (*note Shell Expansions::), and then execute COMMANDS + once for each word in the resultant list, with NAME bound to the + current word. If ‘in WORDS’ is not present, the ‘for’ command + executes the COMMANDS once for each positional parameter that is + set, as if ‘in "$@"’ had been specified (*note Special + Parameters::). + + The return status is the exit status of the last command that + executes. If there are no items in the expansion of WORDS, no + commands are executed, and the return status is zero. + + There is an alternate form of the ‘for’ command which is similar to + the C language: + + for (( EXPR1 ; EXPR2 ; EXPR3 )) [;] do COMMANDS ; done + + First, evaluate the arithmetic expression EXPR1 according to the + rules described below (*note Shell Arithmetic::). Then, repeatedly + evaluate the arithmetic expression EXPR2 until it evaluates to + zero. Each time EXPR2 evaluates to a non-zero value, execute + COMMANDS and evaluate the arithmetic expression EXPR3. 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 COMMANDS + that is executed, or non-zero if any of the expressions is invalid. + + Use the ‘break’ and ‘continue’ builtins (*note Bourne Shell +Builtins::) to control loop execution. + + +File: bash.info, Node: Conditional Constructs, Next: Command Grouping, Prev: Looping Constructs, Up: Compound Commands + +3.2.5.2 Conditional Constructs +.............................. + +‘if’ + The syntax of the ‘if’ command is: + + if TEST-COMMANDS; then + CONSEQUENT-COMMANDS; + [elif MORE-TEST-COMMANDS; then + MORE-CONSEQUENTS;] + [else ALTERNATE-CONSEQUENTS;] + fi + + The TEST-COMMANDS list is executed, and if its return status is + zero, the CONSEQUENT-COMMANDS list is executed. If TEST-COMMANDS + returns a non-zero status, each ‘elif’ list is executed in turn, + and if its exit status is zero, the corresponding MORE-CONSEQUENTS + is executed and the command completes. If ‘else + ALTERNATE-CONSEQUENTS’ is present, and the final command in the + final ‘if’ or ‘elif’ clause has a non-zero exit status, then + ALTERNATE-CONSEQUENTS is executed. The return status is the exit + status of the last command executed, or zero if no condition tested + true. + +‘case’ + The syntax of the ‘case’ command is: + + case WORD in + [ [(] PATTERN [| PATTERN]...) COMMAND-LIST ;;]... + esac + + ‘case’ will selectively execute the COMMAND-LIST corresponding to + the first PATTERN that matches WORD, proceeding from the first + pattern to the last. The match is performed according to the rules + described below in *note Pattern Matching::. If the ‘nocasematch’ + shell option (see the description of ‘shopt’ in *note The Shopt + Builtin::) is enabled, the match is performed without regard to the + case of alphabetic characters. The ‘|’ is used to separate + multiple patterns in a pattern list, and the ‘)’ operator + terminates the pattern list. A pattern list and an associated + COMMAND-LIST is known as a CLAUSE. + + Each clause must be terminated with ‘;;’, ‘;&’, or ‘;;&’. The WORD + undergoes tilde expansion, parameter expansion, command + substitution, process substitution, arithmetic expansion, and quote + removal (*note Shell Parameter Expansion::) before the shell + attempts to match the pattern. Each PATTERN undergoes tilde + expansion, parameter expansion, command substitution, arithmetic + expansion, process substitution, and quote removal. + + There may be an arbitrary number of ‘case’ clauses, each terminated + by a ‘;;’, ‘;&’, or ‘;;&’. The first pattern that matches + determines the command-list that is executed. It's a common idiom + to use ‘*’ as the final pattern to define the default case, since + that pattern will always match. + + Here is an example using ‘case’ in a script that could be used to + describe one interesting feature of an animal: + + echo -n "Enter the name of an animal: " + read ANIMAL + echo -n "The $ANIMAL has " + case $ANIMAL in + horse | dog | cat) echo -n "four";; + man | kangaroo ) echo -n "two";; + *) echo -n "an unknown number of";; + esac + echo " legs." + + If the ‘;;’ operator is used, the ‘case’ command completes after + the first pattern match. Using ‘;&’ in place of ‘;;’ causes + execution to continue with the COMMAND-LIST associated with the + next clause, if any. Using ‘;;&’ in place of ‘;;’ causes the shell + to test the patterns in the next clause, if any, and execute any + associated COMMAND-LIST if the match succeeds, continuing the case + statement execution as if the pattern list had not matched. + + The return status is zero if no PATTERN matches. Otherwise, the + return status is the exit status of the last COMMAND-LIST executed. + +‘select’ + + The ‘select’ construct allows the easy generation of menus. It has + almost the same syntax as the ‘for’ command: + + select NAME [in WORDS ...]; do COMMANDS; done + + First, expand the list of words following ‘in’, generating a list + of items, and print the set of expanded words on the standard error + stream, each preceded by a number. If the ‘in WORDS’ is omitted, + print the positional parameters, as if ‘in "$@"’ had been + specified. ‘select’ then displays the ‘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 ‘select’ sets the + value of NAME to that word. If the line is empty, ‘select’ + displays the words and prompt again. If ‘EOF’ is read, ‘select’ + completes and returns 1. Any other value read causes NAME to be + set to null. The line read is saved in the variable ‘REPLY’. + + The COMMANDS are executed after each selection until a ‘break’ + command is executed, at which point the ‘select’ command completes. + + Here is an example that allows the user to pick a filename from the + current directory, and displays the name and index of the file + selected. + + select fname in *; + do + echo you picked $fname \($REPLY\) + break; + done + +‘((...))’ + (( EXPRESSION )) + + The arithmetic EXPRESSION is evaluated according to the rules + described below (*note Shell Arithmetic::). The EXPRESSION + undergoes the same expansions as if it were within double quotes, + but unescaped double quote characters in EXPRESSION are not treated + specially and are removed. Since this can potentially result in + empty strings, this command treats those as expressions that + evaluate to 0. If the value of the expression is non-zero, the + return status is 0; otherwise the return status is 1. + +‘[[...]]’ + [[ EXPRESSION ]] + + Evaluate the conditional expression EXPRESSION and return a status + of zero (true) or non-zero (false). Expressions are composed of + the primaries described below in *note Bash Conditional + Expressions::. The words between the ‘[[’ and ‘]]’ do not undergo + word splitting and filename expansion. The shell performs tilde + expansion, parameter and variable expansion, arithmetic expansion, + command substitution, process substitution, and quote removal on + those words. Conditional operators such as ‘-f’ must be unquoted + to be recognized as primaries. + + When used with ‘[[’, the ‘<’ and ‘>’ operators sort + lexicographically using the current locale. + + When the ‘==’ and ‘!=’ operators are used, the string to the right + of the operator is considered a pattern and matched according to + the rules described below in *note Pattern Matching::, as if the + ‘extglob’ shell option were enabled. The ‘=’ operator is identical + to ‘==’. If the ‘nocasematch’ shell option (see the description of + ‘shopt’ in *note The Shopt Builtin::) is enabled, the match is + performed without regard to the case of alphabetic characters. The + return value is 0 if the string matches (‘==’) or does not match + (‘!=’) the pattern, and 1 otherwise. + + If you quote any part of the pattern, using any of the shell's + quoting mechanisms, the quoted portion is matched literally. This + means every character in the quoted portion matches itself, instead + of having any special pattern matching meaning. + + An additional binary operator, ‘=~’, is available, with the same + precedence as ‘==’ and ‘!=’. When you use ‘=~’, the string to the + right of the operator is considered a POSIX extended regular + expression pattern and matched accordingly (using the POSIX + ‘regcomp’ and ‘regexec’ interfaces usually described in regex(3)). + The return value is 0 if the string matches the pattern, and 1 if + it does not. If the regular expression is syntactically incorrect, + the conditional expression returns 2. If the ‘nocasematch’ shell + option (see the description of ‘shopt’ in *note The Shopt + Builtin::) is enabled, the match is performed without regard to the + case of alphabetic characters. + + You can quote any part of the pattern to force the quoted portion + to be matched literally instead of as a regular expression (see + above). If the pattern is stored in a shell variable, quoting the + variable expansion forces the entire pattern to be matched + literally. + + The match succeeds if the pattern matches any part of the string. + If you want to force the pattern to match the entire string, anchor + the pattern using the ‘^’ and ‘$’ regular expression operators. + + For example, the following will match a line (stored in the shell + variable ‘line’) if there is a sequence of characters anywhere in + the value consisting of any number, including zero, of characters + in the ‘space’ character class, immediately followed by zero or one + instances of ‘a’, then a ‘b’: + + [[ $line =~ [[:space:]]*(a)?b ]] + + That means values for ‘line’ like ‘aab’, ‘ aaaaaab’, ‘xaby’, and ‘ + ab’ will all match, as will a line containing a ‘b’ anywhere in its + value. + + If you want to match a character that's special to the regular + expression grammar (‘^$|[]()\.*+?’), it has to be quoted to remove + its special meaning. This means that in the pattern ‘xxx.txt’, the + ‘.’ matches any character in the string (its usual regular + expression meaning), but in the pattern ‘"xxx.txt"’, it can only + match a literal ‘.’. + + Likewise, if you want to include a character in your pattern that + has a special meaning to the regular expression grammar, you must + make sure it's not quoted. If you want to anchor a pattern at the + beginning or end of the string, for instance, you cannot quote the + ‘^’ or ‘$’ characters using any form of shell quoting. + + If you want to match ‘initial string’ at the start of a line, the + following will work: + [[ $line =~ ^"initial string" ]] + but this will not: + [[ $line =~ "^initial string" ]] + because in the second example the ‘^’ is quoted and doesn't have + its usual special meaning. + + It is sometimes difficult to specify a regular expression properly + without using quotes, or to keep track of the quoting used by + regular expressions while paying attention to shell quoting and the + shell's quote removal. Storing the regular expression in a shell + variable is often a useful way to avoid problems with quoting + characters that are special to the shell. For example, the + following is equivalent to the pattern used above: + + pattern='[[:space:]]*(a)?b' + [[ $line =~ $pattern ]] + + Shell programmers should take special care with backslashes, since + backslashes are used by both the shell and regular expressions to + remove the special meaning from the following character. This + means that after the shell's word expansions complete (*note Shell + Expansions::), any backslashes remaining in parts of the pattern + that were originally not quoted can remove the special meaning of + pattern characters. If any part of the pattern is quoted, the + shell does its best to ensure that the regular expression treats + those remaining backslashes as literal, if they appeared in a + quoted portion. + + The following two sets of commands are _not_ equivalent: + + pattern='\.' + + [[ . =~ $pattern ]] + [[ . =~ \. ]] + + [[ . =~ "$pattern" ]] + [[ . =~ '\.' ]] + + The first two matches will succeed, but the second two will not, + because in the second two the backslash will be part of the pattern + to be matched. In the first two examples, the pattern passed to + the regular expression parser is ‘\.’. The backslash removes the + special meaning from ‘.’, so the literal ‘.’ matches. In the + second two examples, the pattern passed to the regular expression + parser has the backslash quoted (e.g., ‘\\\.’), which will not + match the string, since it does not contain a backslash. If the + string in the first examples were anything other than ‘.’, say ‘a’, + the pattern would not match, because the quoted ‘.’ in the pattern + loses its special meaning of matching any single character. + + Bracket expressions in regular expressions can be sources of errors + as well, since characters that are normally special in regular + expressions lose their special meanings between brackets. However, + you can use bracket expressions to match special pattern characters + without quoting them, so they are sometimes useful for this + purpose. + + Though it might seem like a strange way to write it, the following + pattern will match a ‘.’ in the string: + + [[ . =~ [.] ]] + + The shell performs any word expansions before passing the pattern + to the regular expression functions, so you can assume that the + shell's quoting takes precedence. As noted above, the regular + expression parser will interpret any unquoted backslashes remaining + in the pattern after shell expansion according to its own rules. + The intention is to avoid making shell programmers quote things + twice as much as possible, so shell quoting should be sufficient to + quote special pattern characters where that's necessary. + + The array variable ‘BASH_REMATCH’ records which parts of the string + matched the pattern. The element of ‘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 + ‘BASH_REMATCH’ indices. The element of ‘BASH_REMATCH’ with index N + is the portion of the string matching the Nth parenthesized + subexpression. + + Bash sets ‘BASH_REMATCH’ in the global scope; declaring it as a + local variable will lead to unexpected results. + + Expressions may be combined using the following operators, listed + in decreasing order of precedence: + + ‘( EXPRESSION )’ + Returns the value of EXPRESSION. This may be used to override + the normal precedence of operators. + + ‘! EXPRESSION’ + True if EXPRESSION is false. + + ‘EXPRESSION1 && EXPRESSION2’ + True if both EXPRESSION1 and EXPRESSION2 are true. + + ‘EXPRESSION1 || EXPRESSION2’ + True if either EXPRESSION1 or EXPRESSION2 is true. + + The ‘&&’ and ‘||’ operators do not evaluate EXPRESSION2 if the + value of EXPRESSION1 is sufficient to determine the return value of + the entire conditional expression. + + +File: bash.info, Node: Command Grouping, Prev: Conditional Constructs, Up: Compound Commands + +3.2.5.3 Grouping Commands +......................... + +Bash provides two ways to group a list of commands to be executed as a +unit. When commands are grouped, redirections may be applied to the +entire command list. For example, the output of all the commands in the +list may be redirected to a single stream. + +‘()’ + ( LIST ) + + Placing a list of commands between parentheses forces the shell to + create a subshell (*note Command Execution Environment::), and each + of the commands in LIST is executed in that subshell environment. + Since the LIST is executed in a subshell, variable assignments do + not remain in effect after the subshell completes. + +‘{}’ + { LIST; } + + Placing a list of commands between curly braces causes the list to + be executed in the current shell environment. No subshell is + created. The semicolon (or newline) following LIST is required. + + In addition to the creation of a subshell, there is a subtle +difference between these two constructs due to historical reasons. The +braces are reserved words, so they must be separated from the LIST by +‘blank’s or other shell metacharacters. The parentheses are operators, +and are recognized as separate tokens by the shell even if they are not +separated from the LIST by whitespace. + + The exit status of both of these constructs is the exit status of +LIST. + + +File: bash.info, Node: Coprocesses, Next: GNU Parallel, Prev: Compound Commands, Up: Shell Commands + +3.2.6 Coprocesses +----------------- + +A ‘coprocess’ is a shell command preceded by the ‘coproc’ reserved word. +A coprocess is executed asynchronously in a subshell, as if the command +had been terminated with the ‘&’ control operator, with a two-way pipe +established between the executing shell and the coprocess. + + The syntax for a coprocess is: + + coproc [NAME] COMMAND [REDIRECTIONS] + +This creates a coprocess named NAME. COMMAND may be either a simple +command (*note Simple Commands::) or a compound command (*note Compound +Commands::). NAME is a shell variable name. If NAME is not supplied, +the default name is ‘COPROC’. + + The recommended form to use for a coprocess is + + coproc NAME { COMMAND; } + +This form is preferred because simple commands result in the coprocess +always being named ‘COPROC’, and it is simpler to use and more complete +than the other compound commands. + + There are other forms of coprocesses: + + coproc NAME COMPOUND-COMMAND + coproc COMPOUND-COMMAND + coproc SIMPLE-COMMAND + +If COMMAND is a compound command, NAME is optional. The word following +‘coproc’ determines whether that word is interpreted as a variable name: +it is interpreted as NAME if it is not a reserved word that introduces a +compound command. If COMMAND is a simple command, NAME is not allowed; +this is to avoid confusion between NAME and the first word of the simple +command. + + When the coprocess is executed, the shell creates an array variable +(*note Arrays::) named NAME in the context of the executing shell. The +standard output of COMMAND is connected via a pipe to a file descriptor +in the executing shell, and that file descriptor is assigned to NAME[0]. +The standard input of COMMAND is connected via a pipe to a file +descriptor in the executing shell, and that file descriptor is assigned +to NAME[1]. This pipe is established before any redirections specified +by the command (*note Redirections::). 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. + + The process ID of the shell spawned to execute the coprocess is +available as the value of the variable ‘NAME_PID’. The ‘wait’ builtin +may be used to wait for the coprocess to terminate. + + Since the coprocess is created as an asynchronous command, the +‘coproc’ command always returns success. The return status of a +coprocess is the exit status of COMMAND. + + +File: bash.info, Node: GNU Parallel, Prev: Coprocesses, Up: Shell Commands + +3.2.7 GNU Parallel +------------------ + +There are ways to run commands in parallel that are not built into Bash. +GNU Parallel is a tool to do just that. + + GNU Parallel, as its name suggests, can be used to build and run +commands in parallel. You may run the same command with different +arguments, whether they are filenames, usernames, hostnames, or lines +read from files. GNU Parallel provides shorthand references to many of +the most common operations (input lines, various portions of the input +line, different ways to specify the input source, and so on). Parallel +can replace ‘xargs’ or feed commands from its input sources to several +different instances of Bash. + + For a complete description, refer to the GNU Parallel documentation, +which is available at +. + + +File: bash.info, Node: Shell Functions, Next: Shell Parameters, Prev: Shell Commands, Up: Basic Shell Features + +3.3 Shell Functions +=================== + +Shell functions are a way to group commands for later execution using a +single name for the group. They are executed just like a "regular" +simple command. When the name of a shell function is used as a simple +command name, the shell executes the list of commands associated with +that function name. Shell functions are executed in the current shell +context; there is no new process created to interpret them. + + Functions are declared using this syntax: + FNAME () COMPOUND-COMMAND [ REDIRECTIONS ] + + or + + function FNAME [()] COMPOUND-COMMAND [ REDIRECTIONS ] + + This defines a shell function named FNAME. The reserved word +‘function’ is optional. If the ‘function’ reserved word is supplied, +the parentheses are optional. The “body” of the function is the +compound command COMPOUND-COMMAND (*note Compound Commands::). That +command is usually a LIST enclosed between { and }, but may be any +compound command listed above. If the ‘function’ reserved word is used, +but the parentheses are not supplied, the braces are recommended. When +the shell is in POSIX mode (*note Bash POSIX Mode::), FNAME must be a +valid shell name and may not be the same as one of the special builtins +(*note Special Builtins::). When not in POSIX mode, a function name can +be any unquoted shell word that does not contain ‘$’. + + Any redirections (*note Redirections::) associated with the shell +function are performed when the function is executed. Function +definitions are deleted using the ‘-f’ option to the ‘unset’ builtin +(*note Bourne Shell Builtins::). + + 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. + + Note that for historical reasons, in the most common usage the curly +braces that surround the body of the function must be separated from the +body by ‘blank’s or newlines. This is because the braces are reserved +words and are only recognized as such when they are separated from the +command list by whitespace or another shell metacharacter. When using +the braces, the LIST must be terminated by a semicolon, a ‘&’, or a +newline. + + COMPOUND-COMMAND is executed whenever FNAME is specified as the name +of a simple command. Functions are executed in the context of the +calling shell; there is no new process 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 (*note Positional +Parameters::). The special parameter ‘#’ that expands to the number of +positional parameters is updated to reflect the new set of positional +parameters. Special parameter ‘0’ is unchanged. The first element of +the ‘FUNCNAME’ variable is set to the name of the function while the +function is executing. + + All other aspects of the shell execution environment are identical +between a function and its caller with these exceptions: the ‘DEBUG’ and +‘RETURN’ traps are not inherited unless the function has been given the +‘trace’ attribute using the ‘declare’ builtin or the ‘-o functrace’ +option has been enabled with the ‘set’ builtin, (in which case all +functions inherit the ‘DEBUG’ and ‘RETURN’ traps), and the ‘ERR’ trap is +not inherited unless the ‘-o errtrace’ shell option has been enabled. +*Note Bourne Shell Builtins::, for the description of the ‘trap’ +builtin. + + The ‘FUNCNEST’ 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. + + If the builtin command ‘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 ‘RETURN’ trap is +executed before execution resumes. When a function completes, the +values of the positional parameters and the special parameter ‘#’ are +restored to the values they had prior to the function's execution. If +‘return’ is supplied a numeric argument, that is the function's return +status; otherwise the function's return status is the exit status of the +last command executed before the ‘return’. + + Variables local to the function are declared with the ‘local’ builtin +(“local variables”). Ordinarily, variables and their values are shared +between a function and its caller. These variables are visible only to +the function and the commands it invokes. This is particularly +important when a shell function calls other functions. + + In the following description, the “current scope” 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. A local variable at the current local scope is a +variable declared using the ‘local’ or ‘declare’ builtins in the +function that is currently executing. + + Local variables "shadow" variables with the same name declared at +previous scopes. For instance, a local variable declared in a function +hides variables with the same name declared at previous scopes, +including global variables: references and assignments refer to the +local variable, leaving the variables at previous scopes unmodified. +When the function returns, the global variable is once again visible. + + The shell uses “dynamic scoping” 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. + + For example, if a variable ‘var’ is declared as local in function +‘func1’, and ‘func1’ calls another function ‘func2’, references to ‘var’ +made from within ‘func2’ resolve to the local variable ‘var’ from +‘func1’, shadowing any global variable named ‘var’. + + The following script demonstrates this behavior. When executed, the +script displays + + In func2, var = func1 local + + func1() + { + local var='func1 local' + func2 + } + + func2() + { + echo "In func2, var = $var" + } + + var=global + func1 + + The ‘unset’ builtin also acts using the same dynamic scope: if a +variable is local to the current scope, ‘unset’ unsets 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 remains 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 becomes visible. If the unset acts on a +variable at a previous scope, any instance of a variable with that name +that had been shadowed becomes visible (see below how the +‘localvar_unset’ shell option changes this behavior). + + The ‘-f’ option to the ‘declare’ (‘typeset’) builtin command (*note +Bash Builtins::) lists function names and definitions. The ‘-F’ option +to ‘declare’ or ‘typeset’ lists the function names only (and optionally +the source file and line number, if the ‘extdebug’ 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 ‘-f’ option to the ‘export’ builtin (*note +Bourne Shell Builtins::). The ‘-f’ option to the ‘unset’ builtin (*note +Bourne Shell Builtins::) deletes a function definition. + + Functions may be recursive. The ‘FUNCNEST’ variable may be used to +limit the depth of the function call stack and restrict the number of +function invocations. By default, Bash places no limit on the number of +recursive calls. + + +File: bash.info, Node: Shell Parameters, Next: Shell Expansions, Prev: Shell Functions, Up: Basic Shell Features + +3.4 Shell Parameters +==================== + +* Menu: + +* Positional Parameters:: The shell's command-line arguments. +* Special Parameters:: Parameters denoted by special characters. + +A “parameter” is an entity that stores values. It can be a ‘name’, a +number, or one of the special characters listed below. A “variable” is +a parameter denoted by a ‘name’. A variable has a ‘value’ and zero or +more ‘attributes’. Attributes are assigned using the ‘declare’ builtin +command (see the description of the ‘declare’ builtin in *note Bash +Builtins::). The ‘export’ and ‘readonly’ builtins assign specific +attributes. + + 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 ‘unset’ builtin command. + + A variable is assigned to using a statement of the form + NAME=[VALUE] +If VALUE is not given, the variable is assigned the null string. All +VALUEs undergo tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote removal (*note +Shell Parameter Expansion::). If the variable has its ‘integer’ +attribute set, then VALUE is evaluated as an arithmetic expression even +if the ‘$((...))’ expansion is not used (*note Arithmetic Expansion::). +Word splitting and filename expansion are not performed. Assignment +statements may also appear as arguments to the ‘alias’, ‘declare’, +‘typeset’, ‘export’, ‘readonly’, and ‘local’ builtin commands +(“declaration commands”). When in POSIX mode (*note Bash POSIX Mode::), +these builtins may appear in a command after one or more instances of +the ‘command’ builtin and retain these assignment statement properties. +For example, + command export var=value + + In the context where an assignment statement is assigning a value to +a shell variable or array index (*note Arrays::), the ‘+=’ operator +appends to or adds to the variable's previous value. This includes +arguments to declaration commands such as ‘declare’ that accept +assignment statements. When ‘+=’ is applied to a variable for which the +‘integer’ attribute has been set, the variable's current value and VALUE +are each evaluated as arithmetic expressions, and the sum of the results +is assigned as the variable's value. The current value is usually an +integer constant, but may be an expression. When ‘+=’ is applied to an +array variable using compound assignment (*note Arrays::), 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, VALUE is expanded and appended to the variable's value. + + A variable can be assigned the ‘nameref’ attribute using the ‘-n’ +option to the ‘declare’ or ‘local’ builtin commands (*note Bash +Builtins::) to create a “nameref”, 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 nameref 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 + declare -n ref=$1 +inside the function creates a local nameref variable ‘ref’ whose value +is the variable name passed as the first argument. References and +assignments to ‘ref’, and changes to its attributes, are treated as +references, assignments, and attribute modifications to the variable +whose name was passed as ‘$1’. + + If the control variable in a ‘for’ loop has the nameref attribute, +the list of words can be a list of shell variables, and a name reference +is established for each word in the list, in turn, when the loop is +executed. Array variables cannot be given the nameref attribute. +However, nameref variables can reference array variables and subscripted +array variables. Namerefs can be unset using the ‘-n’ option to the +‘unset’ builtin (*note Bourne Shell Builtins::). Otherwise, if ‘unset’ +is executed with the name of a nameref variable as an argument, the +variable referenced by the nameref variable is unset. + + When the shell starts, it reads its environment and creates a shell +variable from each environment variable that has a valid name, as +described below (*note Environment::). + + +File: bash.info, Node: Positional Parameters, Next: Special Parameters, Up: Shell Parameters + +3.4.1 Positional Parameters +--------------------------- + +A “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 ‘set’ builtin command. Positional parameter ‘N’ may be +referenced as ‘${N}’, or as ‘$N’ when ‘N’ consists of a single digit. +Positional parameters may not be assigned to with assignment statements. +The ‘set’ and ‘shift’ builtins are used to set and unset them (*note +Shell Builtin Commands::). The positional parameters are temporarily +replaced when a shell function is executed (*note Shell Functions::). + + When a positional parameter consisting of more than a single digit is +expanded, it must be enclosed in braces. Without braces, a digit +following ‘$’ can only refer to one of the first nine positional +parameters ($1\-$9) or the special parameter $0 (see below). + + +File: bash.info, Node: Special Parameters, Prev: Positional Parameters, Up: Shell Parameters + +3.4.2 Special Parameters +------------------------ + +The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. Special +parameters are denoted by one of the following characters. + +‘*’ + ($*) 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 word + expansions are performed, those words are subject to further word + splitting and filename 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 ‘IFS’ variable. + That is, ‘"$*"’ is equivalent to ‘"$1C$2C..."’, where C is the + first character of the value of the ‘IFS’ variable. If ‘IFS’ is + unset, the parameters are separated by spaces. If ‘IFS’ is null, + the parameters are joined without intervening separators. + +‘@’ + ($@) 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, such as the value portion of + an assignment statement, this expands to a single word with each + positional parameter separated by a space. When the expansion + occurs within double quotes, and word splitting is performed, each + parameter expands to a separate word. That is, ‘"$@"’ is + equivalent to ‘"$1" "$2" ...’. If the double-quoted expansion + occurs within a word, the expansion of the first parameter is + joined with the expansion of the beginning part of the original + word, and the expansion of the last parameter is joined with the + expansion of the last part of the original word. When there are no + positional parameters, ‘"$@"’ and ‘$@’ expand to nothing (i.e., + they are removed). + +‘#’ + ($#) Expands to the number of positional parameters in decimal. + +‘?’ + ($?) Expands to the exit status of the most recently executed + command. + +‘-’ + ($-, a hyphen.) Expands to the current option flags as specified + upon invocation, by the ‘set’ builtin command, or those set by the + shell itself (such as the ‘-i’ option). + +‘$’ + ($$) Expands to the process ID of the shell. In a subshell, it + expands to the process ID of the invoking shell, not the subshell. + +‘!’ + ($!) Expands to the process ID of the job most recently placed + into the background, whether executed as an asynchronous command or + using the ‘bg’ builtin (*note Job Control Builtins::). + +‘0’ + ($0) Expands to the name of the shell or shell script. This is set + at shell initialization. If Bash is invoked with a file of + commands (*note Shell Scripts::), ‘$0’ is set to the name of that + file. If Bash is started with the ‘-c’ option (*note Invoking + Bash::), then ‘$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 Bash, as given by argument zero. + + +File: bash.info, Node: Shell Expansions, Next: Redirections, Prev: Shell Parameters, Up: Basic Shell Features + +3.5 Shell Expansions +==================== + +Expansion is performed on the command line after it has been split into +‘token’s. Bash performs these expansions: + + • brace expansion + • tilde expansion + • parameter and variable expansion + • command substitution + • arithmetic expansion + • word splitting + • filename expansion + • quote removal + +* Menu: + +* Brace Expansion:: Expansion of expressions within braces. +* Tilde Expansion:: Expansion of the ~ character. +* Shell Parameter Expansion:: How Bash expands variables to their values. +* Command Substitution:: Using the output of a command as an argument. +* Arithmetic Expansion:: How to use arithmetic in shell expansions. +* Process Substitution:: A way to write and read to and from a + command. +* Word Splitting:: How the results of expansion are split into separate + arguments. +* Filename Expansion:: A shorthand for specifying filenames matching patterns. +* Quote Removal:: How and when quote characters are removed from + words. + + 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; filename +expansion; and quote removal. + + On systems that can support it, there is an additional expansion +available: “process substitution”. This is performed at the same time +as tilde, parameter, variable, and arithmetic expansion and command +substitution. + + “Quote removal” is always performed last. It removes quote +characters present in the original word, not ones resulting from one of +the other expansions, unless they have been quoted themselves. *Note +Quote Removal:: for more details. + + Only brace expansion, word splitting, and filename 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 ‘"$@"’ and ‘$*’ (*note Special Parameters::), and +‘"${NAME[@]}"’ and ‘${NAME[*]}’ (*note Arrays::). + + +File: bash.info, Node: Brace Expansion, Next: Tilde Expansion, Up: Shell Expansions + +3.5.1 Brace Expansion +--------------------- + +Brace expansion is a mechanism to generate arbitrary strings sharing a +common prefix and suffix, either of which can be empty. This mechanism +is similar to “filename expansion” (*note Filename Expansion::), but the +filenames generated need not exist. Patterns to be brace expanded are +formed from an optional PREAMBLE, followed by either a series of +comma-separated strings or a sequence expression between a pair of +braces, followed by an optional 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. + + Brace expansions may be nested. The results of each expanded string +are not sorted; brace expansion preserves left to right order. For +example, + bash$ echo a{d,c,b}e + ade ace abe + + A sequence expression takes the form ‘X..Y[..INCR]’, where X and Y +are either integers or letters, and INCR, an optional increment, is an +integer. When integers are supplied, the expression expands to each +number between X and Y, inclusive. If either X or Y begins with a zero, +each generated term will contain the same number of digits, zero-padding +where necessary. When letters are supplied, the expression expands to +each character lexicographically between X and Y, inclusive, using the C +locale. Note that both X and Y 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. + + Brace expansion is performed before any other expansions, and any +characters special to other expansions are preserved in the result. It +is strictly textual. Bash does not apply any syntactic interpretation +to the context of the expansion or the text between the braces. + + 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 ‘{’ or ‘,’ may be quoted with a backslash to prevent its being +considered part of a brace expression. To avoid conflicts with +parameter expansion, the string ‘${’ is not considered eligible for +brace expansion, and inhibits brace expansion until the closing ‘}’. + + This construct is typically used as shorthand when the common prefix +of the strings to be generated is longer than in the above example: + mkdir /usr/local/src/bash/{old,new,dist,bugs} + or + chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} + + Brace expansion introduces a slight incompatibility with historical +versions of ‘sh’. ‘sh’ does not treat opening or closing braces +specially when they appear as part of a word, and preserves them in the +output. Bash removes braces from words as a consequence of brace +expansion. For example, a word entered to ‘sh’ as ‘file{1,2}’ appears +identically in the output. Bash outputs that word as ‘file1 file2’ +after brace expansion. Start Bash with the ‘+B’ option or disable brace +expansion with the ‘+B’ option to the ‘set’ command (*note Shell Builtin +Commands::) for strict ‘sh’ compatibility. + + +File: bash.info, Node: Tilde Expansion, Next: Shell Parameter Expansion, Prev: Brace Expansion, Up: Shell Expansions + +3.5.2 Tilde Expansion +--------------------- + +If a word begins with an unquoted tilde character (‘~’), all of the +characters up to the first unquoted slash (or all characters, if there +is no unquoted slash) are considered a “tilde-prefix”. 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 “login name”. +If this login name is the null string, the tilde is replaced with the +value of the ‘HOME’ shell variable. If ‘HOME’ is unset, the tilde +expands to the home directory of the user executing the shell instead. +Otherwise, the tilde-prefix is replaced with the home directory +associated with the specified login name. + + If the tilde-prefix is ‘~+’, the value of the shell variable ‘PWD’ +replaces the tilde-prefix. If the tilde-prefix is ‘~-’, the shell +substitutes the value of the shell variable ‘OLDPWD’, if it is set. + + If the characters following the tilde in the tilde-prefix consist of +a number N, 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 ‘dirs’ builtin invoked with the characters +following tilde in the tilde-prefix as an argument (*note The Directory +Stack::). If the tilde-prefix, sans the tilde, consists of a number +without a leading ‘+’ or ‘-’, tilde expansion assumes ‘+’. + + The results of tilde expansion are treated as if they were quoted, so +the replacement is not subject to word splitting and filename expansion. + + If the login name is invalid, or the tilde expansion fails, the +tilde-prefix is left unchanged. + + Bash checks each variable assignment for unquoted tilde-prefixes +immediately following a ‘:’ or the first ‘=’, and performs tilde +expansion in these cases. Consequently, one may use filenames with +tildes in assignments to ‘PATH’, ‘MAILPATH’, and ‘CDPATH’, and the shell +assigns the expanded value. + + The following table shows how Bash treats unquoted tilde-prefixes: + +‘~’ + The value of ‘$HOME’. +‘~/foo’ + ‘$HOME/foo’ + +‘~fred/foo’ + The directory or file ‘foo’ in the home directory of the user + ‘fred’. + +‘~+/foo’ + ‘$PWD/foo’ + +‘~-/foo’ + ‘${OLDPWD-'~-'}/foo’ + +‘~N’ + The string that would be displayed by ‘dirs +N’. + +‘~+N’ + The string that would be displayed by ‘dirs +N’. + +‘~-N’ + The string that would be displayed by ‘dirs -N’. + + Bash also performs tilde expansion on words satisfying the conditions +of variable assignments (*note Shell Parameters::) when they appear as +arguments to simple commands. Bash does not do this, except for the +declaration commands listed above, when in POSIX mode. + + +File: bash.info, Node: Shell Parameter Expansion, Next: Command Substitution, Prev: Tilde Expansion, Up: Shell Expansions + +3.5.3 Shell Parameter Expansion +------------------------------- + +The ‘$’ 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. For example, if the first +positional parameter has the value ‘a’, then ‘${11}’ expands to the +value of the eleventh positional parameter, while ‘$11’ expands to ‘a1’. + + When braces are used, the matching ending brace is the first ‘}’ not +escaped by a backslash or within a quoted string, and not within an +embedded arithmetic expansion, command substitution, or parameter +expansion. + + The basic form of parameter expansion is ${PARAMETER}, which +substitutes the value of PARAMETER. The PARAMETER is a shell parameter +as described above (*note Shell Parameters::) or an array reference +(*note Arrays::). The braces are required when PARAMETER is a +positional parameter with more than one digit, or when PARAMETER is +followed by a character that is not to be interpreted as part of its +name. + + If the first character of PARAMETER is an exclamation point (!), and +PARAMETER is not a nameref, it introduces a level of indirection. Bash +uses the value formed by expanding the rest of PARAMETER as the new +PARAMETER; this new parameter is then expanded and that value is used in +the rest of the expansion, rather than the expansion of the original +PARAMETER. This is known as ‘indirect expansion’. The value is subject +to tilde expansion, parameter expansion, command substitution, and +arithmetic expansion. If PARAMETER is a nameref, this expands to the +name of the variable referenced by PARAMETER instead of performing the +complete indirect expansion, for compatibility. The exceptions to this +are the expansions of ${!PREFIX*} and ${!NAME[@]} described below. The +exclamation point must immediately follow the left brace in order to +introduce indirection. + + In each of the cases below, WORD is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. + + When not performing substring expansion, using the forms described +below (e.g., ‘:-’), Bash tests for a parameter that is unset or null. +Omitting the colon results in a test only for a parameter that is unset. +Put another way, if the colon is included, the operator tests for both +PARAMETER's existence and that its value is not null; if the colon is +omitted, the operator tests only for existence. + +‘${PARAMETER:−WORD}’ + If PARAMETER is unset or null, the expansion of WORD is + substituted. Otherwise, the value of PARAMETER is substituted. + + $ v=123 + $ echo ${v-unset} + 123 + $ echo ${v:-unset-or-null} + 123 + $ unset v + $ echo ${v-unset} + unset + $ v= + $ echo ${v-unset} + + $ echo ${v:-unset-or-null} + unset-or-null + +‘${PARAMETER:=WORD}’ + If PARAMETER is unset or null, the expansion of WORD is assigned to + PARAMETER, and the result of the expansion is the final value of + PARAMETER. Positional parameters and special parameters may not be + assigned in this way. + + $ unset var + $ : ${var=DEFAULT} + $ echo $var + DEFAULT + $ var= + $ : ${var=DEFAULT} + $ echo $var + + $ var= + $ : ${var:=DEFAULT} + $ echo $var + DEFAULT + $ unset var + $ : ${var:=DEFAULT} + $ echo $var + DEFAULT + +‘${PARAMETER:?WORD}’ + If PARAMETER is null or unset, the shell writes the expansion of + WORD (or a message to that effect if WORD is not present) to the + standard error and, if it is not interactive, exits with a non-zero + status. An interactive shell does not exit, but does not execute + the command associated with the expansion. Otherwise, the value of + PARAMETER is substituted. + + $ var= + $ : ${var:?var is unset or null} + bash: var: var is unset or null + $ echo ${var?var is unset} + + $ unset var + $ : ${var?var is unset} + bash: var: var is unset + $ : ${var:?var is unset or null} + bash: var: var is unset or null + $ var=123 + $ echo ${var:?var is unset or null} + 123 + +‘${PARAMETER:+WORD}’ + If PARAMETER is null or unset, nothing is substituted, otherwise + the expansion of WORD is substituted. The value of PARAMETER is + not used. + + $ var=123 + $ echo ${var:+var is set and not null} + var is set and not null + $ echo ${var+var is set} + var is set + $ var= + $ echo ${var:+var is set and not null} + + $ echo ${var+var is set} + var is set + $ unset var + $ echo ${var+var is set} + + $ echo ${var:+var is set and not null} + + $ + +‘${PARAMETER:OFFSET}’ +‘${PARAMETER:OFFSET:LENGTH}’ + This is referred to as Substring Expansion. It expands to up to + LENGTH characters of the value of PARAMETER starting at the + character specified by OFFSET. If PARAMETER is ‘@’ or ‘*’, an + indexed array subscripted by ‘@’ or ‘*’, or an associative array + name, the results differ as described below. If :LENGTH is omitted + (the first form above), this expands to the substring of the value + of PARAMETER starting at the character specified by OFFSET and + extending to the end of the value. If OFFSET is omitted, it is + treated as 0. If LENGTH is omitted, but the colon after OFFSET is + present, it is treated as 0. LENGTH and OFFSET are arithmetic + expressions (*note Shell Arithmetic::). + + If OFFSET evaluates to a number less than zero, the value is used + as an offset in characters from the end of the value of PARAMETER. + If LENGTH evaluates to a number less than zero, it is interpreted + as an offset in characters from the end of the value of PARAMETER + rather than a number of characters, and the expansion is the + characters between OFFSET 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 ‘:-’ expansion. + + Here are some examples illustrating substring expansion on + parameters and subscripted arrays: + + $ string=01234567890abcdefgh + $ echo ${string:7} + 7890abcdefgh + $ echo ${string:7:0} + + $ echo ${string:7:2} + 78 + $ echo ${string:7:-2} + 7890abcdef + $ echo ${string: -7} + bcdefgh + $ echo ${string: -7:0} + + $ echo ${string: -7:2} + bc + $ echo ${string: -7:-2} + bcdef + $ set -- 01234567890abcdefgh + $ echo ${1:7} + 7890abcdefgh + $ echo ${1:7:0} + + $ echo ${1:7:2} + 78 + $ echo ${1:7:-2} + 7890abcdef + $ echo ${1: -7} + bcdefgh + $ echo ${1: -7:0} + + $ echo ${1: -7:2} + bc + $ echo ${1: -7:-2} + bcdef + $ array[0]=01234567890abcdefgh + $ echo ${array[0]:7} + 7890abcdefgh + $ echo ${array[0]:7:0} + + $ echo ${array[0]:7:2} + 78 + $ echo ${array[0]:7:-2} + 7890abcdef + $ echo ${array[0]: -7} + bcdefgh + $ echo ${array[0]: -7:0} + + $ echo ${array[0]: -7:2} + bc + $ echo ${array[0]: -7:-2} + bcdef + + If PARAMETER is ‘@’ or ‘*’, the result is LENGTH positional + parameters beginning at OFFSET. A negative OFFSET is taken + relative to one greater than the greatest positional parameter, so + an offset of -1 evaluates to the last positional parameter (or 0 if + there are no positional parameters). It is an expansion error if + LENGTH evaluates to a number less than zero. + + The following examples illustrate substring expansion using + positional parameters: + + $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h + $ echo ${@:7} + 7 8 9 0 a b c d e f g h + $ echo ${@:7:0} + + $ echo ${@:7:2} + 7 8 + $ echo ${@:7:-2} + bash: -2: substring expression < 0 + $ echo ${@: -7:2} + b c + $ echo ${@:0} + ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h + $ echo ${@:0:2} + ./bash 1 + $ echo ${@: -7:0} + + + If PARAMETER is an indexed array name subscripted by ‘@’ or ‘*’, + the result is the LENGTH members of the array beginning with + ‘${PARAMETER[OFFSET]}’. A negative OFFSET is taken relative to one + greater than the maximum index of the specified array. It is an + expansion error if LENGTH evaluates to a number less than zero. + + These examples show how you can use substring expansion with + indexed arrays: + + $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h) + $ echo ${array[@]:7} + 7 8 9 0 a b c d e f g h + $ echo ${array[@]:7:2} + 7 8 + $ echo ${array[@]: -7:2} + b c + $ echo ${array[@]: -7:-2} + bash: -2: substring expression < 0 + $ echo ${array[@]:0} + 0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h + $ echo ${array[@]:0:2} + 0 1 + $ echo ${array[@]: -7:0} + + + Substring expansion applied to an associative array produces + undefined results. + + Substring indexing is zero-based unless the positional parameters + are used, in which case the indexing starts at 1 by default. If + OFFSET is 0, and the positional parameters are used, ‘$0’ is + prefixed to the list. + +‘${!PREFIX*}’ +‘${!PREFIX@}’ + Expands to the names of variables whose names begin with PREFIX, + separated by the first character of the ‘IFS’ special variable. + When ‘@’ is used and the expansion appears within double quotes, + each variable name expands to a separate word. + +‘${!NAME[@]}’ +‘${!NAME[*]}’ + If NAME is an array variable, expands to the list of array indices + (keys) assigned in NAME. If NAME is not an array, expands to 0 if + NAME is set and null otherwise. When ‘@’ is used and the expansion + appears within double quotes, each key expands to a separate word. + +‘${#PARAMETER}’ + Substitutes the length in characters of the value of PARAMETER. If + PARAMETER is ‘*’ or ‘@’, the value substituted is the number of + positional parameters. If PARAMETER is an array name subscripted + by ‘*’ or ‘@’, the value substituted is the number of elements in + the array. If 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 PARAMETER, so negative indices + count back from the end of the array, and an index of -1 references + the last element. + +‘${PARAMETER#WORD}’ +‘${PARAMETER##WORD}’ + The WORD is expanded to produce a pattern and matched against the + expanded value of PARAMETER according to the rules described below + (*note Pattern Matching::). If the pattern matches the beginning + of the expanded value of PARAMETER, then the result of the + expansion is the expanded value of PARAMETER with the shortest + matching pattern (the ‘#’ case) or the longest matching pattern + (the ‘##’ case) deleted. If PARAMETER is ‘@’ or ‘*’, the pattern + removal operation is applied to each positional parameter in turn, + and the expansion is the resultant list. If PARAMETER is an array + variable subscripted with ‘@’ or ‘*’, the pattern removal operation + is applied to each member of the array in turn, and the expansion + is the resultant list. + +‘${PARAMETER%WORD}’ +‘${PARAMETER%%WORD}’ + The WORD is expanded to produce a pattern and matched against the + expanded value of PARAMETER according to the rules described below + (*note Pattern Matching::). If the pattern matches a trailing + portion of the expanded value of PARAMETER, then the result of the + expansion is the value of PARAMETER with the shortest matching + pattern (the ‘%’ case) or the longest matching pattern (the ‘%%’ + case) deleted. If PARAMETER is ‘@’ or ‘*’, the pattern removal + operation is applied to each positional parameter in turn, and the + expansion is the resultant list. If PARAMETER is an array variable + subscripted with ‘@’ or ‘*’, the pattern removal operation is + applied to each member of the array in turn, and the expansion is + the resultant list. + +‘${PARAMETER/PATTERN/STRING}’ +‘${PARAMETER//PATTERN/STRING}’ +‘${PARAMETER/#PATTERN/STRING}’ +‘${PARAMETER/%PATTERN/STRING}’ + The PATTERN is expanded to produce a pattern and matched against + the expanded value of PARAMETER as described below (*note Pattern + Matching::). The longest match of PATTERN in the expanded value is + replaced with STRING. STRING undergoes tilde expansion, parameter + and variable expansion, arithmetic expansion, command and process + substitution, and quote removal. + + In the first form above, only the first match is replaced. If + there are two slashes separating PARAMETER and PATTERN (the second + form above), all matches of PATTERN are replaced with STRING. If + PATTERN is preceded by ‘#’ (the third form above), it must match at + the beginning of the expanded value of PARAMETER. If PATTERN is + preceded by ‘%’ (the fourth form above), it must match at the end + of the expanded value of PARAMETER. + + If the expansion of STRING is null, matches of PATTERN are deleted + and the ‘/’ following PATTERN may be omitted. + + If the ‘patsub_replacement’ shell option is enabled using ‘shopt’ + (*note The Shopt Builtin::), any unquoted instances of ‘&’ in + STRING are replaced with the matching portion of PATTERN. This is + intended to duplicate a common ‘sed’ idiom. + + Quoting any part of STRING inhibits replacement in the expansion of + the quoted portion, including replacement strings stored in shell + variables. Backslash escapes ‘&’ in STRING; the backslash is + removed in order to permit a literal ‘&’ in the replacement string. + Users should take care if STRING 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 ‘&’ after expanding + STRING, so users should ensure to properly quote any occurrences of + ‘&’ they want to be taken literally in the replacement and ensure + any instances of ‘&’ they want to be replaced are unquoted. + + For instance, + + var=abcdef + rep='& ' + echo ${var/abc/& } + echo "${var/abc/& }" + echo ${var/abc/$rep} + echo "${var/abc/$rep}" + + will display four lines of "abc def", while + + var=abcdef + rep='& ' + echo ${var/abc/\& } + echo "${var/abc/\& }" + echo ${var/abc/"& "} + echo ${var/abc/"$rep"} + + will display four lines of "& def". Like the pattern removal + operators, double quotes surrounding the replacement string quote + the expanded characters, while double quotes enclosing the entire + parameter substitution do not, since the expansion is performed in + a context that doesn't take any enclosing double quotes into + account. + + Since backslash can escape ‘&’, it can also escape a backslash in + the replacement string. This means that ‘\\’ will insert a literal + backslash into the replacement, so these two ‘echo’ commands + + var=abcdef + rep='\\&xyz' + echo ${var/abc/\\&xyz} + echo ${var/abc/$rep} + + will both output ‘\abcxyzdef’. + + It should rarely be necessary to enclose only STRING in double + quotes. + + If the ‘nocasematch’ shell option (see the description of ‘shopt’ + in *note The Shopt Builtin::) is enabled, the match is performed + without regard to the case of alphabetic characters. + + If PARAMETER is ‘@’ or ‘*’, the substitution operation is applied + to each positional parameter in turn, and the expansion is the + resultant list. If PARAMETER is an array variable subscripted with + ‘@’ or ‘*’, the substitution operation is applied to each member of + the array in turn, and the expansion is the resultant list. + +‘${PARAMETER^PATTERN}’ +‘${PARAMETER^^PATTERN}’ +‘${PARAMETER,PATTERN}’ +‘${PARAMETER,,PATTERN}’ + This expansion modifies the case of alphabetic characters in + PARAMETER. First, the PATTERN is expanded to produce a pattern as + described below in *note Pattern Matching::. + + ‘Bash’ then examines characters in the expanded value of PARAMETER + against PATTERN as described below. If a character matches the + pattern, its case is converted. The pattern should not attempt to + match more than one character. + + Using ‘^’ converts lowercase letters matching PATTERN to uppercase; + ‘,’ converts matching uppercase letters to lowercase. The ‘^’ and + ‘,’ variants examine the first character in the expanded value and + convert its case if it matches PATTERN; the ‘^^’ and ‘,,’ variants + examine all characters in the expanded value and convert each one + that matches PATTERN. If PATTERN is omitted, it is treated like a + ‘?’, which matches every character. + + If PARAMETER is ‘@’ or ‘*’, the case modification operation is + applied to each positional parameter in turn, and the expansion is + the resultant list. If PARAMETER is an array variable subscripted + with ‘@’ or ‘*’, the case modification operation is applied to each + member of the array in turn, and the expansion is the resultant + list. + +‘${PARAMETER@OPERATOR}’ + The expansion is either a transformation of the value of PARAMETER + or information about PARAMETER itself, depending on the value of + OPERATOR. Each OPERATOR is a single letter: + + ‘U’ + The expansion is a string that is the value of PARAMETER with + lowercase alphabetic characters converted to uppercase. + ‘u’ + The expansion is a string that is the value of PARAMETER with + the first character converted to uppercase, if it is + alphabetic. + ‘L’ + The expansion is a string that is the value of PARAMETER with + uppercase alphabetic characters converted to lowercase. + ‘Q’ + The expansion is a string that is the value of PARAMETER + quoted in a format that can be reused as input. + ‘E’ + The expansion is a string that is the value of PARAMETER with + backslash escape sequences expanded as with the ‘$'...'’ + quoting mechanism. + ‘P’ + The expansion is a string that is the result of expanding the + value of PARAMETER as if it were a prompt string (*note + Controlling the Prompt::). + ‘A’ + The expansion is a string in the form of an assignment + statement or ‘declare’ command that, if evaluated, recreates + PARAMETER with its attributes and value. + ‘K’ + Produces a possibly-quoted version of the value of PARAMETER, + except that it prints the values of indexed and associative + arrays as a sequence of quoted key-value pairs (*note + Arrays::). The keys and values are quoted in a format that + can be reused as input. + ‘a’ + The expansion is a string consisting of flag values + representing PARAMETER's attributes. + ‘k’ + Like the ‘K’ transformation, but expands the keys and values + of indexed and associative arrays to separate words after word + splitting. + + If PARAMETER is ‘@’ or ‘*’, the operation is applied to each + positional parameter in turn, and the expansion is the resultant + list. If PARAMETER is an array variable subscripted with ‘@’ or + ‘*’, the operation is applied to each member of the array in turn, + and the expansion is the resultant list. + + The result of the expansion is subject to word splitting and + filename expansion as described below. + + +File: bash.info, Node: Command Substitution, Next: Arithmetic Expansion, Prev: Shell Parameter Expansion, Up: Shell Expansions + +3.5.4 Command Substitution +-------------------------- + +Command substitution allows the output of a command to replace the +command itself. The standard form of command substitution occurs when a +command is enclosed as follows: + $(COMMAND) +or (deprecated) + `COMMAND`. + +Bash performs command substitution by executing COMMAND 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 ‘$(cat FILE)’ can be replaced by the equivalent +but faster ‘$(< FILE)’. + + With the old-style backquote form of substitution, backslash retains +its literal meaning except when followed by ‘$’, ‘`’, or ‘\’. The first +backquote not preceded by a backslash terminates the command +substitution. When using the ‘$(COMMAND)’ form, all characters between +the parentheses make up the command; none are treated specially. + + There is an alternate form of command substitution: + + ${C COMMAND; } + +which executes COMMAND in the current execution environment and captures +its output, again with trailing newlines removed. + + The character C following the open brace must be a space, tab, +newline, or ‘|’, and the close brace must be in a position where a +reserved word may appear (i.e., preceded by a command terminator such as +semicolon). Bash allows the close brace to be joined to the remaining +characters in the word without being followed by a shell metacharacter +as a reserved word would usually require. + + Any side effects of COMMAND take effect immediately in the current +execution environment and persist in the current environment after the +command completes (e.g., the ‘exit’ builtin exits the shell). + + This type of command substitution superficially resembles executing +an unnamed shell function: local variables are created as when a shell +function is executing, and the ‘return’ builtin forces COMMAND to +complete; however, the rest of the execution environment, including the +positional parameters, is shared with the caller. + + If the first character following the open brace is a ‘|’, the +construct expands to the value of the ‘REPLY’ shell variable after +COMMAND executes, without removing any trailing newlines, and the +standard output of COMMAND remains the same as in the calling shell. +Bash creates ‘REPLY’ as an initially-unset local variable when COMMAND +executes, and restores ‘REPLY’ to the value it had before the command +substitution after COMMAND completes, as with any local variable. + + For example, this construct expands to ‘12345’, and leaves the shell +variable ‘X’ unchanged in the current execution environment: + + + ${ local X=12345 ; echo $X; } + +(not declaring ‘X’ as local would modify its value in the current +environment, as with normal shell function execution), while this +construct does not require any output to expand to ‘12345’: + + ${| REPLY=12345; } + +and restores ‘REPLY’ to the value it had before the command +substitution. + + Command substitutions may be nested. To nest when using the +backquoted form, escape the inner backquotes with backslashes. + + If the substitution appears within double quotes, Bash does not +perform word splitting and filename expansion on the results. + + +File: bash.info, Node: Arithmetic Expansion, Next: Process Substitution, Prev: Command Substitution, Up: Shell Expansions + +3.5.5 Arithmetic Expansion +-------------------------- + +Arithmetic expansion evaluates an arithmetic expression and substitutes +the result. The format for arithmetic expansion is: + + $(( EXPRESSION )) + + The EXPRESSION undergoes the same expansions as if it were within +double quotes, but unescaped double quote characters in EXPRESSION 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. Since the way Bash handles double quotes can potentially +result in empty strings, arithmetic expansion treats those as +expressions that evaluate to 0. Arithmetic expansions may be nested. + + The evaluation is performed according to the rules listed below +(*note Shell Arithmetic::). If the expression is invalid, Bash prints a +message indicating failure to the standard error, does not perform the +substitution, and does not execute the command associated with the +expansion. + + +File: bash.info, Node: Process Substitution, Next: Word Splitting, Prev: Arithmetic Expansion, Up: Shell Expansions + +3.5.6 Process Substitution +-------------------------- + +Process substitution allows a process's input or output to be referred +to using a filename. It takes the form of + <(LIST) +or + >(LIST) +The process LIST 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 ‘>(LIST)’ form is used, writing to the file provides input for +LIST. If the ‘<(LIST)’ form is used, reading the file obtains the +output of LIST. Note that no space may appear between the ‘<’ or ‘>’ +and the left parenthesis, otherwise the construct would be interpreted +as a redirection. + + Process substitution is supported on systems that support named pipes +(FIFOs) or the ‘/dev/fd’ method of naming open files. + + When available, process substitution is performed simultaneously with +parameter and variable expansion, command substitution, and arithmetic +expansion. + + +File: bash.info, Node: Word Splitting, Next: Filename Expansion, Prev: Process Substitution, Up: Shell Expansions + +3.5.7 Word Splitting +-------------------- + +The shell scans the results of parameter expansion, command +substitution, and arithmetic expansion that did not occur within double +quotes for word splitting. Words that were not expanded are not split. + + The shell treats each character of ‘$IFS’ as a delimiter, and splits +the results of the other expansions into fields using these characters +as field terminators. + + An “IFS whitespace” character is whitespace as defined above (*note +Definitions::) that appears in the value of ‘IFS’. Space, tab, and +newline are always considered IFS whitespace, even if they don't appear +in the locale's ‘space’ category. + + If ‘IFS’ is unset, word splitting behaves as if its value were +‘’, and treats these characters as IFS whitespace. +If the value of ‘IFS’ is null, no word splitting occurs, but implicit +null arguments (see below) are still removed. + + Word splitting begins by removing sequences of IFS whitespace +characters from the beginning and end of the results of the previous +expansions, then splits the remaining words. + + If the value of ‘IFS’ consists solely of IFS whitespace, any sequence +of IFS whitespace characters delimits a field, so a field consists of +characters that are not unquoted IFS whitespace, and null fields result +only from quoting. + + If ‘IFS’ contains a non-whitespace character, then any character in +the value of ‘IFS’ that is not IFS whitespace, along with any adjacent +IFS whitespace characters, delimits a field. This means that adjacent +non-IFS-whitespace delimiters produce a null field. A sequence of IFS +whitespace characters also delimits a field. + + Explicit null arguments (‘""’ or ‘''’) 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. +Expanding a parameter with no value within double quotes produces a null +field, which 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, word splitting removes the null argument portion, leaving +the non-null expansion. That is, the word ‘-d''’ becomes ‘-d’ after +word splitting and null argument removal. + + +File: bash.info, Node: Filename Expansion, Next: Quote Removal, Prev: Word Splitting, Up: Shell Expansions + +3.5.8 Filename Expansion +------------------------ + +* Menu: + +* Pattern Matching:: How the shell matches patterns. + +After word splitting, unless the ‘-f’ option has been set (*note The Set +Builtin::), Bash scans each word for the characters ‘*’, ‘?’, and ‘[’. +If one of these characters appears, and is not quoted, then the word is +regarded as a PATTERN, and replaced with a sorted list of filenames +matching the pattern (*note Pattern Matching::), subject to the value of +the ‘GLOBSORT’ shell variable (*note Bash Variables::). + + If no matching filenames are found, and the shell option ‘nullglob’ +is disabled, the word is left unchanged. If the ‘nullglob’ option is +set, and no matches are found, the word is removed. If the ‘failglob’ +shell option is set, and no matches are found, Bash prints an error +message and does not execute the command. If the shell option +‘nocaseglob’ is enabled, the match is performed without regard to the +case of alphabetic characters. + + When a pattern is used for filename expansion, the character ‘.’ at +the start of a filename or immediately following a slash must be matched +explicitly, unless the shell option ‘dotglob’ is set. In order to match +the filenames ‘.’ and ‘..’, the pattern must begin with ‘.’ (for +example, ‘.?’), even if ‘dotglob’ is set. If the ‘globskipdots’ shell +option is enabled, the filenames ‘.’ and ‘..’ never match, even if the +pattern begins with a ‘.’. When not matching filenames, the ‘.’ +character is not treated specially. + + When matching a filename, 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 (*note +Pattern Matching::). + + See the description of ‘shopt’ in *note The Shopt Builtin::, for a +description of the ‘nocaseglob’, ‘nullglob’, ‘globskipdots’, ‘failglob’, +and ‘dotglob’ options. + + The ‘GLOBIGNORE’ shell variable may be used to restrict the set of +file names matching a pattern. If ‘GLOBIGNORE’ is set, each matching +file name that also matches one of the patterns in ‘GLOBIGNORE’ is +removed from the list of matches. If the ‘nocaseglob’ option is set, +the matching against the patterns in ‘GLOBIGNORE’ is performed without +regard to case. The filenames ‘.’ and ‘..’ are always ignored when +‘GLOBIGNORE’ is set and not null. However, setting ‘GLOBIGNORE’ to a +non-null value has the effect of enabling the ‘dotglob’ shell option, so +all other filenames beginning with a ‘.’ match. To get the old behavior +of ignoring filenames beginning with a ‘.’, make ‘.*’ one of the +patterns in ‘GLOBIGNORE’. The ‘dotglob’ option is disabled when +‘GLOBIGNORE’ is unset. The ‘GLOBIGNORE’ pattern matching honors the +setting of the ‘extglob’ shell option. + + The value of the ‘GLOBSORT’ shell variable controls how the results +of pathname expansion are sorted, as described below (*note Bash +Variables::). + + +File: bash.info, Node: Pattern Matching, Up: Filename Expansion + +3.5.8.1 Pattern Matching +........................ + +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. + + The special pattern characters have the following meanings: +‘*’ + Matches any string, including the null string. When the ‘globstar’ + shell option is enabled, and ‘*’ is used in a filename expansion + context, two adjacent ‘*’s used as a single pattern match all files + and zero or more directories and subdirectories. If followed by a + ‘/’, two adjacent ‘*’s match only directories and subdirectories. +‘?’ + Matches any single character. +‘[...]’ + Matches any one of the characters enclosed between the brackets. + This is known as a “bracket expression” and matches a single + character. A pair of characters separated by a hyphen denotes a + “range expression”; any character that falls between those two + characters, inclusive, using the current locale's collating + sequence and character set, matches. If the first character + following the ‘[’ is a ‘!’ or a ‘^’ then any character not within + the range matches. To match a ‘−’, include it as the first or last + character in the set. To match a ‘]’, include it as the first + character in the set. + + 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 ‘LC_COLLATE’ and ‘LC_ALL’ shell + variables, if set. + + For example, in the default C locale, ‘[a-dx-z]’ is equivalent to + ‘[abcdxyz]’. Many locales sort characters in dictionary order, and + in these locales ‘[a-dx-z]’ is typically not equivalent to + ‘[abcdxyz]’; it might be equivalent to ‘[aBbCcDdxYyZz]’, for + example. To obtain the traditional interpretation of ranges in + bracket expressions, you can force the use of the C locale by + setting the ‘LC_COLLATE’ or ‘LC_ALL’ environment variable to the + value ‘C’, or enable the ‘globasciiranges’ shell option. + + Within a bracket expression, “character classes” can be specified + using the syntax ‘[:’CLASS‘:]’, where CLASS is one of the following + classes defined in the POSIX standard: + alnum alpha ascii blank cntrl digit graph lower + print punct space upper word xdigit + A character class matches any character belonging to that class. + The ‘word’ character class matches letters, digits, and the + character ‘_’. + + For instance, the following pattern will match any character + belonging to the ‘space’ character class in the current locale, + then any upper case letter or ‘!’, a dot, and finally any lower + case letter or a hyphen. + + [[:space:]][[:upper:]!].[-[:lower:]] + + Within a bracket expression, an “equivalence class” can be + specified using the syntax ‘[=’C‘=]’, which matches all characters + with the same collation weight (as defined by the current locale) + as the character C. + + Within a bracket expression, the syntax ‘[.’SYMBOL‘.]’ matches the + collating symbol SYMBOL. + + If the ‘extglob’ shell option is enabled using the ‘shopt’ builtin, +the shell recognizes several extended pattern matching operators. In +the following description, a PATTERN-LIST is a list of one or more +patterns separated by a ‘|’. When matching filenames, the ‘dotglob’ +shell option determines the set of filenames that are tested, as +described above. Composite patterns may be formed using one or more of +the following sub-patterns: + +‘?(PATTERN-LIST)’ + Matches zero or one occurrence of the given patterns. + +‘*(PATTERN-LIST)’ + Matches zero or more occurrences of the given patterns. + +‘+(PATTERN-LIST)’ + Matches one or more occurrences of the given patterns. + +‘@(PATTERN-LIST)’ + Matches one of the given patterns. + +‘!(PATTERN-LIST)’ + Matches anything except one of the given patterns. + + The ‘extglob’ 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 ‘extglob’ is enabled before parsing constructs containing the +patterns, including shell functions and command substitutions. + + When matching filenames, the ‘dotglob’ shell option determines the +set of filenames that are tested: when ‘dotglob’ is enabled, the set of +filenames includes all files beginning with ‘.’, but the filenames ‘.’ +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 ‘.’. +If the ‘globskipdots’ shell option is enabled, the filenames ‘.’ and +‘..’ never appear in the set. As above, ‘.’ only has a special meaning +when matching filenames. + + 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. + + +File: bash.info, Node: Quote Removal, Prev: Filename Expansion, Up: Shell Expansions + +3.5.9 Quote Removal +------------------- + +After the preceding expansions, all unquoted occurrences of the +characters ‘\’, ‘'’, and ‘"’ that did not result from one of the above +expansions are removed. + + +File: bash.info, Node: Redirections, Next: Executing Commands, Prev: Shell Expansions, Up: Basic Shell Features + +3.6 Redirections +================ + +Before a command is executed, its input and output may be “redirected” +using a special notation interpreted by the shell. “Redirection” 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. When used with the ‘exec’ builtin, redirections modify file +handles in the current shell execution environment. The following +redirection operators may precede or appear anywhere within a simple +command or may follow a command. Redirections are processed in the +order they appear, from left to right. + + Each redirection that may be preceded by a file descriptor number may +instead be preceded by a word of the form {VARNAME}. In this case, for +each redirection operator except ‘>&-’ and ‘<&-’, the shell allocates a +file descriptor greater than or equal to 10 and assigns it to {VARNAME}. +If {VARNAME} precedes ‘>&-’ or ‘<&-’, the value of VARNAME defines the +file descriptor to close. If {VARNAME} is supplied, the redirection +persists beyond the scope of the command, which allows the shell +programmer to manage the file descriptor's lifetime manually without +using the ‘exec’ builtin. The ‘varredir_close’ shell option manages +this behavior (*note The Shopt Builtin::). + + In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is ‘<’, the +redirection refers to the standard input (file descriptor 0). If the +first character of the redirection operator is ‘>’, the redirection +refers to the standard output (file descriptor 1). + + 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, filename expansion, and word +splitting. If it expands to more than one word, Bash reports an error. + + The order of redirections is significant. For example, the command + ls > DIRLIST 2>&1 +directs both standard output (file descriptor 1) and standard error +(file descriptor 2) to the file DIRLIST, while the command + ls 2>&1 > DIRLIST +directs only the standard output to file DIRLIST, because the standard +error was made a copy of the standard output before the standard output +was redirected to DIRLIST. + + Bash handles several filenames specially when they are used in +redirections, as described in the following table. If the operating +system on which Bash is running provides these special files, Bash uses +them; otherwise it emulates them internally with the behavior described +below. + +‘/dev/fd/FD’ + If FD is a valid integer, duplicate file descriptor FD. + +‘/dev/stdin’ + File descriptor 0 is duplicated. + +‘/dev/stdout’ + File descriptor 1 is duplicated. + +‘/dev/stderr’ + File descriptor 2 is duplicated. + +‘/dev/tcp/HOST/PORT’ + If HOST is a valid hostname or Internet address, and PORT is an + integer port number or service name, Bash attempts to open the + corresponding TCP socket. + +‘/dev/udp/HOST/PORT’ + If HOST is a valid hostname or Internet address, and PORT is an + integer port number or service name, Bash attempts to open the + corresponding UDP socket. + + A failure to open or create a file causes the redirection to fail. + + Redirections using file descriptors greater than 9 should be used +with care, as they may conflict with file descriptors the shell uses +internally. + +3.6.1 Redirecting Input +----------------------- + +Redirecting input opens the file whose name results from the expansion +of WORD for reading on file descriptor ‘n’, or the standard input (file +descriptor 0) if ‘n’ is not specified. + + The general format for redirecting input is: + [N][|]WORD + + If the redirection operator is ‘>’, and the ‘noclobber’ option to the +‘set’ builtin command has been enabled, the redirection fails if the +file whose name results from the expansion of WORD exists and is a +regular file. If the redirection operator is ‘>|’, or the redirection +operator is ‘>’ and the ‘noclobber’ option to the ‘set’ builtin is not +enabled, Bash attempts the redirection even if the file named by WORD +exists. + +3.6.3 Appending Redirected Output +--------------------------------- + +Redirecting output in this fashion opens the file whose name results +from the expansion of WORD for appending on file descriptor N, or the +standard output (file descriptor 1) if N is not specified. If the file +does not exist it is created. + + The general format for appending output is: + [N]>>WORD + +3.6.4 Redirecting Standard Output and Standard Error +---------------------------------------------------- + +This construct redirects both the standard output (file descriptor 1) +and the standard error output (file descriptor 2) to the file whose name +is the expansion of WORD. + + There are two formats for redirecting standard output and standard +error: + &>WORD +and + >&WORD +Of the two forms, the first is preferred. This is semantically +equivalent to + >WORD 2>&1 + When using the second form, WORD may not expand to a number or ‘-’. +If it does, other redirection operators apply (see Duplicating File +Descriptors below) for compatibility reasons. + +3.6.5 Appending Standard Output and Standard Error +-------------------------------------------------- + +This construct appends both the standard output (file descriptor 1) and +the standard error output (file descriptor 2) to the file whose name is +the expansion of WORD. + + The format for appending standard output and standard error is: + &>>WORD +This is semantically equivalent to + >>WORD 2>&1 + (see Duplicating File Descriptors below). + +3.6.6 Here Documents +-------------------- + +This type of redirection instructs the shell to read input from the +current source until it reads a line containing only DELIMITER (with no +trailing blanks). All of the lines read up to that point then become +the standard input (or file descriptor N if N is specified) for a +command. + + The format of here-documents is: + [N]<<[−]WORD + HERE-DOCUMENT + DELIMITER + + The shell does not perform parameter and variable expansion, command +substitution, arithmetic expansion, or filename expansion on WORD. + + If any part of WORD is quoted, the DELIMITER is the result of quote +removal on WORD, and the lines in the here-document are not expanded. +If WORD is unquoted, DELIMITER is WORD itself, and the here-document +text is treated similarly to a double-quoted string: all lines of the +here-document are subjected to parameter expansion, command +substitution, and arithmetic expansion, the character sequence +‘\newline’ is treated literally, and ‘\’ must be used to quote the +characters ‘\’, ‘$’, and ‘`’; however, double quote characters have no +special meaning. + + If the redirection operator is ‘<<-’, the shell strips leading tab +characters from input lines and the line containing DELIMITER. This +allows here-documents within shell scripts to be indented in a natural +fashion. + + If the delimiter is not quoted, the shell treats the ‘\’ +sequence as a line continuation: the two lines are joined and the +backslash-newline is removed. This happens while reading the +here-document, before the check for the ending delimiter, so joined +lines can form the end delimiter. + +3.6.7 Here Strings +------------------ + +A variant of here documents, the format is: + [N]<<< WORD + + The WORD undergoes tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote removal. Filename +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 N if N is specified). + +3.6.8 Duplicating File Descriptors +---------------------------------- + +The redirection operator + [N]<&WORD +is used to duplicate input file descriptors. If WORD expands to one or +more digits, file descriptor N is made to be a copy of that file +descriptor. It is a redirection error if the digits in WORD do not +specify a file descriptor open for input. If WORD evaluates to ‘-’, +file descriptor N is closed. If N is not specified, this uses the +standard input (file descriptor 0). + + The operator + [N]>&WORD +is used similarly to duplicate output file descriptors. If N is not +specified, this uses the standard output (file descriptor 1). It is a +redirection error if the digits in WORD do not specify a file descriptor +open for output. If WORD evaluates to ‘-’, file descriptor N is closed. +As a special case, if N is omitted, and WORD does not expand to one or +more digits or ‘-’, this redirects the standard output and standard +error as described previously. + +3.6.9 Moving File Descriptors +----------------------------- + +The redirection operator + [N]<&DIGIT- +moves the file descriptor DIGIT to file descriptor N, or the standard +input (file descriptor 0) if N is not specified. DIGIT is closed after +being duplicated to N. + + Similarly, the redirection operator + [N]>&DIGIT- +moves the file descriptor DIGIT to file descriptor N, or the standard +output (file descriptor 1) if N is not specified. + +3.6.10 Opening File Descriptors for Reading and Writing +------------------------------------------------------- + +The redirection operator + [N]<>WORD +opens the file whose name is the expansion of WORD for both reading and +writing on file descriptor N, or on file descriptor 0 if N is not +specified. If the file does not exist, it is created. + + +File: bash.info, Node: Executing Commands, Next: Shell Scripts, Prev: Redirections, Up: Basic Shell Features + +3.7 Executing Commands +====================== + +* Menu: + +* Simple Command Expansion:: How Bash expands simple commands before + executing them. +* Command Search and Execution:: How Bash finds commands and runs them. +* Command Execution Environment:: The environment in which Bash + executes commands that are not + shell builtins. +* Environment:: The environment given to a command. +* Exit Status:: The status returned by commands and how Bash + interprets it. +* Signals:: What happens when Bash or a command it runs + receives a signal. + + +File: bash.info, Node: Simple Command Expansion, Next: Command Search and Execution, Up: Executing Commands + +3.7.1 Simple Command Expansion +------------------------------ + +When the shell executes a simple command, it performs the following +expansions, assignments, and redirections, from left to right, in the +following order. + + 1. The words that the parser has marked as variable assignments (those + preceding the command name) and redirections are saved for later + processing. + + 2. The words that are not variable assignments or redirections are + expanded (*note Shell Expansions::). 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. + + 3. Redirections are performed as described above (*note + Redirections::). + + 4. The text after the ‘=’ in each variable assignment undergoes tilde + expansion, parameter expansion, command substitution, arithmetic + expansion, and quote removal before being assigned to the variable. + + 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. + + 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. + + 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 zero +status. + + +File: bash.info, Node: Command Search and Execution, Next: Command Execution Environment, Prev: Simple Command Expansion, Up: Executing Commands + +3.7.2 Command Search and Execution +---------------------------------- + +After a command has been split into words, if it results in a simple +command and an optional list of arguments, the shell performs the +following actions. + + 1. 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 in *note Shell Functions::. + + 2. 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. + + 3. If the name is neither a shell function nor a builtin, and contains + no slashes, Bash searches each element of ‘$PATH’ for a directory + containing an executable file by that name. Bash uses a hash table + to remember the full pathnames of executable files to avoid + multiple ‘PATH’ searches (see the description of ‘hash’ in *note + Bourne Shell Builtins::). Bash performs a full search of the + directories in ‘$PATH’ 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 ‘command_not_found_handle’. 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. + + 4. 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 + supplied, if any. + + 5. 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 + “shell script”, a file containing shell commands, and the shell + executes it as described in *note Shell Scripts::. + + 6. If the command was not begun asynchronously, the shell waits for + the command to complete and collects its exit status. + + +File: bash.info, Node: Command Execution Environment, Next: Environment, Prev: Command Search and Execution, Up: Executing Commands + +3.7.3 Command Execution Environment +----------------------------------- + +The shell has an “execution environment”, which consists of the +following: + + • Open files inherited by the shell at invocation, as modified by + redirections supplied to the ‘exec’ builtin. + + • The current working directory as set by ‘cd’, ‘pushd’, or ‘popd’, + or inherited by the shell at invocation. + + • The file creation mode mask as set by ‘umask’ or inherited from the + shell's parent. + + • Current traps set by ‘trap’. + + • Shell parameters that are set by variable assignment or with ‘set’ + or inherited from the shell's parent in the environment. + + • Shell functions defined during execution or inherited from the + shell's parent in the environment. + + • Options enabled at invocation (either by default or with + command-line arguments) or by ‘set’. + + • Options enabled by ‘shopt’ (*note The Shopt Builtin::). + + • Shell aliases defined with ‘alias’ (*note Aliases::). + + • Various process IDs, including those of background jobs (*note + Lists::), the value of ‘$$’, and the value of ‘$PPID’. + + 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. + + • The shell's open files, plus any modifications and additions + specified by redirections to the command. + + • The current working directory. + + • The file creation mode mask. + + • Shell variables and functions marked for export, along with + variables exported for the command, passed in the environment + (*note Environment::). + + • Traps caught by the shell are reset to the values inherited from + the shell's parent, and traps ignored by the shell are ignored. + + A command invoked in this separate environment cannot affect the +shell's execution environment. + + A “subshell” is a copy of the shell process. + + 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, +except possibly in the last element depending on the value of the +‘lastpipe’ shell option (*note The Shopt Builtin::), are also executed +in a subshell environment. Changes made to the subshell environment +cannot affect the shell's execution environment. + + When the shell is in POSIX mode, subshells spawned to execute command +substitutions inherit the value of the ‘-e’ option from the parent +shell. When not in POSIX mode, Bash clears the ‘-e’ option in such +subshells See the description of the ‘inherit_errexit’ shell option +(*note Bash Builtins::) for how to control this behavior when not in +POSIX mode. + + If a command is followed by a ‘&’ and job control is not active, the +default standard input for the command is the empty file ‘/dev/null’. +Otherwise, the invoked command inherits the file descriptors of the +calling shell as modified by redirections. + + +File: bash.info, Node: Environment, Next: Exit Status, Prev: Command Execution Environment, Up: Executing Commands + +3.7.4 Environment +----------------- + +When a program is invoked it is given an array of strings called the +“environment”. This is a list of name-value pairs, of the form +‘name=value’. + + Bash 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 ‘export’ to child +processes. Executed commands inherit the environment. The ‘export’, +‘declare -x’, and ‘unset’ commands modify the environment by adding and +deleting parameters and functions. If the value of a parameter in the +environment is modified, the new value automatically 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 +‘unset’ and ‘export -n’ commands, plus any additions via the ‘export’ +and ‘declare -x’ commands. + + If any parameter assignment statements, as described in *note Shell +Parameters::, appear before a simple command, the variable assignments +are part of that command's environment for as long as it executes. +These assignment statements affect only the environment seen by that +command. If these assignments precede a call to a shell function, the +variables are local to the function and exported to that function's +children. + + If the ‘-k’ option is set (*note The Set Builtin::), then all +parameter assignments are placed in the environment for a command, not +just those that precede the command name. + + When Bash invokes an external command, the variable ‘$_’ is set to +the full pathname of the command and passed to that command in its +environment. + + +File: bash.info, Node: Exit Status, Next: Signals, Prev: Environment, Up: Executing Commands + +3.7.5 Exit Status +----------------- + +The exit status of an executed command is the value returned by the +‘waitpid’ 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. + + For the shell's purposes, a command which exits with a zero exit +status has succeeded. So while an exit status of zero indicates +success, a non-zero exit status indicates failure. This seemingly +counter-intuitive scheme is used so there is one well-defined way to +indicate success and a variety of ways to indicate various failure +modes. + + When a command terminates on a fatal signal whose number is N, Bash +uses the value 128+N as the exit status. + + 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. + + If a command fails because of an error during expansion or +redirection, the exit status is greater than zero. + + The exit status is used by the Bash conditional commands (*note +Conditional Constructs::) and some of the list constructs (*note +Lists::). + + All of the Bash builtins return an exit status of zero if they +succeed and a non-zero status on failure, so they may be used by the +conditional and list constructs. All builtins return an exit status of +2 to indicate incorrect usage, generally invalid options or missing +arguments. + + The exit status of the last command is available in the special +parameter $? (*note Special Parameters::). + + Bash 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 ‘exit’ builtin command (*note Bourne Shell +Builtins::). + + +File: bash.info, Node: Signals, Prev: Exit Status, Up: Executing Commands + +3.7.6 Signals +------------- + +When Bash is interactive, in the absence of any traps, it ignores +‘SIGTERM’ (so that ‘kill 0’ does not kill an interactive shell), and +catches and handles ‘SIGINT’ (so that the ‘wait’ builtin is +interruptible). When Bash receives a ‘SIGINT’, it breaks out of any +executing loops. In all cases, Bash ignores ‘SIGQUIT’. If job control +is in effect (*note Job Control::), Bash ignores ‘SIGTTIN’, ‘SIGTTOU’, +and ‘SIGTSTP’. + + The ‘trap’ builtin modifies the shell's signal handling, as described +below (*note Bourne Shell Builtins::). + + Non-builtin commands Bash executes have signal handlers set to the +values inherited by the shell from its parent, unless ‘trap’ sets them +to be ignored, in which case the child process will ignore them as well. +When job control is not in effect, asynchronous commands ignore ‘SIGINT’ +and ‘SIGQUIT’ in addition to these inherited handlers. Commands run as +a result of command substitution ignore the keyboard-generated job +control signals ‘SIGTTIN’, ‘SIGTTOU’, and ‘SIGTSTP’. + + The shell exits by default upon receipt of a ‘SIGHUP’. Before +exiting, an interactive shell resends the ‘SIGHUP’ to all jobs, running +or stopped. The shell sends ‘SIGCONT’ to stopped jobs to ensure that +they receive the ‘SIGHUP’ (*Note Job Control::, for more information +about running and stopped jobs). To prevent the shell from sending the +‘SIGHUP’ signal to a particular job, remove it from the jobs table with +the ‘disown’ builtin (*note Job Control Builtins::) or mark it not to +receive ‘SIGHUP’ using ‘disown -h’. + + If the ‘huponexit’ shell option has been set using ‘shopt’ (*note The +Shopt Builtin::), Bash sends a ‘SIGHUP’ to all jobs when an interactive +login shell exits. + + If Bash is waiting for a command to complete and receives a signal +for which a trap has been set, it will not execute the trap until the +command completes. If Bash is waiting for an asynchronous command via +the ‘wait’ builtin, and it receives a signal for which a trap has been +set, the ‘wait’ builtin will return immediately with an exit status +greater than 128, immediately after which the shell executes the trap. + + When job control is not enabled, and Bash is waiting for a foreground +command to complete, the shell receives keyboard-generated signals such +as ‘SIGINT’ (usually generated by ‘^C’) 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 ‘^C’ sends ‘SIGINT’ +to all processes in that process group. Since Bash does not enable job +control by default when the shell is not interactive, this scenario is +most common in non-interactive shells. + + When job control is enabled, and Bash is waiting for a foreground +command to complete, the shell does not receive keyboard-generated +signals, because it is not in the same process group as the terminal. +This scenario is most common in interactive shells, where Bash attempts +to enable job control by default. See *note Job Control::, for a more +in-depth discussion of process groups. + + When job control is not enabled, and Bash receives ‘SIGINT’ while +waiting for a foreground command, it waits until that foreground command +terminates and then decides what to do about the ‘SIGINT’: + + 1. If the command terminates due to the ‘SIGINT’, Bash concludes that + the user meant to send the ‘SIGINT’ to the shell as well, and acts + on the ‘SIGINT’ (e.g., by running a ‘SIGINT’ trap, exiting a + non-interactive shell, or returning to the top level to read a new + command). + + 2. If the command does not terminate due to ‘SIGINT’, the program + handled the ‘SIGINT’ itself and did not treat it as a fatal signal. + In that case, Bash does not treat ‘SIGINT’ as a fatal signal, + either, instead assuming that the ‘SIGINT’ was used as part of the + program's normal operation (e.g., ‘emacs’ uses it to abort editing + commands) or deliberately discarded. However, Bash will run any + trap set on ‘SIGINT’, as it does with any other trapped signal it + receives while it is waiting for the foreground command to + complete, for compatibility. + + When job control is enabled, Bash does not receive keyboard-generated +signals such as ‘SIGINT’ while it is waiting for a foreground command. +An interactive shell does not pay attention to the ‘SIGINT’, even if the +foreground command terminates as a result, other than noting its exit +status. If the shell is not interactive, and the foreground command +terminates due to the ‘SIGINT’, Bash pretends it received the ‘SIGINT’ +itself (scenario 1 above), for compatibility. + + +File: bash.info, Node: Shell Scripts, Prev: Executing Commands, Up: Basic Shell Features + +3.8 Shell Scripts +================= + +A shell script is a text file containing shell commands. When such a +file is used as the first non-option argument when invoking Bash, and +neither the ‘-c’ nor ‘-s’ option is supplied (*note Invoking Bash::), +Bash reads and executes commands from the file, then exits. This mode +of operation creates a non-interactive shell. If the filename does not +contain any slashes, the shell first searches for the file in the +current directory, and looks in the directories in ‘$PATH’ if not found +there. + + Bash tries to determine whether the file is a text file or a binary, +and will not execute files it determines to be binaries. + + When Bash runs a shell script, it sets the special parameter ‘0’ to +the name of the file, rather than the name of the shell, and the +positional parameters are set to the remaining arguments, if any are +given. If no additional arguments are supplied, the positional +parameters are unset. + + A shell script may be made executable by using the ‘chmod’ command to +turn on the execute bit. When Bash finds such a file while searching +the ‘$PATH’ for a command, it creates a new instance of itself to +execute it. In other words, executing + filename ARGUMENTS +is equivalent to executing + bash filename ARGUMENTS + +if ‘filename’ is an executable shell script. This subshell +reinitializes itself, so that the effect is as if a new shell had been +invoked to interpret the script, with the exception that the locations +of commands remembered by the parent (see the description of ‘hash’ in +*note Bourne Shell Builtins::) are retained by the child. + + The GNU operating system, and most versions of Unix, make this a part +of the operating system's command execution mechanism. If the first +line of a script begins with the two characters ‘#!’, the remainder of +the line specifies an interpreter for the program and, depending on the +operating system, one or more optional arguments for that interpreter. +Thus, you can specify Bash, ‘awk’, Perl, or some other interpreter and +write the rest of the script file in that language. + + The arguments to the interpreter consist of one or more optional +arguments following the interpreter name on the first line of the script +file, followed by the name of the script file, followed by the rest of +the arguments supplied to the script. The details of how the +interpreter line is split into an interpreter name and a set of +arguments vary across systems. Bash will perform this action on +operating systems that do not handle it themselves. Note that some +older versions of Unix limit the interpreter name and a single argument +to a maximum of 32 characters, so it's not portable to assume that using +more than one argument will work. + + Bash scripts often begin with ‘#! /bin/bash’ (assuming that Bash has +been installed in ‘/bin’), since this ensures that Bash will be used to +interpret the script, even if it is executed under another shell. It's +a common idiom to use ‘env’ to find ‘bash’ even if it's been installed +in another directory: ‘#!/usr/bin/env bash’ will find the first +occurrence of ‘bash’ in ‘$PATH’. + + +File: bash.info, Node: Shell Builtin Commands, Next: Shell Variables, Prev: Basic Shell Features, Up: Top + +4 Shell Builtin Commands +************************ + +* Menu: + +* Bourne Shell Builtins:: Builtin commands inherited from the Bourne + Shell. +* Bash Builtins:: Table of builtins specific to Bash. +* Modifying Shell Behavior:: Builtins to modify shell attributes and + optional behavior. +* Special Builtins:: Builtin commands classified specially by + POSIX. + +Builtin commands are contained within the shell itself. When the name +of a builtin command is used as the first word of a simple command +(*note Simple Commands::), the shell executes the command directly, +without invoking another program. Builtin commands are necessary to +implement functionality impossible or inconvenient to obtain with +separate utilities. + + This section briefly describes the builtins which Bash inherits from +the Bourne Shell, as well as the builtin commands which are unique to or +have been extended in Bash. + + Several builtin commands are described in other chapters: builtin +commands which provide the Bash interface to the job control facilities +(*note Job Control Builtins::), the directory stack (*note Directory +Stack Builtins::), the command history (*note Bash History Builtins::), +and the programmable completion facilities (*note Programmable +Completion Builtins::). + + Many of the builtins have been extended by POSIX or Bash. + + Unless otherwise noted, each builtin command documented as accepting +options preceded by ‘-’ accepts ‘--’ to signify the end of the options. +The ‘:’, ‘true’, ‘false’, and ‘test’/‘[’ builtins do not accept options +and do not treat ‘--’ specially. The ‘exit’, ‘logout’, ‘return’, +‘break’, ‘continue’, ‘let’, and ‘shift’ builtins accept and process +arguments beginning with ‘-’ without requiring ‘--’. Other builtins +that accept arguments but are not specified as accepting options +interpret arguments beginning with ‘-’ as invalid options and require +‘--’ to prevent this interpretation. + + +File: bash.info, Node: Bourne Shell Builtins, Next: Bash Builtins, Up: Shell Builtin Commands + +4.1 Bourne Shell Builtins +========================= + +The following shell builtin commands are inherited from the Bourne +Shell. These commands are implemented as specified by the POSIX +standard. + +‘: (a colon)’ + : [ARGUMENTS] + + Do nothing beyond expanding ARGUMENTS and performing redirections. + The return status is zero. + +‘. (a period)’ + . [-p PATH] FILENAME [ARGUMENTS] + + The ‘.’ command reads and execute commands from the FILENAME + argument in the current shell context. + + If FILENAME does not contain a slash, ‘.’ searches for it. If ‘-p’ + is supplied, ‘.’ treats PATH as a colon-separated list of + directories in which to find FILENAME; otherwise, ‘.’ uses the + directories in ‘PATH’ to find FILENAME. FILENAME does not need to + be executable. When Bash is not in POSIX mode, it searches the + current directory if FILENAME is not found in ‘$PATH’, but does not + search the current directory if ‘-p’ is supplied. If the + ‘sourcepath’ option (*note The Shopt Builtin::) is turned off, ‘.’ + does not search ‘PATH’. + + If any ARGUMENTS are supplied, they become the positional + parameters when FILENAME is executed. Otherwise the positional + parameters are unchanged. + + If the ‘-T’ option is enabled, ‘.’ inherits any trap on ‘DEBUG’; if + it is not, any ‘DEBUG’ trap string is saved and restored around the + call to ‘.’, and ‘.’ unsets the ‘DEBUG’ trap while it executes. If + ‘-T’ is not set, and the sourced file changes the ‘DEBUG’ trap, the + new value persists after ‘.’ completes. The return status is the + exit status of the last command executed from FILENAME, or zero if + no commands are executed. If FILENAME is not found, or cannot be + read, the return status is non-zero. This builtin is equivalent to + ‘source’. + +‘break’ + break [N] + + Exit from a ‘for’, ‘while’, ‘until’, or ‘select’ loop. If N is + supplied, ‘break’ exits the Nth enclosing loop. N must be greater + than or equal to 1. The return status is zero unless N is not + greater than or equal to 1. + +‘cd’ + cd [-L] [-@] [DIRECTORY] + cd -P [-e] [-@] [DIRECTORY] + + Change the current working directory to DIRECTORY. If DIRECTORY is + not supplied, the value of the ‘HOME’ shell variable is used as + DIRECTORY. If DIRECTORY is the empty string, ‘cd’ treats it as an + error. If the shell variable ‘CDPATH’ exists, and DIRECTORY does + not begin with a slash, ‘cd’ uses it as a search path: ‘cd’ + searches each directory name in ‘CDPATH’ for DIRECTORY, with + alternative directory names in ‘CDPATH’ separated by a colon (‘:’). + A null directory name in ‘CDPATH’ means the same thing as the + current directory. + + The ‘-P’ option means not to follow symbolic links: symbolic links + are resolved while ‘cd’ is traversing DIRECTORY and before + processing an instance of ‘..’ in DIRECTORY. + + By default, or when the ‘-L’ option is supplied, symbolic links in + DIRECTORY are resolved after ‘cd’ processes an instance of ‘..’ in + DIRECTORY. + + If ‘..’ appears in DIRECTORY, ‘cd’ processes it by removing the + immediately preceding pathname component, back to a slash or the + beginning of DIRECTORY, and verifying that the portion of DIRECTORY + it has processed to that point is still a valid directory name + after removing the pathname component. If it is not a valid + directory name, ‘cd’ returns a non-zero status. + + If the ‘-e’ option is supplied with ‘-P’ and ‘cd’ cannot + successfully determine the current working directory after a + successful directory change, it returns a non-zero status. + + On systems that support it, the ‘-@’ option presents the extended + attributes associated with a file as a directory. + + If DIRECTORY is ‘-’, it is converted to ‘$OLDPWD’ before attempting + the directory change. + + If ‘cd’ uses a non-empty directory name from ‘CDPATH’, or if ‘-’ is + the first argument, and the directory change is successful, ‘cd’ + writes the absolute pathname of the new working directory to the + standard output. + + If the directory change is successful, ‘cd’ sets the value of the + ‘PWD’ environment variable to the new directory name, and sets the + ‘OLDPWD’ environment variable to the value of the current working + directory before the change. + + The return status is zero if the directory is successfully changed, + non-zero otherwise. + +‘continue’ + continue [N] + + ‘continue’ resumes the next iteration of an enclosing ‘for’, + ‘while’, ‘until’, or ‘select’ loop. If N is supplied, Bash resumes + the execution of the Nth enclosing loop. N must be greater than or + equal to 1. The return status is zero unless N is not greater than + or equal to 1. + +‘eval’ + eval [ARGUMENTS] + + The ARGUMENTS are concatenated together into a single command, + separated by spaces. Bash then reads and executes this command and + returns its exit status as the exit status of ‘eval’. If there are + no arguments or only empty arguments, the return status is zero. + +‘exec’ + exec [-cl] [-a NAME] [COMMAND [ARGUMENTS]] + + If COMMAND is supplied, it replaces the shell without creating a + new process. COMMAND cannot be a shell builtin or function. The + ARGUMENTS become the arguments to COMMAND If the ‘-l’ option is + supplied, the shell places a dash at the beginning of the zeroth + argument passed to COMMAND. This is what the ‘login’ program does. + The ‘-c’ option causes COMMAND to be executed with an empty + environment. If ‘-a’ is supplied, the shell passes NAME as the + zeroth argument to COMMAND. + + If COMMAND cannot be executed for some reason, a non-interactive + shell exits, unless the ‘execfail’ shell option is enabled. In + that case, it returns a non-zero status. An interactive shell + returns a non-zero status if the file cannot be executed. A + subshell exits unconditionally if ‘exec’ fails. + + If COMMAND is not specified, redirections may be used to affect the + current shell environment. If there are no redirection errors, the + return status is zero; otherwise the return status is non-zero. + +‘exit’ + exit [N] + + Exit the shell, returning a status of N to the shell's parent. If + N is omitted, the exit status is that of the last command executed. + Any trap on ‘EXIT’ is executed before the shell terminates. + +‘export’ + export [-fn] [-p] [NAME[=VALUE]] + + Mark each NAME to be passed to subsequently executed commands in + the environment. If the ‘-f’ option is supplied, the NAMEs refer + to shell functions; otherwise the names refer to shell variables. + + The ‘-n’ option means to unexport each name: no longer mark it for + export. If no NAMEs are supplied, or if only the ‘-p’ option is + given, ‘export’ displays a list of names of all exported variables + on the standard output. Using ‘-p’ and ‘-f’ together displays + exported functions. The ‘-p’ option displays output in a form that + may be reused as input. + + ‘export’ allows the value of a variable to be set at the same time + it is exported or unexported by following the variable name with + =VALUE. This sets the value of the variable is to VALUE while + modifying the export attribute. + + The return status is zero unless an invalid option is supplied, one + of the names is not a valid shell variable name, or ‘-f’ is + supplied with a name that is not a shell function. + +‘false’ + false + + Does nothing; returns a non-zero status. + +‘getopts’ + getopts OPTSTRING NAME [ARG ...] + + ‘getopts’ is used by shell scripts or functions to parse positional + parameters and obtain options and their arguments. 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 whitespace. The colon (‘:’) + and question mark (‘?’) may not be used as option characters. + + Each time it is invoked, ‘getopts’ places the next option in the + shell variable NAME, initializing NAME if it does not exist, and + the index of the next argument to be processed into the variable + ‘OPTIND’. ‘OPTIND’ is initialized to 1 each time the shell or a + shell script is invoked. When an option requires an argument, + ‘getopts’ places that argument into the variable ‘OPTARG’. + + The shell does not reset ‘OPTIND’ automatically; it must be + manually reset between multiple calls to ‘getopts’ within the same + shell invocation to use a new set of parameters. + + When it reaches the end of options, ‘getopts’ exits with a return + value greater than zero. ‘OPTIND’ is set to the index of the first + non-option argument, and NAME is set to ‘?’. + + ‘getopts’ normally parses the positional parameters, but if more + arguments are supplied as ARG values, ‘getopts’ parses those + instead. + + ‘getopts’ can report errors in two ways. If the first character of + OPTSTRING is a colon, ‘getopts’ uses _silent_ error reporting. In + normal operation, ‘getopts’ prints diagnostic messages when it + encounters invalid options or missing option arguments. If the + variable ‘OPTERR’ is set to 0, ‘getopts’ does not display any error + messages, even if the first character of ‘optstring’ is not a + colon. + + If ‘getopts’ detects an invalid option, it places ‘?’ into NAME + and, if not silent, prints an error message and unsets ‘OPTARG’. + If ‘getopts’ is silent, it assigns the option character found to + ‘OPTARG’ and does not print a diagnostic message. + + If a required argument is not found, and ‘getopts’ is not silent, + it sets the value of NAME to a question mark (‘?’), unsets + ‘OPTARG’, and prints a diagnostic message. If ‘getopts’ is silent, + it sets the value of NAME to a colon (‘:’), and sets ‘OPTARG’ to + the option character found. + + ‘getopts’ returns true if an option, specified or unspecified, is + found. It returns false when it encounters the end of options or + if an error occurs. + +‘hash’ + hash [-r] [-p FILENAME] [-dt] [NAME] + + Each time ‘hash’ is invoked, it remembers the full filenames of the + commands specified as NAME arguments, so they need not be searched + for on subsequent invocations. The commands are found by searching + through the directories listed in ‘$PATH’. Any + previously-remembered filename associated with NAME is discarded. + The ‘-p’ option inhibits the path search, and ‘hash’ uses FILENAME + as the location of NAME. + + The ‘-r’ option causes the shell to forget all remembered + locations. Assigning to the ‘PATH’ variable also clears all hashed + filenames. The ‘-d’ option causes the shell to forget the + remembered location of each NAME. + + If the ‘-t’ option is supplied, ‘hash’ prints the full pathname + corresponding to each NAME. If multiple NAME arguments are + supplied with ‘-t’, ‘hash’ prints each NAME before the + corresponding hashed full path. The ‘-l’ option displays output in + a format that may be reused as input. + + If no arguments are given, or if only ‘-l’ is supplied, ‘hash’ + prints information about remembered commands. The ‘-t’, ‘-d’, and + ‘-p’ options (the options that act on the NAME arguments) are + mutually exclusive. Only one will be active. If more than one is + supplied, ‘-t’ has higher priority than ‘-p’, and both have higher + priority than ‘-d’. + + The return status is zero unless a NAME is not found or an invalid + option is supplied. + +‘pwd’ + pwd [-LP] + + Print the absolute pathname of the current working directory. If + the ‘-P’ option is supplied, or the ‘-o physical’ option to the + ‘set’ builtin (*note The Set Builtin::) is enabled, the pathname + printed will not contain symbolic links. If the ‘-L’ option is + supplied, the pathname printed may contain symbolic links. The + return status is zero unless an error is encountered while + determining the name of the current directory or an invalid option + is supplied. + +‘readonly’ + readonly [-aAf] [-p] [NAME[=VALUE]] ... + + Mark each NAME as readonly. The values of these names may not be + changed by subsequent assignment or unset. If the ‘-f’ option is + supplied, each NAME refers to a shell function. The ‘-a’ option + means each NAME refers to an indexed array variable; the ‘-A’ + option means each NAME refers to an associative array variable. If + both options are supplied, ‘-A’ takes precedence. If no NAME + arguments are supplied, or if the ‘-p’ option is supplied, print a + list of all readonly names. The other options may be used to + restrict the output to a subset of the set of readonly names. The + ‘-p’ option displays output in a format that may be reused as + input. + + ‘readonly’ allows the value of a variable to be set at the same + time the readonly attribute is changed by following the variable + name with =VALUE. This sets the value of the variable is to VALUE + while modifying the readonly attribute. + + The return status is zero unless an invalid option is supplied, one + of the NAME arguments is not a valid shell variable or function + name, or the ‘-f’ option is supplied with a name that is not a + shell function. + +‘return’ + return [N] + + Stop executing a shell function or sourced file and return the + value N to its caller. If N is not supplied, the return value is + the exit status of the last command executed. If ‘return’ is + executed by a trap handler, the last command used to determine the + status is the last command executed before the trap handler. If + ‘return’ is executed during a ‘DEBUG’ trap, the last command used + to determine the status is the last command executed by the trap + handler before ‘return’ was invoked. + + When ‘return’ is used to terminate execution of a script being + executed with the ‘.’ (‘source’) builtin, it returns either N or + the exit status of the last command executed within the script as + the exit status of the script. If N is supplied, the return value + is its least significant 8 bits. + + Any command associated with the ‘RETURN’ trap is executed before + execution resumes after the function or script. + + The return status is non-zero if ‘return’ is supplied a non-numeric + argument or is used outside a function and not during the execution + of a script by ‘.’ or ‘source’. + +‘shift’ + shift [N] + + Shift the positional parameters to the left by N: the positional + parameters from N+1 ... ‘$#’ are renamed to ‘$1’ ... ‘$#’-N. + Parameters represented by the numbers ‘$#’ down to ‘$#’-N+1 are + unset. N must be a non-negative number less than or equal to ‘$#’. + If N is not supplied, it is assumed to be 1. If N is zero or + greater than ‘$#’, the positional parameters are not changed. The + return status is zero unless N is greater than ‘$#’ or less than + zero, non-zero otherwise. + +‘test’ +‘[’ + test EXPR + + Evaluate a conditional expression EXPR and return a status of 0 + (true) or 1 (false). Each operator and operand must be a separate + argument. Expressions are composed of the primaries described + below in *note Bash Conditional Expressions::. ‘test’ does not + accept any options, nor does it accept and ignore an argument of + ‘--’ as signifying the end of options. When using the ‘[’ form, + the last argument to the command must be a ‘]’. + + Expressions may be combined using the following operators, listed + in decreasing order of precedence. The evaluation depends on the + number of arguments; see below. ‘test’ uses operator precedence + when there are five or more arguments. + + ‘! EXPR’ + True if EXPR is false. + + ‘( EXPR )’ + Returns the value of EXPR. This may be used to override + normal operator precedence. + + ‘EXPR1 -a EXPR2’ + True if both EXPR1 and EXPR2 are true. + + ‘EXPR1 -o EXPR2’ + True if either EXPR1 or EXPR2 is true. + + The ‘test’ and ‘[’ builtins evaluate conditional expressions using + a set of rules based on the number of arguments. + + 0 arguments + The expression is false. + + 1 argument + The expression is true if, and only if, the argument is not + null. + + 2 arguments + If the first argument is ‘!’, the expression is true if and + only if the second argument is null. If the first argument is + one of the unary conditional operators (*note Bash Conditional + Expressions::), the expression is true if the unary test is + true. If the first argument is not a valid unary operator, + the expression is false. + + 3 arguments + The following conditions are applied in the order listed. + + 1. If the second argument is one of the binary conditional + operators (*note Bash Conditional Expressions::), the + result of the expression is the result of the binary test + using the first and third arguments as operands. The + ‘-a’ and ‘-o’ operators are considered binary operators + when there are three arguments. + 2. If the first argument is ‘!’, the value is the negation + of the two-argument test using the second and third + arguments. + 3. If the first argument is exactly ‘(’ and the third + argument is exactly ‘)’, the result is the one-argument + test of the second argument. + 4. Otherwise, the expression is false. + + 4 arguments + The following conditions are applied in the order listed. + + 1. If the first argument is ‘!’, the result is the negation + of the three-argument expression composed of the + remaining arguments. + 2. If the first argument is exactly ‘(’ and the fourth + argument is exactly ‘)’, the result is the two-argument + test of the second and third arguments. + 3. Otherwise, the expression is parsed and evaluated + according to precedence using the rules listed above. + + 5 or more arguments + The expression is parsed and evaluated according to precedence + using the rules listed above. + + If the shell is in POSIX mode, or if the expression is part of the + ‘[[’ command, the ‘<’ and ‘>’ operators sort using the current + locale. If the shell is not in POSIX mode, the ‘test’ and ‘[’ + commands sort lexicographically using ASCII ordering. + + The historical operator-precedence parsing with 4 or more arguments + can lead to ambiguities when it encounters strings that look like + primaries. The POSIX standard has deprecated the ‘-a’ and ‘-o’ + primaries and enclosing expressions within parentheses. Scripts + should no longer use them. It's much more reliable to restrict + test invocations to a single primary, and to replace uses of ‘-a’ + and ‘-o’ with the shell's ‘&&’ and ‘||’ list operators. For + example, use + + test -n string1 && test -n string2 + + instead of + + test -n string1 -a -n string2 + +‘times’ + times + + Print out the user and system times used by the shell and its + children. The return status is zero. + +‘trap’ + trap [-lpP] [ACTION] [SIGSPEC ...] + + The ACTION is a command that is read and executed when the shell + receives any of the signals SIGSPEC. If ACTION is absent (and + there is a single SIGSPEC) or equal to ‘-’, each specified + SIGSPEC's disposition is reset to the value it had when the shell + was started. If ACTION is the null string, then the signal + specified by each SIGSPEC is ignored by the shell and commands it + invokes. + + If no arguments are supplied, ‘trap’ prints the actions associated + with each trapped signal as a set of ‘trap’ commands that can be + reused as shell input to restore the current signal dispositions. + + If ACTION is not present and ‘-p’ has been supplied, ‘trap’ + displays the trap commands associated with each SIGSPEC, or, if no + SIGSPECs are supplied, for all trapped signals, as a set of ‘trap’ + commands that can be reused as shell input to restore the current + signal dispositions. The ‘-P’ option behaves similarly, but + displays only the actions associated with each SIGSPEC argument. + ‘-P’ requires at least one SIGSPEC argument. The ‘-P’ or ‘-p’ + options may be used in a subshell environment (e.g., command + substitution) and, as long as they are used before ‘trap’ is used + to change a signal's handling, will display the state of its + parent's traps. + + The ‘-l’ option prints a list of signal names and their + corresponding numbers. Each SIGSPEC is either a signal name or a + signal number. Signal names are case insensitive and the ‘SIG’ + prefix is optional. If ‘-l’ is supplied with no SIGSPEC arguments, + it prints a list of valid signal names. + + If a SIGSPEC is ‘0’ or ‘EXIT’, ACTION is executed when the shell + exits. If a SIGSPEC is ‘DEBUG’, ACTION is executed before every + simple command, ‘for’ command, ‘case’ command, ‘select’ command, (( + arithmetic command, [[ conditional command, arithmetic ‘for’ + command, and before the first command executes in a shell function. + Refer to the description of the ‘extdebug’ shell option (*note The + Shopt Builtin::) for details of its effect on the ‘DEBUG’ trap. If + a SIGSPEC is ‘RETURN’, ACTION is executed each time a shell + function or a script executed with the ‘.’ or ‘source’ builtins + finishes executing. + + If a SIGSPEC is ‘ERR’, ACTION 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 ‘ERR’ trap is not executed if the failed + command is part of the command list immediately following an + ‘until’ or ‘while’ reserved word, part of the test following the + ‘if’ or ‘elif’ reserved words, part of a command executed in a ‘&&’ + or ‘||’ list except the command following the final ‘&&’ or ‘||’, + any command in a pipeline but the last, (subject to the state of + the ‘pipefail’ shell option), or if the command's return status is + being inverted using ‘!’. These are the same conditions obeyed by + the ‘errexit’ (‘-e’) option. + + When the shell is not interactive, signals ignored upon entry to a + non-interactive shell cannot be trapped or reset. Interactive + shells permit trapping signals ignored on entry. 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 zero unless a SIGSPEC does not specify a valid + signal; non-zero otherwise. + +‘true’ + true + + Does nothing, returns a 0 status. + +‘umask’ + umask [-p] [-S] [MODE] + + Set the shell process's file creation mask to MODE. If MODE begins + with a digit, it is interpreted as an octal number; if not, it is + interpreted as a symbolic mode mask similar to that accepted by the + ‘chmod’ command. If MODE is omitted, ‘umask’ prints the current + value of the mask. If the ‘-S’ option is supplied without a MODE + argument, ‘umask’ prints the mask in a symbolic format; the default + output is an octal number. If the ‘-p’ option is supplied, and + MODE is omitted, the output is in a form that may be reused as + input. The return status is zero if the mode is successfully + changed or if no MODE argument is supplied, and non-zero otherwise. + + Note that when the mode is interpreted as an octal number, each + number of the umask is subtracted from ‘7’. Thus, a umask of ‘022’ + results in permissions of ‘755’. + +‘unset’ + unset [-fnv] [NAME] + + Remove each variable or function NAME. If the ‘-v’ option is + given, each NAME refers to a shell variable and that variable is + removed. If the ‘-f’ option is given, the NAMEs refer to shell + functions, and the function definition is removed. If the ‘-n’ + option is supplied, and NAME is a variable with the ‘nameref’ + attribute, NAME will be unset rather than the variable it + references. ‘-n’ has no effect if the ‘-f’ option is supplied. If + no options are supplied, each NAME refers to a variable; if there + is no variable by that name, a function with that name, if any, is + unset. Readonly variables and functions may not be unset. When + variables or functions are removed, they are also removed from the + environment passed to subsequent commands. Some shell variables + may not be unset. Some shell variables lose their special behavior + if they are unset; such behavior is noted in the description of the + individual variables. The return status is zero unless a NAME is + readonly or may not be unset. + + +File: bash.info, Node: Bash Builtins, Next: Modifying Shell Behavior, Prev: Bourne Shell Builtins, Up: Shell Builtin Commands + +4.2 Bash Builtin Commands +========================= + +This section describes builtin commands which are unique to or have been +extended in Bash. Some of these commands are specified in the POSIX +standard. + +‘alias’ + alias [-p] [NAME[=VALUE] ...] + + Without arguments or with the ‘-p’ option, ‘alias’ prints the list + of aliases on the standard output in a form that allows them to be + reused as input. If arguments are supplied, define an alias for + each NAME whose VALUE is given. If no VALUE is given, print the + name and value of the alias NAME. A trailing space in VALUE causes + the next word to be checked for alias substitution when the alias + is expanded during command parsing. ‘alias’ returns true unless a + NAME is given (without a corresponding =VALUE) for which no alias + has been defined. Aliases are described in *note Aliases::. + +‘bind’ + bind [-m KEYMAP] [-lsvSVX] + bind [-m KEYMAP] [-q FUNCTION] [-u FUNCTION] [-r KEYSEQ] + bind [-m KEYMAP] -f FILENAME + bind [-m KEYMAP] -x KEYSEQ[: ]SHELL-COMMAND + bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME + bind [-m KEYMAP] KEYSEQ:READLINE-COMMAND + bind [-m KEYMAP] -p|-P [READLINE-COMMAND] + bind READLINE-COMMAND-LINE + + Display current Readline (*note Command Line Editing::) key and + function bindings, bind a key sequence to a Readline function or + macro or to a shell command, or set a Readline variable. Each + non-option argument is a key binding or command as it would appear + in a Readline initialization file (*note Readline Init File::), but + each binding or command must be passed as a separate argument; + e.g., ‘"\C-x\C-r":re-read-init-file’. + + In the following descriptions, options that display output in a + form available to be re-read format their output as commands that + would appear in a Readline initialization file or that would be + supplied as individual arguments to a ‘bind’ command. + + Options, if supplied, have the following meanings: + + ‘-m KEYMAP’ + Use KEYMAP as the keymap to be affected by the subsequent + bindings. Acceptable KEYMAP names are ‘emacs’, + ‘emacs-standard’, ‘emacs-meta’, ‘emacs-ctlx’, ‘vi’, ‘vi-move’, + ‘vi-command’, and ‘vi-insert’. ‘vi’ is equivalent to + ‘vi-command’ (‘vi-move’ is also a synonym); ‘emacs’ is + equivalent to ‘emacs-standard’. + + ‘-l’ + List the names of all Readline functions. + + ‘-p’ + Display Readline function names and bindings in such a way + that they can be used as an argument to a subsequent ‘bind’ + command or in a Readline initialization file. If arguments + remain after option processing, ‘bind’ treats them as readline + command names and restricts output to those names. + + ‘-P’ + List current Readline function names and bindings. If + arguments remain after option processing, ‘bind’ treats them + as readline command names and restricts output to those names. + + ‘-s’ + Display Readline key sequences bound to macros and the strings + they output in such a way that they can be used as an argument + to a subsequent ‘bind’ command or in a Readline initialization + file. + + ‘-S’ + Display Readline key sequences bound to macros and the strings + they output. + + ‘-v’ + Display Readline variable names and values in such a way that + they can be used as an argument to a subsequent ‘bind’ command + or in a Readline initialization file. + + ‘-V’ + List current Readline variable names and values. + + ‘-f FILENAME’ + Read key bindings from FILENAME. + + ‘-q FUNCTION’ + Display key sequences that invoke the named Readline FUNCTION. + + ‘-u FUNCTION’ + Unbind all key sequences bound to the named Readline FUNCTION. + + ‘-r KEYSEQ’ + Remove any current binding for KEYSEQ. + + ‘-x KEYSEQ:SHELL-COMMAND’ + Cause SHELL-COMMAND to be executed whenever KEYSEQ is entered. + The separator between KEYSEQ and SHELL-COMMAND is either + whitespace or a colon optionally followed by whitespace. If + the separator is whitespace, SHELL-COMMAND must be enclosed in + double quotes and Readline expands any of its special + backslash-escapes in SHELL-COMMAND before saving it. If the + separator is a colon, any enclosing double quotes are + optional, and Readline does not expand the command string + before saving it. Since the entire key binding expression + must be a single argument, it should be enclosed in single + quotes. When SHELL-COMMAND is executed, the shell sets the + ‘READLINE_LINE’ variable to the contents of the Readline line + buffer and the ‘READLINE_POINT’ and ‘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 + ‘READLINE_ARGUMENT’ variable. If there was no argument, that + variable is not set. If the executed command changes the + value of any of ‘READLINE_LINE’, ‘READLINE_POINT’, or + ‘READLINE_MARK’, those new values will be reflected in the + editing state. + + ‘-X’ + List all key sequences bound to shell commands and the + associated commands in a format that can be reused as an + argument to a subsequent ‘bind’ command. + + The return status is zero unless an invalid option is supplied or + an error occurs. + +‘builtin’ + builtin [SHELL-BUILTIN [ARGS]] + + Execute the specified shell builtin SHELL-BUILTIN, passing it ARGS, + and return its exit status. This is useful when defining a shell + function with the same name as a shell builtin, retaining the + functionality of the builtin within the function. The return + status is non-zero if SHELL-BUILTIN is not a shell builtin command. + +‘caller’ + caller [EXPR] + + Returns the context of any active subroutine call (a shell function + or a script executed with the ‘.’ or ‘source’ builtins). + + Without EXPR, ‘caller’ displays the line number and source filename + of the current subroutine call. If a non-negative integer is + supplied as EXPR, ‘caller’ 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 EXPR does not correspond to a valid position in + the call stack. + +‘command’ + command [-pVv] COMMAND [ARGUMENTS ...] + + The ‘command’ builtin runs COMMAND with ARGUMENTS ignoring any + shell function named COMMAND. Only shell builtin commands or + commands found by searching the ‘PATH’ are executed. If there is a + shell function named ‘ls’, running ‘command ls’ within the function + will execute the external command ‘ls’ instead of calling the + function recursively. The ‘-p’ option means to use a default value + for ‘PATH’ that is guaranteed to find all of the standard + utilities. The return status in this case is 127 if COMMAND cannot + be found or an error occurred, and the exit status of COMMAND + otherwise. + + If either the ‘-V’ or ‘-v’ option is supplied, ‘command’ prints a + description of COMMAND. The ‘-v’ option displays a single word + indicating the command or file name used to invoke COMMAND; the + ‘-V’ option produces a more verbose description. In this case, the + return status is zero if COMMAND is found, and non-zero if not. + +‘declare’ + declare [-aAfFgiIlnrtux] [-p] [NAME[=VALUE] ...] + + Declare variables and give them attributes. If no NAMEs are given, + then display the values of variables or shell functions instead. + + The ‘-p’ option will display the attributes and values of each + NAME. When ‘-p’ is used with NAME arguments, additional options, + other than ‘-f’ and ‘-F’, are ignored. + + When ‘-p’ is supplied without NAME arguments, ‘declare’ will + display the attributes and values of all variables having the + attributes specified by the additional options. If no other + options are supplied with ‘-p’, ‘declare’ will display the + attributes and values of all shell variables. The ‘-f’ option + restricts the display to shell functions. + + The ‘-F’ option inhibits the display of function definitions; only + the function name and attributes are printed. If the ‘extdebug’ + shell option is enabled using ‘shopt’ (*note The Shopt Builtin::), + the source file name and line number where each NAME is defined are + displayed as well. ‘-F’ implies ‘-f’. + + The ‘-g’ option forces variables to be created or modified at the + global scope, even when ‘declare’ is executed in a shell function. + It is ignored in when ‘declare’ is not executed in a shell + function. + + The ‘-I’ option causes local variables to inherit the attributes + (except the ‘nameref’ attribute) and value of any existing variable + with the same NAME 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 attributes or to give variables attributes: + + ‘-a’ + Each NAME is an indexed array variable (*note Arrays::). + + ‘-A’ + Each NAME is an associative array variable (*note Arrays::). + + ‘-f’ + Each NAME refers to a shell function. + + ‘-i’ + The variable is to be treated as an integer; arithmetic + evaluation (*note Shell Arithmetic::) is performed when the + variable is assigned a value. + + ‘-l’ + When the variable is assigned a value, all upper-case + characters are converted to lower-case. The upper-case + attribute is disabled. + + ‘-n’ + Give each NAME the ‘nameref’ attribute, making it a name + reference to another variable. That other variable is defined + by the value of NAME. All references, assignments, and + attribute modifications to NAME, except for those using or + changing the ‘-n’ attribute itself, are performed on the + variable referenced by NAME's value. The nameref attribute + cannot be applied to array variables. + + ‘-r’ + Make NAMEs readonly. These names cannot then be assigned + values by subsequent assignment statements or unset. + + ‘-t’ + Give each NAME the ‘trace’ attribute. Traced functions + inherit the ‘DEBUG’ and ‘RETURN’ traps from the calling shell. + The trace attribute has no special meaning for variables. + + ‘-u’ + When the variable is assigned a value, all lower-case + characters are converted to upper-case. The lower-case + attribute is disabled. + + ‘-x’ + Mark each NAME for export to subsequent commands via the + environment. + + Using ‘+’ instead of ‘-’ turns off the specified attribute instead, + with the exceptions that ‘+a’ and ‘+A’ may not be used to destroy + array variables and ‘+r’ will not remove the readonly attribute. + + When used in a function, ‘declare’ makes each NAME local, as with + the ‘local’ command, unless the ‘-g’ option is supplied. If a + variable name is followed by =VALUE, the value of the variable is + set to VALUE. + + When using ‘-a’ or ‘-A’ and the compound assignment syntax to + create array variables, additional attributes do not take effect + until subsequent assignments. + + The return status is zero unless an invalid option is encountered, + an attempt is made to define a function using ‘-f foo=bar’, 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 (*note Arrays::), one of the + NAMEs 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 ‘-f’. + +‘echo’ + echo [-neE] [ARG ...] + + Output the ARGs, separated by spaces, terminated with a newline. + The return status is 0 unless a write error occurs. If ‘-n’ is + specified, the trailing newline is not printed. + + If the ‘-e’ option is given, ‘echo’ interprets the following + backslash-escaped characters. The ‘-E’ option disables + interpretation of these escape characters, even on systems where + they are interpreted by default. The ‘xpg_echo’ shell option + determines whether or not ‘echo’ interprets any options and expands + these escape characters. ‘echo’ does not interpret ‘--’ to mean + the end of options. + + ‘echo’ interprets the following escape sequences: + ‘\a’ + alert (bell) + ‘\b’ + backspace + ‘\c’ + suppress further output + ‘\e’ + ‘\E’ + escape + ‘\f’ + form feed + ‘\n’ + new line + ‘\r’ + carriage return + ‘\t’ + horizontal tab + ‘\v’ + vertical tab + ‘\\’ + backslash + ‘\0NNN’ + The eight-bit character whose value is the octal value NNN + (zero to three octal digits). + ‘\xHH’ + The eight-bit character whose value is the hexadecimal value + HH (one or two hex digits). + ‘\uHHHH’ + The Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value HHHH (one to four hex digits). + ‘\UHHHHHHHH’ + The Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value HHHHHHHH (one to eight hex digits). + + ‘echo’ writes any unrecognized backslash-escaped characters + unchanged. + +‘enable’ + enable [-a] [-dnps] [-f FILENAME] [NAME ...] + + Enable and disable builtin shell commands. Disabling a builtin + allows an executable file 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 files. + + If ‘-n’ is supplied, the NAMEs are disabled. Otherwise NAMEs are + enabled. For example, to use the ‘test’ binary found using ‘$PATH’ + instead of the shell builtin version, type ‘enable -n test’. + + If the ‘-p’ option is supplied, or no NAME arguments are supplied, + print a list of shell builtins. With no other arguments, the list + consists of all enabled shell builtins. The ‘-n’ option means to + print only disabled builtins. The ‘-a’ option means to list each + builtin with an indication of whether or not it is enabled. The + ‘-s’ option means to restrict ‘enable’ to the POSIX special + builtins. + + The ‘-f’ option means to load the new builtin command NAME from + shared object FILENAME, on systems that support dynamic loading. + If FILENAME does not contain a slash. Bash will use the value of + the ‘BASH_LOADABLES_PATH’ variable as a colon-separated list of + directories in which to search for FILENAME. The default for + ‘BASH_LOADABLES_PATH’ is system-dependent, and may include "." to + force a search of the current directory. The ‘-d’ option will + delete a builtin loaded with ‘-f’. If ‘-s’ is used with ‘-f’, the + new builtin becomes a POSIX special builtin (*note Special + Builtins::). + + If no options are supplied and a NAME is not a shell builtin, + ‘enable’ will attempt to load NAME from a shared object named NAME, + as if the command were ‘enable -f NAME NAME’. + + The return status is zero unless a NAME is not a shell builtin or + there is an error loading a new builtin from a shared object. + +‘help’ + help [-dms] [PATTERN] + + Display helpful information about builtin commands. If PATTERN is + specified, ‘help’ gives detailed help on all commands matching + PATTERN as described below; otherwise it displays a list of all + builtins and shell compound commands. + + Options, if supplied, have the following meanings: + + ‘-d’ + Display a short description of each PATTERN + ‘-m’ + Display the description of each PATTERN in a manpage-like + format + ‘-s’ + Display only a short usage synopsis for each PATTERN + + If PATTERN contains pattern matching characters (*note Pattern + Matching::) it's treated as a shell pattern and ‘help’ prints the + description of each help topic matching PATTERN. + + If not, and PATTERN exactly matches the name of a help topic, + ‘help’ prints the description associated with that topic. + Otherwise, ‘help’ performs prefix matching and prints the + descriptions of all matching help topics. + + The return status is zero unless no command matches PATTERN. + +‘let’ + let EXPRESSION [EXPRESSION ...] + + The ‘let’ builtin allows arithmetic to be performed on shell + variables. Each EXPRESSION is evaluated as an arithmetic + expression according to the rules given below in *note Shell + Arithmetic::. If the last EXPRESSION evaluates to 0, ‘let’ returns + 1; otherwise ‘let’ returns 0. + +‘local’ + local [OPTION] NAME[=VALUE] ... + + For each argument, create a local variable named NAME, and assign + it VALUE. The OPTION can be any of the options accepted by + ‘declare’. ‘local’ can only be used within a function; it makes + the variable NAME have a visible scope restricted to that function + and its children. It is an error to use ‘local’ when not within a + function. + + If NAME is ‘-’, it makes the set of shell options local to the + function in which ‘local’ is invoked: any shell options changed + using the ‘set’ builtin inside the function after the call to + ‘local’ are restored to their original values when the function + returns. The restore is performed as if a series of ‘set’ commands + were executed to restore the values that were in place before the + function. + + With no operands, ‘local’ writes a list of local variables to the + standard output. + + The return status is zero unless ‘local’ is used outside a + function, an invalid NAME is supplied, or NAME is a readonly + variable. + +‘logout’ + logout [N] + + Exit a login shell, returning a status of N to the shell's parent. + +‘mapfile’ + mapfile [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] + [-t] [-u FD] [-C CALLBACK] [-c QUANTUM] [ARRAY] + + Read lines from the standard input, or from file descriptor FD if + the ‘-u’ option is supplied, into the indexed array variable ARRAY. + The variable ‘MAPFILE’ is the default ARRAY. Options, if supplied, + have the following meanings: + + ‘-d’ + Use the first character of DELIM to terminate each input line, + rather than newline. If DELIM is the empty string, ‘mapfile’ + will terminate a line when it reads a NUL character. + ‘-n’ + Copy at most COUNT lines. If COUNT is 0, copy all lines. + ‘-O’ + Begin assigning to ARRAY at index ORIGIN. The default index + is 0. + ‘-s’ + Discard the first COUNT lines read. + ‘-t’ + Remove a trailing DELIM (default newline) from each line read. + ‘-u’ + Read lines from file descriptor FD instead of the standard + input. + ‘-C’ + Evaluate CALLBACK each time QUANTUM lines are read. The ‘-c’ + option specifies QUANTUM. + ‘-c’ + Specify the number of lines read between each call to + CALLBACK. + + If ‘-C’ is specified without ‘-c’, the default quantum is 5000. + When CALLBACK 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. CALLBACK is evaluated after the + line is read but before the array element is assigned. + + If not supplied with an explicit origin, ‘mapfile’ will clear ARRAY + before assigning to it. + + ‘mapfile’ returns zero unless an invalid option or option argument + is supplied, ARRAY is invalid or unassignable, or if ARRAY is not + an indexed array. + +‘printf’ + printf [-v VAR] FORMAT [ARGUMENTS] + + Write the formatted ARGUMENTS to the standard output under the + control of the FORMAT. The ‘-v’ option assigns the output to the + variable VAR rather than printing it to the standard output. + + The FORMAT 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 ARGUMENT. In addition to + the standard ‘printf(3)’ format characters ‘cCsSndiouxXeEfFgGaA’, + ‘printf’ interprets the following additional format specifiers: + + ‘%b’ + Causes ‘printf’ to expand backslash escape sequences in the + corresponding ARGUMENT in the same way as ‘echo -e’ (*note + Bash Builtins::). + ‘%q’ + Causes ‘printf’ to output the corresponding ARGUMENT in a + format that can be reused as shell input. ‘%q’ and ‘%Q’P use + the ANSI-C quoting style (*note ANSI-C Quoting::) if any + characters in the argument string require it, and backslash + quoting otherwise. If the format string uses the ‘printf’ + _alternate form_, these two formats quote the argument string + using single quotes. + + ‘%Q’ + like ‘%q’, but applies any supplied precision to the ARGUMENT + before quoting it. + + ‘%(DATEFMT)T’ + Causes ‘printf’ to output the date-time string resulting from + using DATEFMT as a format string for ‘strftime’(3). The + corresponding ARGUMENT is an integer representing the number + of seconds since the epoch. This format specifier recognizes + Two special argument values: -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 + supplied. This is an exception to the usual ‘printf’ + behavior. + + The %b, %q, and %T format specifiers 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. + + The %n format specifier accepts a corresponding argument that is + treated as a shell variable name. + + The %s and %c format specifiers accept an l (long) modifier, which + forces them to convert the argument string to a wide-character + string and apply any supplied field width and precision in terms of + characters, not bytes. The %S and %C format specifiers are + equivalent to %ls and %lc, respectively. + + Arguments to non-string format specifiers are treated as C language + 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 numeric value of the following character, using the current + locale. + + The FORMAT is reused as necessary to consume all of the ARGUMENTS. + If the FORMAT requires more ARGUMENTS 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 if an invalid option is supplied or a write or + assignment error occurs. + +‘read’ + read [-Eers] [-a ANAME] [-d DELIM] [-i TEXT] [-n NCHARS] + [-N NCHARS] [-p PROMPT] [-t TIMEOUT] [-u FD] [NAME ...] + + Read one line from the standard input, or from the file descriptor + FD supplied as an argument to the ‘-u’ option, split it into words + as described above in *note Word Splitting::, and assign the first + word to the first NAME, the second word to the second NAME, and so + on. If there are more words than names, the remaining words and + their intervening delimiters are assigned to the last NAME. If + there are fewer words read from the input stream than names, the + remaining names are assigned empty values. The characters in the + value of the ‘IFS’ variable are used to split the line into words + using the same rules the shell uses for expansion (described above + in *note Word Splitting::). The backslash character ‘\’ removes + any special meaning for the next character read and is used for + line continuation. + + Options, if supplied, have the following meanings: + + ‘-a ANAME’ + The words are assigned to sequential indices of the array + variable ANAME, starting at 0. All elements are removed from + ANAME before the assignment. Other NAME arguments are + ignored. + + ‘-d DELIM’ + The first character of DELIM terminates the input line, rather + than newline. If DELIM is the empty string, ‘read’ will + terminate a line when it reads a NUL character. + + ‘-e’ + If the standard input is coming from a terminal, ‘read’ uses + Readline (*note Command Line Editing::) 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. + + ‘-E’ + If the standard input is coming from a terminal, ‘read’ uses + Readline (*note Command Line Editing::) to obtain the line. + Readline uses the current (or default, if line editing was not + previously active) editing settings, but uses Bash's default + completion, including programmable completion. + + ‘-i TEXT’ + If Readline is being used to read the line, ‘read’ places TEXT + into the editing buffer before editing begins. + + ‘-n NCHARS’ + ‘read’ returns after reading NCHARS characters rather than + waiting for a complete line of input, unless it encounters EOF + or ‘read’ times out, but honors a delimiter if it reads fewer + than NCHARS characters before the delimiter. + + ‘-N NCHARS’ + ‘read’ returns after reading exactly NCHARS characters rather + than waiting for a complete line of input, unless it + encounters EOF or ‘read’ times out. Delimiter characters in + the input are not treated specially and do not cause ‘read’ to + return until it has read NCHARS characters. The result is not + split on the characters in ‘IFS’; the intent is that the + variable is assigned exactly the characters read (with the + exception of backslash; see the ‘-r’ option below). + + ‘-p PROMPT’ + Display PROMPT, without a trailing newline, before attempting + to read any input, but only if input is coming from a + terminal. + + ‘-r’ + If this option is given, 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. + + ‘-s’ + Silent mode. If input is coming from a terminal, characters + are not echoed. + + ‘-t TIMEOUT’ + Cause ‘read’ to time out and return failure if it does not + read a complete line of input (or a specified number of + characters) within TIMEOUT seconds. TIMEOUT may be a decimal + number with a fractional portion following the decimal point. + This option is only effective if ‘read’ is reading input from + a terminal, pipe, or other special file; it has no effect when + reading from regular files. If ‘read’ times out, it saves any + partial input read into the specified variable NAME, and + returns a status greater than 128. If TIMEOUT is 0, ‘read’ + returns immediately, without trying to read any data. In this + case, the exit status is 0 if input is available on the + specified file descriptor, or the read will return EOF, + non-zero otherwise. + + ‘-u FD’ + Read input from file descriptor FD instead of the standard + input. + + Other than the case where DELIM is the empty string, ‘read’ ignores + any NUL characters in the input. + + If no NAMEs are supplied, ‘read’ assigns the line read, without the + ending delimiter but otherwise unmodified, to the variable ‘REPLY’. + + The exit status is zero, unless end-of-file is encountered, ‘read’ + 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 ‘-u’. + +‘readarray’ + readarray [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] + [-t] [-u FD] [-C CALLBACK] [-c QUANTUM] [ARRAY] + + Read lines from the standard input into the indexed array variable + ARRAY, or from file descriptor FD if the ‘-u’ option is supplied. + + A synonym for ‘mapfile’. + +‘source’ + source [-p PATH] FILENAME [ARGUMENTS] + + A synonym for ‘.’ (*note Bourne Shell Builtins::). + +‘type’ + type [-afptP] [NAME ...] + + Indicate how each NAME would be interpreted if used as a command + name. + + If the ‘-t’ option is used, ‘type’ prints a single word which is + one of ‘alias’, ‘keyword’, ‘function’, ‘builtin’, or ‘file’, if + NAME is an alias, shell reserved word, shell function, shell + builtin, or executable file, respectively. If the NAME is not + found, ‘type’ prints nothing and returns a failure status. + + If the ‘-p’ option is used, ‘type’ either returns the name of the + executable file that would be found by searching ‘$PATH’ for + ‘name’, or nothing if ‘-t’ would not return ‘file’. + + The ‘-P’ option forces a path search for each NAME, even if ‘-t’ + would not return ‘file’. + + If a NAME is present in the table of hashed commands, options ‘-p’ + and ‘-P’ print the hashed value, which is not necessarily the file + that appears first in ‘$PATH’. + + If the ‘-a’ option is used, ‘type’ returns all of the places that + contain a command named NAME. This includes aliases, reserved + words, functions, and builtins, but the path search options (‘-p’ + and ‘-P’) can be supplied to restrict the output to executable + files. If ‘-a’ is supplied with ‘-p’, ‘type’ does not look in the + table of hashed commands, and only performs a ‘PATH’ search for + NAME. + + If the ‘-f’ option is used, ‘type’ does not attempt to find shell + functions, as with the ‘command’ builtin. + + The return status is zero if all of the NAMEs are found, non-zero + if any are not found. + +‘typeset’ + typeset [-afFgrxilnrtux] [-p] [NAME[=VALUE] ...] + + The ‘typeset’ command is supplied for compatibility with the Korn + shell. It is a synonym for the ‘declare’ builtin command. + +‘ulimit’ + ulimit [-HS] -a + ulimit [-HS] [-bcdefiklmnpqrstuvxPRT] [LIMIT] + + ‘ulimit’ provides control over the resources available to the shell + and to processes it starts, on systems that allow such control. If + an option is given, it is interpreted as follows: + + ‘-S’ + Change and report the soft limit associated with a resource. + + ‘-H’ + Change and report the hard limit associated with a resource. + + ‘-a’ + Report all current limits; no limits are set. + + ‘-b’ + The maximum socket buffer size. + + ‘-c’ + The maximum size of core files created. + + ‘-d’ + The maximum size of a process's data segment. + + ‘-e’ + The maximum scheduling priority ("nice"). + + ‘-f’ + The maximum size of files written by the shell and its + children. + + ‘-i’ + The maximum number of pending signals. + + ‘-k’ + The maximum number of kqueues that may be allocated. + + ‘-l’ + The maximum size that may be locked into memory. + + ‘-m’ + The maximum resident set size (many systems do not honor this + limit). + + ‘-n’ + The maximum number of open file descriptors (most systems do + not allow this value to be set). + + ‘-p’ + The pipe buffer size. + + ‘-q’ + The maximum number of bytes in POSIX message queues. + + ‘-r’ + The maximum real-time scheduling priority. + + ‘-s’ + The maximum stack size. + + ‘-t’ + The maximum amount of cpu time in seconds. + + ‘-u’ + The maximum number of processes available to a single user. + + ‘-v’ + The maximum amount of virtual memory available to the shell, + and, on some systems, to its children. + + ‘-x’ + The maximum number of file locks. + + ‘-P’ + The maximum number of pseudoterminals. + + ‘-R’ + The maximum time a real-time process can run before blocking, + in microseconds. + + ‘-T’ + The maximum number of threads. + + If LIMIT is supplied, and the ‘-a’ option is not used, LIMIT is the + new value of the specified resource. The special LIMIT values + ‘hard’, ‘soft’, and ‘unlimited’ stand for the current hard limit, + the current soft limit, and no limit, respectively. 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. Otherwise, + ‘ulimit’ prints the current value of the soft limit for the + specified resource, unless the ‘-H’ option is supplied. When more + than one resource is specified, the limit name and unit, if + appropriate, are printed before the value. When setting new + limits, if neither ‘-H’ nor ‘-S’ is supplied, ‘ulimit’ sets both + the hard and soft limits. If no option is supplied, then ‘-f’ is + assumed. + + Values are in 1024-byte increments, except for ‘-t’, which is in + seconds; ‘-R’, which is in microseconds; ‘-p’, which is in units of + 512-byte blocks; ‘-P’, ‘-T’, ‘-b’, ‘-k’, ‘-n’ and ‘-u’, which are + unscaled values; and, when in POSIX mode (*note Bash POSIX Mode::), + ‘-c’ and ‘-f’, which are in 512-byte increments. + + The return status is zero unless an invalid option or argument is + supplied, or an error occurs while setting a new limit. + +‘unalias’ + unalias [-a] [NAME ... ] + + Remove each NAME from the list of aliases. If ‘-a’ is supplied, + remove all aliases. The return value is true unless a supplied + NAME is not a defined alias. Aliases are described in *note + Aliases::. + + +File: bash.info, Node: Modifying Shell Behavior, Next: Special Builtins, Prev: Bash Builtins, Up: Shell Builtin Commands + +4.3 Modifying Shell Behavior +============================ + +* Menu: + +* The Set Builtin:: Change the values of shell attributes and + positional parameters. +* The Shopt Builtin:: Modify shell optional behavior. + + +File: bash.info, Node: The Set Builtin, Next: The Shopt Builtin, Up: Modifying Shell Behavior + +4.3.1 The Set Builtin +--------------------- + +This builtin is so complicated that it deserves its own section. ‘set’ +allows you to change the values of shell options and set the positional +parameters, or to display the names and values of shell variables. + +‘set’ + set [-abefhkmnptuvxBCEHPT] [-o OPTION-NAME] [--] [-] [ARGUMENT ...] + set [+abefhkmnptuvxBCEHPT] [+o OPTION-NAME] [--] [-] [ARGUMENT ...] + set -o + set +o + + If no options or arguments are supplied, ‘set’ displays the names + and values of all shell variables and functions, sorted according + to the current locale, in a format that may be reused as input for + setting or resetting the currently-set variables. Read-only + variables cannot be reset. In POSIX mode, only shell variables are + listed. + + When options are supplied, they set or unset shell attributes. Any + arguments remaining after option processing replace the positional + parameters. + + Options, if specified, have the following meanings: + + ‘-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. + + ‘-b’ + Cause the status of terminated background jobs to be reported + immediately, rather than before printing the next primary + prompt or, under some circumstances, when a foreground command + exits. This is effective only when job control is enabled. + + ‘-e’ + Exit immediately if a pipeline (*note Pipelines::), which may + consist of a single simple command (*note Simple Commands::), + a list (*note Lists::), or a compound command (*note Compound + Commands::) returns a non-zero status. The shell does not + exit if the command that fails is part of the command list + immediately following a ‘while’ or ‘until’ reserved word, part + of the test in an ‘if’ statement, part of any command executed + in a ‘&&’ or ‘||’ list except the command following the final + ‘&&’ or ‘||’, any command in a pipeline but the last (subject + to the state of the ‘pipefail’ shell option), or if the + command's return status is being inverted with ‘!’. If a + compound command other than a subshell returns a non-zero + status because a command failed while ‘-e’ was being ignored, + the shell does not exit. A trap on ‘ERR’, if set, is executed + before the shell exits. + + This option applies to the shell environment and each subshell + environment separately (*note Command Execution + Environment::), and may cause subshells to exit before + executing all the commands in the subshell. + + If a compound command or shell function executes in a context + where ‘-e’ is being ignored, none of the commands executed + within the compound command or function body will be affected + by the ‘-e’ setting, even if ‘-e’ is set and a command returns + a failure status. If a compound command or shell function + sets ‘-e’ while executing in a context where ‘-e’ is ignored, + that setting will not have any effect until the compound + command or the command containing the function call completes. + + ‘-f’ + Disable filename expansion (globbing). + + ‘-h’ + Locate and remember (hash) commands as they are looked up for + execution. This option is enabled by default. + + ‘-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. + + ‘-m’ + Job control is enabled (*note Job Control::). All processes + run in a separate process group. When a background job + completes, the shell prints a line containing its exit status. + + ‘-n’ + Read commands but do not execute them. This may be used to + check a script for syntax errors. This option is ignored by + interactive shells. + + ‘-o OPTION-NAME’ + + Set the option corresponding to OPTION-NAME. If ‘-o’ is + supplied with no OPTION-NAME, ‘set’ prints the current shell + options settings. If ‘+o’ is supplied with no OPTION-NAME, + ‘set’ prints a series of ‘set’ commands to recreate the + current option settings on the standard output. Valid option + names are: + + ‘allexport’ + Same as ‘-a’. + + ‘braceexpand’ + Same as ‘-B’. + + ‘emacs’ + Use an ‘emacs’-style line editing interface (*note + Command Line Editing::). This also affects the editing + interface used for ‘read -e’. + + ‘errexit’ + Same as ‘-e’. + + ‘errtrace’ + Same as ‘-E’. + + ‘functrace’ + Same as ‘-T’. + + ‘hashall’ + Same as ‘-h’. + + ‘histexpand’ + Same as ‘-H’. + + ‘history’ + Enable command history, as described in *note Bash + History Facilities::. This option is on by default in + interactive shells. + + ‘ignoreeof’ + An interactive shell will not exit upon reading EOF. + + ‘keyword’ + Same as ‘-k’. + + ‘monitor’ + Same as ‘-m’. + + ‘noclobber’ + Same as ‘-C’. + + ‘noexec’ + Same as ‘-n’. + + ‘noglob’ + Same as ‘-f’. + + ‘nolog’ + Currently ignored. + + ‘notify’ + Same as ‘-b’. + + ‘nounset’ + Same as ‘-u’. + + ‘onecmd’ + Same as ‘-t’. + + ‘physical’ + Same as ‘-P’. + + ‘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. + + ‘posix’ + Enable POSIX mode; change the behavior of Bash where the + default operation differs from the POSIX standard to + match the standard (*note Bash POSIX Mode::). This is + intended to make Bash behave as a strict superset of that + standard. + + ‘privileged’ + Same as ‘-p’. + + ‘verbose’ + Same as ‘-v’. + + ‘vi’ + Use a ‘vi’-style line editing interface. This also + affects the editing interface used for ‘read -e’. + + ‘xtrace’ + Same as ‘-x’. + + ‘-p’ + Turn on privileged mode. In this mode, the ‘$BASH_ENV’ and + ‘$ENV’ files are not processed, shell functions are not + inherited from the environment, and the ‘SHELLOPTS’, + ‘BASHOPTS’, ‘CDPATH’ and ‘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 ‘-p’ option is not supplied, + these actions are taken and the effective user id is set to + the real user id. If the ‘-p’ 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. + + ‘-r’ + Enable restricted shell mode (*note The Restricted Shell::). + This option cannot be unset once it has been set. + + ‘-t’ + Exit after reading and executing one command. + + ‘-u’ + Treat unset variables and parameters other than the special + parameters ‘@’ or ‘*’, or array variables subscripted with ‘@’ + or ‘*’, as an error when performing parameter expansion. An + error message will be written to the standard error, and a + non-interactive shell will exit. + + ‘-v’ + Print shell input lines to standard error as they are read. + + ‘-x’ + Print a trace of simple commands, ‘for’ commands, ‘case’ + commands, ‘select’ commands, and arithmetic ‘for’ commands and + their arguments or associated word lists to the standard error + after they are expanded and before they are executed. The + shell prints the expanded value of the ‘PS4’ variable before + the command and its expanded arguments. + + ‘-B’ + The shell will perform brace expansion (*note Brace + Expansion::). This option is on by default. + + ‘-C’ + Prevent output redirection using ‘>’, ‘>&’, and ‘<>’ from + overwriting existing files. Using the redirection operator + ‘>|’ instead of ‘>’ will override this and force the creation + of an output file. + + ‘-E’ + If set, any trap on ‘ERR’ is inherited by shell functions, + command substitutions, and commands executed in a subshell + environment. The ‘ERR’ trap is normally not inherited in such + cases. + + ‘-H’ + Enable ‘!’ style history substitution (*note History + Interaction::). This option is on by default for interactive + shells. + + ‘-P’ + If set, Bash does not resolve symbolic links when executing + commands such as ‘cd’ which change the current directory. It + uses the physical directory structure instead. By default, + Bash follows the logical chain of directories when performing + commands which change the current directory. + + For example, if ‘/usr/sys’ is a symbolic link to + ‘/usr/local/sys’ then: + $ cd /usr/sys; echo $PWD + /usr/sys + $ cd ..; pwd + /usr + + If ‘set -P’ is on, then: + $ cd /usr/sys; echo $PWD + /usr/local/sys + $ cd ..; pwd + /usr/local + + ‘-T’ + If set, any traps on ‘DEBUG’ and ‘RETURN’ are inherited by + shell functions, command substitutions, and commands executed + in a subshell environment. The ‘DEBUG’ and ‘RETURN’ traps are + normally not inherited in such cases. + + ‘--’ + If no arguments follow this option, unset the positional + parameters. Otherwise, the positional parameters are set to + the ARGUMENTS, even if some of them begin with a ‘-’. + + ‘-’ + Signal the end of options, and assign all remaining ARGUMENTS + to the positional parameters. The ‘-x’ and ‘-v’ options are + turned off. If there are no arguments, the positional + parameters remain unchanged. + + Using ‘+’ rather than ‘-’ causes these options to be turned off. + The options can also be used upon invocation of the shell. The + current set of options may be found in ‘$-’. + + The remaining N ARGUMENTS are positional parameters and are + assigned, in order, to ‘$1’, ‘$2’, ... ‘$N’. The special parameter + ‘#’ is set to N. + + The return status is always zero unless an invalid option is + supplied. + + +File: bash.info, Node: The Shopt Builtin, Prev: The Set Builtin, Up: Modifying Shell Behavior + +4.3.2 The Shopt Builtin +----------------------- + +This builtin allows you to change additional optional shell behavior. + +‘shopt’ + shopt [-pqsu] [-o] [OPTNAME ...] + + Toggle the values of settings controlling optional shell behavior. + The settings can be either those listed below, or, if the ‘-o’ + option is used, those available with the ‘-o’ option to the ‘set’ + builtin command (*note The Set Builtin::). + + With no options, or with the ‘-p’ option, display a list of all + settable options, with an indication of whether or not each is set; + if any OPTNAMEs are supplied, the output is restricted to those + options. The ‘-p’ option displays output in a form that may be + reused as input. + + Other options have the following meanings: + + ‘-s’ + Enable (set) each OPTNAME. + + ‘-u’ + Disable (unset) each OPTNAME. + + ‘-q’ + Suppresses normal output; the return status indicates whether + the OPTNAME is set or unset. If multiple OPTNAME arguments + are supplied with ‘-q’, the return status is zero if all + OPTNAMEs are enabled; non-zero otherwise. + + ‘-o’ + Restricts the values of OPTNAME to be those defined for the + ‘-o’ option to the ‘set’ builtin (*note The Set Builtin::). + + If either ‘-s’ or ‘-u’ is used with no OPTNAME arguments, ‘shopt’ + shows only those options which are set or unset, respectively. + + Unless otherwise noted, the ‘shopt’ options are disabled (off) by + default. + + The return status when listing options is zero if all OPTNAMEs are + enabled, non-zero otherwise. When setting or unsetting options, + the return status is zero unless an OPTNAME is not a valid shell + option. + + The list of ‘shopt’ options is: + + ‘array_expand_once’ + If set, the shell suppresses multiple evaluation of + associative and indexed array subscripts during arithmetic + expression evaluation, while executing builtins that can + perform variable assignments, and while executing builtins + that perform array dereferencing. + + ‘assoc_expand_once’ + Deprecated; a synonym for ‘array_expand_once’. + + ‘autocd’ + If set, a command name that is the name of a directory is + executed as if it were the argument to the ‘cd’ command. This + option is only used by interactive shells. + + ‘bash_source_fullpath’ + If set, filenames added to the ‘BASH_SOURCE’ array variable + are converted to full pathnames (*note Bash Variables::). + + ‘cdable_vars’ + If this is set, an argument to the ‘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. + + ‘cdspell’ + If set, the ‘cd’ command attempts to correct minor errors in + the spelling of a directory component. Minor errors include + transposed characters, a missing character, and one extra + character. If ‘cd’ corrects the directory name, it prints the + corrected filename, and the command proceeds. This option is + only used by interactive shells. + + ‘checkhash’ + If this is set, Bash checks that a command found in the hash + table exists before trying to execute it. If a hashed command + no longer exists, Bash performs a normal path search. + + ‘checkjobs’ + If set, Bash lists the status of any stopped and running jobs + before exiting an interactive shell. If any jobs are running, + Bash defers the exit until a second exit is attempted without + an intervening command (*note Job Control::). The shell + always postpones exiting if any jobs are stopped. + + ‘checkwinsize’ + If set, Bash checks the window size after each external + (non-builtin) command and, if necessary, updates the values of + ‘LINES’ and ‘COLUMNS’, using the file descriptor associated + with stderr if it is a terminal. This option is enabled by + default. + + ‘cmdhist’ + If set, 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 + (*note Bash History Facilities::). + + ‘compat31’ + ‘compat32’ + ‘compat40’ + ‘compat41’ + ‘compat42’ + ‘compat43’ + ‘compat44’ + These control aspects of the shell's compatibility mode (*note + Shell Compatibility Mode::). + + ‘complete_fullquote’ + If set, Bash quotes all shell metacharacters in filenames and + directory names when performing completion. If not set, 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. + + ‘direxpand’ + If set, 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, Bash + attempts to preserve what the user typed. + + ‘dirspell’ + If set, Bash attempts spelling correction on directory names + during word completion if the directory name initially + supplied does not exist. + + ‘dotglob’ + If set, Bash includes filenames beginning with a ‘.’ in the + results of filename expansion. The filenames ‘.’ and ‘..’ + must always be matched explicitly, even if ‘dotglob’ is set. + + ‘execfail’ + If this is set, a non-interactive shell will not exit if it + cannot execute the file specified as an argument to the ‘exec’ + builtin. An interactive shell does not exit if ‘exec’ fails. + + ‘expand_aliases’ + If set, aliases are expanded as described below under Aliases, + *note Aliases::. This option is enabled by default for + interactive shells. + + ‘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 ‘--debugger’ option. If set after + invocation, behavior intended for use by debuggers is enabled: + + 1. The ‘-F’ option to the ‘declare’ builtin (*note Bash + Builtins::) displays the source file name and line number + corresponding to each function name supplied as an + argument. + + 2. If the command run by the ‘DEBUG’ trap returns a non-zero + value, the next command is skipped and not executed. + + 3. If the command run by the ‘DEBUG’ trap returns a value of + 2, and the shell is executing in a subroutine (a shell + function or a shell script executed by the ‘.’ or + ‘source’ builtins), the shell simulates a call to + ‘return’. + + 4. ‘BASH_ARGC’ and ‘BASH_ARGV’ are updated as described in + their descriptions (*note Bash Variables::). + + 5. Function tracing is enabled: command substitution, shell + functions, and subshells invoked with ‘( COMMAND )’ + inherit the ‘DEBUG’ and ‘RETURN’ traps. + + 6. Error tracing is enabled: command substitution, shell + functions, and subshells invoked with ‘( COMMAND )’ + inherit the ‘ERR’ trap. + + ‘extglob’ + If set, enable the extended pattern matching features + described above (*note Pattern Matching::). + + ‘extquote’ + If set, ‘$'STRING'’ and ‘$"STRING"’ quoting is performed + within ‘${PARAMETER}’ expansions enclosed in double quotes. + This option is enabled by default. + + ‘failglob’ + If set, patterns which fail to match filenames during filename + expansion result in an expansion error. + + ‘force_fignore’ + If set, the suffixes specified by the ‘FIGNORE’ shell variable + cause words to be ignored when performing word completion even + if the ignored words are the only possible completions. *Note + Bash Variables::, for a description of ‘FIGNORE’. This option + is enabled by default. + + ‘globasciiranges’ + If set, range expressions used in pattern matching bracket + expressions (*note Pattern Matching::) behave as if in the + traditional C locale when performing comparisons. That is, + pattern matching does not take the current locale's collating + sequence into account, so ‘b’ will not collate between ‘A’ and + ‘B’, and upper-case and lower-case ASCII characters will + collate together. + + ‘globskipdots’ + If set, filename expansion will never match the filenames ‘.’ + and ‘..’, even if the pattern begins with a ‘.’. This option + is enabled by default. + + ‘globstar’ + If set, the pattern ‘**’ used in a filename expansion context + will match all files and zero or more directories and + subdirectories. If the pattern is followed by a ‘/’, only + directories and subdirectories match. + + ‘gnu_errfmt’ + If set, shell error messages are written in the standard GNU + error message format. + + ‘histappend’ + If set, the history list is appended to the file named by the + value of the ‘HISTFILE’ variable when the shell exits, rather + than overwriting the file. + + ‘histreedit’ + If set, and Readline is being used, the user is given the + opportunity to re-edit a failed history substitution. + + ‘histverify’ + If set, and 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 Readline + editing buffer, allowing further modification. + + ‘hostcomplete’ + If set, and Readline is being used, Bash will attempt to + perform hostname completion when a word containing a ‘@’ is + being completed (*note Commands For Completion::). This + option is enabled by default. + + ‘huponexit’ + If set, Bash will send ‘SIGHUP’ to all jobs when an + interactive login shell exits (*note Signals::). + + ‘inherit_errexit’ + If set, command substitution inherits the value of the + ‘errexit’ option, instead of unsetting it in the subshell + environment. This option is enabled when POSIX mode is + enabled. + + ‘interactive_comments’ + In an interactive shell, a word beginning with ‘#’ causes that + word and all remaining characters on that line to be ignored, + as in a non-interactive shell. This option is enabled by + default. + + ‘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. + + ‘lithist’ + If enabled, and the ‘cmdhist’ option is enabled, multi-line + commands are saved to the history with embedded newlines + rather than using semicolon separators where possible. + + ‘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. + + ‘localvar_unset’ + If set, calling ‘unset’ 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. + + ‘login_shell’ + The shell sets this option if it is started as a login shell + (*note Invoking Bash::). The value may not be changed. + + ‘mailwarn’ + If set, and a file that Bash is checking for mail has been + accessed since the last time it was checked, Bash displays the + message ‘"The mail in MAILFILE has been read"’. + + ‘no_empty_cmd_completion’ + If set, and Readline is being used, Bash does not search the + ‘PATH’ for possible completions when completion is attempted + on an empty line. + + ‘nocaseglob’ + If set, Bash matches filenames in a case-insensitive fashion + when performing filename expansion. + + ‘nocasematch’ + If set, Bash matches patterns in a case-insensitive fashion + when performing matching while executing ‘case’ or ‘[[’ + conditional commands (*note Conditional Constructs::), when + performing pattern substitution word expansions, or when + filtering possible completions as part of programmable + completion. + + ‘noexpand_translation’ + If set, Bash encloses the translated results of $"..." quoting + in single quotes instead of double quotes. If the string is + not translated, this has no effect. + + ‘nullglob’ + If set, filename expansion patterns which match no files + (*note Filename Expansion::) expand to nothing and are + removed, rather than expanding to themselves. + + ‘patsub_replacement’ + If set, Bash expands occurrences of ‘&’ in the replacement + string of pattern substitution to the text matched by the + pattern, as described above (*note Shell Parameter + Expansion::). This option is enabled by default. + + ‘progcomp’ + If set, enable the programmable completion facilities (*note + Programmable Completion::). This option is enabled by + default. + + ‘progcomp_alias’ + If set, and programmable completion is enabled, Bash treats a + command name that doesn't have any completions as a possible + alias and attempts alias expansion. If it has an alias, Bash + attempts programmable completion using the command word + resulting from the expanded alias. + + ‘promptvars’ + If set, prompt strings undergo parameter expansion, command + substitution, arithmetic expansion, and quote removal after + being expanded as described below (*note Controlling the + Prompt::). This option is enabled by default. + + ‘restricted_shell’ + The shell sets this option if it is started in restricted mode + (*note The Restricted Shell::). 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. + + ‘shift_verbose’ + If this is set, the ‘shift’ builtin prints an error message + when the shift count exceeds the number of positional + parameters. + + ‘sourcepath’ + If set, the ‘.’ (‘source’) builtin uses the value of ‘PATH’ to + find the directory containing the file supplied as an argument + when the ‘-p’ option is not supplied. This option is enabled + by default. + + ‘varredir_close’ + If set, the shell automatically closes file descriptors + assigned using the ‘{varname}’ redirection syntax (*note + Redirections::) instead of leaving them open when the command + completes. + + ‘xpg_echo’ + If set, the ‘echo’ builtin expands backslash-escape sequences + by default. If the ‘posix’ shell option (*note The Set + Builtin::) is also enabled, ‘echo’ does not interpret any + options. + + +File: bash.info, Node: Special Builtins, Prev: Modifying Shell Behavior, Up: Shell Builtin Commands + +4.4 Special Builtins +==================== + +For historical reasons, the POSIX standard has classified several +builtin commands as _special_. When Bash is executing in POSIX mode, +the special builtins differ from other builtin commands in three +respects: + + 1. Special builtins are found before shell functions during command + lookup. + + 2. If a special builtin returns an error status, a non-interactive + shell exits. + + 3. Assignment statements preceding the command stay in effect in the + shell environment after the command completes. + + When Bash is not executing in POSIX mode, these builtins behave no +differently than the rest of the Bash builtin commands. The Bash POSIX +mode is described in *note Bash POSIX Mode::. + + These are the POSIX special builtins: + break : . source continue eval exec exit export readonly return set + shift times trap unset + + +File: bash.info, Node: Shell Variables, Next: Bash Features, Prev: Shell Builtin Commands, Up: Top + +5 Shell Variables +***************** + +* Menu: + +* Bourne Shell Variables:: Variables which Bash uses in the same way + as the Bourne Shell. +* Bash Variables:: List of variables that exist in Bash. + +This chapter describes the shell variables that Bash uses. Bash +automatically assigns default values to a number of variables. + + +File: bash.info, Node: Bourne Shell Variables, Next: Bash Variables, Up: Shell Variables + +5.1 Bourne Shell Variables +========================== + +Bash uses certain shell variables in the same way as the Bourne shell. +In some cases, Bash assigns a default value to the variable. + +‘CDPATH’ + A colon-separated list of directories used as a search path for the + ‘cd’ builtin command. + +‘HOME’ + The current user's home directory; the default for the ‘cd’ builtin + command. The value of this variable is also used by tilde + expansion (*note Tilde Expansion::). + +‘IFS’ + A list of characters that separate fields; used when the shell + splits words as part of expansion and by the ‘read’ builtin to + split lines into words. *Note Word Splitting::, for a description + of word splitting. + +‘MAIL’ + If the value is set to a filename or directory name and the + ‘MAILPATH’ variable is not set, Bash informs the user of the + arrival of mail in the specified file or Maildir-format directory. + +‘MAILPATH’ + A colon-separated list of filenames which the shell periodically + checks for new mail. Each list entry can specify the message that + is printed when new mail arrives in the mail file by separating the + filename from the message with a ‘?’. When used in the text of the + message, ‘$_’ expands to the name of the current mail file. + +‘OPTARG’ + The value of the last option argument processed by the ‘getopts’ + builtin. + +‘OPTIND’ + The index of the next argument to be processed by the ‘getopts’ + builtin. + +‘PATH’ + A colon-separated list of directories in which the shell looks for + commands. A zero-length (null) directory name in the value of + ‘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 ‘bash’. A common value is + "/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin". + +‘PS1’ + The primary prompt string. The default value is ‘\s-\v\$ ’. *Note + Controlling the Prompt::, for the complete list of escape sequences + that are expanded before ‘PS1’ is displayed. + +‘PS2’ + The secondary prompt string. The default value is ‘> ’. ‘PS2’ is + expanded in the same way as ‘PS1’ before being displayed. + + +File: bash.info, Node: Bash Variables, Prev: Bourne Shell Variables, Up: Shell Variables + +5.2 Bash Variables +================== + +These variables are set or used by Bash, but other shells do not +normally treat them specially. + + A few variables used by Bash are described in different chapters: +variables for controlling the job control facilities (*note Job Control +Variables::). + +‘_’ + ($_, an underscore.) This has a number of meanings depending on + context. 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, it expands to the last + argument to the previous simple command executed in the foreground, + after expansion. It is also set to the full pathname used to + invoke each command executed and placed in the environment exported + to that command. When checking mail, $_ expands to the name of the + mail file. + +‘BASH’ + The full pathname used to execute the current instance of Bash. + +‘BASHOPTS’ + A colon-separated list of enabled shell options. Each word in the + list is a valid argument for the ‘-s’ option to the ‘shopt’ builtin + command (*note The Shopt Builtin::). The options appearing in + ‘BASHOPTS’ are those reported as ‘on’ by ‘shopt’. If this variable + is in the environment when Bash starts up, the shell enables each + option in the list before reading any startup files. If this + variable is exported, child shells will enable each option in the + list. This variable is readonly. + +‘BASHPID’ + Expands to the process ID of the current Bash process. This + differs from ‘$$’ under certain circumstances, such as subshells + that do not require Bash to be re-initialized. Assignments to + ‘BASHPID’ have no effect. If ‘BASHPID’ is unset, it loses its + special properties, even if it is subsequently reset. + +‘BASH_ALIASES’ + An associative array variable whose members correspond to the + internal list of aliases as maintained by the ‘alias’ builtin. + (*note Bourne Shell Builtins::). 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 ‘BASH_ALIASES’ is unset, it loses its special properties, even + if it is subsequently reset. + +‘BASH_ARGC’ + An array variable whose values are the number of parameters in each + frame of the current Bash execution call stack. The number of + parameters to the current subroutine (shell function or script + executed with ‘.’ or ‘source’) is at the top of the stack. When a + subroutine is executed, the number of parameters passed is pushed + onto ‘BASH_ARGC’. The shell sets ‘BASH_ARGC’ only when in extended + debugging mode (see *note The Shopt Builtin:: for a description of + the ‘extdebug’ option to the ‘shopt’ builtin). Setting ‘extdebug’ + after the shell has started to execute a subroutine, or referencing + this variable when ‘extdebug’ is not set, may result in + inconsistent values. Assignments to ‘BASH_ARGC’ have no effect, + and it may not be unset. + +‘BASH_ARGV’ + An array variable containing all of the parameters in the current + Bash 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 shell pushes the supplied parameters onto ‘BASH_ARGV’. The + shell sets ‘BASH_ARGV’ only when in extended debugging mode (see + *note The Shopt Builtin:: for a description of the ‘extdebug’ + option to the ‘shopt’ builtin). Setting ‘extdebug’ after the shell + has started to execute a script, or referencing this variable when + ‘extdebug’ is not set, may result in inconsistent values. + Assignments to ‘BASH_ARGV’ have no effect, and it may not be unset. + +‘BASH_ARGV0’ + When referenced, this variable expands to the name of the shell or + shell script (identical to ‘$0’; *Note Special Parameters::, for + the description of special parameter 0). Assigning a value to + ‘BASH_ARGV0’ sets ‘$0’ to the same value. If ‘BASH_ARGV0’ is + unset, it loses its special properties, even if it is subsequently + reset. + +‘BASH_CMDS’ + An associative array variable whose members correspond to the + internal hash table of commands as maintained by the ‘hash’ builtin + (*note Bourne Shell Builtins::). Adding elements to this array + makes them appear in the hash table; however, unsetting array + elements currently does not remove command names from the hash + table. If ‘BASH_CMDS’ is unset, it loses its special properties, + even if it is subsequently reset. + +‘BASH_COMMAND’ + Expands to 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 ‘BASH_COMMAND’ is unset, it loses its special + properties, even if it is subsequently reset. + +‘BASH_COMPAT’ + The value is used to set the shell's compatibility level. *Note + Shell Compatibility Mode::, 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 ‘BASH_COMPAT’ is unset or set to + the empty string, the compatibility level is set to the default for + the current version. If ‘BASH_COMPAT’ 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. A subset of the valid values correspond to + the compatibility levels described below (*note Shell Compatibility + Mode::). For example, 4.2 and 42 are valid values that correspond + to the ‘compat42’ ‘shopt’ option and set the compatibility level to + 42. The current version is also a valid value. + +‘BASH_ENV’ + If this variable is set when Bash is invoked to execute a shell + script, its value is expanded and used as the name of a startup + file to read before executing the script. Bash does not use ‘PATH’ + to search for the resultant filename. *Note Bash Startup Files::. + +‘BASH_EXECUTION_STRING’ + The command argument to the ‘-c’ invocation option. + +‘BASH_LINENO’ + An array variable whose members are the line numbers in source + files where each corresponding member of ‘FUNCNAME’ was invoked. + ‘${BASH_LINENO[$i]}’ is the line number in the source file + (‘${BASH_SOURCE[$i+1]}’) where ‘${FUNCNAME[$i]}’ was called (or + ‘${BASH_LINENO[$i-1]}’ if referenced within another shell + function). Use ‘LINENO’ to obtain the current line number. + Assignments to ‘BASH_LINENO’ have no effect, and it may not be + unset. + +‘BASH_LOADABLES_PATH’ + A colon-separated list of directories in which the ‘enable’ command + looks for dynamically loadable builtins. + +‘BASH_MONOSECONDS’ + Each time this variable is referenced, it expands to the value + returned by the system's monotonic clock, if one is available. If + there is no monotonic clock, this is equivalent to ‘EPOCHSECONDS’. + If ‘BASH_MONOSECONDS’ is unset, it loses its special properties, + even if it is subsequently reset. + +‘BASH_REMATCH’ + An array variable whose members are assigned by the ‘=~’ binary + operator to the ‘[[’ conditional command (*note Conditional + Constructs::). The element with index 0 is the portion of the + string matching the entire regular expression. The element with + index N is the portion of the string matching the Nth parenthesized + subexpression. + +‘BASH_SOURCE’ + An array variable whose members are the source filenames where the + corresponding shell function names in the ‘FUNCNAME’ array variable + are defined. The shell function ‘${FUNCNAME[$i]}’ is defined in + the file ‘${BASH_SOURCE[$i]}’ and called from + ‘${BASH_SOURCE[$i+1]}’ Assignments to ‘BASH_SOURCE’ have no effect, + and it may not be unset. + +‘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 ‘BASH_SUBSHELL’ is unset, it loses its special + properties, even if it is subsequently reset. + +‘BASH_TRAPSIG’ + Set to the signal number corresponding to the trap action being + executed during its execution. See the description of ‘trap’ + (*note Bourne Shell Builtins::) for information about signal + numbers and trap execution. + +‘BASH_VERSINFO’ + A readonly array variable (*note Arrays::) whose members hold + version information for this instance of Bash. The values assigned + to the array members are as follows: + + ‘BASH_VERSINFO[0]’ + The major version number (the “release”). + + ‘BASH_VERSINFO[1]’ + The minor version number (the “version”). + + ‘BASH_VERSINFO[2]’ + The patch level. + + ‘BASH_VERSINFO[3]’ + The build version. + + ‘BASH_VERSINFO[4]’ + The release status (e.g., ‘beta’). + + ‘BASH_VERSINFO[5]’ + The value of ‘MACHTYPE’. + +‘BASH_VERSION’ + Expands to a string describing the version of this instance of Bash + (e.g., 5.2.37(3)-release). + +‘BASH_XTRACEFD’ + If set to an integer corresponding to a valid file descriptor, Bash + writes the trace output generated when ‘set -x’ is enabled to that + file descriptor, instead of the standard error. This allows + tracing output to be separated from diagnostic and error messages. + The file descriptor is closed when ‘BASH_XTRACEFD’ is unset or + assigned a new value. Unsetting ‘BASH_XTRACEFD’ or assigning it + the empty string causes the trace output to be sent to the standard + error. Note that setting ‘BASH_XTRACEFD’ to 2 (the standard error + file descriptor) and then unsetting it will result in the standard + error being closed. + +‘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. + +‘COLUMNS’ + Used by the ‘select’ command to determine the terminal width when + printing selection lists. Automatically set if the ‘checkwinsize’ + option is enabled (*note The Shopt Builtin::), or in an interactive + shell upon receipt of a ‘SIGWINCH’. + +‘COMP_CWORD’ + An index into ‘${COMP_WORDS}’ of the word containing the current + cursor position. This variable is available only in shell + functions invoked by the programmable completion facilities (*note + Programmable Completion::). + +‘COMP_KEY’ + The key (or final key of a key sequence) used to invoke the current + completion function. This variable is available only in shell + functions and external commands invoked by the programmable + completion facilities (*note Programmable Completion::). + +‘COMP_LINE’ + The current command line. This variable is available only in shell + functions and external commands invoked by the programmable + completion facilities (*note Programmable Completion::). + +‘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 + ‘${#COMP_LINE}’. This variable is available only in shell + functions and external commands invoked by the programmable + completion facilities (*note Programmable Completion::). + +‘COMP_TYPE’ + Set to an integer value corresponding to the type of attempted + completion that caused a completion function to be called: , + for normal completion, ‘?’, for listing completions after + successive tabs, ‘!’, for listing alternatives on partial word + completion, ‘@’, to list completions if the word is not unmodified, + or ‘%’, for menu completion. This variable is available only in + shell functions and external commands invoked by the programmable + completion facilities (*note Programmable Completion::). + +‘COMP_WORDBREAKS’ + The set of characters that the Readline library treats as word + separators when performing word completion. If ‘COMP_WORDBREAKS’ + is unset, it loses its special properties, even if it is + subsequently reset. + +‘COMP_WORDS’ + An array variable consisting of the individual words in the current + command line. The line is split into words as Readline would split + it, using ‘COMP_WORDBREAKS’ as described above. This variable is + available only in shell functions invoked by the programmable + completion facilities (*note Programmable Completion::). + +‘COMPREPLY’ + An array variable from which Bash reads the possible completions + generated by a shell function invoked by the programmable + completion facility (*note Programmable Completion::). Each array + element contains one possible completion. + +‘COPROC’ + An array variable created to hold the file descriptors for output + from and input to an unnamed coprocess (*note Coprocesses::). + +‘DIRSTACK’ + An array variable containing the current contents of the directory + stack. Directories appear in the stack in the order they are + displayed by the ‘dirs’ builtin. Assigning to members of this + array variable may be used to modify directories already in the + stack, but the ‘pushd’ and ‘popd’ builtins must be used to add and + remove directories. Assigning to this variable does not change the + current directory. If ‘DIRSTACK’ is unset, it loses its special + properties, even if it is subsequently reset. + +‘EMACS’ + If Bash finds this variable in the environment when the shell + starts, and its value is ‘t’, Bash assumes that the shell is + running in an Emacs shell buffer and disables line editing. + +‘ENV’ + Expanded and executed similarly to ‘BASH_ENV’ (*note Bash Startup + Files::) when an interactive shell is invoked in POSIX mode (*note + Bash POSIX Mode::). + +‘EPOCHREALTIME’ + Each time this parameter is referenced, it expands to the number of + seconds since the Unix Epoch as a floating-point value with + micro-second granularity (see the documentation for the C library + function ‘time’ for the definition of Epoch). Assignments to + ‘EPOCHREALTIME’ are ignored. If ‘EPOCHREALTIME’ is unset, it loses + its special properties, even if it is subsequently reset. + +‘EPOCHSECONDS’ + Each time this parameter is referenced, it expands to the number of + seconds since the Unix Epoch (see the documentation for the C + library function ‘time’ for the definition of Epoch). Assignments + to ‘EPOCHSECONDS’ are ignored. If ‘EPOCHSECONDS’ is unset, it + loses its special properties, even if it is subsequently reset. + +‘EUID’ + The numeric effective user id of the current user. This variable + is readonly. + +‘EXECIGNORE’ + A colon-separated list of shell patterns (*note Pattern Matching::) + defining the set of filenames to be ignored by command search using + ‘PATH’. Files whose full pathnames match one of these patterns are + not considered executable files for the purposes of completion and + command execution via ‘PATH’ lookup. This does not affect the + behavior of the ‘[’, ‘test’, and ‘[[’ commands. Full pathnames in + the command hash table are not subject to ‘EXECIGNORE’. 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 ‘extglob’ shell option. + +‘FCEDIT’ + The editor used as a default by the ‘fc’ builtin command. + +‘FIGNORE’ + A colon-separated list of suffixes to ignore when performing + filename completion. A filename whose suffix matches one of the + entries in ‘FIGNORE’ is excluded from the list of matched + filenames. A sample value is ‘.o:~’ + +‘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 ‘"main"’. + This variable exists only when a shell function is executing. + Assignments to ‘FUNCNAME’ have no effect. If ‘FUNCNAME’ is unset, + it loses its special properties, even if it is subsequently reset. + + This variable can be used with ‘BASH_LINENO’ and ‘BASH_SOURCE’. + Each element of ‘FUNCNAME’ has corresponding elements in + ‘BASH_LINENO’ and ‘BASH_SOURCE’ to describe the call stack. For + instance, ‘${FUNCNAME[$i]}’ was called from the file + ‘${BASH_SOURCE[$i+1]}’ at line number ‘${BASH_LINENO[$i]}’. The + ‘caller’ builtin displays the current call stack using this + information. + +‘FUNCNEST’ + A numeric value greater than 0 defines a maximum function nesting + level. Function invocations that exceed this nesting level cause + the current command to abort. + +‘GLOBIGNORE’ + A colon-separated list of patterns defining the set of file names + to be ignored by filename expansion. If a file name matched by a + filename expansion pattern also matches one of the patterns in + ‘GLOBIGNORE’, it is removed from the list of matches. The pattern + matching honors the setting of the ‘extglob’ shell option. + +‘GLOBSORT’ + Controls how the results of filename expansion are sorted. The + value of this variable specifies the sort criteria and sort order + for the results of filename expansion. If this variable is unset + or set to the null string, filename expansion uses the historical + behavior of sorting by name, in ascending lexicographic order as + determined by the ‘LC_COLLATE’ shell variable. + + If set, a valid value begins with an optional ‘+’, which is + ignored, or ‘-’, which reverses the sort order from ascending to + descending, followed by a sort specifier. The valid sort + specifiers are ‘name’, ‘numeric’, ‘size’, ‘mtime’, ‘atime’, + ‘ctime’, and ‘blocks’, which sort the files on name, names in + numeric rather than lexicographic order, file size, modification + time, access time, inode change time, and number of blocks, + respectively. If any of the non-name keys compare as equal (e.g., + if two files are the same size), sorting uses the name as a + secondary sort key. + + For example, a value of ‘-mtime’ sorts the results in descending + order by modification time (newest first). + + The ‘numeric’ specifier treats names consisting solely of digits as + numbers and sorts them using their numeric value (so "2" sorts + before "10", for example). When using ‘numeric’, names containing + non-digits sort after all the all-digit names and are sorted by + name using the traditional behavior. + + A sort specifier of ‘nosort’ disables sorting completely; Bash + returns the results in the order they are read from the file + system, ignoring any leading ‘-’. + + If the sort specifier is missing, it defaults to NAME, so a value + of ‘+’ is equivalent to the null string, and a value of ‘-’ sorts + by name in descending order. + + Any invalid value restores the historical sorting behavior. + +‘GROUPS’ + An array variable containing the list of groups of which the + current user is a member. Assignments to ‘GROUPS’ have no effect. + If ‘GROUPS’ is unset, it loses its special properties, even if it + is subsequently reset. + +‘histchars’ + The two or three characters which control history expansion, quick + substitution, and tokenization (*note History Interaction::). The + first character is the “history expansion” character, the character + which begins a history expansion, normally ‘!’. The second + character is the “quick substitution” character, normally ‘^’. + When it appears as the first character on the line, history + substitution repeats the previous command, replacing one string + with another. The optional third character is the “history + comment” character, normally ‘#’, which indicates that the + remainder of the line is a comment when it appears as the first + character of a word. The history comment character disables + history substitution 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. + +‘HISTCMD’ + The history number, or index in the history list, of the current + command. Assignments to ‘HISTCMD’ have no effect. If ‘HISTCMD’ is + unset, it loses its special properties, even if it is subsequently + reset. + +‘HISTCONTROL’ + A colon-separated list of values controlling how commands are saved + on the history list. If the list of values includes ‘ignorespace’, + lines which begin with a space character are not saved in the + history list. A value of ‘ignoredups’ causes lines which match the + previous history entry not to be saved. A value of ‘ignoreboth’ is + shorthand for ‘ignorespace’ and ‘ignoredups’. A value of + ‘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 ‘HISTCONTROL’ is unset, + or does not include a valid value, Bash saves all lines read by the + shell parser on the history list, subject to the value of + ‘HISTIGNORE’. If the first line of a multi-line compound command + was saved, the second and subsequent lines are not tested, and are + added to the history regardless of the value of ‘HISTCONTROL’. If + the first line was not saved, the second and subsequent lines of + the command are not saved either. + +‘HISTFILE’ + The name of the file to which the command history is saved. Bash + assigns a default value of ‘~/.bash_history’. If ‘HISTFILE’ is + unset or null, the shell does not save the command history when it + exits. + +‘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 the number of history entries + that total no more than that number of lines by removing the oldest + entries. If the history list contains multi-line entries, the + history file may contain more lines than this maximum to avoid + leaving partial history entries. The history file is also + truncated to this size after writing it when a shell exits or by + the ‘history’ builtin. 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 ‘HISTSIZE’ after reading any startup files. + +‘HISTIGNORE’ + A colon-separated list of patterns used to decide which command + lines should be saved on the history list. If a command line + matches one of the patterns in the value of ‘HISTIGNORE’, it is not + saved on the history list. Each pattern is anchored at the + beginning of the line and must match the complete line (Bash does + not implicitly append a ‘*’). Each pattern is tested against the + line after the checks specified by ‘HISTCONTROL’ are applied. In + addition to the normal shell pattern matching characters, ‘&’ + matches the previous history line. A backslash escapes the ‘&’; + the backslash is removed before attempting a match. If the first + line of a multi-line compound command was saved, the second and + subsequent lines are not tested, and are added to the history + regardless of the value of ‘HISTIGNORE’. If the first line was not + saved, the second and subsequent lines of the command are not saved + either. The pattern matching honors the setting of the ‘extglob’ + shell option. + + ‘HISTIGNORE’ subsumes some of the function of ‘HISTCONTROL’. A + pattern of ‘&’ is identical to ‘ignoredups’, and a pattern of ‘[ + ]*’ is identical to ‘ignorespace’. Combining these two patterns, + separating them with a colon, provides the functionality of + ‘ignoreboth’. + +‘HISTSIZE’ + The maximum number of commands to remember on the history list. 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. + +‘HISTTIMEFORMAT’ + If this variable is set and not null, its value is used as a format + string for ‘strftime’(3) to print the time stamp associated with + each history entry displayed by the ‘history’ builtin. If this + variable is set, the shell writes time stamps 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. + +‘HOSTFILE’ + Contains the name of a file in the same format as ‘/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, Bash adds the contents of the new file + to the existing list. If ‘HOSTFILE’ is set, but has no value, or + does not name a readable file, Bash attempts to read ‘/etc/hosts’ + to obtain the list of possible hostname completions. When + ‘HOSTFILE’ is unset, Bash clears the hostname list. + +‘HOSTNAME’ + The name of the current host. + +‘HOSTTYPE’ + A string describing the machine Bash is running on. + +‘IGNOREEOF’ + Controls the action of the shell on receipt of an ‘EOF’ character + as the sole input. If set, the value is the number of consecutive + ‘EOF’ characters that can be read as the first character on an + input line before Bash exits. If the variable is set but does not + have a numeric value, or the value is null, then the default is 10. + If the variable is unset, then ‘EOF’ signifies the end of input to + the shell. This is only in effect for interactive shells. + +‘INPUTRC’ + The name of the Readline initialization file, overriding the + default of ‘~/.inputrc’. + +‘INSIDE_EMACS’ + If Bash finds this variable in the environment when the shell + starts, it assumes that the shell is running in an Emacs shell + buffer and may disable line editing depending on the value of + ‘TERM’. + +‘LANG’ + Used to determine the locale category for any category not + specifically selected with a variable starting with ‘LC_’. + +‘LC_ALL’ + This variable overrides the value of ‘LANG’ and any other ‘LC_’ + variable specifying a locale category. + +‘LC_COLLATE’ + This variable determines the collation order used when sorting the + results of filename expansion, and determines the behavior of range + expressions, equivalence classes, and collating sequences within + filename expansion and pattern matching (*note Filename + Expansion::). + +‘LC_CTYPE’ + This variable determines the interpretation of characters and the + behavior of character classes within filename expansion and pattern + matching (*note Filename Expansion::). + +‘LC_MESSAGES’ + This variable determines the locale used to translate double-quoted + strings preceded by a ‘$’ (*note Locale Translation::). + +‘LC_NUMERIC’ + This variable determines the locale category used for number + formatting. + +‘LC_TIME’ + This variable determines the locale category used for data and time + formatting. + +‘LINENO’ + The line number in the script or shell function currently + executing. Line numbers start with 1. When not in a script or + function, the value is not guaranteed to be meaningful. If + ‘LINENO’ is unset, it loses its special properties, even if it is + subsequently reset. + +‘LINES’ + Used by the ‘select’ command to determine the column length for + printing selection lists. Automatically set if the ‘checkwinsize’ + option is enabled (*note The Shopt Builtin::), or in an interactive + shell upon receipt of a ‘SIGWINCH’. + +‘MACHTYPE’ + A string that fully describes the system type on which Bash is + executing, in the standard GNU CPU-COMPANY-SYSTEM format. + +‘MAILCHECK’ + How often (in seconds) that the shell should check for mail in the + files specified in the ‘MAILPATH’ or ‘MAIL’ variables. 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. + +‘MAPFILE’ + An array variable created to hold the text read by the ‘mapfile’ + builtin when no variable name is supplied. + +‘OLDPWD’ + The previous working directory as set by the ‘cd’ builtin. + +‘OPTERR’ + If set to the value 1, Bash displays error messages generated by + the ‘getopts’ builtin command. ‘OPTERR’ is initialized to 1 each + time the shell is invoked. + +‘OSTYPE’ + A string describing the operating system Bash is running on. + +‘PIPESTATUS’ + An array variable (*note Arrays::) containing a list of exit status + values from the commands in the most-recently-executed foreground + pipeline, which may consist of only a simple command (*note Shell + Commands::). Bash sets ‘PIPESTATUS’ after executing multi-element + pipelines, timed and negated pipelines, simple commands, subshells + created with the ‘(’ operator, the ‘[[’ and ‘((’ compound commands, + and after error conditions that result in the shell aborting + command execution. + +‘POSIXLY_CORRECT’ + If this variable is in the environment when Bash starts, the shell + enters POSIX mode (*note Bash POSIX Mode::) before reading the + startup files, as if the ‘--posix’ invocation option had been + supplied. If it is set while the shell is running, Bash enables + POSIX mode, as if the command + set -o posix + had been executed. When the shell enters POSIX mode, it sets this + variable if it was not already set. + +‘PPID’ + The process ID of the shell's parent process. This variable is + readonly. + +‘PROMPT_COMMAND’ + If this variable is set, and is an array, the value of each set + element is interpreted as a command to execute before printing the + primary prompt (‘$PS1’). If this is set but not an array variable, + its value is used as a command to execute instead. + +‘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 ‘\w’ and ‘\W’ prompt string escapes (*note Controlling the + Prompt::). Characters removed are replaced with an ellipsis. + +‘PS0’ + The value of this parameter is expanded like ‘PS1’ and displayed by + interactive shells after reading a command and before the command + is executed. + +‘PS3’ + The value of this variable is used as the prompt for the ‘select’ + command. If this variable is not set, the ‘select’ command prompts + with ‘#? ’ + +‘PS4’ + The value of this parameter is expanded like ‘PS1’ and the expanded + value is the prompt printed before the command line is echoed when + the ‘-x’ option is set (*note The Set Builtin::). The first + character of the expanded value is replicated multiple times, as + necessary, to indicate multiple levels of indirection. The default + is ‘+ ’. + +‘PWD’ + The current working directory as set by the ‘cd’ builtin. + +‘RANDOM’ + Each time this parameter is referenced, it expands to a random + integer between 0 and 32767. Assigning a value to ‘RANDOM’ + initializes (seeds) the sequence of random numbers. Seeding the + random number generator with the same constant value produces the + same sequence of values. If ‘RANDOM’ is unset, it loses its + special properties, even if it is subsequently reset. + +‘READLINE_ARGUMENT’ + Any numeric argument given to a Readline command that was defined + using ‘bind -x’ (*note Bash Builtins::) when it was invoked. + +‘READLINE_LINE’ + The contents of the Readline line buffer, for use with ‘bind -x’ + (*note Bash Builtins::). + +‘READLINE_MARK’ + The position of the “mark” (saved insertion point) in the Readline + line buffer, for use with ‘bind -x’ (*note Bash Builtins::). The + characters between the insertion point and the mark are often + called the “region”. + +‘READLINE_POINT’ + The position of the insertion point in the Readline line buffer, + for use with ‘bind -x’ (*note Bash Builtins::). + +‘REPLY’ + The default variable for the ‘read’ builtin; set to the line read + when ‘read’ is not supplied a variable name argument. + +‘SECONDS’ + This variable expands to the number of seconds since the shell was + started. Assignment to this variable resets the count to the value + assigned, and the expanded value becomes the value assigned plus + the number of seconds since the assignment. The number of seconds + at shell invocation and the current time are always determined by + querying the system clock at one-second resolution. If ‘SECONDS’ + is unset, it loses its special properties, even if it is + subsequently reset. + +‘SHELL’ + This environment variable expands to the full pathname to the + shell. If it is not set when the shell starts, Bash assigns to it + the full pathname of the current user's login shell. + +‘SHELLOPTS’ + A colon-separated list of enabled shell options. Each word in the + list is a valid argument for the ‘-o’ option to the ‘set’ builtin + command (*note The Set Builtin::). The options appearing in + ‘SHELLOPTS’ are those reported as ‘on’ by ‘set -o’. If this + variable is in the environment when Bash starts up, the shell + enables each option in the list before reading any startup files. + If this variable is exported, child shells will enable each option + in the list. This variable is readonly. + +‘SHLVL’ + Incremented by one each time a new instance of Bash is started. + This is intended to be a count of how deeply your Bash shells are + nested. + +‘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 ‘/dev/urandom’ or ‘arc4random’, 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 ‘SRANDOM’ is unset, it loses its + special properties, even if it is subsequently reset. + +‘TIMEFORMAT’ + The value of this parameter is used as a format string specifying + how the timing information for pipelines prefixed with the ‘time’ + reserved word should be displayed. The ‘%’ 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 brackets denote optional portions. + + ‘%%’ + A literal ‘%’. + + ‘%[P][l]R’ + The elapsed time in seconds. + + ‘%[P][l]U’ + The number of CPU seconds spent in user mode. + + ‘%[P][l]S’ + The number of CPU seconds spent in system mode. + + ‘%P’ + The CPU percentage, computed as (%U + %S) / %R. + + The optional P is a digit specifying the precision, the number of + fractional digits after a decimal point. A value of 0 causes no + decimal point or fraction to be output. ‘time’ prints at most six + digits after the decimal point; values of P greater than 6 are + changed to 6. If P is not specified, ‘time’ prints three digits + after the decimal point. + + The optional ‘l’ specifies a longer format, including minutes, of + the form MMmSS.FFs. The value of P determines whether or not the + fraction is included. + + If this variable is not set, Bash acts as if it had the value + $'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS' + If the value is null, Bash does not display any timing information. + A trailing newline is added when the format string is displayed. + +‘TMOUT’ + If set to a value greater than zero, the ‘read’ builtin uses the + value as its default timeout (*note Bash Builtins::). The ‘select’ + command (*note Conditional Constructs::) terminates if input does + not arrive after ‘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. Bash terminates after waiting for that number of seconds + if a complete line of input does not arrive. + +‘TMPDIR’ + If set, Bash uses its value as the name of a directory in which + Bash creates temporary files for the shell's use. + +‘UID’ + The numeric real user id of the current user. This variable is + readonly. + + +File: bash.info, Node: Bash Features, Next: Job Control, Prev: Shell Variables, Up: Top + +6 Bash Features +*************** + +This chapter describes features unique to Bash. + +* Menu: + +* Invoking Bash:: Command line options that you can give + to Bash. +* Bash Startup Files:: When and how Bash executes scripts. +* Interactive Shells:: What an interactive shell is. +* Bash Conditional Expressions:: Primitives used in composing expressions for + the ‘test’ builtin. +* Shell Arithmetic:: Arithmetic on shell variables. +* Aliases:: Substituting one command for another. +* Arrays:: Array Variables. +* The Directory Stack:: History of visited directories. +* Controlling the Prompt:: Customizing the various prompt strings. +* The Restricted Shell:: A more controlled mode of shell execution. +* Bash POSIX Mode:: Making Bash behave more closely to what + the POSIX standard specifies. +* Shell Compatibility Mode:: How Bash supports behavior that was present + in earlier versions and has changed. + + +File: bash.info, Node: Invoking Bash, Next: Bash Startup Files, Up: Bash Features + +6.1 Invoking Bash +================= + + bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o OPTION] + [-O SHOPT_OPTION] [ARGUMENT ...] + bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o OPTION] + [-O SHOPT_OPTION] -c STRING [ARGUMENT ...] + bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o OPTION] + [-O SHOPT_OPTION] [ARGUMENT ...] + + All of the single-character options used with the ‘set’ builtin +(*note The Set Builtin::) can be used as options when the shell is +invoked. In addition, there are several multi-character options that +you can use. These options must appear on the command line before the +single-character options to be recognized. + +‘--debugger’ + Arrange for the debugger profile to be executed before the shell + starts. Turns on extended debugging mode (see *note The Shopt + Builtin:: for a description of the ‘extdebug’ option to the ‘shopt’ + builtin). + +‘--dump-po-strings’ + Print a list of all double-quoted strings preceded by ‘$’ on the + standard output in the GNU ‘gettext’ PO (portable object) file + format. Equivalent to ‘-D’ except for the output format. + +‘--dump-strings’ + Equivalent to ‘-D’. + +‘--help’ + Display a usage message on standard output and exit successfully. + +‘--init-file FILENAME’ +‘--rcfile FILENAME’ + Execute commands from FILENAME (instead of ‘~/.bashrc’) in an + interactive shell. + +‘--login’ + Equivalent to ‘-l’. + +‘--noediting’ + Do not use the GNU Readline library (*note Command Line Editing::) + to read command lines when the shell is interactive. + +‘--noprofile’ + Don't load the system-wide startup file ‘/etc/profile’ or any of + the personal initialization files ‘~/.bash_profile’, + ‘~/.bash_login’, or ‘~/.profile’ when Bash is invoked as a login + shell. + +‘--norc’ + Don't read the ‘~/.bashrc’ initialization file in an interactive + shell. This is on by default if the shell is invoked as ‘sh’. + +‘--posix’ + Enable POSIX mode; change the behavior of Bash where the default + operation differs from the POSIX standard to match the standard. + This is intended to make Bash behave as a strict superset of that + standard. *Note Bash POSIX Mode::, for a description of the Bash + POSIX mode. + +‘--restricted’ + Equivalent to ‘-r’. Make the shell a restricted shell (*note The + Restricted Shell::). + +‘--verbose’ + Equivalent to ‘-v’. Print shell input lines as they're read. + +‘--version’ + Show version information for this instance of Bash on the standard + output and exit successfully. + + There are several single-character options that may be supplied at +invocation which are not available with the ‘set’ builtin. + +‘-c’ + Read and execute commands from the first non-option argument + COMMAND_STRING, then exit. If there are arguments after the + COMMAND_STRING, the first argument is assigned to ‘$0’ and any + remaining arguments are assigned to the positional parameters. The + assignment to ‘$0’ sets the name of the shell, which is used in + warning and error messages. + +‘-i’ + Force the shell to run interactively. Interactive shells are + described in *note Interactive Shells::. + +‘-l’ + Make this shell act as if it had been directly invoked by login. + When the shell is interactive, this is equivalent to starting a + login shell with ‘exec -l bash’. When the shell is not + interactive, it will read and execute the login shell startup + files. ‘exec bash -l’ or ‘exec bash --login’ will replace the + current shell with a Bash login shell. *Note Bash Startup Files::, + for a description of the special behavior of a login shell. + +‘-r’ + Make the shell a restricted shell (*note The Restricted Shell::). + +‘-s’ + If this option is present, or if no arguments remain after option + processing, then Bash reads commands 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. + +‘-D’ + Print a list of all double-quoted strings preceded by ‘$’ on the + standard output. These are the strings that are subject to + language translation when the current locale is not ‘C’ or ‘POSIX’ + (*note Locale Translation::). This implies the ‘-n’ option; no + commands will be executed. + +‘[-+]O [SHOPT_OPTION]’ + SHOPT_OPTION is one of the shell options accepted by the ‘shopt’ + builtin (*note The Shopt Builtin::). If SHOPT_OPTION is present, + ‘-O’ sets the value of that option; ‘+O’ unsets it. If + SHOPT_OPTION is not supplied, Bash prints the names and values of + the shell options accepted by ‘shopt’ on the standard output. If + the invocation option is ‘+O’, the output is displayed in a format + that may be reused as input. + +‘--’ + A ‘--’ signals the end of options and disables further option + processing. Any arguments after the ‘--’ are treated as a shell + script filename (*note Shell Scripts::) and arguments passed to + that script. + +‘-’ + Equivalent to ‘--’. + + A “login shell” is one whose first character of argument zero is ‘-’, +or one invoked with the ‘--login’ option. + + An “interactive shell” is one started without non-option arguments, +unless ‘-s’ is specified, without specifying the ‘-c’ option, and whose +standard input and standard error are both connected to terminals (as +determined by isatty(3)), or one started with the ‘-i’ option. *Note +Interactive Shells::, for more information. + + If arguments remain after option processing, and neither the ‘-c’ nor +the ‘-s’ option has been supplied, the first argument is treated as the +name of a file containing shell commands (*note Shell Scripts::). When +Bash is invoked in this fashion, ‘$0’ is set to the name of the file, +and the positional parameters are set to the remaining arguments. Bash +reads and executes commands from this file, then exits. Bash'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. Bash first attempts +to open the file in the current directory, and, if no file is found, +searches the directories in ‘PATH’ for the script. + + +File: bash.info, Node: Bash Startup Files, Next: Interactive Shells, Prev: Invoking Bash, Up: Bash Features + +6.2 Bash Startup Files +====================== + +This section describes how Bash executes its startup files. If any of +the files exist but cannot be read, Bash reports an error. Tildes are +expanded in filenames as described above under Tilde Expansion (*note +Tilde Expansion::). + + Interactive shells are described in *note Interactive Shells::. + +Invoked as an interactive login shell, or with ‘--login’ +........................................................ + +When Bash is invoked as an interactive login shell, or as a +non-interactive shell with the ‘--login’ option, it first reads and +executes commands from the file ‘/etc/profile’, if that file exists. +After reading that file, it looks for ‘~/.bash_profile’, +‘~/.bash_login’, and ‘~/.profile’, in that order, and reads and executes +commands from the first one that exists and is readable. The +‘--noprofile’ option inhibits this behavior. + + When an interactive login shell exits, or a non-interactive login +shell executes the ‘exit’ builtin command, Bash reads and executes +commands from the file ‘~/.bash_logout’, if it exists. + +Invoked as an interactive non-login shell +......................................... + +When Bash runs as an interactive shell that is not a login shell, it +reads and executes commands from ‘~/.bashrc’, if that file exists. The +‘--norc’ option inhibits this behavior. The ‘--rcfile FILE’ option +causes Bash to use FILE instead of ‘~/.bashrc’. + + So, typically, your ‘~/.bash_profile’ contains the line + if [ -f ~/.bashrc ]; then . ~/.bashrc; fi +after (or before) any login-specific initializations. + +Invoked non-interactively +......................... + +When Bash is started non-interactively, to run a shell script, for +example, it looks for the variable ‘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. Bash behaves as if the +following command were executed: + if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi +but does not the value of the ‘PATH’ variable to search for the +filename. + + As noted above, if a non-interactive shell is invoked with the +‘--login’ option, Bash attempts to read and execute commands from the +login shell startup files. + +Invoked with name ‘sh’ +...................... + +If Bash is invoked with the name ‘sh’, it tries to mimic the startup +behavior of historical versions of ‘sh’ as closely as possible, while +conforming to the POSIX standard as well. + + When invoked as an interactive login shell, or as a non-interactive +shell with the ‘--login’ option, it first attempts to read and execute +commands from ‘/etc/profile’ and ‘~/.profile’, in that order. The +‘--noprofile’ option inhibits this behavior. + + When invoked as an interactive shell with the name ‘sh’, Bash looks +for the variable ‘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 ‘sh’ does not attempt to read and execute commands from any +other startup files, the ‘--rcfile’ option has no effect. + + A non-interactive shell invoked with the name ‘sh’ does not attempt +to read any other startup files. + + When invoked as ‘sh’, Bash enters POSIX mode after reading the +startup files. + +Invoked in POSIX mode +..................... + +When Bash is started in POSIX mode, as with the ‘--posix’ command line +option, it follows the POSIX standard for startup files. In this mode, +interactive shells expand the ‘ENV’ variable and read and execute +commands from the file whose name is the expanded value. No other +startup files are read. + +Invoked by remote shell daemon +.............................. + +Bash attempts to determine when it is being run with its standard input +connected to a network connection, as when executed by the historical +and rarely-seen remote shell daemon, usually ‘rshd’, or the secure shell +daemon ‘sshd’. If Bash determines it is being run non-interactively in +this fashion, it reads and executes commands from ‘~/.bashrc’, if that +file exists and is readable. Bash does not read this file if invoked as +‘sh’. The ‘--norc’ option inhibits this behavior, and the ‘--rcfile’ +option makes Bash use a different file instead of ‘~/.bashrc’, but +neither ‘rshd’ nor ‘sshd’ generally invoke the shell with those options +or allow them to be specified. + +Invoked with unequal effective and real UID/GIDs +................................................ + +If Bash is started with the effective user (group) id not equal to the +real user (group) id, and the ‘-p’ option is not supplied, no startup +files are read, shell functions are not inherited from the environment, +the ‘SHELLOPTS’, ‘BASHOPTS’, ‘CDPATH’, and ‘GLOBIGNORE’ variables, if +they appear in the environment, are ignored, and the effective user id +is set to the real user id. If the ‘-p’ option is supplied at +invocation, the startup behavior is the same, but the effective user id +is not reset. + + +File: bash.info, Node: Interactive Shells, Next: Bash Conditional Expressions, Prev: Bash Startup Files, Up: Bash Features + +6.3 Interactive Shells +====================== + +* Menu: + +* What is an Interactive Shell?:: What determines whether a shell is Interactive. +* Is this Shell Interactive?:: How to tell if a shell is interactive. +* Interactive Shell Behavior:: What changes in an interactive shell? + + +File: bash.info, Node: What is an Interactive Shell?, Next: Is this Shell Interactive?, Up: Interactive Shells + +6.3.1 What is an Interactive Shell? +----------------------------------- + +An interactive shell is one started without non-option arguments (unless +‘-s’ is specified) and without specifying the ‘-c’ option, whose input +and error output are both connected to terminals (as determined by +‘isatty(3)’), or one started with the ‘-i’ option. + + An interactive shell generally reads from and writes to a user's +terminal. + + The ‘-s’ invocation option may be used to set the positional +parameters when an interactive shell starts. + + +File: bash.info, Node: Is this Shell Interactive?, Next: Interactive Shell Behavior, Prev: What is an Interactive Shell?, Up: Interactive Shells + +6.3.2 Is this Shell Interactive? +-------------------------------- + +To determine within a startup script whether or not Bash is running +interactively, test the value of the ‘-’ special parameter. It contains +‘i’ when the shell is interactive. For example: + + case "$-" in + *i*) echo This shell is interactive ;; + *) echo This shell is not interactive ;; + esac + + Alternatively, startup scripts may examine the variable ‘PS1’; it is +unset in non-interactive shells, and set in interactive shells. Thus: + + if [ -z "$PS1" ]; then + echo This shell is not interactive + else + echo This shell is interactive + fi + + +File: bash.info, Node: Interactive Shell Behavior, Prev: Is this Shell Interactive?, Up: Interactive Shells + +6.3.3 Interactive Shell Behavior +-------------------------------- + +When the shell is running interactively, it changes its behavior in +several ways. + + 1. Bash reads and executes startup files as described in *note Bash + Startup Files::. + + 2. Job Control (*note Job Control::) is enabled by default. When job + control is in effect, Bash ignores the keyboard-generated job + control signals ‘SIGTTIN’, ‘SIGTTOU’, and ‘SIGTSTP’. + + 3. Bash executes the values of the set elements of the + ‘PROMPT_COMMAND’ array variable as commands before printing the + primary prompt, ‘$PS1’ (*note Bash Variables::). + + 4. Bash expands and displays ‘PS1’ before reading the first line of a + command, and expands and displays ‘PS2’ before reading the second + and subsequent lines of a multi-line command. Bash expands and + displays ‘PS0’ after it reads a command but before executing it. + See *note Controlling the Prompt::, for a complete list of prompt + string escape sequences. + + 5. Bash uses Readline (*note Command Line Editing::) to read commands + from the user's terminal. + + 6. Bash inspects the value of the ‘ignoreeof’ option to ‘set -o’ + instead of exiting immediately when it receives an ‘EOF’ on its + standard input when reading a command (*note The Set Builtin::). + + 7. Bash enables Command history (*note Bash History Facilities::) and + history expansion (*note History Interaction::) by default. When a + shell with history enabled exits, Bash saves the command history to + the file named by ‘$HISTFILE’. + + 8. Alias expansion (*note Aliases::) is performed by default. + + 9. In the absence of any traps, Bash ignores ‘SIGTERM’ (*note + Signals::). + + 10. In the absence of any traps, ‘SIGINT’ is caught and handled (*note + Signals::). ‘SIGINT’ will interrupt some shell builtins. + + 11. An interactive login shell sends a ‘SIGHUP’ to all jobs on exit if + the ‘huponexit’ shell option has been enabled (*note Signals::). + + 12. The ‘-n’ option has no effect, whether at invocation or when using + ‘set -n’ (*note The Set Builtin::). + + 13. Bash will check for mail periodically, depending on the values of + the ‘MAIL’, ‘MAILPATH’, and ‘MAILCHECK’ shell variables (*note Bash + Variables::). + + 14. The shell will not exit on expansion errors due to references to + unbound shell variables after ‘set -u’ has been enabled (*note The + Set Builtin::). + + 15. The shell will not exit on expansion errors caused by VAR being + unset or null in ‘${VAR:?WORD}’ expansions (*note Shell Parameter + Expansion::). + + 16. Redirection errors encountered by shell builtins will not cause + the shell to exit. + + 17. When running in POSIX mode, a special builtin returning an error + status will not cause the shell to exit (*note Bash POSIX Mode::). + + 18. A failed ‘exec’ will not cause the shell to exit (*note Bourne + Shell Builtins::). + + 19. Parser syntax errors will not cause the shell to exit. + + 20. If the ‘cdspell’ shell option is enabled, the shell will attempt + simple spelling correction for directory arguments to the ‘cd’ + builtin (see the description of the ‘cdspell’ option to the ‘shopt’ + builtin in *note The Shopt Builtin::). The ‘cdspell’ option is + only effective in interactive shells. + + 21. The shell will check the value of the ‘TMOUT’ variable and exit if + a command is not read within the specified number of seconds after + printing ‘$PS1’ (*note Bash Variables::). + + +File: bash.info, Node: Bash Conditional Expressions, Next: Shell Arithmetic, Prev: Interactive Shells, Up: Bash Features + +6.4 Bash Conditional Expressions +================================ + +Conditional expressions are used by the ‘[[’ compound command (*note +Conditional Constructs::) and the ‘test’ and ‘[’ builtin commands (*note +Bourne Shell Builtins::). The ‘test’ and ‘[’ commands determine their +behavior based on the number of arguments; see the descriptions of those +commands for any other command-specific actions. + + Expressions may be unary or binary, and are formed from the primaries +listed below. Unary expressions are often used to examine the status of +a file or shell variable. Binary operators are used for string, +numeric, and file attribute comparisons. + + Bash handles several filenames specially when they are used in +expressions. If the operating system on which Bash is running provides +these special files, Bash uses them; otherwise it emulates them +internally with this behavior: If the FILE argument to one of the +primaries is of the form ‘/dev/fd/N’, then Bash checks file descriptor +N. If the FILE argument to one of the primaries is one of ‘/dev/stdin’, +‘/dev/stdout’, or ‘/dev/stderr’, Bash checks file descriptor 0, 1, or 2, +respectively. + + When used with ‘[[’, the ‘<’ and ‘>’ operators sort lexicographically +using the current locale. The ‘test’ command uses ASCII ordering. + + Unless otherwise specified, primaries that operate on files follow +symbolic links and operate on the target of the link, rather than the +link itself. + +‘-a FILE’ + True if FILE exists. + +‘-b FILE’ + True if FILE exists and is a block special file. + +‘-c FILE’ + True if FILE exists and is a character special file. + +‘-d FILE’ + True if FILE exists and is a directory. + +‘-e FILE’ + True if FILE exists. + +‘-f FILE’ + True if FILE exists and is a regular file. + +‘-g FILE’ + True if FILE exists and its set-group-id bit is set. + +‘-h FILE’ + True if FILE exists and is a symbolic link. + +‘-k FILE’ + True if FILE exists and its "sticky" bit is set. + +‘-p FILE’ + True if FILE exists and is a named pipe (FIFO). + +‘-r FILE’ + True if FILE exists and is readable. + +‘-s FILE’ + True if FILE exists and has a size greater than zero. + +‘-t FD’ + True if file descriptor FD is open and refers to a terminal. + +‘-u FILE’ + True if FILE exists and its set-user-id bit is set. + +‘-w FILE’ + True if FILE exists and is writable. + +‘-x FILE’ + True if FILE exists and is executable. + +‘-G FILE’ + True if FILE exists and is owned by the effective group id. + +‘-L FILE’ + True if FILE exists and is a symbolic link. + +‘-N FILE’ + True if FILE exists and has been modified since it was last + accessed. + +‘-O FILE’ + True if FILE exists and is owned by the effective user id. + +‘-S FILE’ + True if FILE exists and is a socket. + +‘FILE1 -ef FILE2’ + True if FILE1 and FILE2 refer to the same device and inode numbers. + +‘FILE1 -nt FILE2’ + True if FILE1 is newer (according to modification date) than FILE2, + or if FILE1 exists and FILE2 does not. + +‘FILE1 -ot FILE2’ + True if FILE1 is older than FILE2, or if FILE2 exists and FILE1 + does not. + +‘-o OPTNAME’ + True if the shell option OPTNAME is enabled. The list of options + appears in the description of the ‘-o’ option to the ‘set’ builtin + (*note The Set Builtin::). + +‘-v VARNAME’ + True if the shell variable VARNAME is set (has been assigned a + value). If VARNAME is an indexed array variable name subscripted + by ‘@’ or ‘*’, this returns true if the array has any set elements. + If VARNAME is an associative array variable name subscripted by ‘@’ + or ‘*’, this returns true if an element with that key is set. + +‘-R VARNAME’ + True if the shell variable VARNAME is set and is a name reference. + +‘-z STRING’ + True if the length of STRING is zero. + +‘-n STRING’ +‘STRING’ + True if the length of STRING is non-zero. + +‘STRING1 == STRING2’ +‘STRING1 = STRING2’ + True if the strings are equal. When used with the ‘[[’ command, + this performs pattern matching as described above (*note + Conditional Constructs::). + + ‘=’ should be used with the ‘test’ command for POSIX conformance. + +‘STRING1 != STRING2’ + True if the strings are not equal. + +‘STRING1 < STRING2’ + True if STRING1 sorts before STRING2 lexicographically. + +‘STRING1 > STRING2’ + True if STRING1 sorts after STRING2 lexicographically. + +‘ARG1 OP ARG2’ + ‘OP’ is one of ‘-eq’, ‘-ne’, ‘-lt’, ‘-le’, ‘-gt’, or ‘-ge’. These + arithmetic binary operators return true if ARG1 is equal to, not + equal to, less than, less than or equal to, greater than, or + greater than or equal to ARG2, respectively. ARG1 and ARG2 may be + positive or negative integers. When used with the ‘[[’ command, + ARG1 and ARG2 are evaluated as arithmetic expressions (*note Shell + Arithmetic::). Since the expansions the ‘[[’ command performs on + ARG1 and ARG2 can potentially result in empty strings, arithmetic + expression evaluation treats those as expressions that evaluate to + 0. + + +File: bash.info, Node: Shell Arithmetic, Next: Aliases, Prev: Bash Conditional Expressions, Up: Bash Features + +6.5 Shell Arithmetic +==================== + +The shell allows arithmetic expressions to be evaluated, as one of the +shell expansions or by using the ‘((’ compound command, the ‘let’ and +‘declare’ builtins, the arithmetic ‘for’ command, the ‘[[’ conditional +command, or the ‘-i’ option to the ‘declare’ builtin. + + Evaluation is done in the largest fixed-width integers available, +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. + +‘ID++ ID--’ + variable post-increment and post-decrement + +‘++ID --ID’ + variable pre-increment and pre-decrement + +‘- +’ + unary minus and plus + +‘! ~’ + logical and bitwise negation + +‘**’ + exponentiation + +‘* / %’ + multiplication, division, remainder + +‘+ -’ + addition, subtraction + +‘<< >>’ + left and right bitwise shifts + +‘<= >= < >’ + comparison + +‘== !=’ + equality and inequality + +‘&’ + bitwise AND + +‘^’ + bitwise exclusive OR + +‘|’ + bitwise OR + +‘&&’ + logical AND + +‘||’ + logical OR + +‘expr ? if-true-expr : if-false-expr’ + conditional operator + +‘= *= /= %= += -= <<= >>= &= ^= |=’ + assignment + +‘expr1 , expr2’ + comma + + 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. This means you can use X, where X is a +shell variable name, in an arithmetic expression, and the shell will +evaluate its value as an expression and use the result. A shell +variable that is null or unset evaluates to 0 when referenced by name in +an expression. + + The value of a variable is evaluated as an arithmetic expression when +it is referenced, or when a variable which has been given the ‘integer’ +attribute using ‘declare -i’ is assigned a value. A null value +evaluates to 0. A shell variable need not have its ‘integer’ attribute +enabled to be used in an expression. + + 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 [BASE‘#’]N, where the optional BASE is a decimal +number between 2 and 64 representing the arithmetic base, and N is a +number in that base. If BASE‘#’ is omitted, then base 10 is used. When +specifying N, 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 BASE is less than or equal to 36, lowercase and +uppercase letters may be used interchangeably to represent numbers +between 10 and 35. + + Operators are evaluated in precedence order. Sub-expressions in +parentheses are evaluated first and may override the precedence rules +above. + + +File: bash.info, Node: Aliases, Next: Arrays, Prev: Shell Arithmetic, Up: Bash Features + +6.6 Aliases +=========== + +“Aliases” allow a string to be substituted for a word that is in a +position in the input where it can be the first word of a simple +command. Aliases have names and corresponding values that are set and +unset using the ‘alias’ and ‘unalias’ builtin commands (*note Shell +Builtin Commands::). + + If the shell reads an unquoted word in the right position, it checks +the word to see if it matches an alias name. If it matches, the shell +replaces the word with the alias value, and reads that value as if it +had been read instead of the word. The shell doesn't look at any +characters following the word before attempting alias substitution. + + The characters ‘/’, ‘$’, ‘`’, ‘=’ and any of the shell metacharacters +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 ‘ls’ to ‘"ls +-F"’, for instance, and Bash does not try to recursively expand the +replacement text. + + If the last character of the alias value is a ‘blank’, then the shell +checks the next command word following the alias for alias expansion. + + Aliases are created and listed with the ‘alias’ command, and removed +with the ‘unalias’ command. + + There is no mechanism for using arguments in the replacement text, as +in ‘csh’. If arguments are needed, use a shell function (*note Shell +Functions::) instead. + + Aliases are not expanded when the shell is not interactive, unless +the ‘expand_aliases’ shell option is set using ‘shopt’ (*note The Shopt +Builtin::). + + The rules concerning the definition and use of aliases are somewhat +confusing. 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 shell reads the next line of input, and an alias +definition in a compound command does not take effect until the shell +parses and executes the entire compound command. The commands following +the alias definition on that line, or in the rest of a compound command, +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 +‘alias’ in compound commands. + + For almost every purpose, shell functions are preferable to aliases. + + +File: bash.info, Node: Arrays, Next: The Directory Stack, Prev: Aliases, Up: Bash Features + +6.7 Arrays +========== + +Bash provides one-dimensional indexed and associative array variables. +Any variable may be used as an indexed array; the ‘declare’ builtin +explicitly declares 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 arithmetic +expressions that must expand to an integer (*note Shell Arithmetic::)) +and are zero-based; associative arrays use arbitrary strings. Unless +otherwise noted, indexed array indices must be non-negative integers. + + The shell performs parameter and variable expansion, arithmetic +expansion, command substitution, and quote removal on indexed array +subscripts. Since this can potentially result in empty strings, +subscript indexing treats those as expressions that evaluate to 0. + + The shell performs tilde expansion, parameter and variable expansion, +arithmetic expansion, command substitution, and quote removal on +associative array subscripts. Empty strings cannot be used as +associative array keys. + + Bash automatically creates an indexed array if any variable is +assigned to using the syntax + NAME[SUBSCRIPT]=VALUE + +The SUBSCRIPT is treated as an arithmetic expression that must evaluate +to a number greater than or equal to zero. To explicitly declare an +indexed array, use + declare -a NAME +(*note Bash Builtins::). The syntax + declare -a NAME[SUBSCRIPT] +is also accepted; the SUBSCRIPT is ignored. + +Associative arrays are created using + declare -A NAME + + Attributes may be specified for an array variable using the ‘declare’ +and ‘readonly’ builtins. Each attribute applies to all members of an +array. + + Arrays are assigned using compound assignments of the form + NAME=(VALUE1 VALUE2 ... ) +where each VALUE may be of the form ‘[SUBSCRIPT]=’STRING. Indexed array +assignments do not require anything but STRING. + + Each VALUE in the list undergoes the shell expansions described above +(*note Shell Expansions::), but VALUEs that are valid variable +assignments including the brackets and subscript do not undergo brace +expansion and word splitting, as with individual variable assignments. + + When assigning to indexed arrays, if the optional subscript is +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. + + 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: NAME=(KEY1 VALUE1 KEY2 VALUE2 ... ). These +are treated identically to NAME=( [KEY1]=VALUE1 [KEY2]=VALUE2 ... ). +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. + + This syntax is also accepted by the ‘declare’ builtin. Individual +array elements may be assigned to using the ‘NAME[SUBSCRIPT]=VALUE’ +syntax introduced above. + + When assigning to an indexed array, if NAME is subscripted by a +negative number, that number is interpreted as relative to one greater +than the maximum index of NAME, so negative indices count back from the +end of the array, and an index of -1 references the last element. + + The ‘+=’ operator appends to an array variable when assigning using +the compound assignment syntax; see *note Shell Parameters:: above. + + An array element is referenced using ‘${NAME[SUBSCRIPT]}’. The +braces are required to avoid conflicts with the shell's filename +expansion operators. If the SUBSCRIPT is ‘@’ or ‘*’, the word expands +to all members of the array NAME, unless otherwise noted in the +description of a builtin or word expansion. These subscripts differ +only when the word appears within double quotes. If the word is +double-quoted, ‘${NAME[*]}’ expands to a single word with the value of +each array member separated by the first character of the ‘IFS’ +variable, and ‘${NAME[@]}’ expands each element of NAME to a separate +word. When there are no array members, ‘${NAME[@]}’ 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 expansion +of the original word, and the expansion of the last parameter is joined +with the last part of the expansion of the original word. This is +analogous to the expansion of the special parameters ‘@’ and ‘*’. + + ‘${#NAME[SUBSCRIPT]}’ expands to the length of ‘${NAME[SUBSCRIPT]}’. +If SUBSCRIPT is ‘@’ or ‘*’, the expansion is the number of elements in +the array. + + If the 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 refers to the +last element. + + Referencing an array variable without a subscript is equivalent to +referencing with a subscript of 0. Any reference to a variable using a +valid subscript is valid; Bash creates an array if necessary. + + An array variable is considered set if a subscript has been assigned +a value. The null string is a valid value. + + It is possible to obtain the keys (indices) of an array as well as +the values. ${!NAME[@]} and ${!NAME[*]} expand to the indices assigned +in array variable NAME. The treatment when in double quotes is similar +to the expansion of the special parameters ‘@’ and ‘*’ within double +quotes. + + The ‘unset’ builtin is used to destroy arrays. ‘unset +NAME[SUBSCRIPT]’ unsets the array element at index SUBSCRIPT. Negative +subscripts to indexed arrays are interpreted as described above. +Unsetting the last element of an array variable does not unset the +variable. ‘unset NAME’, where NAME is an array, removes the entire +array. ‘unset NAME[SUBSCRIPT]’ behaves differently depending on the +array type when SUBSCRIPT is ‘*’ or ‘@’. When NAME is an associative +array, it removes the element with key ‘*’ or ‘@’. If NAME is an +indexed array, ‘unset’ removes all of the elements, but does not remove +the array itself. + + When using a variable name with a subscript as an argument to a +command, such as with ‘unset’, without using the word expansion syntax +described above (e.g., unset a[4]), the argument is subject to the +shell's filename expansion. Quote the argument if pathname expansion is +not desired (e.g., unset 'a[4]'). + + The ‘declare’, ‘local’, and ‘readonly’ builtins each accept a ‘-a’ +option to specify an indexed array and a ‘-A’ option to specify an +associative array. If both options are supplied, ‘-A’ takes precedence. +The ‘read’ builtin accepts a ‘-a’ option to assign a list of words read +from the standard input to an array, and can read values from the +standard input into individual array elements. The ‘set’ and ‘declare’ +builtins display array values in a way that allows them to be reused as +input. Other builtins accept array name arguments as well (e.g., +‘mapfile’); see the descriptions of individual builtins for details. +The shell provides a number of builtin array variables. + + +File: bash.info, Node: The Directory Stack, Next: Controlling the Prompt, Prev: Arrays, Up: Bash Features + +6.8 The Directory Stack +======================= + +* Menu: + +* Directory Stack Builtins:: Bash builtin commands to manipulate + the directory stack. + +The directory stack is a list of recently-visited directories. The +‘pushd’ builtin adds directories to the stack as it changes the current +directory, and the ‘popd’ builtin removes specified directories from the +stack and changes the current directory to the directory removed. The +‘dirs’ builtin displays the contents of the directory stack. The +current directory is always the "top" of the directory stack. + + The contents of the directory stack are also visible as the value of +the ‘DIRSTACK’ shell variable. + + +File: bash.info, Node: Directory Stack Builtins, Up: The Directory Stack + +6.8.1 Directory Stack Builtins +------------------------------ + +‘dirs’ + dirs [-clpv] [+N | -N] + + Without options, display the list of currently remembered + directories. Directories are added to the list with the ‘pushd’ + command; the ‘popd’ command removes directories from the list. The + current directory is always the first directory in the stack. + + Options, if supplied, have the following meanings: + + ‘-c’ + Clears the directory stack by deleting all of the elements. + ‘-l’ + Produces a listing using full pathnames; the default listing + format uses a tilde to denote the home directory. + ‘-p’ + Causes ‘dirs’ to print the directory stack with one entry per + line. + ‘-v’ + Causes ‘dirs’ to print the directory stack with one entry per + line, prefixing each entry with its index in the stack. + ‘+N’ + Displays the Nth directory (counting from the left of the list + printed by ‘dirs’ when invoked without options), starting with + zero. + ‘-N’ + Displays the Nth directory (counting from the right of the + list printed by ‘dirs’ when invoked without options), starting + with zero. + +‘popd’ + popd [-n] [+N | -N] + + Remove elements from the directory stack. The elements are + numbered from 0 starting at the first directory listed by ‘dirs’; + that is, ‘popd’ is equivalent to ‘popd +0’. + + When no arguments are given, ‘popd’ removes the top directory from + the stack and changes to the new top directory. + + Arguments, if supplied, have the following meanings: + + ‘-n’ + Suppress the normal change of directory when removing + directories from the stack, only manipulate the stack. + ‘+N’ + Remove the Nth directory (counting from the left of the list + printed by ‘dirs’), starting with zero, from the stack. + ‘-N’ + Remove the Nth directory (counting from the right of the list + printed by ‘dirs’), starting with zero, from the stack. + + If the top element of the directory stack is modified, and the ‘-n’ + option was not supplied, ‘popd’ uses the ‘cd’ builtin to change to + the directory at the top of the stack. If the ‘cd’ fails, ‘popd’ + returns a non-zero value. + + Otherwise, ‘popd’ returns an unsuccessful status if an invalid + option is specified, the directory stack is empty, or N specifies a + non-existent directory stack entry. + + If the ‘popd’ command is successful, Bash runs ‘dirs’ to show the + final contents of the directory stack, and the return status is 0. + +‘pushd’ + pushd [-n] [+N | -N | DIR] + + Add a directory to the top of the directory stack, or rotate the + stack, making the new top of the stack the current working + directory. With no arguments, ‘pushd’ exchanges the top two + elements of the directory stack. + + Arguments, if supplied, have the following meanings: + + ‘-n’ + Suppress the normal change of directory when rotating or + adding directories to the stack, only manipulate the stack. + ‘+N’ + Rotate the stack so that the Nth directory (counting from the + left of the list printed by ‘dirs’, starting with zero) is at + the top. + ‘-N’ + Rotate the stack so that the Nth directory (counting from the + right of the list printed by ‘dirs’, starting with zero) is at + the top. + ‘DIR’ + Make DIR be the top of the stack. + + After the stack has been modified, if the ‘-n’ option was not + supplied, ‘pushd’ uses the ‘cd’ builtin to change to the directory + at the top of the stack. If the ‘cd’ fails, ‘pushd’ returns a + non-zero value. + + Otherwise, if no arguments are supplied, ‘pushd’ returns zero + unless the directory stack is empty. When rotating the directory + stack, ‘pushd’ returns zero unless the directory stack is empty or + N specifies a non-existent directory stack element. + + If the ‘pushd’ command is successful, Bash runs ‘dirs’ to show the + final contents of the directory stack. + + +File: bash.info, Node: Controlling the Prompt, Next: The Restricted Shell, Prev: The Directory Stack, Up: Bash Features + +6.9 Controlling the Prompt +========================== + +In addition, the following table describes the special characters which +can appear in the prompt variables ‘PS0’, ‘PS1’, ‘PS2’, and ‘PS4’: + +‘\a’ + A bell character. +‘\d’ + The date, in "Weekday Month Date" format (e.g., "Tue May 26"). +‘\D{FORMAT}’ + The FORMAT is passed to ‘strftime’(3) and the result is inserted + into the prompt string; an empty FORMAT results in a + locale-specific time representation. The braces are required. +‘\e’ + An escape character. +‘\h’ + The hostname, up to the first ‘.’. +‘\H’ + The hostname. +‘\j’ + The number of jobs currently managed by the shell. +‘\l’ + The basename of the shell's terminal device name (e.g., "ttys0"). +‘\n’ + A newline. +‘\r’ + A carriage return. +‘\s’ + The name of the shell: the basename of ‘$0’ (the portion following + the final slash). +‘\t’ + The time, in 24-hour HH:MM:SS format. +‘\T’ + The time, in 12-hour HH:MM:SS format. +‘\@’ + The time, in 12-hour am/pm format. +‘\A’ + The time, in 24-hour HH:MM format. +‘\u’ + The username of the current user. +‘\v’ + The Bash version (e.g., 2.00). +‘\V’ + The Bash release, version + patchlevel (e.g., 2.00.0). +‘\w’ + The value of the ‘PWD’ shell variable (‘$PWD’), with ‘$HOME’ + abbreviated with a tilde (uses the ‘$PROMPT_DIRTRIM’ variable). +‘\W’ + The basename of ‘$PWD’, with ‘$HOME’ abbreviated with a tilde. +‘\!’ + The history number of this command. +‘\#’ + The command number of this command. +‘\$’ + If the effective uid is 0, ‘#’, otherwise ‘$’. +‘\NNN’ + The character whose ASCII code is the octal value NNN. +‘\\’ + A backslash. +‘\[’ + Begin a sequence of non-printing characters. Thiss could be used + to embed a terminal control sequence into the prompt. +‘\]’ + End a sequence of non-printing characters. + + 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 (*note Bash History +Facilities::), 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 ‘promptvars’ shell option (*note The Shopt +Builtin::). This can have unwanted side effects if escaped portions of +the string appear within command substitution or contain characters +special to word expansion. + + +File: bash.info, Node: The Restricted Shell, Next: Bash POSIX Mode, Prev: Controlling the Prompt, Up: Bash Features + +6.10 The Restricted Shell +========================= + +If Bash is started with the name ‘rbash’, or the ‘--restricted’ or ‘-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. A restricted shell behaves identically to ‘bash’ +with the exception that the following are disallowed or not performed: + + • Changing directories with the ‘cd’ builtin. + • Setting or unsetting the values of the ‘SHELL’, ‘PATH’, ‘HISTFILE’, + ‘ENV’, or ‘BASH_ENV’ variables. + • Specifying command names containing slashes. + • Specifying a filename containing a slash as an argument to the ‘.’ + builtin command. + • Using the ‘-p’ option to the ‘.’ builtin command to specify a + search path. + • Specifying a filename containing a slash as an argument to the + ‘history’ builtin command. + • Specifying a filename containing a slash as an argument to the ‘-p’ + option to the ‘hash’ builtin command. + • Importing function definitions from the shell environment at + startup. + • Parsing the value of ‘SHELLOPTS’ from the shell environment at + startup. + • Redirecting output using the ‘>’, ‘>|’, ‘<>’, ‘>&’, ‘&>’, and ‘>>’ + redirection operators. + • Using the ‘exec’ builtin to replace the shell with another command. + • Adding or deleting builtin commands with the ‘-f’ and ‘-d’ options + to the ‘enable’ builtin. + • Using the ‘enable’ builtin command to enable disabled shell + builtins. + • Specifying the ‘-p’ option to the ‘command’ builtin. + • Turning off restricted mode with ‘set +r’ or ‘shopt -u + restricted_shell’. + + These restrictions are enforced after any startup files are read. + + When a command that is found to be a shell script is executed (*note +Shell Scripts::), ‘rbash’ turns off any restrictions in the shell +spawned to execute the script. + + The restricted shell mode is only one component of a useful +restricted environment. It should be accompanied by setting ‘PATH’ to a +value that allows execution of only a few verified commands (commands +that allow shell escapes are particularly vulnerable), changing the +current directory to a non-writable directory other than ‘$HOME’ after +login, not allowing the restricted shell to execute shell scripts, and +cleaning the environment of variables that cause some commands to modify +their behavior (e.g., ‘VISUAL’ or ‘PAGER’). + + Modern systems provide more secure ways to implement a restricted +environment, such as ‘jails’, ‘zones’, or ‘containers’. + + +File: bash.info, Node: Bash POSIX Mode, Next: Shell Compatibility Mode, Prev: The Restricted Shell, Up: Bash Features + +6.11 Bash and POSIX +=================== + +6.11.1 What is POSIX? +--------------------- + +POSIX is the name for a family of standards based on Unix. A number of +Unix services, tools, and functions are part of the standard, ranging +from the basic system calls and C library functions to common +applications and tools to system administration and management. + + The POSIX Shell and Utilities standard was originally developed by +IEEE Working Group 1003.2 (POSIX.2). The first edition of the 1003.2 +standard was published in 1992. It was merged with the original IEEE +1003.1 Working Group and is currently maintained by the Austin Group (a +joint working group of the IEEE, The Open Group and ISO/IEC SC22/WG15). +Today the Shell and Utilities are a volume within the set of documents +that make up IEEE Std 1003.1-2024, and thus the former POSIX.2 (from +1992) is now part of the current unified POSIX standard. + + The Shell and Utilities volume concentrates on the command +interpreter interface and utility programs commonly executed from the +command line or by other programs. The standard is freely available on +the web at +. + + Bash is concerned with the aspects of the shell's behavior defined by +the POSIX Shell and Utilities volume. The shell command language has of +course been standardized, including the basic flow control and program +execution constructs, I/O redirection and pipelines, argument handling, +variable expansion, and quoting. + + The special builtins, which must be implemented as part of the shell +to provide the desired functionality, are specified as being part of the +shell; examples of these are ‘eval’ and ‘export’. Other utilities +appear in the sections of POSIX not devoted to the shell which are +commonly (and in some cases must be) implemented as builtin commands, +such as ‘read’ and ‘test’. POSIX also specifies aspects of the shell's +interactive behavior, including job control and command line editing. +Only vi-style line editing commands have been standardized; emacs +editing commands were left out due to objections. + +6.11.2 Bash POSIX Mode +---------------------- + +Although Bash is an implementation of the POSIX shell specification, +there are areas where the Bash default behavior differs from the +specification. The Bash “posix mode” changes the Bash behavior in these +areas so that it conforms more strictly to the standard. + + Starting Bash with the ‘--posix’ command-line option or executing +‘set -o posix’ while Bash is running will cause Bash to conform more +closely to the POSIX standard by changing the behavior to match that +specified by POSIX in areas where the Bash default differs. + + When invoked as ‘sh’, Bash enters POSIX mode after reading the +startup files. + + The following list is what's changed when POSIX mode is in effect: + + 1. Bash ensures that the ‘POSIXLY_CORRECT’ variable is set. + + 2. Bash reads and executes the POSIX startup files (‘$ENV’) rather + than the normal Bash files (*note Bash Startup Files::). + + 3. Alias expansion is always enabled, even in non-interactive shells. + + 4. Reserved words appearing in a context where reserved words are + recognized do not undergo alias expansion. + + 5. Alias expansion is performed when initially parsing a command + substitution. The default (non-posix) mode generally defers it, + when enabled, until the command substitution is executed. This + means that command substitution will not expand aliases that are + defined after the command substitution is initially parsed (e.g., + as part of a function definition). + + 6. The ‘time’ reserved word may be used by itself as a simple command. + When used in this way, it displays timing statistics for the shell + and its completed children. The ‘TIMEFORMAT’ variable controls the + format of the timing information. + + 7. The parser does not recognize ‘time’ as a reserved word if the next + token begins with a ‘-’. + + 8. When parsing and expanding a ${...} expansion that appears within + double quotes, single quotes are no longer special and cannot be + used to quote a closing brace or other special character, unless + the operator is one of those defined to perform pattern removal. + In this case, they do not have to appear as matched pairs. + + 9. Redirection operators do not perform filename expansion on the word + in a redirection unless the shell is interactive. + + 10. Redirection operators do not perform word splitting on the word in + a redirection. + + 11. Function names may not be the same as one of the POSIX special + builtins. + + 12. Tilde expansion is only performed on assignments preceding a + command name, rather than on all assignment statements on the line. + + 13. While variable indirection is available, it may not be applied to + the ‘#’ and ‘?’ special parameters. + + 14. Expanding the ‘*’ special parameter in a pattern context where the + expansion is double-quoted does not treat the ‘$*’ as if it were + double-quoted. + + 15. A double quote character (‘"’) is treated specially when it + appears in a backquoted command substitution in the body of a + here-document that undergoes expansion. That means, for example, + that a backslash preceding a double quote character will escape it + and the backslash will be removed. + + 16. Command substitutions don't set the ‘?’ special parameter. The + exit status of a simple command without a command word is still the + exit status of the last command substitution that occurred while + evaluating the variable assignments and redirections in that + command, but that does not happen until after all of the + assignments and redirections. + + 17. Literal tildes that appear as the first character in elements of + the ‘PATH’ variable are not expanded as described above under *note + Tilde Expansion::. + + 18. Command lookup finds POSIX special builtins before shell + functions, including output printed by the ‘type’ and ‘command’ + builtins. + + 19. Even if a shell function whose name contains a slash was defined + before entering POSIX mode, the shell will not execute a function + whose name contains one or more slashes. + + 20. When a command in the hash table no longer exists, Bash will + re-search ‘$PATH’ to find the new location. This is also available + with ‘shopt -s checkhash’. + + 21. Bash will not insert a command without the execute bit set into + the command hash table, even if it returns it as a (last-ditch) + result from a ‘$PATH’ search. + + 22. The message printed by the job control code and builtins when a + job exits with a non-zero status is "Done(status)". + + 23. The message printed by the job control code and builtins when a + job is stopped is "Stopped(SIGNAME)", where SIGNAME is, for + example, ‘SIGTSTP’. + + 24. If the shell is interactive, Bash does not perform job + notifications between executing commands in lists separated by ‘;’ + or newline. Non-interactive shells print status messages after a + foreground job in a list completes. + + 25. If the shell is interactive, Bash waits until the next prompt + before printing the status of a background job that changes status + or a foreground job that terminates due to a signal. + Non-interactive shells print status messages after a foreground job + completes. + + 26. Bash permanently removes jobs from the jobs table after notifying + the user of their termination via the ‘wait’ or ‘jobs’ builtins. + It removes the job from the jobs list after notifying the user of + its termination, but the status is still available via ‘wait’, as + long as ‘wait’ is supplied a PID argument. + + 27. The ‘vi’ editing mode will invoke the ‘vi’ editor directly when + the ‘v’ command is run, instead of checking ‘$VISUAL’ and + ‘$EDITOR’. + + 28. Prompt expansion enables the POSIX ‘PS1’ and ‘PS2’ expansions of + ‘!’ to the history number and ‘!!’ to ‘!’, and Bash performs + parameter expansion on the values of ‘PS1’ and ‘PS2’ regardless of + the setting of the ‘promptvars’ option. + + 29. The default history file is ‘~/.sh_history’ (this is the default + value the shell assigns to ‘$HISTFILE’). + + 30. The ‘!’ character does not introduce history expansion within a + double-quoted string, even if the ‘histexpand’ option is enabled. + + 31. When printing shell function definitions (e.g., by ‘type’), Bash + does not print the ‘function’ reserved word unless necessary. + + 32. Non-interactive shells exit if a syntax error in an arithmetic + expansion results in an invalid expression. + + 33. Non-interactive shells exit if a parameter expansion error occurs. + + 34. If a POSIX special builtin returns an error status, a + non-interactive shell exits. The fatal errors are those listed in + the POSIX standard, and include things like passing incorrect + options, redirection errors, variable assignment errors for + assignments preceding the command name, and so on. + + 35. A non-interactive shell exits with an error status if a variable + assignment error occurs when no command name follows the assignment + statements. A variable assignment error occurs, for example, when + trying to assign a value to a readonly variable. + + 36. A non-interactive shell exits with an error status if a variable + assignment error occurs in an assignment statement preceding a + special builtin, but not with any other simple command. For any + other simple command, the shell aborts execution of that command, + and execution continues at the top level ("the shell shall not + perform any further processing of the command in which the error + occurred"). + + 37. A non-interactive shell exits with an error status if the + iteration variable in a ‘for’ statement or the selection variable + in a ‘select’ statement is a readonly variable or has an invalid + name. + + 38. Non-interactive shells exit if FILENAME in ‘.’ FILENAME is not + found. + + 39. Non-interactive shells exit if there is a syntax error in a script + read with the ‘.’ or ‘source’ builtins, or in a string processed by + the ‘eval’ builtin. + + 40. Non-interactive shells exit if the ‘export’, ‘readonly’ or ‘unset’ + builtin commands get an argument that is not a valid identifier, + and they are not operating on shell functions. These errors force + an exit because these are special builtins. + + 41. Assignment statements preceding POSIX special builtins persist in + the shell environment after the builtin completes. + + 42. The ‘command’ builtin does not prevent builtins that take + assignment statements as arguments from expanding them as + assignment statements; when not in POSIX mode, declaration commands + lose their assignment statement expansion properties when preceded + by ‘command’. + + 43. Enabling POSIX mode has the effect of setting the + ‘inherit_errexit’ option, so subshells spawned to execute command + substitutions inherit the value of the ‘-e’ option from the parent + shell. When the ‘inherit_errexit’ option is not enabled, Bash + clears the ‘-e’ option in such subshells. + + 44. Enabling POSIX mode has the effect of setting the ‘shift_verbose’ + option, so numeric arguments to ‘shift’ that exceed the number of + positional parameters will result in an error message. + + 45. Enabling POSIX mode has the effect of setting the + ‘interactive_comments’ option (*note Comments::). + + 46. The ‘.’ and ‘source’ builtins do not search the current directory + for the filename argument if it is not found by searching ‘PATH’. + + 47. When the ‘alias’ builtin displays alias definitions, it does not + display them with a leading ‘alias ’ unless the ‘-p’ option is + supplied. + + 48. The ‘bg’ builtin uses the required format to describe each job + placed in the background, which does not include an indication of + whether the job is the current or previous job. + + 49. When the ‘cd’ builtin is invoked in logical mode, and the pathname + constructed from ‘$PWD’ and the directory name supplied as an + argument does not refer to an existing directory, ‘cd’ will fail + instead of falling back to physical mode. + + 50. When the ‘cd’ builtin cannot change a directory because the length + of the pathname constructed from ‘$PWD’ and the directory name + supplied as an argument exceeds ‘PATH_MAX’ when canonicalized, ‘cd’ + will attempt to use the supplied directory name. + + 51. When the ‘xpg_echo’ option is enabled, Bash does not attempt to + interpret any arguments to ‘echo’ as options. ‘echo’ displays each + argument after converting escape sequences. + + 52. The ‘export’ and ‘readonly’ builtin commands display their output + in the format required by POSIX. + + 53. When listing the history, the ‘fc’ builtin does not include an + indication of whether or not a history entry has been modified. + + 54. The default editor used by ‘fc’ is ‘ed’. + + 55. ‘fc’ treats extra arguments as an error instead of ignoring them. + + 56. If there are too many arguments supplied to ‘fc -s’, ‘fc’ prints + an error message and returns failure. + + 57. The output of ‘kill -l’ prints all the signal names on a single + line, separated by spaces, without the ‘SIG’ prefix. + + 58. The ‘kill’ builtin does not accept signal names with a ‘SIG’ + prefix. + + 59. The ‘kill’ builtin returns a failure status if any of the pid or + job arguments are invalid or if sending the specified signal to any + of them fails. In default mode, ‘kill’ returns success if the + signal was successfully sent to any of the specified processes. + + 60. The ‘printf’ builtin uses ‘double’ (via ‘strtod’) to convert + arguments corresponding to floating point conversion specifiers, + instead of ‘long double’ if it's available. The ‘L’ length + modifier forces ‘printf’ to use ‘long double’ if it's available. + + 61. The ‘pwd’ builtin verifies that the value it prints is the same as + the current directory, even if it is not asked to check the file + system with the ‘-P’ option. + + 62. The ‘read’ builtin may be interrupted by a signal for which a trap + has been set. If Bash receives a trapped signal while executing + ‘read’, the trap handler executes and ‘read’ returns an exit status + greater than 128. + + 63. When the ‘set’ builtin is invoked without options, it does not + display shell function names and definitions. + + 64. When the ‘set’ builtin is invoked without options, it displays + variable values without quotes, unless they contain shell + metacharacters, even if the result contains nonprinting characters. + + 65. The ‘test’ builtin compares strings using the current locale when + evaluating the ‘<’ and ‘>’ binary operators. + + 66. The ‘test’ builtin's ‘-t’ unary primary requires an argument. + Historical versions of ‘test’ made the argument optional in certain + cases, and Bash attempts to accommodate those for backwards + compatibility. + + 67. The ‘trap’ builtin displays signal names without the leading + ‘SIG’. + + 68. The ‘trap’ builtin doesn't check the first argument for a possible + signal specification and revert the signal handling to the original + disposition if it is, unless that argument consists solely of + digits and is a valid signal number. If users want to reset the + handler for a given signal to the original disposition, they should + use ‘-’ as the first argument. + + 69. ‘trap -p’ without arguments displays signals whose dispositions + are set to SIG_DFL and those that were ignored when the shell + started, not just trapped signals. + + 70. The ‘type’ and ‘command’ builtins will not report a non-executable + file as having been found, though the shell will attempt to execute + such a file if it is the only so-named file found in ‘$PATH’. + + 71. The ‘ulimit’ builtin uses a block size of 512 bytes for the ‘-c’ + and ‘-f’ options. + + 72. The ‘unset’ builtin with the ‘-v’ option specified returns a fatal + error if it attempts to unset a ‘readonly’ or ‘non-unsettable’ + variable, which causes a non-interactive shell to exit. + + 73. When asked to unset a variable that appears in an assignment + statement preceding the command, the ‘unset’ builtin attempts to + unset a variable of the same name in the current or previous scope + as well. This implements the required "if an assigned variable is + further modified by the utility, the modifications made by the + utility shall persist" behavior. + + 74. The arrival of ‘SIGCHLD’ when a trap is set on ‘SIGCHLD’ does not + interrupt the ‘wait’ builtin and cause it to return immediately. + The trap command is run once for each child that exits. + + 75. Bash removes an exited background process's status from the list + of such statuses after the ‘wait’ builtin returns it. + + There is additional POSIX behavior that Bash does not implement by +default even when in POSIX mode. Specifically: + + 1. POSIX requires that word splitting be byte-oriented. That is, each + _byte_ in the value of ‘IFS’ potentially splits a word, even if + that byte is part of a multibyte character in ‘IFS’ or part of + multibyte character in the word. Bash allows multibyte characters + in the value of ‘IFS’, treating a valid multibyte character as a + single delimiter, and will not split a valid multibyte character + even if one of the bytes composing that character appears in ‘IFS’. + This is POSIX interpretation 1560, further modified by issue 1924. + + 2. The ‘fc’ builtin checks ‘$EDITOR’ as a program to edit history + entries if ‘FCEDIT’ is unset, rather than defaulting directly to + ‘ed’. ‘fc’ uses ‘ed’ if ‘EDITOR’ is unset. + + 3. As noted above, Bash requires the ‘xpg_echo’ option to be enabled + for the ‘echo’ builtin to be fully conformant. + + Bash can be configured to be POSIX-conformant by default, by +specifying the ‘--enable-strict-posix-default’ to ‘configure’ when +building (*note Optional Features::). + + +File: bash.info, Node: Shell Compatibility Mode, Prev: Bash POSIX Mode, Up: Bash Features + +6.12 Shell Compatibility Mode +============================= + +Bash-4.0 introduced the concept of a “shell compatibility level”, +specified as a set of options to the shopt builtin (‘compat31’, +‘compat32’, ‘compat40’, ‘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. + + This section does not mention behavior that is standard for a +particular version (e.g., setting ‘compat32’ means that quoting the +right hand side of the regexp matching operator quotes special regexp +characters in the word, which is default behavior in bash-3.2 and +subsequent versions). + + If a user enables, say, ‘compat32’, 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 Bash, but that behavior may have been present +in earlier versions. For instance, the change to use locale-based +comparisons with the ‘[[’ command came in bash-4.1, and earlier versions +used ASCII-based comparisons, so enabling ‘compat32’ 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. + + Bash-4.3 introduced a new shell variable: ‘BASH_COMPAT’. The value +assigned to this variable (a decimal version number like 4.2, or an +integer corresponding to the ‘compat’NN option, like 42) determines the +compatibility level. + + Starting with bash-4.4, Bash began deprecating older compatibility +levels. Eventually, the options will be removed in favor of +‘BASH_COMPAT’. + + Bash-5.0 was the final version for which there was an individual +shopt option for the previous version. ‘BASH_COMPAT’ is the only +mechanism to control the compatibility level in versions newer than +bash-5.0. + + The following table describes the behavior changes controlled by each +compatibility level setting. The ‘compat’NN tag is used as shorthand +for setting the compatibility level to NN using one of the following +mechanisms. For versions prior to bash-5.0, the compatibility level may +be set using the corresponding ‘compat’NN shopt option. For bash-4.3 +and later versions, the ‘BASH_COMPAT’ variable is preferred, and it is +required for bash-5.1 and later versions. + +‘compat31’ + • Quoting the rhs of the ‘[[’ command's regexp matching operator + (=~) has no special effect + +‘compat40’ + • The ‘<’ and ‘>’ operators to the ‘[[’ 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 strcmp(3); bash-4.1 and later use the current locale's + collation sequence and strcoll(3). + +‘compat41’ + • In POSIX mode, ‘time’ may be followed by options and still be + recognized as a reserved word (this is POSIX interpretation + 267). + • In POSIX mode, the parser requires that an even number of + single quotes occur in the WORD 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). + +‘compat42’ + • The replacement string in double-quoted pattern substitution + does not undergo quote removal, as it does in versions after + bash-4.2. + • In POSIX mode, single quotes are considered special when + expanding the WORD 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. + +‘compat43’ + • 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). + • When executing a shell function, the loop state + (while/until/etc.) is not reset, so ‘break’ or ‘continue’ in + that function will break or continue loops in the calling + context. Bash-4.4 and later reset the loop state to prevent + this. + +‘compat44’ + • The shell sets up the values used by ‘BASH_ARGV’ and + ‘BASH_ARGC’ so they can expand to the shell's positional + parameters even if extended debugging mode is not enabled. + • A subshell inherits loops from its parent context, so ‘break’ + or ‘continue’ will cause the subshell to exit. Bash-5.0 and + later reset the loop state to prevent the exit. + • Variable assignments preceding builtins like ‘export’ and + ‘readonly’ that set attributes continue to affect variables + with the same name in the calling environment even if the + shell is not in POSIX mode. + +‘compat50 (set using BASH_COMPAT)’ + • Bash-5.1 changed the way ‘$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 ‘RANDOM’ will produce the same sequence + as in bash-5.0. + • 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 ‘-l’ option is supplied. + +‘compat51 (set using BASH_COMPAT)’ + • The ‘unset’ builtin will unset the array ‘a’ given an argument + like ‘a[@]’. Bash-5.2 will unset an element with key ‘@’ + (associative arrays) or remove all the elements without + unsetting the array (indexed arrays). + • Arithmetic commands ( ((...)) ) and the expressions in an + arithmetic for statement can be expanded more than once. + • Expressions used as arguments to arithmetic operators in the + ‘[[’ conditional command can be expanded more than once. + • The expressions in substring parameter brace expansion can be + expanded more than once. + • The expressions in the $(( ... )) word expansion can be + expanded more than once. + • Arithmetic expressions used as indexed array subscripts can be + expanded more than once. + • ‘test -v’, when given an argument of ‘A[@]’, where A is an + existing associative array, will return true if the array has + any set elements. Bash-5.2 will look for and report on a key + named ‘@’. + • the ${PARAMETER[:]=VALUE} word expansion will return VALUE, + before any variable-specific transformations have been + performed (e.g., converting to lowercase). Bash-5.2 will + return the final value assigned to the variable. + • Parsing command substitutions will behave as if extended + globbing (*note The Shopt Builtin::) is enabled, so that + parsing a command substitution containing an extglob pattern + (say, as part of a shell function) will not fail. This + assumes the intent is to enable extglob before the command is + executed and word expansions are performed. It will fail at + word expansion time if extglob hasn't been enabled by the time + the command is executed. + +‘compat52 (set using BASH_COMPAT)’ + • The ‘test’ builtin uses its historical algorithm to parse + parenthesized subexpressions when given five or more + arguments. + • If the ‘-p’ or ‘-P’ option is supplied to the ‘bind’ builtin, + ‘bind’ treats any arguments remaining after option processing + as bindable command names, and displays any key sequences + bound to those commands, instead of treating the arguments as + key sequences to bind. + • Interactive shells will notify the user of completed jobs + while sourcing a script. Newer versions defer notification + until script execution completes. + + +File: bash.info, Node: Job Control, Next: Command Line Editing, Prev: Bash Features, Up: Top + +7 Job Control +************* + +This chapter discusses what job control is, how it works, and how Bash +allows you to access its facilities. + +* Menu: + +* Job Control Basics:: How job control works. +* Job Control Builtins:: Bash builtin commands used to interact + with job control. +* Job Control Variables:: Variables Bash uses to customize job + control. + + +File: bash.info, Node: Job Control Basics, Next: Job Control Builtins, Up: Job Control + +7.1 Job Control Basics +====================== + +Job control refers to the ability to selectively stop (suspend) the +execution of processes and continue (resume) 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 Bash. + + The shell associates a JOB with each pipeline. It keeps a table of +currently executing jobs, which the ‘jobs’ command will display. Each +job has a “job number”, which ‘jobs’ displays between brackets. Job +numbers start at 1. When Bash starts a job asynchronously, it prints a +line that looks like: + [1] 25647 +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. Bash +uses the JOB abstraction as the basis for job control. + + To facilitate the implementation of the user interface to job +control, each process has a “process group ID”, and the operating system +maintains the notion of a current terminal process group ID. This +terminal process group ID is associated with the “controlling terminal”. + + Processes that have the same process group ID are said to be part of +the same “process group”. Members of the foreground process group +(processes whose process group ID is equal to the current terminal +process group ID) receive keyboard-generated signals such as ‘SIGINT’. +Processes in the foreground process group are said to be foreground +processes. Background processes are those whose process group ID +differs from the controlling 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 ‘stty tostop’, write to the +controlling terminal. The system sends a ‘SIGTTIN’ (‘SIGTTOU’) signal +to background processes which attempt to read from (write to when +‘tostop’ is in effect) the terminal, which, unless caught, suspends the +process. + + If the operating system on which Bash is running supports job +control, Bash contains facilities to use it. Typing the “suspend” +character (typically ‘^Z’, Control-Z) while a process is running stops +that process and returns control to Bash. Typing the “delayed suspend” +character (typically ‘^Y’, Control-Y) causes the process to stop when it +attempts to read input from the terminal, and returns control to Bash. +The user then manipulates the state of this job, using the ‘bg’ command +to continue it in the background, the ‘fg’ command to continue it in the +foreground, or the ‘kill’ command to kill it. The suspend character +takes effect immediately, and has the additional side effect of +discarding any pending output and typeahead. If you want to force a +background process to stop, or stop a process that's not associated with +your terminal session, send it the ‘SIGSTOP’ signal using ‘kill’. + + There are a number of ways to refer to a job in the shell. The ‘%’ +character introduces a “job specification” (jobspec). + + Job number ‘n’ may be referred to as ‘%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, ‘%ce’ refers +to a job whose command name begins with ‘ce’. Using ‘%?ce’, on the +other hand, refers to any job containing the string ‘ce’ in its command +line. If the prefix or substring matches more than one job, Bash +reports an error. + + The symbols ‘%%’ and ‘%+’ refer to the shell's notion of the “current +job”. A single ‘%’ (with no accompanying job specification) also refers +to the current job. ‘%-’ refers to the “previous job”. When a job +starts in the background, a job stops while in the foreground, or a job +is resumed in the background, it becomes the current job. The job that +was the current job becomes the previous job. When the current job +terminates, the previous job becomes the current job. If there is only +a single job, ‘%+’ and ‘%-’ can both be used to refer to that job. In +output pertaining to jobs (e.g., the output of the ‘jobs’ command), the +current job is always marked with a ‘+’, and the previous job with a +‘-’. + + Simply naming a job can be used to bring it into the foreground: ‘%1’ +is a synonym for ‘fg %1’, bringing job 1 from the background into the +foreground. Similarly, ‘%1 &’ resumes job 1 in the background, +equivalent to ‘bg %1’. + + The shell learns immediately whenever a job changes state. Normally, +Bash waits until it is about to print a prompt before notifying the user +about changes in a job's status so as to not interrupt any other output, +though it will notify of changes in a job's status after a foreground +command in a list completes, before executing the next command in the +list. If the ‘-b’ option to the ‘set’ builtin is enabled, Bash reports +status changes immediately (*note The Set Builtin::). Bash executes any +trap on ‘SIGCHLD’ for each child process that terminates. + + When a job terminates and Bash notifies the user about it, Bash +removes the job from the jobs table. It will not appear in ‘jobs’ +output, but ‘wait’ will report its exit status, as long as it's supplied +the process ID associated with the job as an argument. When the table +is empty, job numbers start over at 1. + + If a user attempts to exit Bash while jobs are stopped, (or running, +if the ‘checkjobs’ option is enabled - see *note The Shopt Builtin::), +the shell prints a warning message, and if the ‘checkjobs’ option is +enabled, lists the jobs and their statuses. The ‘jobs’ command may then +be used to inspect their status. If the user immediately attempts to +exit again, without an intervening command, Bash does not print another +warning, and terminates any stopped jobs. + + When the shell is waiting for a job or process using the ‘wait’ +builtin, and job control is enabled, ‘wait’ will return when the job +changes state. The ‘-f’ option causes ‘wait’ to wait until the job or +process terminates before returning. + + +File: bash.info, Node: Job Control Builtins, Next: Job Control Variables, Prev: Job Control Basics, Up: Job Control + +7.2 Job Control Builtins +======================== + +‘bg’ + bg [JOBSPEC ...] + + Resume each suspended job JOBSPEC in the background, as if it had + been started with ‘&’. If JOBSPEC is not supplied, the shell uses + its notion of the current job. ‘bg’ returns zero unless it is run + when job control is not enabled, or, when run with job control + enabled, any JOBSPEC was not found or specifies a job that was + started without job control. + +‘fg’ + fg [JOBSPEC] + + Resume the job JOBSPEC in the foreground and make it the current + job. If JOBSPEC is not supplied, ‘fg’ resumes the current job. + The return status is that of the command placed into the + foreground, or non-zero if run when job control is disabled or, + when run with job control enabled, JOBSPEC does not specify a valid + job or JOBSPEC specifies a job that was started without job + control. + +‘jobs’ + jobs [-lnprs] [JOBSPEC] + jobs -x COMMAND [ARGUMENTS] + + The first form lists the active jobs. The options have the + following meanings: + + ‘-l’ + List process IDs in addition to the normal information. + + ‘-n’ + Display information only about jobs that have changed status + since the user was last notified of their status. + + ‘-p’ + List only the process ID of the job's process group leader. + + ‘-r’ + Display only running jobs. + + ‘-s’ + Display only stopped jobs. + + If JOBSPEC is supplied, ‘jobs’ restricts output to information + about that job. If JOBSPEC is not supplied, ‘jobs’ lists the + status of all jobs. The return status is zero unless an invalid + option is encountered or an invalid JOBSPEC is supplied. + + If the ‘-x’ option is supplied, ‘jobs’ replaces any JOBSPEC found + in COMMAND or ARGUMENTS with the corresponding process group ID, + and executes COMMAND, passing it ARGUMENTs, returning its exit + status. + +‘kill’ + kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] ID [...] + kill -l|-L [EXIT_STATUS] + + Send a signal specified by SIGSPEC or SIGNUM to the processes named + by each ID. Each ID may be a job specification JOBSPEC or process + ID PID. SIGSPEC is either a case-insensitive signal name such as + ‘SIGINT’ (with or without the ‘SIG’ prefix) or a signal number; + SIGNUM is a signal number. If SIGSPEC and SIGNUM are not present, + ‘kill’ sends ‘SIGTERM’. + + The ‘-l’ option lists the signal names. If any arguments are + supplied when ‘-l’ is supplied, ‘kill’ lists the names of the + signals corresponding to the arguments, and the return status is + zero. EXIT_STATUS is a number specifying a signal number or the + exit status of a process terminated by a signal; if it is supplied, + ‘kill’ prints the name of the signal that caused the process to + terminate. ‘kill’ assumes that process exit statuses are greater + than 128; anything less than that is a signal number. The ‘-L’ + option is equivalent to ‘-l’. + + The return status is zero if at least one signal was successfully + sent, or non-zero if an error occurs or an invalid option is + encountered. + +‘wait’ + wait [-fn] [-p VARNAME] [ID ...] + + Wait until the child process specified by each ID exits and return + the exit status of the last ID. Each ID may be a process ID PID or + a job specification JOBSPEC; if a jobspec is supplied, ‘wait’ waits + for all processes in the job. + + If no options or IDs are supplied, ‘wait’ waits for all running + background jobs and the last-executed process substitution, if its + process id is the same as $!, and the return status is zero. + + If the ‘-n’ option is supplied, ‘wait’ waits for any one of the IDs + or, if no IDs are supplied, any job or process substitution, to + complete and returns its exit status. If none of the supplied IDs + 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 ‘-p’ option is supplied, ‘wait’ assigns the process or job + identifier of the job for which the exit status is returned to the + variable VARNAME named by the option argument. The variable, which + cannot be readonly, will be unset initially, before any assignment. + This is useful only when used with the ‘-n’ option. + + Supplying the ‘-f’ option, when job control is enabled, forces + ‘wait’ to wait for each ID to terminate before returning its + status, instead of returning when it changes status. + + If none of the IDs specify one of the shell's an active child + processes, the return status is 127. If ‘wait’ is interrupted by a + signal, any VARNAME will remain unset, and the return status will + be greater than 128, as described above (*note Signals::). + Otherwise, the return status is the exit status of the last ID. + +‘disown’ + disown [-ar] [-h] [ID ...] + + Without options, remove each ID from the table of active jobs. + Each ID may be a job specification JOBSPEC or a process ID PID; if + ID is a PID, ‘disown’ uses the job containing PID as JOBSPEC. + + If the ‘-h’ option is supplied, ‘disown’ does not remove the jobs + corresponding to each ‘id’ from the jobs table, but rather marks + them so the shell does not send ‘SIGHUP’ to the job if the shell + receives a ‘SIGHUP’. + + If no ID is supplied, the ‘-a’ option means to remove or mark all + jobs; the ‘-r’ option without an ID argument removes or marks + running jobs. If no ID is supplied, and neither the ‘-a’ nor the + ‘-r’ option is supplied, ‘disown’ removes or marks the current job. + + The return value is 0 unless an ID does not specify a valid job. + +‘suspend’ + suspend [-f] + + Suspend the execution of this shell until it receives a ‘SIGCONT’ + signal. A login shell, or a shell without job control enabled, + cannot be suspended; the ‘-f’ option will 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 ‘-f’ is not supplied. + + When job control is not active, the ‘kill’ and ‘wait’ builtins do not +accept JOBSPEC arguments. They must be supplied process IDs. + + +File: bash.info, Node: Job Control Variables, Prev: Job Control Builtins, Up: Job Control + +7.3 Job Control Variables +========================= + +‘auto_resume’ + This variable controls how the shell interacts with the user and + job control. If this variable exists then simple commands + consisting of only a single word, without redirections, are treated + as candidates for resumption of an existing job. There is no + ambiguity allowed; if there is more than one job beginning with or + containing the word, then this selects the most recently accessed + job. The name of a stopped job, in this context, is the command + line used to start it, as displayed by ‘jobs’. If this variable is + set to the value ‘exact’, the word must match the name of a stopped + job exactly; if set to ‘substring’, the word needs to match a + substring of the name of a stopped job. The ‘substring’ value + provides functionality analogous to the ‘%?string’ job ID (*note + Job Control Basics::). If set to any other value (e.g., ‘prefix’), + the word must be a prefix of a stopped job's name; this provides + functionality analogous to the ‘%string’ job ID. + + +File: bash.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Job Control, Up: Top + +8 Command Line Editing +********************** + +This chapter describes the basic features of the GNU command line +editing interface. Command line editing is provided by the Readline +library, which is used by several different programs, including Bash. +Command line editing is enabled by default when using an interactive +shell, unless the ‘--noediting’ option is supplied at shell invocation. +Line editing is also used when using the ‘-e’ option to the ‘read’ +builtin command (*note Bash Builtins::). 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 ‘-o emacs’ or ‘-o vi’ options to the ‘set’ builtin command +(*note The Set Builtin::), or disabled using the ‘+o emacs’ or ‘+o vi’ +options to ‘set’. + +* Menu: + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. +* Programmable Completion:: How to specify the possible completions for + a specific command. +* Programmable Completion Builtins:: Builtin commands to specify how to + complete arguments for a particular command. +* A Programmable Completion Example:: An example shell function for + generating possible completions. + + +File: bash.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing + +8.1 Introduction to Line Editing +================================ + +The following paragraphs use Emacs style to describe the notation used +to represent keystrokes. + + The text ‘C-k’ is read as "Control-K" and describes the character +produced when the key is pressed while the Control key is depressed. + + The text ‘M-k’ is read as "Meta-K" and describes the character +produced when the Meta key (if you have one) is depressed, and the +key is pressed (a “meta character”), then both are released. The Meta +key is labeled or