diff options
Diffstat (limited to 'doc/builtins.0')
| -rw-r--r-- | doc/builtins.0 | 2014 |
1 files changed, 2014 insertions, 0 deletions
diff --git a/doc/builtins.0 b/doc/builtins.0 new file mode 100644 index 0000000..614524e --- /dev/null +++ b/doc/builtins.0 @@ -0,0 +1,2014 @@ +BASH_BUILTINS(1) General Commands Manual BASH_BUILTINS(1) + + + +NNAAMMEE + bash, :, ., [, alias, bg, bind, break, builtin, caller, cd, command, + compgen, complete, compopt, continue, declare, dirs, disown, echo, en- + able, eval, exec, exit, export, false, fc, fg, getopts, hash, help, + history, jobs, kill, let, local, logout, mapfile, popd, printf, pushd, + pwd, read, readonly, return, set, shift, shopt, source, suspend, test, + times, trap, true, type, typeset, ulimit, umask, unalias, unset, wait - + bash built-in commands, see bbaasshh(1) + +BBAASSHH BBUUIILLTTIINN CCOOMMMMAANNDDSS + Unless otherwise noted, each builtin command documented in this section + as accepting options preceded by -- accepts ---- to signify the end of the + options. The ::, ttrruuee, ffaallssee, and tteesstt/[[ builtins do not accept options + and do not treat ---- specially. The eexxiitt, llooggoouutt, rreettuurrnn, bbrreeaakk, ccoonn-- + ttiinnuuee, lleett, and sshhiifftt builtins accept and process arguments beginning + with -- without requiring ----. Other builtins that accept arguments but + are not specified as accepting options interpret arguments beginning + with -- as invalid options and require ---- to prevent this interpreta- + tion. + :: [_a_r_g_u_m_e_n_t_s] + No effect; the command does nothing beyond expanding _a_r_g_u_m_e_n_t_s + and performing any specified redirections. The return status is + zero. + + .. _f_i_l_e_n_a_m_e [_a_r_g_u_m_e_n_t_s] + ssoouurrccee _f_i_l_e_n_a_m_e [_a_r_g_u_m_e_n_t_s] + Read and execute commands from _f_i_l_e_n_a_m_e in the current shell en- + vironment and return the exit status of the last command exe- + cuted from _f_i_l_e_n_a_m_e. If _f_i_l_e_n_a_m_e does not contain a slash, + filenames in PPAATTHH are used to find the directory containing + _f_i_l_e_n_a_m_e. The file searched for in PPAATTHH need not be executable. + When bbaasshh is not in _p_o_s_i_x _m_o_d_e, the current directory is + searched if no file is found in PPAATTHH. If the ssoouurrcceeppaatthh option + to the sshhoopptt builtin command is turned off, the PPAATTHH is not + searched. If any _a_r_g_u_m_e_n_t_s are supplied, they become the posi- + tional parameters when _f_i_l_e_n_a_m_e is executed. Otherwise the po- + sitional parameters are unchanged. If the --TT option is enabled, + ssoouurrccee inherits any trap on DDEEBBUUGG; if it is not, any DDEEBBUUGG trap + string is saved and restored around the call to ssoouurrccee, and + ssoouurrccee unsets the DDEEBBUUGG trap while it executes. If --TT is not + set, and the sourced file changes the DDEEBBUUGG trap, the new value + is retained when ssoouurrccee completes. The return status is the + status of the last command exited within the script (0 if no + commands are executed), and false if _f_i_l_e_n_a_m_e is not found or + cannot be read. + + aalliiaass [--pp] [_n_a_m_e[=_v_a_l_u_e] ...] + AAlliiaass with no arguments or with the --pp option prints the list of + aliases in the form aalliiaass _n_a_m_e=_v_a_l_u_e on standard output. When + arguments are supplied, an alias is defined for each _n_a_m_e whose + _v_a_l_u_e is given. A trailing space in _v_a_l_u_e causes the next word + to be checked for alias substitution when the alias is expanded. + For each _n_a_m_e in the argument list for which no _v_a_l_u_e is sup- + plied, the name and value of the alias is printed. AAlliiaass re- + turns true unless a _n_a_m_e is given for which no alias has been + defined. + + bbgg [_j_o_b_s_p_e_c ...] + Resume each suspended job _j_o_b_s_p_e_c in the background, as if it + had been started with &&. If _j_o_b_s_p_e_c is not present, the shell's + notion of the _c_u_r_r_e_n_t _j_o_b is used. bbgg _j_o_b_s_p_e_c returns 0 unless + run when job control is disabled or, when run with job control + enabled, any specified _j_o_b_s_p_e_c was not found or was started + without job control. + + bbiinndd [--mm _k_e_y_m_a_p] [--llppssvvPPSSVVXX] + bbiinndd [--mm _k_e_y_m_a_p] [--qq _f_u_n_c_t_i_o_n] [--uu _f_u_n_c_t_i_o_n] [--rr _k_e_y_s_e_q] + bbiinndd [--mm _k_e_y_m_a_p] --ff _f_i_l_e_n_a_m_e + bbiinndd [--mm _k_e_y_m_a_p] --xx _k_e_y_s_e_q:_s_h_e_l_l_-_c_o_m_m_a_n_d + bbiinndd [--mm _k_e_y_m_a_p] _k_e_y_s_e_q:_f_u_n_c_t_i_o_n_-_n_a_m_e + bbiinndd [--mm _k_e_y_m_a_p] _k_e_y_s_e_q:_r_e_a_d_l_i_n_e_-_c_o_m_m_a_n_d + Display current rreeaaddlliinnee key and function bindings, bind a key + sequence to a rreeaaddlliinnee function or macro, or set a rreeaaddlliinnee + variable. Each non-option argument is a command as it would ap- + pear in _._i_n_p_u_t_r_c, but each binding or command must be passed as + a separate argument; e.g., '"\C-x\C-r": re-read-init-file'. Op- + tions, if supplied, have the following meanings: + --mm _k_e_y_m_a_p + Use _k_e_y_m_a_p as the keymap to be affected by the subsequent + bindings. Acceptable _k_e_y_m_a_p names are _e_m_a_c_s_, _e_m_a_c_s_-_s_t_a_n_- + _d_a_r_d_, _e_m_a_c_s_-_m_e_t_a_, _e_m_a_c_s_-_c_t_l_x_, _v_i_, _v_i_-_m_o_v_e_, _v_i_-_c_o_m_m_a_n_d, + and _v_i_-_i_n_s_e_r_t. _v_i is equivalent to _v_i_-_c_o_m_m_a_n_d (_v_i_-_m_o_v_e + is also a synonym); _e_m_a_c_s is equivalent to _e_m_a_c_s_-_s_t_a_n_- + _d_a_r_d. + --ll List the names of all rreeaaddlliinnee functions. + --pp Display rreeaaddlliinnee function names and bindings in such a + way that they can be re-read. + --PP List current rreeaaddlliinnee function names and bindings. + --ss Display rreeaaddlliinnee key sequences bound to macros and the + strings they output in such a way that they can be re- + read. + --SS Display rreeaaddlliinnee key sequences bound to macros and the + strings they output. + --vv Display rreeaaddlliinnee variable names and values in such a way + that they can be re-read. + --VV List current rreeaaddlliinnee variable names and values. + --ff _f_i_l_e_n_a_m_e + Read key bindings from _f_i_l_e_n_a_m_e. + --qq _f_u_n_c_t_i_o_n + Query about which keys invoke the named _f_u_n_c_t_i_o_n. + --uu _f_u_n_c_t_i_o_n + Unbind all keys bound to the named _f_u_n_c_t_i_o_n. + --rr _k_e_y_s_e_q + Remove any current binding for _k_e_y_s_e_q. + --xx _k_e_y_s_e_q::_s_h_e_l_l_-_c_o_m_m_a_n_d + Cause _s_h_e_l_l_-_c_o_m_m_a_n_d to be executed whenever _k_e_y_s_e_q is en- + tered. When _s_h_e_l_l_-_c_o_m_m_a_n_d is executed, the shell sets + the RREEAADDLLIINNEE__LLIINNEE variable to the contents of the rreeaadd-- + lliinnee line buffer and the RREEAADDLLIINNEE__PPOOIINNTT and RREEAADDLLIINNEE__MMAARRKK + variables to the current location of the insertion point + and the saved insertion point (the mark), respectively. + If the executed command changes the value of any of RREEAADD-- + LLIINNEE__LLIINNEE, RREEAADDLLIINNEE__PPOOIINNTT, or RREEAADDLLIINNEE__MMAARRKK, those new + values will be reflected in the editing state. + --XX List all key sequences bound to shell commands and the + associated commands in a format that can be reused as in- + put. + + The return value is 0 unless an unrecognized option is given or + an error occurred. + + bbrreeaakk [_n] + Exit from within a ffoorr, wwhhiillee, uunnttiill, or sseelleecctt loop. If _n is + specified, break _n levels. _n must be >= 1. If _n is greater + than the number of enclosing loops, all enclosing loops are ex- + ited. The return value is 0 unless _n is not greater than or + equal to 1. + + bbuuiillttiinn _s_h_e_l_l_-_b_u_i_l_t_i_n [_a_r_g_u_m_e_n_t_s] + Execute the specified shell builtin, passing it _a_r_g_u_m_e_n_t_s, and + return its exit status. This is useful when defining a function + whose name is the same as a shell builtin, retaining the func- + tionality of the builtin within the function. The ccdd builtin is + commonly redefined this way. The return status is false if + _s_h_e_l_l_-_b_u_i_l_t_i_n is not a shell builtin command. + + ccaalllleerr [_e_x_p_r] + Returns the context of any active subroutine call (a shell func- + tion or a script executed with the .. or ssoouurrccee builtins). With- + out _e_x_p_r, ccaalllleerr displays the line number and source filename of + the current subroutine call. If a non-negative integer is sup- + plied as _e_x_p_r, ccaalllleerr displays the line number, subroutine name, + and source file corresponding to that position in the current + execution call stack. This extra information may be used, for + example, to print a stack trace. The current frame is frame 0. + The return value is 0 unless the shell is not executing a sub- + routine call or _e_x_p_r does not correspond to a valid position in + the call stack. + + ccdd [--LL|[--PP [--ee]] [-@]] [_d_i_r] + Change the current directory to _d_i_r. if _d_i_r is not supplied, + the value of the HHOOMMEE shell variable is the default. Any addi- + tional arguments following _d_i_r are ignored. The variable CCDDPPAATTHH + defines the search path for the directory containing _d_i_r: each + directory name in CCDDPPAATTHH is searched for _d_i_r. Alternative di- + rectory names in CCDDPPAATTHH are separated by a colon (:). A null + directory name in CCDDPPAATTHH is the same as the current directory, + i.e., ``..''. If _d_i_r begins with a slash (/), then CCDDPPAATTHH is not + used. The --PP option causes ccdd to use the physical directory + structure by resolving symbolic links while traversing _d_i_r and + before processing instances of _._. in _d_i_r (see also the --PP option + to the sseett builtin command); the --LL option forces symbolic links + to be followed by resolving the link after processing instances + of _._. in _d_i_r. If _._. appears in _d_i_r, it is processed by removing + the immediately previous pathname component from _d_i_r, back to a + slash or the beginning of _d_i_r. If the --ee option is supplied + with --PP, and the current working directory cannot be success- + fully determined after a successful directory change, ccdd will + return an unsuccessful status. On systems that support it, the + --@@ option presents the extended attributes associated with a + file as a directory. An argument of -- is converted to $$OOLLDDPPWWDD + before the directory change is attempted. If a non-empty direc- + tory name from CCDDPPAATTHH is used, or if -- is the first argument, + and the directory change is successful, the absolute pathname of + the new working directory is written to the standard output. + The return value is true if the directory was successfully + changed; false otherwise. + + ccoommmmaanndd [--ppVVvv] _c_o_m_m_a_n_d [_a_r_g ...] + Run _c_o_m_m_a_n_d with _a_r_g_s suppressing the normal shell function + lookup. Only builtin commands or commands found in the PPAATTHH are + executed. If the --pp option is given, the search for _c_o_m_m_a_n_d is + performed using a default value for PPAATTHH that is guaranteed to + find all of the standard utilities. If either the --VV or --vv op- + tion is supplied, a description of _c_o_m_m_a_n_d is printed. The --vv + option causes a single word indicating the command or filename + used to invoke _c_o_m_m_a_n_d to be displayed; the --VV option produces a + more verbose description. If the --VV or --vv option is supplied, + the exit status is 0 if _c_o_m_m_a_n_d was found, and 1 if not. If + neither option is supplied and an error occurred or _c_o_m_m_a_n_d can- + not be found, the exit status is 127. Otherwise, the exit sta- + tus of the ccoommmmaanndd builtin is the exit status of _c_o_m_m_a_n_d. + + ccoommppggeenn [_o_p_t_i_o_n] [_w_o_r_d] + Generate possible completion matches for _w_o_r_d according to the + _o_p_t_i_o_ns, which may be any option accepted by the ccoommpplleettee + builtin with the exception of --pp and --rr, and write the matches + to the standard output. When using the --FF or --CC options, the + various shell variables set by the programmable completion fa- + cilities, while available, will not have useful values. + + The matches will be generated in the same way as if the program- + mable completion code had generated them directly from a comple- + tion specification with the same flags. If _w_o_r_d is specified, + only those completions matching _w_o_r_d will be displayed. + + The return value is true unless an invalid option is supplied, + or no matches were generated. + + ccoommpplleettee [--aabbccddeeffggjjkkssuuvv] [--oo _c_o_m_p_-_o_p_t_i_o_n] [--DDEEII] [--AA _a_c_t_i_o_n] [--GG _g_l_o_b_- + _p_a_t] [--WW _w_o_r_d_l_i_s_t] + [--FF _f_u_n_c_t_i_o_n] [--CC _c_o_m_m_a_n_d] [--XX _f_i_l_t_e_r_p_a_t] [--PP _p_r_e_f_i_x] [--SS _s_u_f_- + _f_i_x] _n_a_m_e [_n_a_m_e _._._.] + ccoommpplleettee --pprr [--DDEEII] [_n_a_m_e ...] + Specify how arguments to each _n_a_m_e should be completed. If the + --pp option is supplied, or if no options are supplied, existing + completion specifications are printed in a way that allows them + to be reused as input. The --rr option removes a completion spec- + ification for each _n_a_m_e, or, if no _n_a_m_es are supplied, all com- + pletion specifications. The --DD option indicates that other sup- + plied options and actions should apply to the ``default'' com- + mand completion; that is, completion attempted on a command for + which no completion has previously been defined. The --EE option + indicates that other supplied options and actions should apply + to ``empty'' command completion; that is, completion attempted + on a blank line. The --II option indicates that other supplied + options and actions should apply to completion on the initial + non-assignment word on the line, or after a command delimiter + such as ;; or ||, which is usually command name completion. If + multiple options are supplied, the --DD option takes precedence + over --EE, and both take precedence over --II. If any of --DD, --EE, or + --II are supplied, any other _n_a_m_e arguments are ignored; these + completions only apply to the case specified by the option. + + The process of applying these completion specifications when + word completion is attempted is described above under PPrrooggrraamm-- + mmaabbllee CCoommpplleettiioonn. + + Other options, if specified, have the following meanings. The + arguments to the --GG, --WW, and --XX options (and, if necessary, the + --PP and --SS options) should be quoted to protect them from expan- + sion before the ccoommpplleettee builtin is invoked. + --oo _c_o_m_p_-_o_p_t_i_o_n + The _c_o_m_p_-_o_p_t_i_o_n controls several aspects of the comp- + spec's behavior beyond the simple generation of comple- + tions. _c_o_m_p_-_o_p_t_i_o_n may be one of: + bbaasshhddeeffaauulltt + Perform the rest of the default bbaasshh completions + if the compspec generates no matches. + ddeeffaauulltt Use readline's default filename completion if + the compspec generates no matches. + ddiirrnnaammeess + Perform directory name completion if the comp- + spec generates no matches. + ffiilleennaammeess + Tell readline that the compspec generates file- + names, so it can perform any filename-specific + processing (like adding a slash to directory + names, quoting special characters, or suppress- + ing trailing spaces). Intended to be used with + shell functions. + nnooqquuoottee Tell readline not to quote the completed words + if they are filenames (quoting filenames is the + default). + nnoossoorrtt Tell readline not to sort the list of possible + completions alphabetically. + nnoossppaaccee Tell readline not to append a space (the de- + fault) to words completed at the end of the + line. + pplluussddiirrss + After any matches defined by the compspec are + generated, directory name completion is at- + tempted and any matches are added to the results + of the other actions. + --AA _a_c_t_i_o_n + The _a_c_t_i_o_n may be one of the following to generate a + list of possible completions: + aalliiaass Alias names. May also be specified as --aa. + aarrrraayyvvaarr + Array variable names. + bbiinnddiinngg RReeaaddlliinnee key binding names. + bbuuiillttiinn Names of shell builtin commands. May also be + specified as --bb. + ccoommmmaanndd Command names. May also be specified as --cc. + ddiirreeccttoorryy + Directory names. May also be specified as --dd. + ddiissaabblleedd + Names of disabled shell builtins. + eennaabblleedd Names of enabled shell builtins. + eexxppoorrtt Names of exported shell variables. May also be + specified as --ee. + ffiillee File names. May also be specified as --ff. + ffuunnccttiioonn + Names of shell functions. + ggrroouupp Group names. May also be specified as --gg. + hheellppttooppiicc + Help topics as accepted by the hheellpp builtin. + hhoossttnnaammee + Hostnames, as taken from the file specified by + the HHOOSSTTFFIILLEE shell variable. + jjoobb Job names, if job control is active. May also + be specified as --jj. + kkeeyywwoorrdd Shell reserved words. May also be specified as + --kk. + rruunnnniinngg Names of running jobs, if job control is active. + sseerrvviiccee Service names. May also be specified as --ss. + sseettoopptt Valid arguments for the --oo option to the sseett + builtin. + sshhoopptt Shell option names as accepted by the sshhoopptt + builtin. + ssiiggnnaall Signal names. + ssttooppppeedd Names of stopped jobs, if job control is active. + uusseerr User names. May also be specified as --uu. + vvaarriiaabbllee + Names of all shell variables. May also be spec- + ified as --vv. + --CC _c_o_m_m_a_n_d + _c_o_m_m_a_n_d is executed in a subshell environment, and its + output is used as the possible completions. + --FF _f_u_n_c_t_i_o_n + The shell function _f_u_n_c_t_i_o_n is executed in the current + shell environment. When the function is executed, the + first argument ($$11) is the name of the command whose ar- + guments are being completed, the second argument ($$22) is + the word being completed, and the third argument ($$33) is + the word preceding the word being completed on the cur- + rent command line. When it finishes, the possible com- + pletions are retrieved from the value of the CCOOMMPPRREEPPLLYY + array variable. + --GG _g_l_o_b_p_a_t + The pathname expansion pattern _g_l_o_b_p_a_t is expanded to + generate the possible completions. + --PP _p_r_e_f_i_x + _p_r_e_f_i_x is added at the beginning of each possible com- + pletion after all other options have been applied. + --SS _s_u_f_f_i_x + _s_u_f_f_i_x is appended to each possible completion after all + other options have been applied. + --WW _w_o_r_d_l_i_s_t + The _w_o_r_d_l_i_s_t is split using the characters in the IIFFSS + special variable as delimiters, and each resultant word + is expanded. Shell quoting is honored within _w_o_r_d_l_i_s_t, + in order to provide a mechanism for the words to contain + shell metacharacters or characters in the value of IIFFSS. + The possible completions are the members of the resul- + tant list which match the word being completed. + --XX _f_i_l_t_e_r_p_a_t + _f_i_l_t_e_r_p_a_t is a pattern as used for pathname expansion. + It is applied to the list of possible completions gener- + ated by the preceding options and arguments, and each + completion matching _f_i_l_t_e_r_p_a_t is removed from the list. + A leading !! in _f_i_l_t_e_r_p_a_t negates the pattern; in this + case, any completion not matching _f_i_l_t_e_r_p_a_t is removed. + + The return value is true unless an invalid option is supplied, + an option other than --pp or --rr is supplied without a _n_a_m_e argu- + ment, an attempt is made to remove a completion specification + for a _n_a_m_e for which no specification exists, or an error occurs + adding a completion specification. + + ccoommppoopptt [--oo _o_p_t_i_o_n] [--DDEEII] [++oo _o_p_t_i_o_n] [_n_a_m_e] + Modify completion options for each _n_a_m_e according to the _o_p_- + _t_i_o_ns, or for the currently-executing completion if no _n_a_m_es are + supplied. If no _o_p_t_i_o_ns are given, display the completion op- + tions for each _n_a_m_e or the current completion. The possible + values of _o_p_t_i_o_n are those valid for the ccoommpplleettee builtin de- + scribed above. The --DD option indicates that other supplied op- + tions should apply to the ``default'' command completion; that + is, completion attempted on a command for which no completion + has previously been defined. The --EE option indicates that other + supplied options should apply to ``empty'' command completion; + that is, completion attempted on a blank line. The --II option + indicates that other supplied options should apply to completion + on the initial non-assignment word on the line, or after a com- + mand delimiter such as ;; or ||, which is usually command name + completion. + + The return value is true unless an invalid option is supplied, + an attempt is made to modify the options for a _n_a_m_e for which no + completion specification exists, or an output error occurs. + + ccoonnttiinnuuee [_n] + Resume the next iteration of the enclosing ffoorr, wwhhiillee, uunnttiill, or + sseelleecctt loop. If _n is specified, resume at the _nth enclosing + loop. _n must be >= 1. If _n is greater than the number of en- + closing loops, the last enclosing loop (the ``top-level'' loop) + is resumed. The return value is 0 unless _n is not greater than + or equal to 1. + + ddeeccllaarree [--aaAAffFFggiiIIllnnrrttuuxx] [--pp] [_n_a_m_e[=_v_a_l_u_e] ...] + ttyyppeesseett [--aaAAffFFggiiIIllnnrrttuuxx] [--pp] [_n_a_m_e[=_v_a_l_u_e] ...] + Declare variables and/or give them attributes. If no _n_a_m_es are + given then display the values of variables. The --pp option will + display the attributes and values of each _n_a_m_e. When --pp is used + with _n_a_m_e arguments, additional options, other than --ff and --FF, + are ignored. When --pp is supplied without _n_a_m_e arguments, it + will display the attributes and values of all variables having + the attributes specified by the additional options. If no other + options are supplied with --pp, ddeeccllaarree will display the at- + tributes and values of all shell variables. The --ff option will + restrict the display to shell functions. The --FF option inhibits + the display of function definitions; only the function name and + attributes are printed. If the eexxttddeebbuugg shell option is enabled + using sshhoopptt, the source file name and line number where each + _n_a_m_e is defined are displayed as well. The --FF option implies + --ff. The --gg option forces variables to be created or modified at + the global scope, even when ddeeccllaarree is executed in a shell func- + tion. It is ignored in all other cases. The --II option causes + local variables to inherit the attributes (except the _n_a_m_e_r_e_f + attribute) and value of any existing variable with the same _n_a_m_e + at a surrounding scope. If there is no existing variable, the + local variable is initially unset. The following options can be + used to restrict output to variables with the specified attri- + bute or to give variables attributes: + --aa Each _n_a_m_e is an indexed array variable (see AArrrraayyss + above). + --AA Each _n_a_m_e is an associative array variable (see AArrrraayyss + above). + --ff Use function names only. + --ii The variable is treated as an integer; arithmetic evalua- + tion (see AARRIITTHHMMEETTIICC EEVVAALLUUAATTIIOONN above) is performed when + the variable is assigned a value. + --ll When the variable is assigned a value, all upper-case + characters are converted to lower-case. The upper-case + attribute is disabled. + --nn Give each _n_a_m_e the _n_a_m_e_r_e_f attribute, making it a name + reference to another variable. That other variable is + defined by the value of _n_a_m_e. All references, assign- + ments, and attribute modifications to _n_a_m_e, except those + using or changing the --nn attribute itself, are performed + on the variable referenced by _n_a_m_e's value. The nameref + attribute cannot be applied to array variables. + --rr Make _n_a_m_es readonly. These names cannot then be assigned + values by subsequent assignment statements or unset. + --tt Give each _n_a_m_e the _t_r_a_c_e attribute. Traced functions in- + herit the DDEEBBUUGG and RREETTUURRNN traps from the calling shell. + The trace attribute has no special meaning for variables. + --uu When the variable is assigned a value, all lower-case + characters are converted to upper-case. The lower-case + attribute is disabled. + --xx Mark _n_a_m_es for export to subsequent commands via the en- + vironment. + + Using `+' instead of `-' turns off the attribute instead, with + the exceptions that ++aa and ++AA may not be used to destroy array + variables and ++rr will not remove the readonly attribute. When + used in a function, ddeeccllaarree and ttyyppeesseett make each _n_a_m_e local, as + with the llooccaall command, unless the --gg option is supplied. If a + variable name is followed by =_v_a_l_u_e, the value of the variable + is set to _v_a_l_u_e. When using --aa or --AA and the compound assign- + ment syntax to create array variables, additional attributes do + not take effect until subsequent assignments. The return value + is 0 unless an invalid option is encountered, an attempt is made + to define a function using ``-f foo=bar'', an attempt is made to + assign a value to a readonly variable, an attempt is made to as- + sign a value to an array variable without using the compound as- + signment syntax (see AArrrraayyss above), one of the _n_a_m_e_s is not a + valid shell variable name, an attempt is made to turn off read- + only status for a readonly variable, an attempt is made to turn + off array status for an array variable, or an attempt is made to + display a non-existent function with --ff. + + ddiirrss [[--ccllppvv]] [[++_n]] [[--_n]] + Without options, displays the list of currently remembered di- + rectories. The default display is on a single line with direc- + tory names separated by spaces. Directories are added to the + list with the ppuusshhdd command; the ppooppdd command removes entries + from the list. The current directory is always the first direc- + tory in the stack. + --cc Clears the directory stack by deleting all of the en- + tries. + --ll Produces a listing using full pathnames; the default + listing format uses a tilde to denote the home directory. + --pp Print the directory stack with one entry per line. + --vv Print the directory stack with one entry per line, pre- + fixing each entry with its index in the stack. + ++_n Displays the _nth entry counting from the left of the list + shown by ddiirrss when invoked without options, starting with + zero. + --_n Displays the _nth entry counting from the right of the + list shown by ddiirrss when invoked without options, starting + with zero. + + The return value is 0 unless an invalid option is supplied or _n + indexes beyond the end of the directory stack. + + ddiissoowwnn [--aarr] [--hh] [_j_o_b_s_p_e_c ... | _p_i_d ... ] + Without options, remove each _j_o_b_s_p_e_c from the table of active + jobs. If _j_o_b_s_p_e_c is not present, and neither the --aa nor the --rr + option is supplied, the _c_u_r_r_e_n_t _j_o_b is used. If the --hh option + is given, each _j_o_b_s_p_e_c is not removed from the table, but is + marked so that SSIIGGHHUUPP is not sent to the job if the shell re- + ceives a SSIIGGHHUUPP. If no _j_o_b_s_p_e_c is supplied, the --aa option means + to remove or mark all jobs; the --rr option without a _j_o_b_s_p_e_c ar- + gument restricts operation to running jobs. The return value is + 0 unless a _j_o_b_s_p_e_c does not specify a valid job. + + eecchhoo [--nneeEE] [_a_r_g ...] + Output the _a_r_gs, separated by spaces, followed by a newline. + The return status is 0 unless a write error occurs. If --nn is + specified, the trailing newline is suppressed. If the --ee option + is given, interpretation of the following backslash-escaped + characters is enabled. The --EE option disables the interpreta- + tion of these escape characters, even on systems where they are + interpreted by default. The xxppgg__eecchhoo shell option may be used + to dynamically determine whether or not eecchhoo expands these es- + cape characters by default. eecchhoo does not interpret ---- to mean + the end of options. eecchhoo interprets the following escape se- + quences: + \\aa alert (bell) + \\bb backspace + \\cc suppress further output + \\ee + \\EE an escape character + \\ff form feed + \\nn new line + \\rr carriage return + \\tt horizontal tab + \\vv vertical tab + \\\\ backslash + \\00_n_n_n the eight-bit character whose value is the octal value + _n_n_n (zero to three octal digits) + \\xx_H_H the eight-bit character whose value is the hexadecimal + value _H_H (one or two hex digits) + \\uu_H_H_H_H the Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value _H_H_H_H (one to four hex digits) + \\UU_H_H_H_H_H_H_H_H + the Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value _H_H_H_H_H_H_H_H (one to eight hex digits) + + eennaabbllee [--aa] [--ddnnppss] [--ff _f_i_l_e_n_a_m_e] [_n_a_m_e ...] + Enable and disable builtin shell commands. Disabling a builtin + allows a disk command which has the same name as a shell builtin + to be executed without specifying a full pathname, even though + the shell normally searches for builtins before disk commands. + If --nn is used, each _n_a_m_e is disabled; otherwise, _n_a_m_e_s are en- + abled. For example, to use the tteesstt binary found via the PPAATTHH + instead of the shell builtin version, run ``enable -n test''. + The --ff option means to load the new builtin command _n_a_m_e from + shared object _f_i_l_e_n_a_m_e, on systems that support dynamic loading. + The --dd option will delete a builtin previously loaded with --ff. + If no _n_a_m_e arguments are given, or if the --pp option is supplied, + a list of shell builtins is printed. With no other option argu- + ments, the list consists of all enabled shell builtins. If --nn + is supplied, only disabled builtins are printed. If --aa is sup- + plied, the list printed includes all builtins, with an indica- + tion of whether or not each is enabled. If --ss is supplied, the + output is restricted to the POSIX _s_p_e_c_i_a_l builtins. The return + value is 0 unless a _n_a_m_e is not a shell builtin or there is an + error loading a new builtin from a shared object. + + eevvaall [_a_r_g ...] + The _a_r_gs are read and concatenated together into a single com- + mand. This command is then read and executed by the shell, and + its exit status is returned as the value of eevvaall. If there are + no _a_r_g_s, or only null arguments, eevvaall returns 0. + + eexxeecc [--ccll] [--aa _n_a_m_e] [_c_o_m_m_a_n_d [_a_r_g_u_m_e_n_t_s]] + If _c_o_m_m_a_n_d is specified, it replaces the shell. No new process + is created. The _a_r_g_u_m_e_n_t_s become the arguments to _c_o_m_m_a_n_d. If + the --ll option is supplied, the shell places a dash at the begin- + ning of the zeroth argument passed to _c_o_m_m_a_n_d. This is what _l_o_- + _g_i_n(1) does. The --cc option causes _c_o_m_m_a_n_d to be executed with + an empty environment. If --aa is supplied, the shell passes _n_a_m_e + as the zeroth argument to the executed command. If _c_o_m_m_a_n_d can- + not be executed for some reason, a non-interactive shell exits, + unless the eexxeeccffaaiill shell option is enabled. In that case, it + returns failure. An interactive shell returns failure if the + file cannot be executed. A subshell exits unconditionally if + eexxeecc fails. If _c_o_m_m_a_n_d is not specified, any redirections take + effect in the current shell, and the return status is 0. If + there is a redirection error, the return status is 1. + + eexxiitt [_n] + Cause the shell to exit with a status of _n. If _n is omitted, + the exit status is that of the last command executed. A trap on + EEXXIITT is executed before the shell terminates. + + eexxppoorrtt [--ffnn] [_n_a_m_e[=_w_o_r_d]] ... + eexxppoorrtt --pp + The supplied _n_a_m_e_s are marked for automatic export to the envi- + ronment of subsequently executed commands. If the --ff option is + given, the _n_a_m_e_s refer to functions. If no _n_a_m_e_s are given, or + if the --pp option is supplied, a list of names of all exported + variables is printed. The --nn option causes the export property + to be removed from each _n_a_m_e. If a variable name is followed by + =_w_o_r_d, the value of the variable is set to _w_o_r_d. eexxppoorrtt returns + an exit status of 0 unless an invalid option is encountered, one + of the _n_a_m_e_s is not a valid shell variable name, or --ff is sup- + plied with a _n_a_m_e that is not a function. + + ffcc [--ee _e_n_a_m_e] [--llnnrr] [_f_i_r_s_t] [_l_a_s_t] + ffcc --ss [_p_a_t=_r_e_p] [_c_m_d] + The first form selects a range of commands from _f_i_r_s_t to _l_a_s_t + from the history list and displays or edits and re-executes + them. _F_i_r_s_t and _l_a_s_t may be specified as a string (to locate + the last command beginning with that string) or as a number (an + index into the history list, where a negative number is used as + an offset from the current command number). When listing, a + _f_i_r_s_t or _l_a_s_t of 0 is equivalent to -1 and -0 is equivalent to + the current command (usually the ffcc command); otherwise 0 is + equivalent to -1 and -0 is invalid. If _l_a_s_t is not specified, + it is set to the current command for listing (so that ``fc -l + -10'' prints the last 10 commands) and to _f_i_r_s_t otherwise. If + _f_i_r_s_t is not specified, it is set to the previous command for + editing and -16 for listing. + + The --nn option suppresses the command numbers when listing. The + --rr option reverses the order of the commands. If the --ll option + is given, the commands are listed on standard output. Other- + wise, the editor given by _e_n_a_m_e is invoked on a file containing + those commands. If _e_n_a_m_e is not given, the value of the FFCCEEDDIITT + variable is used, and the value of EEDDIITTOORR if FFCCEEDDIITT is not set. + If neither variable is set, _v_i is used. When editing is com- + plete, the edited commands are echoed and executed. + + In the second form, _c_o_m_m_a_n_d is re-executed after each instance + of _p_a_t is replaced by _r_e_p. _C_o_m_m_a_n_d is interpreted the same as + _f_i_r_s_t above. A useful alias to use with this is ``r="fc -s"'', + so that typing ``r cc'' runs the last command beginning with + ``cc'' and typing ``r'' re-executes the last command. + + If the first form is used, the return value is 0 unless an in- + valid option is encountered or _f_i_r_s_t or _l_a_s_t specify history + lines out of range. If the --ee option is supplied, the return + value is the value of the last command executed or failure if an + error occurs with the temporary file of commands. If the second + form is used, the return status is that of the command re-exe- + cuted, unless _c_m_d does not specify a valid history line, in + which case ffcc returns failure. + + ffgg [_j_o_b_s_p_e_c] + Resume _j_o_b_s_p_e_c in the foreground, and make it the current job. + If _j_o_b_s_p_e_c is not present, the shell's notion of the _c_u_r_r_e_n_t _j_o_b + is used. The return value is that of the command placed into + the foreground, or failure if run when job control is disabled + or, when run with job control enabled, if _j_o_b_s_p_e_c does not spec- + ify a valid job or _j_o_b_s_p_e_c specifies a job that was started + without job control. + + ggeettooppttss _o_p_t_s_t_r_i_n_g _n_a_m_e [_a_r_g _._._.] + ggeettooppttss is used by shell procedures to parse positional parame- + ters. _o_p_t_s_t_r_i_n_g contains the option characters to be recog- + nized; if a character is followed by a colon, the option is ex- + pected to have an argument, which should be separated from it by + white space. The colon and question mark characters may not be + used as option characters. Each time it is invoked, ggeettooppttss + places the next option in the shell variable _n_a_m_e, initializing + _n_a_m_e if it does not exist, and the index of the next argument to + be processed into the variable OOPPTTIINNDD. OOPPTTIINNDD is initialized to + 1 each time the shell or a shell script is invoked. When an op- + tion requires an argument, ggeettooppttss places that argument into the + variable OOPPTTAARRGG. The shell does not reset OOPPTTIINNDD automatically; + it must be manually reset between multiple calls to ggeettooppttss + within the same shell invocation if a new set of parameters is + to be used. + + When the end of options is encountered, ggeettooppttss exits with a re- + turn value greater than zero. OOPPTTIINNDD is set to the index of the + first non-option argument, and _n_a_m_e is set to ?. + + ggeettooppttss normally parses the positional parameters, but if more + arguments are supplied as _a_r_g values, ggeettooppttss parses those in- + stead. + + ggeettooppttss can report errors in two ways. If the first character + of _o_p_t_s_t_r_i_n_g is a colon, _s_i_l_e_n_t error reporting is used. In + normal operation, diagnostic messages are printed when invalid + options or missing option arguments are encountered. If the + variable OOPPTTEERRRR is set to 0, no error messages will be dis- + played, even if the first character of _o_p_t_s_t_r_i_n_g is not a colon. + + If an invalid option is seen, ggeettooppttss places ? into _n_a_m_e and, if + not silent, prints an error message and unsets OOPPTTAARRGG. If + ggeettooppttss is silent, the option character found is placed in OOPP-- + TTAARRGG and no diagnostic message is printed. + + If a required argument is not found, and ggeettooppttss is not silent, + a question mark (??) is placed in _n_a_m_e, OOPPTTAARRGG is unset, and a + diagnostic message is printed. If ggeettooppttss is silent, then a + colon (::) is placed in _n_a_m_e and OOPPTTAARRGG is set to the option + character found. + + ggeettooppttss returns true if an option, specified or unspecified, is + found. It returns false if the end of options is encountered or + an error occurs. + + hhaasshh [--llrr] [--pp _f_i_l_e_n_a_m_e] [--ddtt] [_n_a_m_e] + Each time hhaasshh is invoked, the full pathname of the command _n_a_m_e + is determined by searching the directories in $$PPAATTHH and remem- + bered. Any previously-remembered pathname is discarded. If the + --pp option is supplied, no path search is performed, and _f_i_l_e_n_a_m_e + is used as the full filename of the command. The --rr option + causes the shell to forget all remembered locations. The --dd op- + tion causes the shell to forget the remembered location of each + _n_a_m_e. If the --tt option is supplied, the full pathname to which + each _n_a_m_e corresponds is printed. If multiple _n_a_m_e arguments + are supplied with --tt, the _n_a_m_e is printed before the hashed full + pathname. The --ll option causes output to be displayed in a for- + mat that may be reused as input. If no arguments are given, or + if only --ll is supplied, information about remembered commands is + printed. The return status is true unless a _n_a_m_e is not found + or an invalid option is supplied. + + hheellpp [--ddmmss] [_p_a_t_t_e_r_n] + Display helpful information about builtin commands. If _p_a_t_t_e_r_n + is specified, hheellpp gives detailed help on all commands matching + _p_a_t_t_e_r_n; otherwise help for all the builtins and shell control + structures is printed. + --dd Display a short description of each _p_a_t_t_e_r_n + --mm Display the description of each _p_a_t_t_e_r_n in a manpage-like + format + --ss Display only a short usage synopsis for each _p_a_t_t_e_r_n + + The return status is 0 unless no command matches _p_a_t_t_e_r_n. + + hhiissttoorryy [[_n]] + hhiissttoorryy --cc + hhiissttoorryy --dd _o_f_f_s_e_t + hhiissttoorryy --dd _s_t_a_r_t-_e_n_d + hhiissttoorryy --aannrrww [_f_i_l_e_n_a_m_e] + hhiissttoorryy --pp _a_r_g [_a_r_g _._._.] + hhiissttoorryy --ss _a_r_g [_a_r_g _._._.] + With no options, display the command history list with line num- + bers. Lines listed with a ** have been modified. An argument of + _n lists only the last _n lines. If the shell variable HHIISSTTTTIIMMEE-- + FFOORRMMAATT is set and not null, it is used as a format string for + _s_t_r_f_t_i_m_e(3) to display the time stamp associated with each dis- + played history entry. No intervening blank is printed between + the formatted time stamp and the history line. If _f_i_l_e_n_a_m_e is + supplied, it is used as the name of the history file; if not, + the value of HHIISSTTFFIILLEE is used. Options, if supplied, have the + following meanings: + --cc Clear the history list by deleting all the entries. + --dd _o_f_f_s_e_t + Delete the history entry at position _o_f_f_s_e_t. If _o_f_f_s_e_t + is negative, it is interpreted as relative to one greater + than the last history position, so negative indices count + back from the end of the history, and an index of -1 + refers to the current hhiissttoorryy --dd command. + --dd _s_t_a_r_t-_e_n_d + Delete the history entries between positions _s_t_a_r_t and + _e_n_d, inclusive. Positive and negative values for _s_t_a_r_t + and _e_n_d are interpreted as described above. + --aa Append the ``new'' history lines to the history file. + These are history lines entered since the beginning of + the current bbaasshh session, but not already appended to the + history file. + --nn Read the history lines not already read from the history + file into the current history list. These are lines ap- + pended to the history file since the beginning of the + current bbaasshh session. + --rr Read the contents of the history file and append them to + the current history list. + --ww Write the current history list to the history file, over- + writing the history file's contents. + --pp Perform history substitution on the following _a_r_g_s and + display the result on the standard output. Does not + store the results in the history list. Each _a_r_g must be + quoted to disable normal history expansion. + --ss Store the _a_r_g_s in the history list as a single entry. + The last command in the history list is removed before + the _a_r_g_s are added. + + If the HHIISSTTTTIIMMEEFFOORRMMAATT variable is set, the time stamp informa- + tion associated with each history entry is written to the his- + tory file, marked with the history comment character. When the + history file is read, lines beginning with the history comment + character followed immediately by a digit are interpreted as + timestamps for the following history entry. The return value is + 0 unless an invalid option is encountered, an error occurs while + reading or writing the history file, an invalid _o_f_f_s_e_t is sup- + plied as an argument to --dd, or the history expansion supplied as + an argument to --pp fails. + + jjoobbss [--llnnpprrss] [ _j_o_b_s_p_e_c ... ] + jjoobbss --xx _c_o_m_m_a_n_d [ _a_r_g_s ... ] + The first form lists the active jobs. The options have the fol- + lowing meanings: + --ll List process IDs in addition to the normal information. + --nn Display information only about jobs that have changed + status since the user was last notified of their status. + --pp List only the process ID of the job's process group + leader. + --rr Display only running jobs. + --ss Display only stopped jobs. + + If _j_o_b_s_p_e_c is given, output is restricted to information about + that job. The return status is 0 unless an invalid option is + encountered or an invalid _j_o_b_s_p_e_c is supplied. + + If the --xx option is supplied, jjoobbss replaces any _j_o_b_s_p_e_c found in + _c_o_m_m_a_n_d or _a_r_g_s with the corresponding process group ID, and ex- + ecutes _c_o_m_m_a_n_d passing it _a_r_g_s, returning its exit status. + + kkiillll [--ss _s_i_g_s_p_e_c | --nn _s_i_g_n_u_m | --_s_i_g_s_p_e_c] [_p_i_d | _j_o_b_s_p_e_c] ... + kkiillll --ll|--LL [_s_i_g_s_p_e_c | _e_x_i_t___s_t_a_t_u_s] + Send the signal named by _s_i_g_s_p_e_c or _s_i_g_n_u_m to the processes + named by _p_i_d or _j_o_b_s_p_e_c. _s_i_g_s_p_e_c is either a case-insensitive + signal name such as SSIIGGKKIILLLL (with or without the SSIIGG prefix) or + a signal number; _s_i_g_n_u_m is a signal number. If _s_i_g_s_p_e_c is not + present, then SSIIGGTTEERRMM is assumed. An argument of --ll lists the + signal names. If any arguments are supplied when --ll is given, + the names of the signals corresponding to the arguments are + listed, and the return status is 0. The _e_x_i_t___s_t_a_t_u_s argument to + --ll is a number specifying either a signal number or the exit + status of a process terminated by a signal. The --LL option is + equivalent to --ll. kkiillll returns true if at least one signal was + successfully sent, or false if an error occurs or an invalid op- + tion is encountered. + + lleett _a_r_g [_a_r_g ...] + Each _a_r_g is an arithmetic expression to be evaluated (see AARRIITTHH-- + MMEETTIICC EEVVAALLUUAATTIIOONN above). If the last _a_r_g evaluates to 0, lleett + returns 1; 0 is returned otherwise. + + llooccaall [_o_p_t_i_o_n] [_n_a_m_e[=_v_a_l_u_e] ... | - ] + For each argument, a local variable named _n_a_m_e is created, and + assigned _v_a_l_u_e. The _o_p_t_i_o_n can be any of the options accepted + by ddeeccllaarree. When llooccaall is used within a function, it causes the + variable _n_a_m_e to have a visible scope restricted to that func- + tion and its children. If _n_a_m_e is -, the set of shell options + is made local to the function in which llooccaall is invoked: shell + options changed using the sseett builtin inside the function are + restored to their original values when the function returns. + The restore is effected as if a series of sseett commands were exe- + cuted to restore the values that were in place before the func- + tion. With no operands, llooccaall writes a list of local variables + to the standard output. It is an error to use llooccaall when not + within a function. The return status is 0 unless llooccaall is used + outside a function, an invalid _n_a_m_e is supplied, or _n_a_m_e is a + readonly variable. + + llooggoouutt Exit a login shell. + + mmaappffiillee [--dd _d_e_l_i_m] [--nn _c_o_u_n_t] [--OO _o_r_i_g_i_n] [--ss _c_o_u_n_t] [--tt] [--uu _f_d] [--CC + _c_a_l_l_b_a_c_k] [--cc _q_u_a_n_t_u_m] [_a_r_r_a_y] + rreeaaddaarrrraayy [--dd _d_e_l_i_m] [--nn _c_o_u_n_t] [--OO _o_r_i_g_i_n] [--ss _c_o_u_n_t] [--tt] [--uu _f_d] [--CC + _c_a_l_l_b_a_c_k] [--cc _q_u_a_n_t_u_m] [_a_r_r_a_y] + Read lines from the standard input into the indexed array vari- + able _a_r_r_a_y, or from file descriptor _f_d if the --uu option is sup- + plied. The variable MMAAPPFFIILLEE is the default _a_r_r_a_y. Options, if + supplied, have the following meanings: + --dd The first character of _d_e_l_i_m is used to terminate each + input line, rather than newline. If _d_e_l_i_m is the empty + string, mmaappffiillee will terminate a line when it reads a NUL + character. + --nn Copy at most _c_o_u_n_t lines. If _c_o_u_n_t is 0, all lines are + copied. + --OO Begin assigning to _a_r_r_a_y at index _o_r_i_g_i_n. The default + index is 0. + --ss Discard the first _c_o_u_n_t lines read. + --tt Remove a trailing _d_e_l_i_m (default newline) from each line + read. + --uu Read lines from file descriptor _f_d instead of the stan- + dard input. + --CC Evaluate _c_a_l_l_b_a_c_k each time _q_u_a_n_t_u_m lines are read. The + --cc option specifies _q_u_a_n_t_u_m. + --cc Specify the number of lines read between each call to + _c_a_l_l_b_a_c_k. + + If --CC is specified without --cc, the default quantum is 5000. + When _c_a_l_l_b_a_c_k is evaluated, it is supplied the index of the next + array element to be assigned and the line to be assigned to that + element as additional arguments. _c_a_l_l_b_a_c_k is evaluated after + the line is read but before the array element is assigned. + + If not supplied with an explicit origin, mmaappffiillee will clear _a_r_- + _r_a_y before assigning to it. + + mmaappffiillee returns successfully unless an invalid option or option + argument is supplied, _a_r_r_a_y is invalid or unassignable, or if + _a_r_r_a_y is not an indexed array. + + ppooppdd [-nn] [+_n] [-_n] + Removes entries from the directory stack. With no arguments, + removes the top directory from the stack, and performs a ccdd to + the new top directory. Arguments, if supplied, have the follow- + ing meanings: + --nn Suppresses the normal change of directory when removing + directories from the stack, so that only the stack is ma- + nipulated. + ++_n Removes the _nth entry counting from the left of the list + shown by ddiirrss, starting with zero. For example: ``popd + +0'' removes the first directory, ``popd +1'' the second. + --_n Removes the _nth entry counting from the right of the list + shown by ddiirrss, starting with zero. For example: ``popd + -0'' removes the last directory, ``popd -1'' the next to + last. + + If the ppooppdd command is successful, a ddiirrss is performed as well, + and the return status is 0. ppooppdd returns false if an invalid + option is encountered, the directory stack is empty, a non-exis- + tent directory stack entry is specified, or the directory change + fails. + + pprriinnttff [--vv _v_a_r] _f_o_r_m_a_t [_a_r_g_u_m_e_n_t_s] + Write the formatted _a_r_g_u_m_e_n_t_s to the standard output under the + control of the _f_o_r_m_a_t. The --vv option causes the output to be + assigned to the variable _v_a_r rather than being printed to the + standard output. + + The _f_o_r_m_a_t is a character string which contains three types of + objects: plain characters, which are simply copied to standard + output, character escape sequences, which are converted and + copied to the standard output, and format specifications, each + of which causes printing of the next successive _a_r_g_u_m_e_n_t. In + addition to the standard _p_r_i_n_t_f(1) format specifications, pprriinnttff + interprets the following extensions: + %%bb causes pprriinnttff to expand backslash escape sequences in the + corresponding _a_r_g_u_m_e_n_t in the same way as eecchhoo --ee. + %%qq causes pprriinnttff to output the corresponding _a_r_g_u_m_e_n_t in a + format that can be reused as shell input. + %%((_d_a_t_e_f_m_t))TT + causes pprriinnttff to output the date-time string resulting + from using _d_a_t_e_f_m_t as a format string for _s_t_r_f_t_i_m_e(3). + The corresponding _a_r_g_u_m_e_n_t is an integer representing the + number of seconds since the epoch. Two special argument + values may be used: -1 represents the current time, and + -2 represents the time the shell was invoked. If no ar- + gument is specified, conversion behaves as if -1 had been + given. This is an exception to the usual pprriinnttff behav- + ior. + + The %b, %q, and %T directives all use the field width and preci- + sion arguments from the format specification and write that many + bytes from (or use that wide a field for) the expanded argument, + which usually contains more characters than the original. + + Arguments to non-string format specifiers are treated as C con- + stants, except that a leading plus or minus sign is allowed, and + if the leading character is a single or double quote, the value + is the ASCII value of the following character. + + The _f_o_r_m_a_t is reused as necessary to consume all of the _a_r_g_u_- + _m_e_n_t_s. If the _f_o_r_m_a_t requires more _a_r_g_u_m_e_n_t_s than are supplied, + the extra format specifications behave as if a zero value or + null string, as appropriate, had been supplied. The return + value is zero on success, non-zero on failure. + + ppuusshhdd [--nn] [+_n] [-_n] + ppuusshhdd [--nn] [_d_i_r] + Adds a directory to the top of the directory stack, or rotates + the stack, making the new top of the stack the current working + directory. With no arguments, ppuusshhdd exchanges the top two di- + rectories and returns 0, unless the directory stack is empty. + Arguments, if supplied, have the following meanings: + --nn Suppresses the normal change of directory when rotating + or adding directories to the stack, so that only the + stack is manipulated. + ++_n Rotates the stack so that the _nth directory (counting + from the left of the list shown by ddiirrss, starting with + zero) is at the top. + --_n Rotates the stack so that the _nth directory (counting + from the right of the list shown by ddiirrss, starting with + zero) is at the top. + _d_i_r Adds _d_i_r to the directory stack at the top, making it the + new current working directory as if it had been supplied + as the argument to the ccdd builtin. + + If the ppuusshhdd command is successful, a ddiirrss is performed as well. + If the first form is used, ppuusshhdd returns 0 unless the cd to _d_i_r + fails. With the second form, ppuusshhdd returns 0 unless the direc- + tory stack is empty, a non-existent directory stack element is + specified, or the directory change to the specified new current + directory fails. + + ppwwdd [--LLPP] + Print the absolute pathname of the current working directory. + The pathname printed contains no symbolic links if the --PP option + is supplied or the --oo pphhyyssiiccaall option to the sseett builtin command + is enabled. If the --LL option is used, the pathname printed may + contain symbolic links. The return status is 0 unless an error + occurs while reading the name of the current directory or an in- + valid option is supplied. + + rreeaadd [--eerrss] [--aa _a_n_a_m_e] [--dd _d_e_l_i_m] [--ii _t_e_x_t] [--nn _n_c_h_a_r_s] [--NN _n_c_h_a_r_s] [--pp + _p_r_o_m_p_t] [--tt _t_i_m_e_o_u_t] [--uu _f_d] [_n_a_m_e ...] + One line is read from the standard input, or from the file de- + scriptor _f_d supplied as an argument to the --uu option, split into + words as described above under WWoorrdd SSpplliittttiinngg, and the first + word is assigned to the first _n_a_m_e, the second word to the sec- + ond _n_a_m_e, and so on. If there are more words than names, the + remaining words and their intervening delimiters are assigned to + the last _n_a_m_e. If there are fewer words read from the input + stream than names, the remaining names are assigned empty val- + ues. The characters in IIFFSS are used to split the line into + words using the same rules the shell uses for expansion (de- + scribed above under WWoorrdd SSpplliittttiinngg). The backslash character + (\\) may be used to remove any special meaning for the next char- + acter read and for line continuation. Options, if supplied, + have the following meanings: + --aa _a_n_a_m_e + The words are assigned to sequential indices of the array + variable _a_n_a_m_e, starting at 0. _a_n_a_m_e is unset before any + new values are assigned. Other _n_a_m_e arguments are ig- + nored. + --dd _d_e_l_i_m + The first character of _d_e_l_i_m is used to terminate the in- + put line, rather than newline. If _d_e_l_i_m is the empty + string, rreeaadd will terminate a line when it reads a NUL + character. + --ee If the standard input is coming from a terminal, rreeaaddlliinnee + (see RREEAADDLLIINNEE above) is used to obtain the line. Read- + line uses the current (or default, if line editing was + not previously active) editing settings, but uses Read- + line's default filename completion. + --ii _t_e_x_t + If rreeaaddlliinnee is being used to read the line, _t_e_x_t is + placed into the editing buffer before editing begins. + --nn _n_c_h_a_r_s + rreeaadd returns after reading _n_c_h_a_r_s characters rather than + waiting for a complete line of input, but honors a delim- + iter if fewer than _n_c_h_a_r_s characters are read before the + delimiter. + --NN _n_c_h_a_r_s + rreeaadd returns after reading exactly _n_c_h_a_r_s characters + rather than waiting for a complete line of input, unless + EOF is encountered or rreeaadd times out. Delimiter charac- + ters encountered in the input are not treated specially + and do not cause rreeaadd to return until _n_c_h_a_r_s characters + are read. The result is not split on the characters in + IIFFSS; the intent is that the variable is assigned exactly + the characters read (with the exception of backslash; see + the --rr option below). + --pp _p_r_o_m_p_t + Display _p_r_o_m_p_t on standard error, without a trailing new- + line, before attempting to read any input. The prompt is + displayed only if input is coming from a terminal. + --rr Backslash does not act as an escape character. The back- + slash is considered to be part of the line. In particu- + lar, a backslash-newline pair may not then be used as a + line continuation. + --ss Silent mode. If input is coming from a terminal, charac- + ters are not echoed. + --tt _t_i_m_e_o_u_t + Cause rreeaadd to time out and return failure if a complete + line of input (or a specified number of characters) is + not read within _t_i_m_e_o_u_t seconds. _t_i_m_e_o_u_t may be a deci- + mal number with a fractional portion following the deci- + mal point. This option is only effective if rreeaadd is + reading input from a terminal, pipe, or other special + file; it has no effect when reading from regular files. + If rreeaadd times out, rreeaadd saves any partial input read into + the specified variable _n_a_m_e. If _t_i_m_e_o_u_t is 0, rreeaadd re- + turns immediately, without trying to read any data. The + exit status is 0 if input is available on the specified + file descriptor, non-zero otherwise. The exit status is + greater than 128 if the timeout is exceeded. + --uu _f_d Read input from file descriptor _f_d. + + If no _n_a_m_e_s are supplied, the line read, without the ending de- + limiter but otherwise unmodified, is assigned to the variable + RREEPPLLYY. The exit status is zero, unless end-of-file is encoun- + tered, rreeaadd times out (in which case the status is greater than + 128), a variable assignment error (such as assigning to a read- + only variable) occurs, or an invalid file descriptor is supplied + as the argument to --uu. + + rreeaaddoonnllyy [--aaAAff] [--pp] [_n_a_m_e[=_w_o_r_d] ...] + The given _n_a_m_e_s are marked readonly; the values of these _n_a_m_e_s + may not be changed by subsequent assignment. If the --ff option + is supplied, the functions corresponding to the _n_a_m_e_s are so + marked. The --aa option restricts the variables to indexed ar- + rays; the --AA option restricts the variables to associative ar- + rays. If both options are supplied, --AA takes precedence. If no + _n_a_m_e arguments are given, or if the --pp option is supplied, a + list of all readonly names is printed. The other options may be + used to restrict the output to a subset of the set of readonly + names. The --pp option causes output to be displayed in a format + that may be reused as input. If a variable name is followed by + =_w_o_r_d, the value of the variable is set to _w_o_r_d. The return + status is 0 unless an invalid option is encountered, one of the + _n_a_m_e_s is not a valid shell variable name, or --ff is supplied with + a _n_a_m_e that is not a function. + + rreettuurrnn [_n] + Causes a function to stop executing and return the value speci- + fied by _n to its caller. If _n is omitted, the return status is + that of the last command executed in the function body. If rree-- + ttuurrnn is executed by a trap handler, the last command used to de- + termine the status is the last command executed before the trap + handler. If rreettuurrnn is executed during a DDEEBBUUGG trap, the last + command used to determine the status is the last command exe- + cuted by the trap handler before rreettuurrnn was invoked. If rreettuurrnn + is used outside a function, but during execution of a script by + the .. (ssoouurrccee) command, it causes the shell to stop executing + that script and return either _n or the exit status of the last + command executed within the script as the exit status of the + script. If _n is supplied, the return value is its least signif- + icant 8 bits. The return status is non-zero if rreettuurrnn is sup- + plied a non-numeric argument, or is used outside a function and + not during execution of a script by .. or ssoouurrccee. Any command + associated with the RREETTUURRNN trap is executed before execution re- + sumes after the function or script. + + sseett [----aabbeeffhhkkmmnnppttuuvvxxBBCCEEHHPPTT] [--oo _o_p_t_i_o_n_-_n_a_m_e] [_a_r_g ...] + sseett [++aabbeeffhhkkmmnnppttuuvvxxBBCCEEHHPPTT] [++oo _o_p_t_i_o_n_-_n_a_m_e] [_a_r_g ...] + Without options, the name and value of each shell variable are + displayed in a format that can be reused as input for setting or + resetting the currently-set variables. Read-only variables can- + not be reset. In _p_o_s_i_x _m_o_d_e, only shell variables are listed. + The output is sorted according to the current locale. When op- + tions are specified, they set or unset shell attributes. Any + arguments remaining after option processing are treated as val- + ues for the positional parameters and are assigned, in order, to + $$11, $$22, ...... $$_n. Options, if specified, have the following + meanings: + --aa Each variable or function that is created or modified is + given the export attribute and marked for export to the + environment of subsequent commands. + --bb Report the status of terminated background jobs immedi- + ately, rather than before the next primary prompt. This + is effective only when job control is enabled. + --ee Exit immediately if a _p_i_p_e_l_i_n_e (which may consist of a + single _s_i_m_p_l_e _c_o_m_m_a_n_d), a _l_i_s_t, or a _c_o_m_p_o_u_n_d _c_o_m_m_a_n_d + (see SSHHEELLLL GGRRAAMMMMAARR above), exits with a non-zero status. + The shell does not exit if the command that fails is + part of the command list immediately following a wwhhiillee + or uunnttiill keyword, part of the test following the iiff or + eelliiff reserved words, part of any command executed in a + &&&& or |||| list except the command following the final &&&& + or ||||, any command in a pipeline but the last, or if the + command's return value is being inverted with !!. If a + compound command other than a subshell returns a non- + zero status because a command failed while --ee was being + ignored, the shell does not exit. A trap on EERRRR, if + set, is executed before the shell exits. This option + applies to the shell environment and each subshell envi- + ronment separately (see CCOOMMMMAANNDD EEXXEECCUUTTIIOONN EENNVVIIRROONNMMEENNTT + above), and may cause subshells to exit before executing + all the commands in the subshell. + + If a compound command or shell function executes in a + context where --ee is being ignored, none of the commands + executed within the compound command or function body + will be affected by the --ee setting, even if --ee is set + and a command returns a failure status. If a compound + command or shell function sets --ee while executing in a + context where --ee is ignored, that setting will not have + any effect until the compound command or the command + containing the function call completes. + --ff Disable pathname expansion. + --hh Remember the location of commands as they are looked up + for execution. This is enabled by default. + --kk All arguments in the form of assignment statements are + placed in the environment for a command, not just those + that precede the command name. + --mm Monitor mode. Job control is enabled. This option is + on by default for interactive shells on systems that + support it (see JJOOBB CCOONNTTRROOLL above). All processes run + in a separate process group. When a background job com- + pletes, the shell prints a line containing its exit sta- + tus. + --nn Read commands but do not execute them. This may be used + to check a shell script for syntax errors. This is ig- + nored by interactive shells. + --oo _o_p_t_i_o_n_-_n_a_m_e + The _o_p_t_i_o_n_-_n_a_m_e can be one of the following: + aalllleexxppoorrtt + Same as --aa. + bbrraacceeeexxppaanndd + Same as --BB. + eemmaaccss Use an emacs-style command line editing inter- + face. This is enabled by default when the shell + is interactive, unless the shell is started with + the ----nnooeeddiittiinngg option. This also affects the + editing interface used for rreeaadd --ee. + eerrrreexxiitt Same as --ee. + eerrrrttrraaccee + Same as --EE. + ffuunnccttrraaccee + Same as --TT. + hhaasshhaallll Same as --hh. + hhiisstteexxppaanndd + Same as --HH. + hhiissttoorryy Enable command history, as described above under + HHIISSTTOORRYY. This option is on by default in inter- + active shells. + iiggnnoorreeeeooff + The effect is as if the shell command ``IG- + NOREEOF=10'' had been executed (see SShheellll VVaarrii-- + aabblleess above). + kkeeyywwoorrdd Same as --kk. + mmoonniittoorr Same as --mm. + nnoocclloobbbbeerr + Same as --CC. + nnooeexxeecc Same as --nn. + nnoogglloobb Same as --ff. + nnoolloogg Currently ignored. + nnoottiiffyy Same as --bb. + nnoouunnsseett Same as --uu. + oonneeccmmdd Same as --tt. + pphhyyssiiccaall + Same as --PP. + ppiippeeffaaiill + If set, the return value of a pipeline is the + value of the last (rightmost) command to exit + with a non-zero status, or zero if all commands + in the pipeline exit successfully. This option + is disabled by default. + ppoossiixx Change the behavior of bbaasshh where the default + operation differs from the POSIX standard to + match the standard (_p_o_s_i_x _m_o_d_e). See SSEEEE AALLSSOO + below for a reference to a document that details + how posix mode affects bash's behavior. + pprriivviilleeggeedd + Same as --pp. + vveerrbboossee Same as --vv. + vvii Use a vi-style command line editing interface. + This also affects the editing interface used for + rreeaadd --ee. + xxttrraaccee Same as --xx. + If --oo is supplied with no _o_p_t_i_o_n_-_n_a_m_e, the values of the + current options are printed. If ++oo is supplied with no + _o_p_t_i_o_n_-_n_a_m_e, a series of sseett commands to recreate the + current option settings is displayed on the standard + output. + --pp Turn on _p_r_i_v_i_l_e_g_e_d mode. In this mode, the $$EENNVV and + $$BBAASSHH__EENNVV files are not processed, shell functions are + not inherited from the environment, and the SSHHEELLLLOOPPTTSS, + BBAASSHHOOPPTTSS, CCDDPPAATTHH, and GGLLOOBBIIGGNNOORREE variables, if they ap- + pear in the environment, are ignored. If the shell is + started with the effective user (group) id not equal to + the real user (group) id, and the --pp option is not sup- + plied, these actions are taken and the effective user id + is set to the real user id. If the --pp option is sup- + plied at startup, the effective user id is not reset. + Turning this option off causes the effective user and + group ids to be set to the real user and group ids. + --tt Exit after reading and executing one command. + --uu Treat unset variables and parameters other than the spe- + cial parameters "@" and "*" as an error when performing + parameter expansion. If expansion is attempted on an + unset variable or parameter, the shell prints an error + message, and, if not interactive, exits with a non-zero + status. + --vv Print shell input lines as they are read. + --xx After expanding each _s_i_m_p_l_e _c_o_m_m_a_n_d, ffoorr command, ccaassee + command, sseelleecctt command, or arithmetic ffoorr command, dis- + play the expanded value of PPSS44, followed by the command + and its expanded arguments or associated word list. + --BB The shell performs brace expansion (see BBrraaccee EExxppaannssiioonn + above). This is on by default. + --CC If set, bbaasshh does not overwrite an existing file with + the >>, >>&&, and <<>> redirection operators. This may be + overridden when creating output files by using the redi- + rection operator >>|| instead of >>. + --EE If set, any trap on EERRRR is inherited by shell functions, + command substitutions, and commands executed in a sub- + shell environment. The EERRRR trap is normally not inher- + ited in such cases. + --HH Enable !! style history substitution. This option is on + by default when the shell is interactive. + --PP If set, the shell does not resolve symbolic links when + executing commands such as ccdd that change the current + working directory. It uses the physical directory + structure instead. By default, bbaasshh follows the logical + chain of directories when performing commands which + change the current directory. + --TT If set, any traps on DDEEBBUUGG and RREETTUURRNN are inherited by + shell functions, command substitutions, and commands ex- + ecuted in a subshell environment. The DDEEBBUUGG and RREETTUURRNN + traps are normally not inherited in such cases. + ---- If no arguments follow this option, then the positional + parameters are unset. Otherwise, the positional parame- + ters are set to the _a_r_gs, even if some of them begin + with a --. + -- Signal the end of options, cause all remaining _a_r_gs to + be assigned to the positional parameters. The --xx and --vv + options are turned off. If there are no _a_r_gs, the posi- + tional parameters remain unchanged. + + The options are off by default unless otherwise noted. Using + + rather than - causes these options to be turned off. The op- + tions can also be specified as arguments to an invocation of the + shell. The current set of options may be found in $$--. The re- + turn status is always true unless an invalid option is encoun- + tered. + + sshhiifftt [_n] + The positional parameters from _n+1 ... are renamed to $$11 ........ + Parameters represented by the numbers $$## down to $$##-_n+1 are un- + set. _n must be a non-negative number less than or equal to $$##. + If _n is 0, no parameters are changed. If _n is not given, it is + assumed to be 1. If _n is greater than $$##, the positional param- + eters are not changed. The return status is greater than zero + if _n is greater than $$## or less than zero; otherwise 0. + + sshhoopptt [--ppqqssuu] [--oo] [_o_p_t_n_a_m_e ...] + Toggle the values of settings controlling optional shell behav- + ior. The settings can be either those listed below, or, if the + --oo option is used, those available with the --oo option to the sseett + builtin command. With no options, or with the --pp option, a list + of all settable options is displayed, with an indication of + whether or not each is set; if _o_p_t_n_a_m_e_s are supplied, the output + is restricted to those options. The --pp option causes output to + be displayed in a form that may be reused as input. Other op- + tions have the following meanings: + --ss Enable (set) each _o_p_t_n_a_m_e. + --uu Disable (unset) each _o_p_t_n_a_m_e. + --qq Suppresses normal output (quiet mode); the return status + indicates whether the _o_p_t_n_a_m_e is set or unset. If multi- + ple _o_p_t_n_a_m_e arguments are given with --qq, the return sta- + tus is zero if all _o_p_t_n_a_m_e_s are enabled; non-zero other- + wise. + --oo Restricts the values of _o_p_t_n_a_m_e to be those defined for + the --oo option to the sseett builtin. + + If either --ss or --uu is used with no _o_p_t_n_a_m_e arguments, sshhoopptt + shows only those options which are set or unset, respectively. + Unless otherwise noted, the sshhoopptt options are disabled (unset) + by default. + + The return status when listing options is zero if all _o_p_t_n_a_m_e_s + are enabled, non-zero otherwise. When setting or unsetting op- + tions, the return status is zero unless an _o_p_t_n_a_m_e is not a + valid shell option. + + The list of sshhoopptt options is: + + aassssoocc__eexxppaanndd__oonnccee + If set, the shell suppresses multiple evaluation of as- + sociative array subscripts during arithmetic expression + evaluation, while executing builtins that can perform + variable assignments, and while executing builtins that + perform array dereferencing. + aauuttooccdd If set, a command name that is the name of a directory + is executed as if it were the argument to the ccdd com- + mand. This option is only used by interactive shells. + ccddaabbllee__vvaarrss + If set, an argument to the ccdd builtin command that is + not a directory is assumed to be the name of a variable + whose value is the directory to change to. + ccddssppeellll If set, minor errors in the spelling of a directory com- + ponent in a ccdd command will be corrected. The errors + checked for are transposed characters, a missing charac- + ter, and one character too many. If a correction is + found, the corrected filename is printed, and the com- + mand proceeds. This option is only used by interactive + shells. + cchheecckkhhaasshh + If set, bbaasshh checks that a command found in the hash ta- + ble exists before trying to execute it. If a hashed + command no longer exists, a normal path search is per- + formed. + cchheecckkjjoobbss + If set, bbaasshh lists the status of any stopped and running + jobs before exiting an interactive shell. If any jobs + are running, this causes the exit to be deferred until a + second exit is attempted without an intervening command + (see JJOOBB CCOONNTTRROOLL above). The shell always postpones ex- + iting if any jobs are stopped. + cchheecckkwwiinnssiizzee + If set, bbaasshh checks the window size after each external + (non-builtin) command and, if necessary, updates the + values of LLIINNEESS and CCOOLLUUMMNNSS. This option is enabled by + default. + ccmmddhhiisstt If set, bbaasshh attempts to save all lines of a multiple- + line command in the same history entry. This allows + easy re-editing of multi-line commands. This option is + enabled by default, but only has an effect if command + history is enabled, as described above under HHIISSTTOORRYY. + ccoommppaatt3311 + ccoommppaatt3322 + ccoommppaatt4400 + ccoommppaatt4411 + ccoommppaatt4422 + ccoommppaatt4433 + ccoommppaatt4444 + These control aspects of the shell's compatibility mode + (see SSHHEELLLL CCOOMMPPAATTIIBBIILLIITTYY MMOODDEE below). + + ccoommpplleettee__ffuullllqquuoottee + If set, bbaasshh quotes all shell metacharacters in file- + names and directory names when performing completion. + If not set, bbaasshh removes metacharacters such as the dol- + lar sign from the set of characters that will be quoted + in completed filenames when these metacharacters appear + in shell variable references in words to be completed. + This means that dollar signs in variable names that ex- + pand to directories will not be quoted; however, any + dollar signs appearing in filenames will not be quoted, + either. This is active only when bash is using back- + slashes to quote completed filenames. This variable is + set by default, which is the default bash behavior in + versions through 4.2. + + ddiirreexxppaanndd + If set, bbaasshh replaces directory names with the results + of word expansion when performing filename completion. + This changes the contents of the readline editing buf- + fer. If not set, bbaasshh attempts to preserve what the + user typed. + + ddiirrssppeellll + If set, bbaasshh attempts spelling correction on directory + names during word completion if the directory name ini- + tially supplied does not exist. + + ddoottgglloobb If set, bbaasshh includes filenames beginning with a `.' in + the results of pathname expansion. The filenames ````..'''' + and ````....'''' must always be matched explicitly, even if + ddoottgglloobb is set. + + eexxeeccffaaiill + If set, a non-interactive shell will not exit if it can- + not execute the file specified as an argument to the + eexxeecc builtin command. An interactive shell does not + exit if eexxeecc fails. + + eexxppaanndd__aalliiaasseess + If set, aliases are expanded as described above under + AALLIIAASSEESS. This option is enabled by default for interac- + tive shells. + + eexxttddeebbuugg + If set at shell invocation, or in a shell startup file, + arrange to execute the debugger profile before the shell + starts, identical to the ----ddeebbuuggggeerr option. If set af- + ter invocation, behavior intended for use by debuggers + is enabled: + + 11.. The --FF option to the ddeeccllaarree builtin displays the + source file name and line number corresponding to + each function name supplied as an argument. + + 22.. If the command run by the DDEEBBUUGG trap returns a + non-zero value, the next command is skipped and + not executed. + + 33.. If the command run by the DDEEBBUUGG trap returns a + value of 2, and the shell is executing in a sub- + routine (a shell function or a shell script exe- + cuted by the .. or ssoouurrccee builtins), the shell + simulates a call to rreettuurrnn. + + 44.. BBAASSHH__AARRGGCC and BBAASSHH__AARRGGVV are updated as described + in their descriptions above. + + 55.. Function tracing is enabled: command substitu- + tion, shell functions, and subshells invoked with + (( _c_o_m_m_a_n_d )) inherit the DDEEBBUUGG and RREETTUURRNN traps. + + 66.. Error tracing is enabled: command substitution, + shell functions, and subshells invoked with (( + _c_o_m_m_a_n_d )) inherit the EERRRR trap. + + eexxttgglloobb If set, the extended pattern matching features described + above under PPaatthhnnaammee EExxppaannssiioonn are enabled. + + eexxttqquuoottee + If set, $$'_s_t_r_i_n_g' and $$"_s_t_r_i_n_g" quoting is performed + within $${{_p_a_r_a_m_e_t_e_r}} expansions enclosed in double + quotes. This option is enabled by default. + + ffaaiillgglloobb + If set, patterns which fail to match filenames during + pathname expansion result in an expansion error. + + ffoorrccee__ffiiggnnoorree + If set, the suffixes specified by the FFIIGGNNOORREE shell + variable cause words to be ignored when performing word + completion even if the ignored words are the only possi- + ble completions. See SSHHEELLLL VVAARRIIAABBLLEESS above for a de- + scription of FFIIGGNNOORREE. This option is enabled by de- + fault. + + gglloobbaasscciiiirraannggeess + If set, range expressions used in pattern matching + bracket expressions (see PPaatttteerrnn MMaattcchhiinngg above) behave + as if in the traditional C locale when performing com- + parisons. That is, the current locale's collating se- + quence is not taken into account, so bb will not collate + between AA and BB, and upper-case and lower-case ASCII + characters will collate together. + + gglloobbssttaarr + If set, the pattern **** used in a pathname expansion con- + text will match all files and zero or more directories + and subdirectories. If the pattern is followed by a //, + only directories and subdirectories match. + + ggnnuu__eerrrrffmmtt + If set, shell error messages are written in the standard + GNU error message format. + + hhiissttaappppeenndd + If set, the history list is appended to the file named + by the value of the HHIISSTTFFIILLEE variable when the shell ex- + its, rather than overwriting the file. + + hhiissttrreeeeddiitt + If set, and rreeaaddlliinnee is being used, a user is given the + opportunity to re-edit a failed history substitution. + + hhiissttvveerriiffyy + If set, and rreeaaddlliinnee is being used, the results of his- + tory substitution are not immediately passed to the + shell parser. Instead, the resulting line is loaded + into the rreeaaddlliinnee editing buffer, allowing further modi- + fication. + + hhoossttccoommpplleettee + If set, and rreeaaddlliinnee is being used, bbaasshh will attempt to + perform hostname completion when a word containing a @@ + is being completed (see CCoommpplleettiinngg under RREEAADDLLIINNEE + above). This is enabled by default. + + hhuuppoonneexxiitt + If set, bbaasshh will send SSIIGGHHUUPP to all jobs when an inter- + active login shell exits. + + iinnhheerriitt__eerrrreexxiitt + If set, command substitution inherits the value of the + eerrrreexxiitt option, instead of unsetting it in the subshell + environment. This option is enabled when _p_o_s_i_x _m_o_d_e is + enabled. + + iinntteerraaccttiivvee__ccoommmmeennttss + If set, allow a word beginning with ## to cause that word + and all remaining characters on that line to be ignored + in an interactive shell (see CCOOMMMMEENNTTSS above). This op- + tion is enabled by default. + + llaassttppiippee + If set, and job control is not active, the shell runs + the last command of a pipeline not executed in the back- + ground in the current shell environment. + + lliitthhiisstt If set, and the ccmmddhhiisstt option is enabled, multi-line + commands are saved to the history with embedded newlines + rather than using semicolon separators where possible. + + llooccaallvvaarr__iinnhheerriitt + If set, local variables inherit the value and attributes + of a variable of the same name that exists at a previous + scope before any new value is assigned. The nameref at- + tribute is not inherited. + + llooccaallvvaarr__uunnsseett + If set, calling uunnsseett on local variables in previous + function scopes marks them so subsequent lookups find + them unset until that function returns. This is identi- + cal to the behavior of unsetting local variables at the + current function scope. + + llooggiinn__sshheellll + The shell sets this option if it is started as a login + shell (see IINNVVOOCCAATTIIOONN above). The value may not be + changed. + + mmaaiillwwaarrnn + If set, and a file that bbaasshh is checking for mail has + been accessed since the last time it was checked, the + message ``The mail in _m_a_i_l_f_i_l_e has been read'' is dis- + played. + + nnoo__eemmppttyy__ccmmdd__ccoommpplleettiioonn + If set, and rreeaaddlliinnee is being used, bbaasshh will not at- + tempt to search the PPAATTHH for possible completions when + completion is attempted on an empty line. + + nnooccaasseegglloobb + If set, bbaasshh matches filenames in a case-insensitive + fashion when performing pathname expansion (see PPaatthhnnaammee + EExxppaannssiioonn above). + + nnooccaasseemmaattcchh + If set, bbaasshh matches patterns in a case-insensitive + fashion when performing matching while executing ccaassee or + [[[[ conditional commands, when performing pattern substi- + tution word expansions, or when filtering possible com- + pletions as part of programmable completion. + + nnuullllgglloobb + If set, bbaasshh allows patterns which match no files (see + PPaatthhnnaammee EExxppaannssiioonn above) to expand to a null string, + rather than themselves. + + pprrooggccoommpp + If set, the programmable completion facilities (see PPrroo-- + ggrraammmmaabbllee CCoommpplleettiioonn above) are enabled. This option is + enabled by default. + + pprrooggccoommpp__aalliiaass + If set, and programmable completion is enabled, bbaasshh + treats a command name that doesn't have any completions + as a possible alias and attempts alias expansion. If it + has an alias, bbaasshh attempts programmable completion us- + ing the command word resulting from the expanded alias. + + pprroommppttvvaarrss + If set, prompt strings undergo parameter expansion, com- + mand substitution, arithmetic expansion, and quote re- + moval after being expanded as described in PPRROOMMPPTTIINNGG + above. This option is enabled by default. + + rreessttrriicctteedd__sshheellll + The shell sets this option if it is started in re- + stricted mode (see RREESSTTRRIICCTTEEDD SSHHEELLLL below). The value + may not be changed. This is not reset when the startup + files are executed, allowing the startup files to dis- + cover whether or not a shell is restricted. + + sshhiifftt__vveerrbboossee + If set, the sshhiifftt builtin prints an error message when + the shift count exceeds the number of positional parame- + ters. + + ssoouurrcceeppaatthh + If set, the ssoouurrccee (..) builtin uses the value of PPAATTHH to + find the directory containing the file supplied as an + argument. This option is enabled by default. + + xxppgg__eecchhoo + If set, the eecchhoo builtin expands backslash-escape se- + quences by default. + + ssuussppeenndd [--ff] + Suspend the execution of this shell until it receives a SSIIGGCCOONNTT + signal. A login shell cannot be suspended; the --ff option can be + used to override this and force the suspension. The return sta- + tus is 0 unless the shell is a login shell and --ff is not sup- + plied, or if job control is not enabled. + + tteesstt _e_x_p_r + [[ _e_x_p_r ]] + Return a status of 0 (true) or 1 (false) depending on the evalu- + ation of the conditional expression _e_x_p_r. Each operator and op- + erand must be a separate argument. Expressions are composed of + the primaries described in the bbaasshh manual page under CCOONNDDII-- + TTIIOONNAALL EEXXPPRREESSSSIIOONNSS. tteesstt does not accept any options, nor does + it accept and ignore an argument of ---- as signifying the end of + options. + + Expressions may be combined using the following operators, + listed in decreasing order of precedence. The evaluation de- + pends on the number of arguments; see below. Operator prece- + dence is used when there are five or more arguments. + !! _e_x_p_r True if _e_x_p_r is false. + (( _e_x_p_r )) + Returns the value of _e_x_p_r. This may be used to override + the normal precedence of operators. + _e_x_p_r_1 -aa _e_x_p_r_2 + True if both _e_x_p_r_1 and _e_x_p_r_2 are true. + _e_x_p_r_1 -oo _e_x_p_r_2 + True if either _e_x_p_r_1 or _e_x_p_r_2 is true. + + tteesstt and [[ evaluate conditional expressions using a set of rules + based on the number of arguments. + + 0 arguments + The expression is false. + 1 argument + The expression is true if and only if the argument is not + null. + 2 arguments + If the first argument is !!, the expression is true if and + only if the second argument is null. If the first argu- + ment is one of the unary conditional operators listed + above under CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS, the expression is + true if the unary test is true. If the first argument is + not a valid unary conditional operator, the expression is + false. + 3 arguments + The following conditions are applied in the order listed. + If the second argument is one of the binary conditional + operators listed above under CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS, the + result of the expression is the result of the binary test + using the first and third arguments as operands. The --aa + and --oo operators are considered binary operators when + there are three arguments. If the first argument is !!, + the value is the negation of the two-argument test using + the second and third arguments. If the first argument is + exactly (( and the third argument is exactly )), the result + is the one-argument test of the second argument. Other- + wise, the expression is false. + 4 arguments + If the first argument is !!, the result is the negation of + the three-argument expression composed of the remaining + arguments. Otherwise, the expression is parsed and eval- + uated according to precedence using the rules listed + above. + 5 or more arguments + The expression is parsed and evaluated according to + precedence using the rules listed above. + + When used with tteesstt or [[, the << and >> operators sort lexico- + graphically using ASCII ordering. + + ttiimmeess Print the accumulated user and system times for the shell and + for processes run from the shell. The return status is 0. + + ttrraapp [--llpp] [[_a_r_g] _s_i_g_s_p_e_c ...] + The command _a_r_g is to be read and executed when the shell re- + ceives signal(s) _s_i_g_s_p_e_c. If _a_r_g is absent (and there is a sin- + gle _s_i_g_s_p_e_c) or --, each specified signal is reset to its origi- + nal disposition (the value it had upon entrance to the shell). + If _a_r_g is the null string the signal specified by each _s_i_g_s_p_e_c + is ignored by the shell and by the commands it invokes. If _a_r_g + is not present and --pp has been supplied, then the trap commands + associated with each _s_i_g_s_p_e_c are displayed. If no arguments are + supplied or if only --pp is given, ttrraapp prints the list of com- + mands associated with each signal. The --ll option causes the + shell to print a list of signal names and their corresponding + numbers. Each _s_i_g_s_p_e_c is either a signal name defined in <_s_i_g_- + _n_a_l_._h>, or a signal number. Signal names are case insensitive + and the SSIIGG prefix is optional. + + If a _s_i_g_s_p_e_c is EEXXIITT (0) the command _a_r_g is executed on exit + from the shell. If a _s_i_g_s_p_e_c is DDEEBBUUGG, the command _a_r_g is exe- + cuted before every _s_i_m_p_l_e _c_o_m_m_a_n_d, _f_o_r command, _c_a_s_e command, + _s_e_l_e_c_t command, every arithmetic _f_o_r command, and before the + first command executes in a shell function (see SSHHEELLLL GGRRAAMMMMAARR + above). Refer to the description of the eexxttddeebbuugg option to the + sshhoopptt builtin for details of its effect on the DDEEBBUUGG trap. If a + _s_i_g_s_p_e_c is RREETTUURRNN, the command _a_r_g is executed each time a shell + function or a script executed with the .. or ssoouurrccee builtins fin- + ishes executing. + + If a _s_i_g_s_p_e_c is EERRRR, the command _a_r_g is executed whenever a + pipeline (which may consist of a single simple command), a list, + or a compound command returns a non-zero exit status, subject to + the following conditions. The EERRRR trap is not executed if the + failed command is part of the command list immediately following + a wwhhiillee or uunnttiill keyword, part of the test in an _i_f statement, + part of a command executed in a &&&& or |||| list except the command + following the final &&&& or ||||, any command in a pipeline but the + last, or if the command's return value is being inverted using + !!. These are the same conditions obeyed by the eerrrreexxiitt (--ee) op- + tion. + + Signals ignored upon entry to the shell cannot be trapped or re- + set. Trapped signals that are not being ignored are reset to + their original values in a subshell or subshell environment when + one is created. The return status is false if any _s_i_g_s_p_e_c is + invalid; otherwise ttrraapp returns true. + + ttyyppee [--aaffttppPP] _n_a_m_e [_n_a_m_e ...] + With no options, indicate how each _n_a_m_e would be interpreted if + used as a command name. If the --tt option is used, ttyyppee prints a + string which is one of _a_l_i_a_s, _k_e_y_w_o_r_d, _f_u_n_c_t_i_o_n, _b_u_i_l_t_i_n, or + _f_i_l_e if _n_a_m_e is an alias, shell reserved word, function, + builtin, or disk file, respectively. If the _n_a_m_e is not found, + then nothing is printed, and an exit status of false is re- + turned. If the --pp option is used, ttyyppee either returns the name + of the disk file that would be executed if _n_a_m_e were specified + as a command name, or nothing if ``type -t name'' would not re- + turn _f_i_l_e. The --PP option forces a PPAATTHH search for each _n_a_m_e, + even if ``type -t name'' would not return _f_i_l_e. If a command is + hashed, --pp and --PP print the hashed value, which is not necessar- + ily the file that appears first in PPAATTHH. If the --aa option is + used, ttyyppee prints all of the places that contain an executable + named _n_a_m_e. This includes aliases and functions, if and only if + the --pp option is not also used. The table of hashed commands is + not consulted when using --aa. The --ff option suppresses shell + function lookup, as with the ccoommmmaanndd builtin. ttyyppee returns true + if all of the arguments are found, false if any are not found. + + uulliimmiitt [--HHSS] --aa + uulliimmiitt [--HHSS] [--bbccddeeffiikkllmmnnppqqrrssttuuvvxxPPRRTT [_l_i_m_i_t]] + Provides control over the resources available to the shell and + to processes started by it, on systems that allow such control. + The --HH and --SS options specify that the hard or soft limit is set + for the given resource. A hard limit cannot be increased by a + non-root user once it is set; a soft limit may be increased up + to the value of the hard limit. If neither --HH nor --SS is speci- + fied, both the soft and hard limits are set. The value of _l_i_m_i_t + can be a number in the unit specified for the resource or one of + the special values hhaarrdd, ssoofftt, or uunnlliimmiitteedd, which stand for the + current hard limit, the current soft limit, and no limit, re- + spectively. If _l_i_m_i_t is omitted, the current value of the soft + limit of the resource is printed, unless the --HH option is given. + When more than one resource is specified, the limit name and + unit, if appropriate, are printed before the value. Other op- + tions are interpreted as follows: + --aa All current limits are reported; no limits are set + --bb The maximum socket buffer size + --cc The maximum size of core files created + --dd The maximum size of a process's data segment + --ee The maximum scheduling priority ("nice") + --ff The maximum size of files written by the shell and its + children + --ii The maximum number of pending signals + --kk The maximum number of kqueues that may be allocated + --ll The maximum size that may be locked into memory + --mm The maximum resident set size (many systems do not honor + this limit) + --nn The maximum number of open file descriptors (most systems + do not allow this value to be set) + --pp The pipe size in 512-byte blocks (this may not be set) + --qq The maximum number of bytes in POSIX message queues + --rr The maximum real-time scheduling priority + --ss The maximum stack size + --tt The maximum amount of cpu time in seconds + --uu The maximum number of processes available to a single + user + --vv The maximum amount of virtual memory available to the + shell and, on some systems, to its children + --xx The maximum number of file locks + --PP The maximum number of pseudoterminals + --RR The maximum time a real-time process can run before + blocking, in microseconds + --TT The maximum number of threads + + If _l_i_m_i_t is given, and the --aa option is not used, _l_i_m_i_t is the + new value of the specified resource. If no option is given, + then --ff is assumed. Values are in 1024-byte increments, except + for --tt, which is in seconds; --RR, which is in microseconds; --pp, + which is in units of 512-byte blocks; --PP, --TT, --bb, --kk, --nn, and + --uu, which are unscaled values; and, when in posix mode, --cc and + --ff, which are in 512-byte increments. The return status is 0 + unless an invalid option or argument is supplied, or an error + occurs while setting a new limit. + + uummaasskk [--pp] [--SS] [_m_o_d_e] + The user file-creation mask is set to _m_o_d_e. If _m_o_d_e begins with + a digit, it is interpreted as an octal number; otherwise it is + interpreted as a symbolic mode mask similar to that accepted by + _c_h_m_o_d(1). If _m_o_d_e is omitted, the current value of the mask is + printed. The --SS option causes the mask to be printed in sym- + bolic form; the default output is an octal number. If the --pp + option is supplied, and _m_o_d_e is omitted, the output is in a form + that may be reused as input. The return status is 0 if the mode + was successfully changed or if no _m_o_d_e argument was supplied, + and false otherwise. + + uunnaalliiaass [-aa] [_n_a_m_e ...] + Remove each _n_a_m_e from the list of defined aliases. If --aa is + supplied, all alias definitions are removed. The return value + is true unless a supplied _n_a_m_e is not a defined alias. + + uunnsseett [-ffvv] [-nn] [_n_a_m_e ...] + For each _n_a_m_e, remove the corresponding variable or function. + If the --vv option is given, each _n_a_m_e refers to a shell variable, + and that variable is removed. Read-only variables may not be + unset. If --ff is specified, each _n_a_m_e refers to a shell func- + tion, and the function definition is removed. If the --nn option + is supplied, and _n_a_m_e is a variable with the _n_a_m_e_r_e_f attribute, + _n_a_m_e will be unset rather than the variable it references. --nn + has no effect if the --ff option is supplied. If no options are + supplied, each _n_a_m_e refers to a variable; if there is no vari- + able by that name, a function with that name, if any, is unset. + Each unset variable or function is removed from the environment + passed to subsequent commands. If any of BBAASSHH__AALLIIAASSEESS, + BBAASSHH__AARRGGVV00, BBAASSHH__CCMMDDSS, BBAASSHH__CCOOMMMMAANNDD, BBAASSHH__SSUUBBSSHHEELLLL, BBAASSHHPPIIDD, + CCOOMMPP__WWOORRDDBBRREEAAKKSS, DDIIRRSSTTAACCKK, EEPPOOCCHHRREEAALLTTIIMMEE, EEPPOOCCHHSSEECCOONNDDSS, FFUUNNCC-- + NNAAMMEE, GGRROOUUPPSS, HHIISSTTCCMMDD, LLIINNEENNOO, RRAANNDDOOMM, SSEECCOONNDDSS, or SSRRAANNDDOOMM are + unset, they lose their special properties, even if they are sub- + sequently reset. The exit status is true unless a _n_a_m_e is read- + only. + + wwaaiitt [--ffnn] [--pp _v_a_r_n_a_m_e] [_i_d _._._.] + Wait for each specified child process and return its termination + status. Each _i_d may be a process ID or a job specification; if + a job spec is given, all processes in that job's pipeline are + waited for. If _i_d is not given, wwaaiitt waits for all running + background jobs and the last-executed process substitution, if + its process id is the same as $$!!, and the return status is zero. + If the --nn option is supplied, wwaaiitt waits for a single job from + the list of _i_ds or, if no _i_ds are supplied, any job, to complete + and returns its exit status. If none of the supplied arguments + is a child of the shell, or if no arguments are supplied and the + shell has no unwaited-for children, the exit status is 127. If + the --pp option is supplied, the process or job identifier of the + job for which the exit status is returned is assigned to the + variable _v_a_r_n_a_m_e named by the option argument. The variable + will be unset initially, before any assignment. This is useful + only when the --nn option is supplied. Supplying the --ff option, + when job control is enabled, forces wwaaiitt to wait for _i_d to ter- + minate before returning its status, instead of returning when it + changes status. If _i_d specifies a non-existent process or job, + the return status is 127. Otherwise, the return status is the + 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. + + 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 + regexp matching operator quotes special regexp characters in the word, + which is default behavior in bash-3.2 and above). + + If a user enables, say, ccoommppaatt3322, it may affect the behavior of other + compatibility levels up to and including the current compatibility + level. The idea is that each compatibility level controls behavior + that changed in that version of bbaasshh, but that behavior may have been + present in earlier versions. For instance, the change to use locale- + based comparisons with the [[[[ command came in bash-4.1, and earlier + versions used ASCII-based comparisons, so enabling ccoommppaatt3322 will enable + ASCII-based comparisons as well. That granularity may not be suffi- + cient for all uses, and as a result users should employ compatibility + levels carefully. Read the documentation for a particular feature to + find out the current behavior. + + Bash-4.3 introduced a new shell variable: BBAASSHH__CCOOMMPPAATT. The value as- + signed to this variable (a decimal version number like 4.2, or an inte- + ger corresponding to the ccoommppaatt_N_N option, like 42) determines the com- + patibility level. + + Starting with bash-4.4, Bash has begun deprecating older compatibility + levels. Eventually, the options will be removed in favor of BBAASSHH__CCOOMM-- + PPAATT. + + Bash-5.0 is the final version for which there will be an individual + shopt option for the previous version. Users should use BBAASSHH__CCOOMMPPAATT on + bash-5.0 and later versions. + + The following table describes the behavior changes controlled by each + compatibility level setting. The ccoommppaatt_N_N tag is used as shorthand for + setting the compatibility level to _N_N using one of the following mecha- + nisms. For versions prior to bash-5.0, the compatibility level may be + set using the corresponding ccoommppaatt_N_N shopt option. For bash-4.3 and + later versions, the BBAASSHH__CCOOMMPPAATT variable is preferred, and it is re- + quired for bash-5.1 and later versions. + + ccoommppaatt3311 + +o quoting the rhs of the [[[[ command's regexp matching oper- + ator (=~) has no special effect + + ccoommppaatt3322 + +o interrupting a command list such as "a ; b ; c" causes + the execution of the next command in the list (in + bash-4.0 and later versions, the shell acts as if it re- + ceived the interrupt, so interrupting one command in a + list aborts the execution of the entire list) + + ccoommppaatt4400 + +o the << and >> operators to the [[[[ command do not consider + the current locale when comparing strings; they use ASCII + ordering. Bash versions prior to bash-4.1 use ASCII col- + lation and _s_t_r_c_m_p(3); bash-4.1 and later use the current + locale's collation sequence and _s_t_r_c_o_l_l(3). + + ccoommppaatt4411 + +o in _p_o_s_i_x mode, ttiimmee may be followed by options and still + be recognized as a reserved word (this is POSIX interpre- + tation 267) + +o in _p_o_s_i_x mode, the parser requires that an even number of + single quotes occur in the _w_o_r_d portion of a double- + quoted parameter expansion and treats them specially, so + that characters within the single quotes are considered + quoted (this is POSIX interpretation 221) + + ccoommppaatt4422 + +o the replacement string in double-quoted pattern substitu- + tion does not undergo quote removal, as it does in ver- + sions after bash-4.2 + +o in posix mode, single quotes are considered special when + expanding the _w_o_r_d portion of a double-quoted parameter + expansion and can be used to quote a closing brace or + other special character (this is part of POSIX interpre- + tation 221); in later versions, single quotes are not + special within double-quoted word expansions + + ccoommppaatt4433 + +o the shell does not print a warning message if an attempt + is made to use a quoted compound assignment as an argu- + ment to declare (declare -a foo='(1 2)'). Later versions + warn that this usage is deprecated + +o word expansion errors are considered non-fatal errors + that cause the current command to fail, even in posix + mode (the default behavior is to make them fatal errors + that cause the shell to exit) + +o when executing a shell function, the loop state + (while/until/etc.) is not reset, so bbrreeaakk or ccoonnttiinnuuee in + that function will break or continue loops in the calling + context. Bash-4.4 and later reset the loop state to pre- + vent this + + ccoommppaatt4444 + +o the shell sets up the values used by BBAASSHH__AARRGGVV and + BBAASSHH__AARRGGCC so they can expand to the shell's positional + parameters even if extended debugging mode is not enabled + +o a subshell inherits loops from its parent context, so + bbrreeaakk or ccoonnttiinnuuee will cause the subshell to exit. + Bash-5.0 and later reset the loop state to prevent the + exit + +o variable assignments preceding builtins like eexxppoorrtt and + rreeaaddoonnllyy that set attributes continue to affect variables + with the same name in the calling environment even if the + shell is not in posix mode + + ccoommppaatt5500 + +o Bash-5.1 changed the way $$RRAANNDDOOMM is generated to intro- + duce slightly more randomness. If the shell compatibility + level is set to 50 or lower, it reverts to the method + from bash-5.0 and previous versions, so seeding the ran- + dom number generator by assigning a value to RRAANNDDOOMM will + produce the same sequence as in bash-5.0 + +o If the command hash table is empty, bash versions prior + to bash-5.1 printed an informational message to that ef- + fect, even when producing output that can be reused as + input. Bash-5.1 suppresses that message when the --ll op- + tion is supplied. + +SSEEEE AALLSSOO + bash(1), sh(1) + + + +GNU Bash 5.0 2004 Apr 20 BASH_BUILTINS(1) |