diff options
Diffstat (limited to 'documentation/builtins.txt')
| -rw-r--r-- | documentation/builtins.txt | 1188 |
1 files changed, 1188 insertions, 0 deletions
diff --git a/documentation/builtins.txt b/documentation/builtins.txt new file mode 100644 index 0000000..3df6380 --- /dev/null +++ b/documentation/builtins.txt @@ -0,0 +1,1188 @@ + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + +NAME + bash, :, ., alias, bg, bind, break, builtin, bye, case, cd, + command, continue, declare, dirs, echo, enable, eval, exec, + exit, export, fc, fg, for, getopts, hash, help, history, if, + jobs, kill, let, local, logout, popd, pushd, pwd, read, + readonly, return, set, shift, source, suspend, test, times, + trap, type, typeset, ulimit, umask, unalias, unset, until, + wait, while - bash built-in commands, see bash(1) + +BASH BUILTIN COMMANDS + : [_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. A + zero exit code is returned. + + . _f_i_l_e_n_a_m_e [_a_r_g_u_m_e_n_t_s] + source _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 executed from _f_i_l_e_n_a_m_e. If _f_i_l_e_n_a_m_e does + not contain a slash, pathnames in PATH are used to find + the directory containing _f_i_l_e_n_a_m_e. The file searched + for in PATH need not be executable. The current direc- + tory is searched if no file is found in PATH. If any + _a_r_g_u_m_e_n_t_s are supplied, they become the positional + parameters when _f_i_l_e is executed. Otherwise the posi- + tional parameters are unchanged. 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. + + alias [_n_a_m_e[=_v_a_l_u_e] ...] + Alias with no arguments prints the list of aliases in + the form _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 supplied, the name and value of + the alias is printed. Alias returns true unless a _n_a_m_e + is given for which no alias has been defined. + + bg [_j_o_b_s_p_e_c] + Place _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. bg _j_o_b_s_p_e_c returns + 0 unless run when job control is disabled or, when run + with job control enabled, if _j_o_b_s_p_e_c was not found or + started without job control. + + bind [-m _k_e_y_m_a_p] [-lvd] [-q _n_a_m_e] + bind [-m _k_e_y_m_a_p] -f _f_i_l_e_n_a_m_e + + + +GNU Last change: 1993 September 16 1 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + bind [-m _k_e_y_m_a_p] _k_e_y_s_e_q:_f_u_n_c_t_i_o_n-_n_a_m_e + Display current readline key and function bindings, or + bind a key sequence to a readline function or macro. + The binding syntax accepted is identical to that of + ._i_n_p_u_t_r_c, but each binding must be passed as a separate + argument; e.g., '"\C-x\C-r": re-read-init-file'. + Options, if supplied, have the following meanings: + -m _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; _e_m_a_c_s is equivalent to + _e_m_a_c_s-_s_t_a_n_d_a_r_d. + -l List the names of all readline functions + -v List current function names and bindings + -d Dump function names and bindings in such a way + that they can be re-read + -f _f_i_l_e_n_a_m_e + Read key bindings from _f_i_l_e_n_a_m_e + -q _f_u_n_c_t_i_o_n + Query about which keys invoke the named _f_u_n_c_t_i_o_n + + The return value is 0 unless an unrecognized option is + given or an error occurred. + + break [_n] + Exit from within a for, while, or until loop. If _n is + specified, break _n levels. _n must be >_ 1. If _n is + greater than the number of enclosing loops, all enclos- + ing loops are exited. The return value is 0 unless the + shell is not executing a loop when break is executed. + + builtin _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 + you wish to define a function whose name is the same as + a shell builtin, but need the functionality of the + builtin within the function itself. The cd 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. + + cd [_d_i_r] + Change the current directory to _d_i_r. The variable HOME + is the default _d_i_r. The variable CDPATH defines the + search path for the directory containing _d_i_r. Alterna- + tive directory names are separated by a colon (:). A + null directory name in CDPATH is the same as the + current directory, i.e., ``.''. If _d_i_r begins with a + slash (/), then CDPATH is not used. An argument of - + is equivalent to $OLDPWD. The return value is true if + the directory was successfully changed; false + + + +GNU Last change: 1993 September 16 2 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + otherwise. + + command [-pVv] _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 PATH are executed. If the -p option is + given, the search for _c_o_m_m_a_n_d is performed using a + default value for PATH that is guaranteed to find all + of the standard utilities. If either the -V or -v + option is supplied, a description of _c_o_m_m_a_n_d is + printed. The -v option causes a single word indicating + the command or pathname used to invoke _c_o_m_m_a_n_d to be + printed; the -V option produces a more verbose descrip- + tion. An argument of -- disables option checking for + the rest of the arguments. If the -V or -v 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 cannot be found, the exit + status is 127. Otherwise, the exit status of the com- + mand builtin is the exit status of _c_o_m_m_a_n_d. + + continue [_n] + Resume the next iteration of the enclosing for, while, + or until 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 the shell is not executing a loop when con- + tinue is executed. + + declare [-frxi] [_n_a_m_e[=_v_a_l_u_e]] + typeset [-frxi] [_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 + instead. The options can be used to restrict output to + variables with the specified attribute. + -f Use function names only + -r Make _n_a_m_es readonly. These names cannot then be + assigned values by subsequent assignment state- + ments. + -x Mark _n_a_m_es for export to subsequent commands via + the environment. + -i The variable is treated as an integer; arithmetic + evaluation (see ARITHMETIC EVALUATION ) is per- + formed when the variable is assigned a value. + + Using `+' instead of `-' turns off the attribute + instead. When used in a function, makes _n_a_m_es local, + as with the local command. The return value is 0 + unless an illegal option is encountered, an attempt is + made to define a function using "-f foo=bar", one of + the _n_a_m_e_s is not a legal shell variable name, an + + + +GNU Last change: 1993 September 16 3 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + attempt is made to turn off readonly status for a + readonly variable, or an attempt is made to display a + non-existant function with -f. + + dirs [-l] [+/-n] + Display the list of currently remembered directories. + Directories are added to the list with the pushd com- + mand; the popd command moves back up through the list. + +n displays the _nth entry counting from the left of + the list shown by dirs when invoked without + options, starting with zero. + -n displays the _nth entry counting from the right of + the list shown by dirs when invoked without + options, starting with zero. + -l produces a longer listing; the default listing + format uses a tilde to denote the home directory. + + The return value is 0 unless an illegal option is sup- + plied or _n indexes beyond the end of the directory + stack. + + echo [-neE] [_a_r_g ...] + Output the _a_r_gs, separated by spaces. The return + status is always 0. If -n is specified, the trailing + newline is suppressed. If the -e option is given, + interpretation of the following backslash-escaped char- + acters is enabled. The -E option disables the + interpretation of these escape characters, even on sys- + tems where they are interpreted by default. + \a alert (bell) + \b backspace + \c suppress trailing newline + \f form feed + \n new line + \r carriage return + \t horizontal tab + \v vertical tab + \\ backslash + \nnn the character whose ASCII code is _n_n_n (octal) + + enable [-n] [-all] [_n_a_m_e ...] + Enable and disable builtin shell commands. This allows + the execution of a disk command which has the same name + as a shell builtin without specifying a full pathname. + If -n is used, each _n_a_m_e is disabled; otherwise, _n_a_m_e_s + are enabled. For example, to use the test binary found + via the PATH instead of the shell builtin version, type + ``enable -n test''. If no arguments are given, a list + of all enabled shell builtins is printed. If only -n + is supplied, a list of all disabled builtins is + printed. If only -all is supplied, the list printed + includes all builtins, with an indication of whether or + + + +GNU Last change: 1993 September 16 4 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + not each is enabled. enable accepts -a as a synonym + for -all. The return value is 0 unless a _n_a_m_e is not a + shell builtin. + + eval [_a_r_g ...] + The _a_r_gs are read and concatenated together into a sin- + gle command. This command is then read and executed by + the shell, and its exit status is returned as the value + of the eval command. If there are no _a_r_g_s, or only + null arguments, eval returns true. + + exec [[-] _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 first argument is -, the shell + places a dash in the zeroth arg passed to _c_o_m_m_a_n_d. + This is what login does. If the file cannot be exe- + cuted for some reason, a non-interactive shell exits, + unless the shell variable no_exit_on_failed_exec + exists, in which case it returns failure. An interac- + tive shell returns failure if the file cannot be exe- + cuted. 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. + + exit [_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 EXIT is executed before the shell + terminates. + + export [-nf] [_n_a_m_e[=_w_o_r_d]] ... + export -p + The supplied _n_a_m_e_s are marked for automatic export to + the environment of subsequently executed commands. If + the -f option is given, the _n_a_m_e_s refer to functions. + If no _n_a_m_e_s are given, or if the -p option is supplied, + a list of all names that are exported in this shell is + printed. The -n option causes the export property to + be removed from the named variables. An argument of -- + disables option checking for the rest of the arguments. + export returns an exit status of 0 unless an illegal + option is encountered, one of the _n_a_m_e_s is not a legal + shell variable name, or -f is supplied with a _n_a_m_e that + is not a function. + + fc [-e _e_n_a_m_e] [-nlr] [_f_i_r_s_t] [_l_a_s_t] + fc -s [_p_a_t=_r_e_p] [_c_m_d] + Fix Command. In the first form, a range of commands + from _f_i_r_s_t to _l_a_s_t is selected from the history list. + _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 + + + +GNU Last change: 1993 September 16 5 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + number (an index into the history list, where a nega- + tive number is used as an offset from the current com- + mand 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 otherwise. + If _f_i_r_s_t is not specified it is set to the previous + command for editing and -16 for listing. + + The -n flag suppresses the command numbers when list- + ing. The -r flag reverses the order of the commands. + If the -l flag is given, the commands are listed on + standard output. Otherwise, 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 FCEDIT variable is + used, and the value of EDITOR if FCEDIT is not set. If + neither variable is set, 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. 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 illegal option is encountered or _f_i_r_s_t or _l_a_s_t + specify history lines out of range. If the -e option + is supplied, the return value is the value of the last + command executed or failure if an error occurs with the + temporary file of commands. If the second form is + used, the return status is that of the command re- + executed, unless _c_m_d does not specify a valid history + line, in which case fc returns failure. + + fg [_j_o_b_s_p_e_c] + Place _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 + specify a valid job or _j_o_b_s_p_e_c specifies a job that was + started without job control. + + getopts _o_p_t_s_t_r_i_n_g _n_a_m_e [_a_r_g_s] + getopts is used by shell procedures to parse positional + parameters. _o_p_t_s_t_r_i_n_g contains the option letters to + be recognized; if a letter is followed by a colon, the + option is expected to have an argument, which should be + separated from it by white space. Each time it is + invoked, getopts places the next option in the shell + variable _n_a_m_e, initializing _n_a_m_e if it does not exist, + + + +GNU Last change: 1993 September 16 6 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + and the index of the next argument to be processed into + the variable OPTIND. OPTIND is initialized to 1 each + time the shell or a shell script is invoked. When an + option requires an argument, getopts places that argu- + ment into the variable OPTARG. The shell does not + reset OPTIND automatically; it must be manually reset + between multiple calls to getopts within the same shell + invocation if a new set of parameters is to be used. + + getopts 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 report- + ing is used. In normal operation diagnostic messages + are printed when illegal options or missing option + arguments are encountered. If the variable OPTERR is + set to 0, no error message will be displayed, even if + the first character of _o_p_t_s_t_r_i_n_g is not a colon. + + If an illegal option is seen, getopts places ? into + _n_a_m_e and, if not silent, prints an error message and + unsets OPTARG. If getopts is silent, the option char- + acter found is placed in OPTARG and no diagnostic mes- + sage is printed. + + If a required argument is not found, and getopts is not + silent, a question mark (?) is placed in _n_a_m_e, OPTARG + is unset, and a diagnostic message is printed. If + getopts is silent, then a colon (:) is placed in _n_a_m_e + and OPTARG is set to the option character found. + + getopts normally parses the positional parameters, but + if more arguments are given in _a_r_g_s, getopts parses + those instead. getopts returns true if an option, + specified or unspecified, is found. It returns false + if the end of options is encountered or an error + occurs. + + hash [-r] [_n_a_m_e] + For each _n_a_m_e, the full pathname of the command is + determined and remembered. The -r option causes the + shell to forget all remembered locations. If no argu- + ments are given, information about remembered commands + is printed. An argument of -- disables option checking + for the rest of the arguments. The return status is + true unless a _n_a_m_e is not found or an illegal option is + supplied. + + help [_p_a_t_t_e_r_n] + Display helpful information about builtin commands. If + _p_a_t_t_e_r_n is specified, help gives detailed help on all + commands matching _p_a_t_t_e_r_n; otherwise a list of the + builtins is printed. The return status is 0 unless no + command matches _p_a_t_t_e_r_n. + + + +GNU Last change: 1993 September 16 7 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + history [_n] + history -rwan [_f_i_l_e_n_a_m_e] + With no options, display the command history list with + line numbers. Lines listed with a * have been modi- + fied. An argument of _n lists only the last _n lines. + If a non-option argument is supplied, it is used as the + name of the history file; if not, the value of HISTFILE + is used. Options, if supplied, have the following + meanings: + -a Append the ``new'' history lines (history lines + entered since the beginning of the current bash + session) to the history file + -n Read the history lines not already read from the + history file into the current history list. These + are lines appended to the history file since the + beginning of the current bash session. + -r Read the contents of the history file and use them + as the current history + -w Write the current history to the history file, + overwriting the history file's contents. + + The return value is 0 unless an illegal option is + encountered or an error occurs while reading or writing + the history file. + + jobs [-lnp] [ _j_o_b_s_p_e_c ... ] + jobs -x _c_o_m_m_a_n_d [ _a_r_g_s ... ] + The first form lists the active jobs. The -l option + lists process IDs in addition to the normal informa- + tion; the -p option lists only the process ID of the + job's process group leader. The -n option displays + only jobs that have changed status since last notified. + If _j_o_b_s_p_e_c is given, output is restricted to informa- + tion about that job. The return status is 0 unless an + illegal option is encountered or an illegal _j_o_b_s_p_e_c is + supplied. + + If the -x option is supplied, jobs 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, return- + ing its exit status. + + kill [-s sigspec | -sigspec] [_p_i_d | _j_o_b_s_p_e_c] ... + kill -l [_s_i_g_n_u_m] + Send the signal named by _s_i_g_s_p_e_c 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 signal name + such as SIGKILL or a signal number. If _s_i_g_s_p_e_c is a + signal name, the name is case insensitive and may be + given with or without the SIG prefix. If _s_i_g_s_p_e_c is + not present, then SIGTERM is assumed. An argument of + -l lists the signal names. If any arguments are sup- + plied when -l is given, the names of the specified + + + +GNU Last change: 1993 September 16 8 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + signals are listed, and the return status is 0. An + argument of -- disables option checking for the rest of + the arguments. kill returns true if at least one sig- + nal was successfully sent, or false if an error occurs + or an illegal option is encountered. + + let _a_r_g [_a_r_g ...] + Each _a_r_g is an arithmetic expression to be evaluated + (see ARITHMETIC EVALUATION). If the last _a_r_g evaluates + to 0, let returns 1; 0 is returned otherwise. + + local [_n_a_m_e[=_v_a_l_u_e] ...] + For each argument, create a local variable named _n_a_m_e, + and assign it _v_a_l_u_e. When local is used within a func- + tion, it causes the variable _n_a_m_e to have a visible + scope restricted to that function and its children. + With no operands, local writes a list of local vari- + ables to the standard output. It is an error to use + local when not within a function. The return status is + 0 unless local is used outside a function, or an ille- + gal _n_a_m_e is supplied. + + logout + Exit a login shell. + + popd [+/-n] + Removes entries from the directory stack. With no + arguments, removes the top directory from the stack, + and performs a cd to the new top directory. + +n removes the _nth entry counting from the left of + the list shown by dirs, 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 dirs, starting with zero. For + example: ``popd -0'' removes the last directory, + ``popd -1'' the next to last. + + If the popd command is successful, a dirs is performed + as well, and the return status is 0. popd returns + false if an illegal option is encountered, the direc- + tory stack is empty, a non-existent directory stack + entry is specified, or the directory change fails. + + pushd [_d_i_r] + pushd +/-n + 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, + exchanges the top two directories and returns 0, unless + the directory stack is empty. + +n Rotates the stack so that the _nth directory + + + +GNU Last change: 1993 September 16 9 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + (counting from the left of the list shown by dirs) + is at the top. + -n Rotates the stack so that the _nth directory + (counting from the right) is at the top. + dir adds _d_i_r to the directory stack at the top, making + it the new current working directory. + + If the pushd command is successful, a dirs is performed + as well. If the first form is used, pushd returns 0 + unless the cd to _d_i_r fails. With the second form, + pushd returns 0 unless the directory stack is empty, a + non-existant directory stack element is specified, or + the directory change to the specified new current + directory fails. + + pwd Print the absolute pathname of the current working + directory. The path printed contains no symbolic links + if the -P option to the set builtin command is set. + See also the description of nolinks under Shell Vari- + ables above). The return status is 0 unless an error + occurs while reading the pathname of the current direc- + tory. + + read [-r] [_n_a_m_e ...] + One line is read from the standard input, 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, with leftover words + assigned to the last _n_a_m_e. Only the characters in IFS + are recognized as word delimiters. If no _n_a_m_e_s are + supplied, the line read is assigned to the variable + REPLY. The return code is zero, unless end-of-file is + encountered. If the -r option is given, a backslash- + newline pair is not ignored, and the backslash is con- + sidered to be part of the line. + + readonly [-f] [_n_a_m_e ...] + readonly -p + The given _n_a_m_e_s are marked readonly and the values of + these _n_a_m_e_s may not be changed by subsequent assign- + ment. If the -f option is supplied, the functions + corresponding to the _n_a_m_e_s are so marked. If no argu- + ments are given, or if the -p option is supplied, a + list of all readonly names is printed. An argument of + -- disables option checking for the rest of the argu- + ments. The return status is 0 unless an illegal option + is encountered, one of the _n_a_m_e_s is not a legal shell + variable name, or -f is supplied with a _n_a_m_e that is + not a function. + + return [_n] + Causes a function to exit with the return value speci- + fied by _n. If _n is omitted, the return status is that + + + +GNU Last change: 1993 September 16 10 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + of the last command executed in the function body. If + used outside a function, but during execution of a + script by the . (source) 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 used out- + side a function and not during execution of a script by + ., the return status is false. + + set [--abefhkmnptuvxldCHP] [-o _o_p_t_i_o_n] [_a_r_g ...] + -a Automatically mark variables which are modified + or created for export to the environment of + subsequent commands. + -b Cause the status of terminated background jobs + to be reported immediately, rather than before + the next primary prompt. (Also see notify + under Shell Variables above). + -e Exit immediately if a _s_i_m_p_l_e-_c_o_m_m_a_n_d (see SHELL + GRAMMAR above) exits with a non-zero status. + The shell does not exit if the command that + fails is part of an _u_n_t_i_l or _w_h_i_l_e loop, part + of an _i_f statement, part of a && or || list, or + if the command's return value is being inverted + via !. + -f Disable pathname expansion. + -h Locate and remember function commands as func- + tions are defined. Function commands are nor- + mally looked up when the function is executed. + -k All keyword arguments are placed in the + environment for a command, not just those that + precede the command name. + -m Monitor mode. Job control is enabled. This + flag is on by default for interactive shells on + systems that support it (see JOB CONTROL + above). Background processes run in a separate + process group and a line containing their exit + status is printed upon their completion. + -n Read commands but do not execute them. This + may be used to check a shell script for syntax + errors. This is ignored for interactive + shells. + -o _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: + allexport + Same as -a. + braceexpand + The shell performs brace expansion (see + Brace Expansion above). This is on by + default. + emacs Use an emacs-style command line editing + interface. This is enabled by default + when the shell is interactive, unless + + + +GNU Last change: 1993 September 16 11 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + the shell is started with the -nol- + ineediting option. + errexit Same as -e. + histexpand + Same as -H. + ignoreeof + The effect is as if the shell command + `IGNOREEOF=10' had been executed (see + Shell Variables above). + interactive-comments + Allow a word beginning with # to cause + that word and all remaining characters + on that line to be ignored in an + interactive shell (see COMMENTS above). + monitor Same as -m. + noclobber + Same as -C. + noexec Same as -n. + noglob Same as -f. + nohash Same as -d. + notify Same as -b. + nounset Same as -u. + physical + Same as -P. + posix Change the behavior of bash where the + default operation differs from the + Posix 1003.2 standard to match the + standard. + privileged + Same as -p. + verbose Same as -v. + vi Use a vi-style command line editing + interface. + xtrace Same as -x. + If no _o_p_t_i_o_n-_n_a_m_e is supplied, the values of + the current options are printed. + -p Turn on _p_r_i_v_i_l_e_g_e_d mode. In this mode, the + $ENV file is not processed, and shell functions + are not inherited from the environment. This + is enabled automatically on startup if the + effective user (group) id is not equal to the + real user (group) id. Turning this option off + causes the effective user and group ids to be + set to the real user and group ids. + -t Exit after reading and executing one command. + -u Treat unset variables as an error when perform- + ing parameter expansion. If expansion is + attempted on an unset variable, the shell + prints an error message, and, if not interac- + tive, exits with a non-zero status. + -v Print shell input lines as they are read. + -x After expanding each _s_i_m_p_l_e-_c_o_m_m_a_n_d, bash + + + +GNU Last change: 1993 September 16 12 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + displays the expanded value of PS4, followed by + the command and its expanded arguments. + -l Save and restore the binding of _n_a_m_e in a for + _n_a_m_e [in word] command (see SHELL GRAMMAR + above). + -d Disable the hashing of commands that are looked + up for execution. Normally, commands are + remembered in a hash table, and once found, do + not have to be looked up again. + -C The effect is as if the shell command + `noclobber=' had been executed (see Shell Vari- + ables above). + -H Enable ! style history substitution. This flag + is on by default when the shell is interactive. + -P If set, do not follow symbolic links when per- + forming commands such as cd which change the + current directory. The physical directory is + used instead. + -- If no arguments follow this flag, then the + positional parameters are unset. Otherwise, + the positional parameters 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 parame- + ters. The -x and -v options are turned off. + If there are no _a_r_gs, the positional parameters + remain unchanged. + + The flags are off by default unless otherwise noted. + Using + rather than - causes these flags to be turned + off. The flags can also be specified as options to an + invocation of the shell. The current set of flags may + be found in $-. After the option arguments are pro- + cessed, the remaining _n _a_r_gs are treated as values for + the positional parameters and are assigned, in order, + to $1, $2, ... $_n. If no options or _a_r_gs are supplied, + all shell variables are printed. The return status is + always true unless an illegal option is encountered. + + shift [_n] + The positional parameters from _n+1 ... are renamed to + $1 .... Parameters represented by the numbers $# down + to $#-_n+1 are unset. If _n is 0, no parameters are + changed. If _n is not given, it is assumed to be 1. _n + must be a non-negative number less than or equal to $#. + If _n is greater than $#, the positional parameters are + not changed. The return status is greater than 0 if _n + is greater than $# or less than 0; otherwise 0. + + suspend [-f] + Suspend the execution of this shell until it receives a + SIGCONT signal. The -f option says not to complain if + + + +GNU Last change: 1993 September 16 13 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + this is a login shell; just suspend anyway. The return + status is 0 unless the shell is a login shell and -f is + not supplied, or if job control is not enabled. + + test _e_x_p_r + [ _e_x_p_r ] + Return a status of 0 (true) or 1 (false) depending on + the evaluation of the conditional expression _e_x_p_r. + Expressions may be unary or binary. Unary expressions + are often used to examine the status of a file. There + are string operators and numeric comparison operators + as well. Each operator and operand must be a separate + argument. If _f_i_l_e is of the form /dev/fd/_n, then file + descriptor _n is checked. + -b _f_i_l_e + True if _f_i_l_e exists and is block special. + -c _f_i_l_e + True if _f_i_l_e exists and is character special. + -d _f_i_l_e + True if _f_i_l_e exists and is a directory. + -e _f_i_l_e + True if _f_i_l_e exists. + -f _f_i_l_e + True if _f_i_l_e exists and is a regular file. + -g _f_i_l_e + True if _f_i_l_e exists and is set-group-id. + -k _f_i_l_e + True if _f_i_l_e has its ``sticky'' bit set. + -L _f_i_l_e + True if _f_i_l_e exists and is a symbolic link. + -p _f_i_l_e + True if _f_i_l_e exists and is a named pipe. + -r _f_i_l_e + True if _f_i_l_e exists and is readable. + -s _f_i_l_e + True if _f_i_l_e exists and has a size greater than + zero. + -S _f_i_l_e + True if _f_i_l_e exists and is a socket. + -t _f_d + True if _f_d is opened on a terminal. + -u _f_i_l_e + True if _f_i_l_e exists and its set-user-id bit is + set. + -w _f_i_l_e + True if _f_i_l_e exists and is writable. + -x _f_i_l_e + True if _f_i_l_e exists and is executable. + -O _f_i_l_e + True if _f_i_l_e exists and is owned by the effective + user id. + -G _f_i_l_e + + + +GNU Last change: 1993 September 16 14 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + True if _f_i_l_e exists and is owned by the effective + group id. + _f_i_l_e_1 -nt _f_i_l_e_2 + True if _f_i_l_e_1 is newer (according to modification + date) than _f_i_l_e_2. + _f_i_l_e_1 -ot _f_i_l_e_2 + True if _f_i_l_e_1 is older than file2. + _f_i_l_e_1 -ef _f_i_l_e + True if _f_i_l_e_1 and _f_i_l_e_2 have the same device and + inode numbers. + -z _s_t_r_i_n_g + True if the length of _s_t_r_i_n_g is zero. + -n _s_t_r_i_n_g + _s_t_r_i_n_g + True if the length of _s_t_r_i_n_g is non-zero. + _s_t_r_i_n_g_1 = _s_t_r_i_n_g_2 + True if the strings are equal. + _s_t_r_i_n_g_1 != _s_t_r_i_n_g_2 + True if the strings are not equal. + ! _e_x_p_r + True if _e_x_p_r is false. + _e_x_p_r_1 -a _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 -o _e_x_p_r_2 + True if either _e_x_p_r_1 OR _e_x_p_r_2 is true. + _a_r_g_1 OP _a_r_g_2 + OP is one of -eq, -ne, -lt, -le, -gt, or -ge. + These arithmetic binary operators return true if + _a_r_g_1 is equal, not-equal, less-than, less-than- + or-equal, greater-than, or greater-than-or-equal + than _a_r_g_2, respectively. _A_r_g_1 and _a_r_g_2 may be + positive integers, negative integers, or the spe- + cial expression -l _s_t_r_i_n_g, which evaluates to the + length of _s_t_r_i_n_g. + + times + Print the accumulated user and system times for the + shell and for processes run from the shell. The return + status is 0. + + trap [-l] [_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 or + -, all specified signals are reset to their original + values (the values they had upon entrance to the + shell). If _a_r_g is the null string this signal is + ignored by the shell and by the commands it invokes. + _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. If _s_i_g_s_p_e_c is EXIT (0) the command + _a_r_g is executed on exit from the shell. With no argu- + ments, trap prints the list of commands associated with + each signal number. The -l option causes the shell to + + + +GNU Last change: 1993 September 16 15 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + print a list of signal names and their corresponding + numbers. An argument of -- disables option checking + for the rest of the arguments. Signals ignored upon + entry to the shell cannot be trapped or reset. Trapped + signals are reset to their original values in a child + process when it is created. The return status is false + if either the trap name or number is invalid; otherwise + trap returns true. + + type [-all] [-type | -path] _n_a_m_e [_n_a_m_e ...] + With no options, indicate how each _n_a_m_e would be inter- + preted if used as a command name. If the -type flag is + used, type prints a phrase 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 name is not found, then nothing is + printed, and an exit status of false is returned. If + the -path flag is used, type either returns the name of + the disk file that would be executed if _n_a_m_e were + specified as a command name, or nothing if -type would + not return _f_i_l_e. If a command is hashed, -path prints + the hashed value, not necessarily the file that appears + first in PATH. If the -all flag is used, type prints + all of the places that contain an executable named + _n_a_m_e. This includes aliases and functions, if and only + if the -path flag is not also used. The table of + hashed commands is not consulted when using -all. type + accepts -a, -t, and -p in place of -all, -type, and + -path, respectively. An argument of -- disables option + checking for the rest of the arguments. type returns + true if any of the arguments are found, false if none + are found. + + ulimit [-SHacdfmstpnuv [_l_i_m_i_t]] + Ulimit provides control over the resources available to + the shell and to processes started by it, on systems + that allow such control. The value of _l_i_m_i_t can be a + number in the unit specified for the resource, or the + value unlimited. The H and S options specify that the + hard or soft limit is set for the given resource. A + hard limit cannot be increased once it is set; a soft + limit may be increased up to the value of the hard + limit. If neither H nor S is specified, the command + applies to the soft limit. If _l_i_m_i_t is omitted, the + current value of the soft limit of the resource is + printed, unless the H option is given. When more than + one resource is specified, the limit name and unit is + printed before the value. Other options are inter- + preted as follows: + -a all current limits are reported + -c the maximum size of core files created + -d the maximum size of a process's data segment + + + +GNU Last change: 1993 September 16 16 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + -f the maximum size of files created by the shell + -m the maximum resident set size + -s the maximum stack size + -t the maximum amount of cpu time in seconds + -p the pipe size in 512-byte blocks (this may not be + set) + -n the maximum number of open file descriptors (most + systems do not allow this value to be set, only + displayed) + -u the maximum number of processes available to a + single user + -v The maximum amount of virtual memory available to + the shell + + An argument of -- disables option checking for the rest + of the arguments. If _l_i_m_i_t is given, it is the new + value of the specified resource (the -a option is + display only). If no option is given, then -f is + assumed. Values are in 1024-byte increments, except + for -t, which is in seconds, -p, which is in units of + 512-byte blocks, and -n and -u, which are unscaled + values. The return status is 0 unless an illegal + option is encountered, a non-numeric argument other + than unlimited is supplied as _l_i_m_i_t, or an error occurs + while setting a new limit. + + umask [-S] [_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, or if the -S option is supplied, the current + value of the mask is printed. The -S option causes the + mask to be printed in symbolic form; the default output + is an octal number. An argument of -- disables option + checking for the rest of the arguments. The return + status is 0 if the mode was successfully changed or if + no _m_o_d_e argument was supplied, and false otherwise. + + unalias [-a] [_n_a_m_e ...] + Remove _n_a_m_es from the list of defined aliases. If -a + is supplied, all alias definitions are removed. The + return value is true unless a supplied _n_a_m_e is not a + defined alias. + + unset [-fv] [_n_a_m_e ...] + For each _n_a_m_e, remove the corresponding variable or, + given the -f option, function. An argument of -- dis- + ables option checking for the rest of the arguments. + Note that PATH, IFS, PPID, PS1, PS2, UID, and EUID can- + not be unset. If any of RANDOM, SECONDS, LINENO, or + HISTCMD are unset, they lose their special properties, + + + +GNU Last change: 1993 September 16 17 + + + + + + +BASH_BUILTINS(1) USER COMMANDS BASH_BUILTINS(1) + + + + even if they are subsequently reset. The exit status + is true unless a _n_a_m_e does not exist or is non- + unsettable. + + wait [_n] + Wait for the specified process and return its termina- + tion status. _n may be a process ID or a job specifica- + tion; if a job spec is given, all processes in that + job's pipeline are waited for. If _n is not given, all + currently active child processes are waited for, and + the return status is zero. If _n specifies a non- + existant process or job, the return status is 127. + Otherwise, the return status is the exit status of the + last process or job waited for. + +SEE ALSO + bash(1), sh(1) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +GNU Last change: 1993 September 16 18 + + + |