diff options
Diffstat (limited to 'doc/bash.0')
| -rw-r--r-- | doc/bash.0 | 970 |
1 files changed, 508 insertions, 462 deletions
@@ -9,7 +9,7 @@ SSYYNNOOPPSSIISS bbaasshh [options] [command_string | file] CCOOPPYYRRIIGGHHTT - Bash is Copyright (C) 1989-2021 by the Free Software Foundation, Inc. + Bash is Copyright (C) 1989-2022 by the Free Software Foundation, Inc. DDEESSCCRRIIPPTTIIOONN BBaasshh is an sshh-compatible command language interpreter that executes @@ -715,7 +715,7 @@ PPAARRAAMMEETTEERRSS or add to the variable's previous value. This includes arguments to builtin commands such as ddeeccllaarree that accept assignment statements (_d_e_c_l_a_r_a_t_i_o_n commands). When += is applied to a variable for which the - _i_n_t_e_g_e_r attribute has been set, _v_a_l_u_e is evaluated as an arithmetic ex- + iinntteeggeerr attribute has been set, _v_a_l_u_e is evaluated as an arithmetic ex- pression and added to the variable's current value, which is also eval- uated. When += is applied to an array variable using compound assign- ment (see AArrrraayyss below), the variable's value is not unset (as it is @@ -1120,8 +1120,8 @@ PPAARRAAMMEETTEERRSS value that is not one of the valid compatibility levels, the shell prints an error message and sets the compatibility level to the default for the current version. The valid values corre- - spond to the compatibility levels described below under BBSSHHEELLLL-- - COMPATIBILITYMMOODDEE. For example, 4.2 and 42 are valid values + spond 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 compat- ibility level to 42. The current version is also a valid value. BBAASSHH__EENNVV @@ -1494,126 +1494,129 @@ PPAARRAAMMEETTEERRSS count back from the end of the array, and an index of -1 references the last element. - Any element of an array may be referenced using ${_n_a_m_e[_s_u_b_s_c_r_i_p_t]}. + The += operator will append to an array variable when assigning using + the compound assignment syntax; see PPAARRAAMMEETTEERRSS above. + + Any element of an array may be 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. These - subscripts differ only when the word appears within double quotes. If + _s_u_b_s_c_r_i_p_t is @@ or **, the word expands to all members of _n_a_m_e. These + subscripts differ only when the word appears within double quotes. If the word is double-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 + value of each array member separated by the first character of the IIFFSS special variable, and ${_n_a_m_e[@]} expands each element of _n_a_m_e to a sep- - arate word. When there are no array members, ${_n_a_m_e[@]} expands to - nothing. If the double-quoted expansion occurs within a word, the ex- + arate word. When there are no array members, ${_n_a_m_e[@]} expands to + nothing. If the double-quoted expansion occurs within a word, the ex- pansion of the first parameter is joined with the beginning part of the - original word, and the expansion of the last parameter is joined with + original word, and the expansion of the last parameter is joined with the last part of the original word. This is analogous to the expansion - of the special parameters ** and @@ (see SSppeecciiaall 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 + of the special parameters ** and @@ (see SSppeecciiaall 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 - 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 + evaluates to a number less than zero, it is interpreted as relative to + one greater than the maximum index of the array, so negative indices count back from the end of the array, and an index of -1 references the last element. Referencing an array variable without a subscript is equivalent to ref- - erencing the array with a subscript of 0. Any reference to a variable + erencing the array with a subscript of 0. Any reference to a variable using a valid subscript is legal, and bbaasshh will create an array if nec- essary. - An array variable is considered set if a subscript has been assigned a + 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 + 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] de- stroys 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- + 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], where _s_u_b_s_c_r_i_p_t is ** or @@, behaves differently depending on whether _n_a_m_e is an indexed or asso- - ciative array. If _n_a_m_e is an associative array, this unsets the ele- + ciative array. If _n_a_m_e is an associative array, this unsets the ele- ment with subscript ** or @@. If _n_a_m_e 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 com- - mand, such as with uunnsseett, without using the word expansion syntax de- + 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, the argument is subject to pathname expansion. If path- name expansion is not desired, the argument should be quoted. - 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 + 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. EEXXPPAANNSSIIOONN Expansion is performed on the command line after it has been split into - words. There are seven kinds of expansion performed: _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_- + words. There are seven kinds of expansion performed: _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, and _p_a_t_h_n_a_m_e _e_x_p_a_n_s_i_o_n. The order of expansions is: brace expansion; tilde expansion, parameter - and variable expansion, arithmetic expansion, and command substitution - (done in a left-to-right fashion); word splitting; and pathname expan- + and variable expansion, arithmetic expansion, and command substitution + (done in a left-to-right fashion); word splitting; and pathname expan- sion. 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- + 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. - After these expansions are performed, quote characters present in the - original word are removed unless they have been quoted themselves + After these expansions are performed, quote characters present in the + original word are removed unless they have been quoted themselves (_q_u_o_t_e _r_e_m_o_v_a_l). - 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- + 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 by which arbitrary strings may be gener- - ated. This mechanism is similar to _p_a_t_h_n_a_m_e _e_x_p_a_n_s_i_o_n, but the file- + ated. This mechanism is similar to _p_a_t_h_n_a_m_e _e_x_p_a_n_s_i_o_n, but the file- names generated need not exist. Patterns to be brace expanded take the form of an optional _p_r_e_a_m_b_l_e, followed by either a series of comma-sep- - arated strings or a sequence expression between a pair of braces, fol- - lowed by an optional _p_o_s_t_s_c_r_i_p_t. The preamble is prefixed to each + arated strings or a sequence expression between a pair of braces, fol- + lowed 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; left to right order is preserved. For example, + Brace expansions may be nested. The results of each expanded string + are not sorted; left to right order is preserved. For example, 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 + 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. Supplied integers may be prefixed - with _0 to force each term to have the same width. When either _x or _y - begins with a zero, the shell attempts to force all generated terms to - contain the same number of digits, zero-padding where necessary. When - letters are supplied, the expression expands to each character lexico- - graphically between _x and _y, inclusive, using the default 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 + number between _x and _y, inclusive. Supplied integers may be prefixed + with _0 to force each term to have the same width. When either _x or _y + begins with a zero, the shell attempts to force all generated terms to + contain the same number of digits, zero-padding where necessary. When + letters are supplied, the expression expands to each character lexico- + graphically between _x and _y, inclusive, using the default 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 char- - acters special to other expansions are preserved in the result. It is - strictly textual. BBaasshh does not apply any syntactic interpretation to + 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 + 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 ,, may be quoted with a backslash to prevent its being considered - part of a brace expression. To avoid conflicts with parameter expan- + {{ or ,, may be quoted with a backslash to prevent its being considered + part of a brace expression. To avoid conflicts with parameter expan- sion, the string $${{ is not considered eligible for brace expansion, and inhibits brace expansion until the closing }}. @@ -1624,36 +1627,36 @@ EEXXPPAANNSSIIOONN 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 _f_i_l_e_{_1_,_2_} appears identically in - the output. The same word is output as _f_i_l_e_1 _f_i_l_e_2 after expansion by - bbaasshh. If strict compatibility with sshh is desired, start bbaasshh with the + 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 _f_i_l_e_{_1_,_2_} appears identically in + the output. The same word is output as _f_i_l_e_1 _f_i_l_e_2 after expansion by + bbaasshh. If strict compatibility with sshh is desired, start bbaasshh with the ++BB option or disable brace expansion with the ++BB option to the sseett com- mand (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). 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 home direc- - tory of the user executing the shell is substituted instead. Other- - wise, the tilde-prefix is replaced with the home directory associated + 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 home direc- + tory of the user executing the shell is substituted 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 value of - the shell variable OOLLDDPPWWDD, if it is set, is substituted. If the char- - acters following the tilde in the tilde-prefix consist of a number _N, - optionally prefixed by a `+' or a `-', the tilde-prefix is replaced + 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 value of + the shell variable OOLLDDPPWWDD, if it is set, is substituted. If the char- + acters 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 tilde-prefix as an argu- - ment. If the characters following the tilde in the tilde-prefix con- + ment. If the characters following the tilde in the tilde-prefix con- sist of a number without a leading `+' or `-', `+' is assumed. If the login name is invalid, or the tilde expansion fails, the word is @@ -1662,99 +1665,100 @@ EEXXPPAANNSSIIOONN Each variable assignment is checked for unquoted tilde-prefixes immedi- ately following a :: or the first ==. In these cases, tilde expansion is also performed. Consequently, one may use filenames with tildes in as- - signments to PPAATTHH, MMAAIILLPPAATTHH, and CCDDPPAATTHH, and the shell assigns the ex- + signments to PPAATTHH, MMAAIILLPPAATTHH, and CCDDPPAATTHH, and the shell assigns the ex- panded value. - Bash also performs tilde expansion on words satisfying the conditions + Bash 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. Bash does not do this, except + appear as arguments to simple commands. Bash does not do this, except for the _d_e_c_l_a_r_a_t_i_o_n commands listed above, when in _p_o_s_i_x _m_o_d_e. 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 + 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 + 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- + bedded arithmetic expansion, command substitution, or parameter expan- sion. ${_p_a_r_a_m_e_t_e_r} - The value of _p_a_r_a_m_e_t_e_r is substituted. The braces are required - when _p_a_r_a_m_e_t_e_r is a positional parameter with more than one + The value of _p_a_r_a_m_e_t_e_r is substituted. 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 + 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 + 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 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. + _r_a_m_e_t_e_r; this 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 ex- - pansion, parameter expansion, command substitution, and arithmetic ex- - pansion. 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. 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 indirec- + pansion, parameter expansion, command substitution, and arithmetic ex- + pansion. 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. 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 indirec- tion. 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 results in a test only for a parameter that is un- + low (e.g., ::--), bbaasshh tests for a parameter that is unset or null. + Omitting the colon results in a test only for a parameter that is un- set. ${_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 + 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. The value of _p_a_r_a_m_e_- - _t_e_r is then substituted. Positional parameters and special pa- + 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. The value of _p_a_r_a_m_e_- + _t_e_r is then substituted. Positional parameters and special pa- rameters may not be assigned to 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 expansion of _w_o_r_d (or a message to that effect if _w_o_r_d is - not present) is written to the standard error and the shell, if + DDiissppllaayy EErrrroorr iiff NNuullll oorr UUnnsseett. If _p_a_r_a_m_e_t_e_r is null or unset, + the expansion of _w_o_r_d (or a message to that effect if _w_o_r_d is + not present) is written to the standard error and the shell, if it is not interactive, exits. 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} - UUssee AAlltteerrnnaattee VVaalluuee. If _p_a_r_a_m_e_t_e_r is null or unset, nothing is + 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. ${_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 @@, an indexed array subscripted by @@ or **, - or an associative array name, the results differ as described - below. If _l_e_n_g_t_h is omitted, 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. _l_e_n_g_t_h and _o_f_f_s_e_t are - arithmetic expressions (see AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN below). - - If _o_f_f_s_e_t evaluates to a number less than zero, the value is + 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, 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. _l_e_n_g_t_h and _o_f_f_s_e_t + are arithmetic expressions (see AARRIITTHHMMEETTIICC 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 + _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 + 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 @@, the result is _l_e_n_g_t_h positional parameters - 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. It is an expan- - sion 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 @@ 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. 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_- @@ -1849,24 +1853,34 @@ EEXXPPAANNSSIIOONN 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. If _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 en- - abled using sshhoopptt, any unquoted instances of && in _s_t_r_i_n_g are re- - placed with the matching portion of _p_a_t_t_e_r_n. Backslash is used - to quote && in _s_t_r_i_n_g; the backslash is removed in order to per- - mit a literal && in the replacement string. Users should take - care if _s_t_r_i_n_g is double-quoted to avoid unwanted interactions - between the backslash and double-quoting. Pattern substitution - performs the check for && after expanding _s_t_r_i_n_g; shell program- - mers should quote backslashes intended to escape the && and in- - hibit replacement so they survive any quote removal performed by - the expansion of _s_t_r_i_n_g. If the nnooccaasseemmaattcchh shell option is en- - abled, the match is performed without regard to the case of al- - phabetic 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 resultant 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 member of the array in turn, and the expansion - is the resultant list. + 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 will escape && in _s_t_r_i_n_g; the back- + slash is removed in order to permit a literal && in the replace- + ment 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 + interactions 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 in- + stances of && they want to be replaced are unquoted. + + 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} @@ -2460,15 +2474,23 @@ FFUUNNCCTTIIOONNSS option has been enabled. Variables local to the function may be declared with the llooccaall builtin - command. Ordinarily, variables and their values are shared between the - function and its caller. If a variable is declared llooccaall, the vari- - able's visible scope is restricted to that function and its children - (including the functions it calls). Local variables "shadow" variables - with the same name declared at previous scopes. For instance, a local - variable declared in a function hides a global variable of the same - name: references and assignments refer to the local variable, leaving - the global variable unmodified. When the function returns, the global - variable is once again visible. + 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. Consequently, 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 a global variable of the same name: references and assignments + refer to the local variable, leaving the global variable unmodified. + When the function returns, the global variable is once again visible. 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 @@ -2488,44 +2510,45 @@ FFUUNNCCTTIIOONNSS is local to the current scope, uunnsseett will unset it; otherwise the unset will refer to the variable found in any calling scope as described above. If a variable at the current local scope is unset, it will re- - main so until it is reset in that scope or until the function returns. - Once the function returns, any instance of the variable at a previous - scope will become visible. If the unset acts on a variable at a previ- - ous scope, any instance of a variable with that name that had been - shadowed will become visible. - - The FFUUNNCCNNEESSTT variable, if set to a numeric value greater than 0, de- - fines a maximum function nesting level. Function invocations that ex- + main so (appearing as unset) until it is reset in that scope or until + the function returns. Once the function returns, any instance of the + variable at a previous scope will become visible. If the unset acts on + a variable at a previous scope, any instance of a variable with that + name that had been shadowed will become visible (see below how the lloo-- + ccaallvvaarr__uunnsseett 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- + 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. Any command associated with the RREETTUURRNN trap is executed be- - fore execution resumes. When a function completes, the values of the - positional parameters and the special parameter ## are restored to the + fore 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. - Function names and definitions may be listed with the --ff option to the + Function names and definitions may be listed with the --ff option to the ddeeccllaarree or ttyyppeesseett builtin commands. The --FF option to ddeeccllaarree or ttyyppee-- - sseett will list 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 exe- - cuting a separate shell invocation) automatically have them defined + sseett will list 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 exe- + cuting a separate shell invocation) automatically have them defined with the --ff option to the eexxppoorrtt builtin. A function definition may be deleted using the --ff option to the uunnsseett builtin. 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- + the depth of the function call stack and restrict the number of func- tion invocations. By default, no limit is imposed on the number of re- cursive calls. AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN - The shell allows arithmetic expressions to be evaluated, under certain - circumstances (see the lleett and ddeeccllaarree builtin commands, the (((( com- + The shell allows arithmetic expressions to be evaluated, under certain + circumstances (see the lleett and ddeeccllaarree builtin commands, the (((( com- pound command, and AArriitthhmmeettiicc EExxppaannssiioonn). Evaluation is done in fixed- - width integers with no check for overflow, though division by 0 is - trapped and flagged as an error. The operators and their precedence, - associativity, and values are the same as in the C language. The fol- + width integers with no check for overflow, though division by 0 is + trapped and flagged as an error. The operators and their precedence, + associativity, and values are the same as in the C language. The fol- lowing list of operators is grouped into levels of equal-precedence op- erators. The levels are listed in order of decreasing precedence. @@ -2554,55 +2577,55 @@ AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN _e_x_p_r_1 ,, _e_x_p_r_2 comma - Shell variables are allowed as operands; parameter expansion is per- + 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. A shell variable that is null or unset evaluates to + variables may also be referenced by name without using the parameter + expansion syntax. A shell variable that is null or unset evaluates to 0 when referenced by name without using the parameter expansion syntax. - The value of a variable is evaluated as an arithmetic expression when - it is referenced, or when a variable which has been given the _i_n_t_e_g_e_r + 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 turned on + to 0. A shell variable need not have its _i_n_t_e_g_e_r attribute turned on 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 + 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- + 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 order of precedence. Sub-expressions in - parentheses are evaluated first and may override the precedence rules + Operators are evaluated in order of precedence. Sub-expressions in + parentheses 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 + 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 following unary or binary primaries. - BBaasshh handles several filenames specially when they are used in expres- + Expressions are formed from the following unary or binary primaries. + 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- + 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 file descriptor _n is checked. 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, file descriptor 0, 1, or 2, respectively, + 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, file descriptor 0, 1, or 2, respectively, is checked. 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 [[[[, the << and >> operators sort lexicographically using + When used with [[[[, the << and >> operators sort lexicographically using the current locale. The tteesstt command sorts using ASCII ordering. --aa _f_i_l_e @@ -2641,30 +2664,30 @@ CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS --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 + True if _f_i_l_e exists and has been modified since it was last read. --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. _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- + 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 + 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 + 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. --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 + 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 + True if the shell variable _v_a_r_n_a_m_e is set (has been assigned a value). --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- + 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. @@ -2674,8 +2697,8 @@ CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS _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, + 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). @@ -2689,113 +2712,113 @@ CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS True if _s_t_r_i_n_g_1 sorts after _s_t_r_i_n_g_2 lexicographically. _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 + 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). SSIIMMPPLLEE CCOOMMMMAANNDD EEXXPPAANNSSIIOONN When a simple command is executed, the shell performs the following ex- - pansions, assignments, and redirections, from left to right, in the + 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 + 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 + 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- + 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- + 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 + 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 + 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 + 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 status of zero. CCOOMMMMAANNDD EEXXEECCUUTTIIOONN - After a command has been split into words, if it results in a simple - command and an optional list of arguments, the following actions are + After a command has been split into words, if it results in a simple + command and an optional list of arguments, the following actions are taken. - 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 + 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- + 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). A full search of the directories in PPAATTHH is - performed only if the command is not found in the hash table. If the + member the full pathnames of executable files (see hhaasshh under SSHHEELLLL + BBUUIILLTTIINN CCOOMMMMAANNDDSS below). A full search of the directories in PPAATTHH is + performed only if the command is not found in the hash table. If the search is unsuccessful, the shell searches for a defined shell function named ccoommmmaanndd__nnoott__ffoouunndd__hhaannddllee. 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 + 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 sta- tus of 127. - If the search is successful, or if the command name contains one or + 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 + 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. This subshell reinitializes itself, so that the + itself to execute it. This subshell reinitializes itself, so that the effect is as if a new shell had been invoked to handle the script, with - the exception that the locations of commands remembered by the parent - (see hhaasshh below under SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS) are retained by the + the exception 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 + 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 + 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- + 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 + +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 + +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 + +o the file creation mode mask as set by uummaasskk or inherited from the shell's parent +o current traps set by ttrraapp @@ -2803,282 +2826,282 @@ CCOOMMMMAANNDD EEXXEECCUUTTIIOONN EENNVVIIRROONNMMEENN +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 + +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- + +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 + +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- + 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 + +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 + +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 + 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- + 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- + set to the values that the shell inherited from its parent at invoca- tion. Builtin commands that are invoked as part of a pipeline are also executed in a subshell environment. Changes made to the subshell envi- ronment cannot affect the shell's execution environment. Subshells spawned to execute command substitutions inherit the value of - the --ee option from the parent shell. When not in _p_o_s_i_x _m_o_d_e, bbaasshh + the --ee option from the parent shell. When not in _p_o_s_i_x _m_o_d_e, bbaasshh clears the --ee option in such subshells. - If a command is followed by a && and job control is not active, the de- + 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- + 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 + 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 pro- + 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 pro- cesses. Executed commands inherit the environment. The eexxppoorrtt and ddee-- - ccllaarree --xx commands allow parameters and functions to be added to and + ccllaarree --xx commands allow parameters and functions to be added to and deleted from the environment. If the value of a parameter in the envi- ronment is modified, the new value becomes part of the environment, re- - placing the old. The environment inherited by any executed command - consists of the shell's initial environment, whose values may be modi- - fied in the shell, less any pairs removed by the uunnsseett command, plus + placing the old. The environment inherited by any executed command + consists of the shell's initial environment, whose values may be modi- + fied in the shell, less any pairs removed by the uunnsseett command, plus any additions via the eexxppoorrtt and ddeeccllaarree --xx commands. - The environment for any _s_i_m_p_l_e _c_o_m_m_a_n_d or function may be augmented - temporarily by prefixing it with parameter assignments, as described + The environment for any _s_i_m_p_l_e _c_o_m_m_a_n_d or function may be augmented + temporarily by prefixing it with parameter assignments, as described above in PPAARRAAMMEETTEERRSS. These assignment statements affect only the envi- ronment seen by that command. - 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 + 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 + When bbaasshh invokes an external command, the variable __ is set to the full filename 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 + 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 + 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. An exit status of zero indicates success. A non-zero - exit status indicates failure. When a command terminates on a fatal + has succeeded. 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, + 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- + 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 + 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 + When bbaasshh is interactive, in the absence of any traps, it ignores SSIIGGTTEERRMM (so that kkiillll 00 does not kill an interactive shell), and SSIIGGIINNTT - is caught and handled (so that the wwaaiitt builtin is interruptible). In + is caught and handled (so that the wwaaiitt builtin is interruptible). In all cases, bbaasshh ignores SSIIGGQQUUIITT. If job control is in effect, bbaasshh ig- nores SSIIGGTTTTIINN, SSIIGGTTTTOOUU, and SSIIGGTTSSTTPP. Non-builtin commands run by bbaasshh have signal handlers set to the values inherited by the shell from its parent. When job control is not in ef- - fect, asynchronous commands ignore SSIIGGIINNTT and SSIIGGQQUUIITT in addition to - these inherited handlers. Commands run as a result of command substi- + fect, asynchronous commands ignore SSIIGGIINNTT and SSIIGGQQUUIITT in addition to + these inherited handlers. Commands run as a result of command substi- tution ignore the keyboard-generated job control signals SSIIGGTTTTIINN, SSIIGGTT-- TTOOUU, 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 + The shell exits by default upon receipt of a SSIIGGHHUUPP. Before exiting, + an interactive shell resends the SSIIGGHHUUPP to all jobs, running or stopped. Stopped jobs are sent SSIIGGCCOONNTT to ensure that they receive the - SSIIGGHHUUPP. To prevent the shell from sending the signal to a particular - job, it should be removed from the jobs table with the ddiissoowwnn builtin - (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below) or marked to not receive SSIIGGHHUUPP us- + SSIIGGHHUUPP. To prevent the shell from sending the signal to a particular + job, it should be removed from the jobs table with the ddiissoowwnn builtin + (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below) or marked to not receive SSIIGGHHUUPP us- ing ddiissoowwnn --hh. - If the hhuuppoonneexxiitt shell option has been set with sshhoopptt, bbaasshh sends a + If the hhuuppoonneexxiitt shell option has been set with 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 + If bbaasshh is waiting for a command to complete and receives a signal for which a trap has been set, the trap will not be executed until the com- - mand completes. When bbaasshh is waiting for an asynchronous command via - the wwaaiitt builtin, the reception of a signal for which a trap has been + mand completes. When bbaasshh is waiting for an asynchronous command via + the wwaaiitt builtin, the reception of a signal for which a trap has been set will cause the wwaaiitt builtin to return immediately with an exit sta- tus greater than 128, immediately after which the trap is executed. - When job control is not enabled, and bbaasshh is waiting for a foreground + 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 + 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 pro- cesses in that process group. - When bbaasshh is running without job control enabled and receives SSIIGGIINNTT - while waiting for a foreground command, it waits until that foreground + When bbaasshh is running without job control enabled and receives SSIIGGIINNTT + while waiting for a foreground command, it waits until that foreground command terminates 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 end the entire script, and acts on the SSIIGGIINNTT + the user meant to end the entire script, and acts on the SSIIGGIINNTT (e.g., by running a SSIIGGIINNTT trap or exiting itself); - 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 + 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- + 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. 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 + 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 driver and bbaasshh. - The shell associates a _j_o_b with each pipeline. It keeps a table of - currently executing jobs, which may be listed with the jjoobbss command. - When bbaasshh starts a job asynchronously (in the _b_a_c_k_g_r_o_u_n_d), it prints a + The shell associates a _j_o_b with each pipeline. It keeps a table of + currently executing jobs, which may be listed with the jjoobbss command. + 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 + 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, + To facilitate the implementation of the user interface to job control, 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. Members of this process group (processes whose process group ID is equal to the current terminal process group ID) receive keyboard- - generated signals such as SSIIGGIINNTT. These processes are said to be in - the _f_o_r_e_g_r_o_u_n_d. _B_a_c_k_g_r_o_u_n_d processes are those whose process group ID + generated signals such as SSIIGGIINNTT. These processes are said to be in + the _f_o_r_e_g_r_o_u_n_d. _B_a_c_k_g_r_o_u_n_d processes are those whose process group ID differs from the terminal's; such processes are immune to keyboard-gen- erated signals. Only foreground processes are allowed to read from or, - if the user so specifies with stty tostop, write to the terminal. - Background processes which attempt to read from (write to when stty - tostop is in effect) the terminal are sent a SSIIGGTTTTIINN ((SSIIGGTTTTOOUU)) signal - by the kernel's terminal driver, which, unless caught, suspends the + if the user so specifies with stty tostop, write to the terminal. + Background processes which attempt to read from (write to when stty + tostop is in effect) the terminal are sent a SSIIGGTTTTIINN ((SSIIGGTTTTOOUU)) signal + by the kernel's terminal driver, which, unless caught, suspends the process. - If the operating system on which bbaasshh is running supports job control, + 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 causes that process to - be stopped and returns control to bbaasshh. Typing the _d_e_l_a_y_e_d _s_u_s_p_e_n_d - character (typically ^^YY, Control-Y) causes the process to be stopped + be stopped and returns control to bbaasshh. Typing the _d_e_l_a_y_e_d _s_u_s_p_e_n_d + character (typically ^^YY, Control-Y) causes the process to be stopped when it attempts to read input from the terminal, and control to be re- - turned to bbaasshh. The user may then manipulate the state of this job, - using the bbgg command to continue it in the background, the ffgg command + turned to bbaasshh. The user may then manipulate 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. A ^^ZZ takes effect immediately, and has the additional side effect of causing pending output and typeahead to be discarded. There are a number of ways to refer to a job in the shell. The charac- - ter %% introduces a job specification (_j_o_b_s_p_e_c). Job number _n may be + ter %% introduces a job specification (_j_o_b_s_p_e_c). 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 stopped job whose command name be- - gins with ccee. If a prefix matches more than one job, bbaasshh reports an + line. For example, %%ccee refers to a stopped job whose command name be- + gins with ccee. If a prefix matches more than one job, bbaasshh reports an error. Using %%??ccee, on the other hand, refers to any job containing the - string ccee in its command line. If the substring matches more than one + string ccee in its command line. If the 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, which is the last job stopped while it was - in the foreground or started in the background. The _p_r_e_v_i_o_u_s _j_o_b may - be referenced using %%--. If there is only a single job, %%++ and %%-- can + notion of the _c_u_r_r_e_n_t _j_o_b, which is the last job stopped while it was + in the foreground or started in the background. The _p_r_e_v_i_o_u_s _j_o_b may + be referenced using %%--. 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 jjoobbss command), the current job is always flagged with - a ++, and the previous job with a --. A single % (with no accompanying + a ++, and the previous job with a --. A single % (with no accompanying job specification) also refers to the current job. - Simply naming a job can be used to bring it into the foreground: %%11 is - a synonym for ````ffgg %%11'''', bringing job 1 from the background into the - foreground. Similarly, ````%%11 &&'''' resumes job 1 in the background, + Simply naming a job can be used to bring it into the foreground: %%11 is + a synonym for ````ffgg %%11'''', bringing job 1 from the background into the + foreground. Similarly, ````%%11 &&'''' resumes job 1 in the background, equivalent to ````bbgg %%11''''. - The shell learns immediately whenever a job changes state. Normally, + The shell learns immediately whenever a job changes state. Normally, bbaasshh waits until it is about to print a prompt before reporting changes - in a job's status so as to not interrupt any other output. If the --bb + in a job's status so as to not interrupt any other output. If the --bb option to the sseett builtin command is enabled, bbaasshh reports such changes - immediately. Any trap on SSIIGGCCHHLLDD is executed for each child that ex- + immediately. Any trap on SSIIGGCCHHLLDD is executed for each child that ex- its. - If an attempt to exit bbaasshh is made while jobs are stopped (or, if the - cchheecckkjjoobbss shell option has been enabled using the sshhoopptt builtin, run- + If an attempt to exit bbaasshh is made 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 a second attempt to exit is - made without an intervening command, the shell does not print another + is enabled, lists the jobs and their statuses. The jjoobbss command may + then be used to inspect their status. If a second attempt to exit is + made without an intervening command, the shell does not print another warning, and any stopped jobs are terminated. - 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- + 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 displays PPSS00 after it - reads a command but before executing it. BBaasshh displays PPSS44 as de- - scribed above before tracing each command when the --xx option is en- - abled. BBaasshh allows these prompt strings to be customized by inserting - a number of backslash-escaped special characters that are decoded as + it is ready to read a command, and the secondary prompt PPSS22 when it + needs more input to complete a command. BBaasshh displays PPSS00 after it + reads a command but before executing it. BBaasshh displays PPSS44 as de- + scribed above before tracing each command when the --xx option is en- + abled. BBaasshh allows these prompt strings 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 + \\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 + a locale-specific time representation. The braces are required \\ee an ASCII escape character (033) \\hh the hostname up to the first `.' @@ -3087,7 +3110,7 @@ PPRROOMMPPTTIINNGG \\ll the basename of the shell's terminal device name \\nn newline \\rr carriage return - \\ss the name of the shell, the basename of $$00 (the portion + \\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 @@ -3096,8 +3119,8 @@ PPRROOMMPPTTIINNGG \\uu the username of the current user \\vv the version of bbaasshh (e.g., 2.00) \\VV the release of bbaasshh, 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 + \\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 @@ -3105,70 +3128,70 @@ PPRROOMMPPTTIINNGG \\$$ 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 + \\[[ 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 + 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 + 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- + This is the library that handles reading input when using an interac- tive shell, unless the ----nnooeeddiittiinngg option is given at shell invocation. 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 editing 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 + 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 In this section, the Emacs-style notation is used to denote keystrokes. - Control keys are denoted by C-_k_e_y, e.g., C-n means Control-N. Simi- - larly, _m_e_t_a keys are denoted by M-_k_e_y, so M-x means Meta-X. (On key- - boards without a _m_e_t_a key, M-_x means ESC _x, i.e., press the Escape key + Control keys are denoted by C-_k_e_y, e.g., C-n means Control-N. Simi- + larly, _m_e_t_a keys are denoted by M-_k_e_y, so M-x means Meta-X. (On key- + boards without a _m_e_t_a key, M-_x means ESC _x, i.e., press the Escape key then the _x key. This makes ESC the _m_e_t_a _p_r_e_f_i_x. The combination M-C-_x - means ESC-Control-_x, or press the Escape key then hold the Control key + means ESC-Control-_x, or press the Escape key then hold the Control key while pressing the _x key.) Readline 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) causes that command to - act in a backward direction. Commands whose behavior with arguments + 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) causes that command to + act in a backward direction. Commands whose behavior with arguments deviates from this are noted below. - When a command is described as _k_i_l_l_i_n_g text, the text deleted is saved + 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 cause the text to be accumulated into one unit, which can be yanked all at once. Commands which do not kill text separate the chunks of text on the kill ring. RReeaaddlliinnee IInniittiiaalliizzaattiioonn - Readline 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 + Readline 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 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, the ultimate - default is _/_e_t_c_/_i_n_p_u_t_r_c. When a program which uses the readline li- - brary starts up, the initialization file is read, and the key bindings - and variables are set. There are only a few basic constructs allowed - in the readline initialization file. Blank lines are ignored. Lines - beginning with a ## are comments. Lines beginning with a $$ indicate - conditional constructs. Other lines denote key bindings and variable + _p_u_t_r_c. If that file does not exist or cannot be read, the ultimate + default is _/_e_t_c_/_i_n_p_u_t_r_c. When a program which uses the readline li- + brary starts up, the initialization file is read, and the key bindings + and variables are set. There are only a few basic constructs allowed + in the readline initialization file. Blank lines are ignored. Lines + beginning with a ## are comments. Lines beginning with a $$ indicate + conditional constructs. Other lines denote key bindings and variable settings. - The default key-bindings may be changed with an _i_n_p_u_t_r_c file. Other + The default key-bindings may be changed with an _i_n_p_u_t_r_c file. Other programs that use this library may add their own commands and bindings. For example, placing @@ -3176,18 +3199,18 @@ RREEAADDLLIINNEE 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 readline command _u_n_i_v_e_r_- + into the _i_n_p_u_t_r_c would make M-C-u execute the readline command _u_n_i_v_e_r_- _s_a_l_-_a_r_g_u_m_e_n_t. - The following symbolic character names are recognized: _R_U_B_O_U_T, _D_E_L, + The following symbolic character names are recognized: _R_U_B_O_U_T, _D_E_L, _E_S_C, _L_F_D, _N_E_W_L_I_N_E, _R_E_T, _R_E_T_U_R_N, _S_P_C, _S_P_A_C_E, and _T_A_B. - In addition to command names, readline allows keys to be bound to a + In addition to command names, readline allows keys to be bound to a string that is inserted when the key is pressed (a _m_a_c_r_o). 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 + 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 name may be speci- fied 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. @@ -3199,15 +3222,15 @@ RREEAADDLLIINNEE 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 + 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 + 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 the symbolic character names are not recognized. "\C-u": universal-argument @@ -3215,7 +3238,7 @@ RREEAADDLLIINNEE "\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 + _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 is @@ -3226,7 +3249,7 @@ RREEAADDLLIINNEE \\"" literal " \\'' literal ' - In addition to the GNU Emacs style escape sequences, a second set of + In addition to the GNU Emacs style escape sequences, a second set of backslash escapes is available: \\aa alert (bell) \\bb backspace @@ -3236,20 +3259,20 @@ RREEAADDLLIINNEE \\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 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 + \\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. In the macro body, the backslash escapes described above - are expanded. Backslash will quote any other character in the macro + tion name. In the macro body, the backslash escapes described above + are expanded. Backslash will quote any other character in the macro text, including " and '. - BBaasshh allows the current readline key bindings to be displayed or modi- - fied with the bbiinndd builtin command. The editing mode may be switched - during interactive use by using the --oo option to the sseett builtin com- + BBaasshh allows the current readline key bindings to be displayed or modi- + fied with the bbiinndd builtin command. The editing mode may be switched + during interactive use by using the --oo option to the sseett builtin com- mand (see SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS below). RReeaaddlliinnee VVaarriiaabblleess @@ -3260,12 +3283,35 @@ RREEAADDLLIINNEE 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, readline variables can take the values OOnn or OOffff - (without regard to case). Unrecognized variable names are ignored. - When a variable value is read, empty or null values, "on" (case-insen- + Except where noted, readline variables can take the values OOnn or OOffff + (without regard to case). Unrecognized variable names are ignored. + When a variable value is read, empty or null values, "on" (case-insen- sitive), and "1" are equivalent to OOnn. All other values are equivalent to OOffff. 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 readline wants to ring the terminal bell. If set to nnoonnee, readline never rings the bell. If set to @@ -3356,17 +3402,17 @@ RREEAADDLLIINNEE referred to as the _r_e_g_i_o_n. When this variable is set to _O_n, readline allows certain commands to designate the region as _a_c_- _t_i_v_e. When the region is active, readline highlights the text - in the region using 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. + in the region using the value of the aaccttiivvee--rreeggiioonn--ssttaarrtt--ccoolloorr, + which defaults to the string that enables the terminal's stand- + out mode. The active region shows the text inserted by brack- + eted-paste and any matching text found by incremental and non- + incremental history searches. eennaabbllee--bbrraacckkeetteedd--ppaassttee ((OOnn)) - When set to OOnn, readline will configure the terminal in a way - that will enable it to insert each paste into the editing buffer - as a single string of characters, instead of treating each char- - acter as if it had been read from the keyboard. This can pre- - vent pasted characters from being interpreted as editing com- - mands. + When set to OOnn, readline configures the terminal to insert each + paste into the editing buffer as a single string of characters, + instead of treating each character as if it had been read from + the keyboard. This prevents readline from executing any editing + commands bound to key sequences appearing in the pasted text. eennaabbllee--kkeeyyppaadd ((OOffff)) When set to OOnn, readline will try to enable the application key- pad when it is called. Some systems need this to enable the ar- @@ -6325,14 +6371,14 @@ SSHHEELLLL BBUUIILLTTIINN CCOOMMMMAANNDDSS exit status of the last process or job waited for. SSHHEELLLL CCOOMMPPAATTIIBBIILLIITTYY MMOODDEE - Bash-4.0 introduced the concept of a `shell compatibility level', spec- - ified 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. + 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, + ccoommppaatt4400, ccoommppaatt4411, and so on). There is only one current compatibil- + ity level -- each option is mutually exclusive. The compatibility + level is intended to allow users to select behavior from previous ver- + sions 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 particu- lar version (e.g., setting ccoommppaatt3322 means that quoting the rhs of the @@ -6597,4 +6643,4 @@ BBUUGGSS -GNU Bash 5.2 2021 December 26 BASH(1) +GNU Bash 5.2 2022 March 11 BASH(1) |