From 1d5cace9db9aef76f26b2d7ba54bbb76443b00b2 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 5 May 2024 20:33:23 +0200 Subject: Adding upstream version 5.0. Signed-off-by: Daniel Baumann --- doc/builtins.0 | 1851 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1851 insertions(+) create mode 100644 doc/builtins.0 (limited to 'doc/builtins.0') diff --git a/doc/builtins.0 b/doc/builtins.0 new file mode 100644 index 0000000..76f08b7 --- /dev/null +++ b/doc/builtins.0 @@ -0,0 +1,1851 @@ +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, + enable, 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 + environment 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 + positional 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 + returns 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 + appear 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'. + Options, 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 + entered. 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 variable to the + current location of the insertion point. If the executed + command changes the value of RREEAADDLLIINNEE__LLIINNEE or RREEAADD-- + LLIINNEE__PPOOIINNTT, 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 + input. + + 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 + exited. The return value is 0 unless _n is not greater than or + equal to 1. + + bbuuiillttiinn _s_h_e_l_l_-_b_u_i_l_t_i_n [_a_r_g_u_m_e_n_t_s] + Execute the specified shell builtin, 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 + directory 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 + option 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 + facilities, while available, will not have useful values. + + The matches will be generated in the same way as if the program- + mable completion code had generated them directly from a comple- + tion specification with the same flags. If _w_o_r_d is specified, + only those completions matching _w_o_r_d will be displayed. + + 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 inital + 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 + default) to words completed at the end of the + line. + pplluussddiirrss + After any matches defined by the compspec are + generated, directory name completion is + attempted and any matches are added to the + results of the other actions. + --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 + arguments 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 + current command line. When it finishes, the possible + completions are retrieved from the value of the CCOOMMPPRREE-- + PPLLYY 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 + options for each _n_a_m_e or the current completion. The possible + values of _o_p_t_i_o_n are those valid for the ccoommpplleettee builtin + described above. The --DD option indicates that other supplied + options should apply to the ``default'' command completion; that + is, completion attempted on a command for which no completion + has previously been defined. The --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 inital 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 + enclosing 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 [--aaAAffFFggiillnnrrttuuxx] [--pp] [_n_a_m_e[=_v_a_l_u_e] ...] + ttyyppeesseett [--aaAAffFFggiillnnrrttuuxx] [--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 + attributes 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 function. It is ignored in all other cases. The follow- + ing options can be used to restrict output to variables with the + specified attribute 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 + inherit 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 + environment. + + 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 + assign a value to an array variable without using the compound + assignment syntax (see AArrrraayyss above), one of the _n_a_m_e_s is not a + valid shell variable name, an attempt is made to turn off 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 + directories. The default display is on a single line with + directory names separated by spaces. Directories are added to + the list with the ppuusshhdd command; the ppooppdd command removes + entries from the list. The current directory is always the + first directory in the stack. + --cc Clears the directory stack by deleting all of the + entries. + --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 + receives 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 argument 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 + escape characters by default. eecchhoo does not interpret ---- to + mean the end of options. eecchhoo interprets the following escape + sequences: + \\aa alert (bell) + \\bb backspace + \\cc suppress further output + \\ee + \\EE an escape character + \\ff form feed + \\nn new line + \\rr carriage return + \\tt horizontal tab + \\vv vertical tab + \\\\ backslash + \\00_n_n_n the eight-bit character whose value is the octal value + _n_n_n (zero to three octal digits) + \\xx_H_H the eight-bit character whose value is the hexadecimal + value _H_H (one or two hex digits) + \\uu_H_H_H_H the Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value _H_H_H_H (one to four hex digits) + \\UU_H_H_H_H_H_H_H_H + the Unicode (ISO/IEC 10646) character whose value is the + hexadecimal value _H_H_H_H_H_H_H_H (one to eight hex digits) + + 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 + enabled. 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). 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 other- + wise. If _f_i_r_s_t is not specified, it is set to the previous com- + mand 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 + invalid 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_s] + 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 + expected to have an argument, which should be separated from it + by white space. The colon and question mark characters may not + be used as option characters. Each time it is invoked, ggeettooppttss + places the next option in the shell variable _n_a_m_e, initializing + _n_a_m_e if it does not exist, and the index of the next argument to + be processed into the variable OOPPTTIINNDD. OOPPTTIINNDD is initialized to + 1 each time the shell or a shell script is invoked. When an + option requires an argument, ggeettooppttss places that argument into + the variable OOPPTTAARRGG. The shell does not reset OOPPTTIINNDD automati- + cally; it must be manually reset between multiple calls to + ggeettooppttss within the same shell invocation if a new set of parame- + ters is to be used. + + When the end of options is encountered, ggeettooppttss exits with a + return value greater than zero. OOPPTTIINNDD is set to the index of + the first non-option argument, and _n_a_m_e is set to ?. + + ggeettooppttss normally parses the positional parameters, but if more + arguments are given in _a_r_g_s, ggeettooppttss parses those instead. + + 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 + OOPPTTAARRGG 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 + option 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 argu- + ments are supplied with --tt, the _n_a_m_e is printed before the + hashed full pathname. The --ll option causes output to be dis- + played in a format that may be reused as input. If no arguments + are given, or if only --ll is supplied, information about remem- + bered 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 + appended 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 + executes _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 + option 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. + 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 + manipulated. + ++_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 + argument is specified, conversion behaves as if -1 had + been given. This is an exception to the usual pprriinnttff + behavior. + + 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 + directories 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 + invalid 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 + descriptor _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 + second _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 + (described 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 + ignored. + --dd _d_e_l_i_m + The first character of _d_e_l_i_m is used to terminate the + input line, rather than newline. If _d_e_l_i_m is the empty + string, rreeaadd will terminate a line when it reads a NUL + character. + --ee If the standard input is coming from a terminal, 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 + returns immediately, without trying to read any data. + The exit status is 0 if input is available on the speci- + fied file descriptor, non-zero otherwise. The exit sta- + tus 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 is assigned to the vari- + able RREEPPLLYY. The exit status is zero, unless end-of-file is + encountered, rreeaadd times out (in which case the status is greater + than 128), a variable assignment error (such as assigning to a + readonly variable) occurs, or an invalid file descriptor is sup- + plied 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 + arrays; the --AA option restricts the variables to associative + arrays. 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 + rreettuurrnn is executed by a trap handler, the last command used to + determine the status is the last command executed before the + trap handler. If rreettuurrnn is executed during a DDEEBBUUGG trap, the + last command used to determine the status is the last command + executed by the trap handler before rreettuurrnn was invoked. 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 + significant 8 bits. The return status is non-zero if rreettuurrnn is + supplied a non-numeric argument, or is used outside a function + and not during execution of a script by .. or ssoouurrccee. Any com- + mand associated with the RREETTUURRNN trap is executed before execu- + tion resumes 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 + options 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 + ignored by interactive shells. + --oo _o_p_t_i_o_n_-_n_a_m_e + The _o_p_t_i_o_n_-_n_a_m_e can be one of the following: + aalllleexxppoorrtt + Same as --aa. + bbrraacceeeexxppaanndd + Same as --BB. + eemmaaccss Use an emacs-style command line editing inter- + face. This is enabled by default when the shell + is interactive, unless the shell is started with + the ----nnooeeddiittiinngg option. This also affects the + editing interface used for rreeaadd --ee. + eerrrreexxiitt Same as --ee. + eerrrrttrraaccee + Same as --EE. + ffuunnccttrraaccee + Same as --TT. + hhaasshhaallll Same as --hh. + hhiisstteexxppaanndd + Same as --HH. + hhiissttoorryy Enable command history, as described above under + HHIISSTTOORRYY. This option is on by default in inter- + active shells. + iiggnnoorreeeeooff + The effect is as if the shell command + ``IGNOREEOF=10'' had been executed (see SShheellll + VVaarriiaabblleess above). + kkeeyywwoorrdd Same as --kk. + mmoonniittoorr Same as --mm. + nnoocclloobbbbeerr + Same as --CC. + nnooeexxeecc Same as --nn. + nnoogglloobb Same as --ff. + nnoolloogg Currently ignored. + nnoottiiffyy Same as --bb. + nnoouunnsseett Same as --uu. + oonneeccmmdd Same as --tt. + pphhyyssiiccaall + Same as --PP. + ppiippeeffaaiill + If set, the return value of a pipeline is the + value of the last (rightmost) command to exit + with a non-zero status, or zero if all commands + in the pipeline exit successfully. This option + is disabled by default. + ppoossiixx 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 + appear in the environment, are ignored. If the shell is + started with the effective user (group) id not equal to + the real user (group) id, and the --pp option is not 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 + executed 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 + options can also be specified as arguments to an invocation of + the shell. The current set of options may be found in $$--. The + return 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 + unset. _n must be a non-negative number less than or equal to + $$##. If _n is 0, no parameters are changed. If _n is not given, + it is assumed to be 1. If _n is greater than $$##, the positional + parameters are not changed. The return status is greater than + zero if _n is greater than $$## or less than zero; otherwise 0. + + sshhoopptt [--ppqqssuu] [--oo] [_o_p_t_n_a_m_e ...] + Toggle the values of settings controlling optional shell behav- + ior. The settings can be either those listed below, or, if the + --oo option is used, those available with the --oo option to the sseett + builtin command. With no options, or with the --pp option, 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 + options have the following meanings: + --ss Enable (set) each _o_p_t_n_a_m_e. + --uu Disable (unset) each _o_p_t_n_a_m_e. + --qq Suppresses normal output (quiet mode); the return status + indicates whether the _o_p_t_n_a_m_e is set or unset. If multi- + ple _o_p_t_n_a_m_e arguments are 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 + options, 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 + associative array subscripts during arithmetic expres- + sion evaluation, while executing builtins that can per- + form 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 + exiting if any jobs are stopped. + cchheecckkwwiinnssiizzee + If set, bbaasshh checks the window size after each external + (non-builtin) command and, if necessary, updates the + values of LLIINNEESS and CCOOLLUUMMNNSS. 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 + If set, bbaasshh changes its behavior to that of version 3.1 + with respect to quoted arguments to the [[[[ conditional + command's ==~~ operator and locale-specific string compar- + ison when using the [[[[ conditional command's << and >> + operators. Bash versions prior to bash-4.1 use ASCII + collation and _s_t_r_c_m_p(3); bash-4.1 and later use the cur- + rent locale's collation sequence and _s_t_r_c_o_l_l(3). + ccoommppaatt3322 + If set, bbaasshh changes its behavior to that of version 3.2 + with respect to locale-specific string comparison when + using the [[[[ conditional command's << and >> operators + (see previous item) and the effect of interrupting a + command list. Bash versions 3.2 and earlier continue + with the next command in the list after one terminates + due to an interrupt. + ccoommppaatt4400 + If set, bbaasshh changes its behavior to that of version 4.0 + with respect to locale-specific string comparison when + using the [[[[ conditional command's << and >> operators + (see description of ccoommppaatt3311) and the effect of inter- + rupting a command list. Bash versions 4.0 and later + interrupt the list as if the shell received the inter- + rupt; previous versions continue with the next command + in the list. + ccoommppaatt4411 + If set, bbaasshh, when in _p_o_s_i_x _m_o_d_e, treats a single quote + in a double-quoted parameter expansion as a special + character. The single quotes must match (an even num- + ber) and the characters between the single quotes are + considered quoted. This is the behavior of posix mode + through version 4.1. The default bash behavior remains + as in previous versions. + ccoommppaatt4422 + If set, bbaasshh does not process the replacement string in + the pattern substitution word expansion using quote + removal. + ccoommppaatt4433 + If set, bbaasshh does not print a warning message if an + attempt is made to use a quoted compound array assign- + ment as an argument to ddeeccllaarree, makes word expansion + errors non-fatal errors that cause the current command + to fail (the default behavior is to make them fatal + errors that cause the shell to exit), and does not reset + the loop state when a shell function is executed (this + allows bbrreeaakk or ccoonnttiinnuuee in a shell function to affect + loops in the caller's context). + ccoommppaatt4444 + If set, bbaasshh saves the positional parameters to + BASH_ARGV and BASH_ARGC before they are used, regardless + of whether or not extended debugging mode is enabled. + 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 + expand to directories will not be quoted; however, any + dollar signs appearing in filenames will not be quoted, + either. This is active only when bash is using 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, arrange to execute the + debugger profile before the shell starts, identical to + the ----ddeebbuuggggeerr option. If set after invocation, behav- + ior 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 + description of FFIIGGNNOORREE. This option is enabled by + default. + 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 + sequence is not taken into account, so bb will not col- + late 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 + exits, 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 + option is enabled by default. + llaassttppiippee + If set, and job control is not active, the shell runs + the last command of a pipeline not executed in the back- + ground in the current shell environment. + lliitthhiisstt If set, and the ccmmddhhiisstt option is enabled, multi-line + commands are saved to the history with embedded newlines + rather than using semicolon separators where possible. + llooccaallvvaarr__iinnhheerriitt + If set, local variables inherit the value and attributes + of a variable of the same name that exists at a previous + scope before any new value is assigned. The nameref + attribute 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 + attempt 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 + using the command word resulting from the expanded + alias. + pprroommppttvvaarrss + If set, prompt strings undergo parameter expansion, com- + mand substitution, arithmetic expansion, and quote + removal 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 + restricted 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 + sequences 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 above under CCOONNDDIITTIIOONNAALL EEXXPPRREESSSSIIOONNSS. + tteesstt does not accept any options, nor does it accept and ignore + an argument of ---- as signifying the end of options. + + Expressions may be combined using the following operators, + listed in decreasing order of precedence. The evaluation + depends 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 + receives signal(s) _s_i_g_s_p_e_c. If _a_r_g is absent (and there is a + single _s_i_g_s_p_e_c) or --, each specified signal is reset to its + original 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 commands associated with each signal. The --ll option + causes the shell to print a list of signal names and their cor- + responding 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) + option. + + Signals ignored upon entry to the shell cannot be trapped or + reset. Trapped signals that are not being ignored are reset to + their original values in a subshell or subshell environment when + one is created. The return status is false if any _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 + returned. 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 speci- + fied as a command name, or nothing if ``type -t name'' would not + return _f_i_l_e. The --PP option forces a PPAATTHH search for each _n_a_m_e, + even if ``type -t name'' would not return _f_i_l_e. If 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 [--HHSSaabbccddeeffiikkllmmnnppqqrrssttuuvvxxPPTT [_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, + respectively. 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 are printed before the value. Other options are inter- + preted as follows: + --aa All current limits are reported + --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 + --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; --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 incre- + ments. The return status is 0 unless an invalid option or argu- + ment 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, any function with that name is unset. Each + unset variable or function is removed from the environment + passed to subsequent commands. If any of CCOOMMPP__WWOORRDDBBRREEAAKKSS, RRAANN-- + DDOOMM, SSEECCOONNDDSS, LLIINNEENNOO, HHIISSTTCCMMDD, FFUUNNCCNNAAMMEE, GGRROOUUPPSS, or DDIIRRSSTTAACCKK 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] [_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, all currently active child pro- + cesses are waited for, and the return status is zero. If the --nn + option is supplied, wwaaiitt waits for any job to terminate and + returns its exit status. If the --ff option is supplied, and job + control is enabled, wwaaiitt forces _i_d to terminate 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. + +SSEEEE AALLSSOO + bash(1), sh(1) + + + +GNU Bash 5.0 2004 Apr 20 BASH_BUILTINS(1) -- cgit v1.2.3