diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/builtins.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/builtins.1 | 3909 |
1 files changed, 3909 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/builtins.1 b/upstream/mageia-cauldron/man1/builtins.1 new file mode 100644 index 00000000..00dc28b0 --- /dev/null +++ b/upstream/mageia-cauldron/man1/builtins.1 @@ -0,0 +1,3909 @@ +.lf 1 ./builtins.1 +.\" This is a hack to force bash builtins into the whatis database +.\" and to get the list of builtins to come up with the man command. +.\" +.\" File Name macro. This used to be `.PN', for Path Name, +.\" but Sun doesn't seem to like that very much. +.\" +.de FN +\fI\|\\$1\|\fP +.. +.TH BASH_BUILTINS 1 "2021 November 22" "GNU Bash 5.2" +.SH NAME +:, ., [, 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, +readarray, readonly, return, set, +shift, shopt, source, suspend, test, times, trap, true, type, typeset, +ulimit, umask, unalias, unset, wait \- bash built-in commands, see \fBbash\fR(1) +.SH BASH BUILTIN COMMANDS +.nr zZ 1 +.lf 1 ./bash.1 +.\" +.\" MAN PAGE COMMENTS to +.\" +.\" Chet Ramey +.\" Case Western Reserve University +.\" chet.ramey@case.edu +.\" +.\" Last Change: Mon Sep 19 11:13:21 EDT 2022 +.\" +.\" bash_builtins, strip all but Built-Ins section +.PP +Unless otherwise noted, each builtin command documented in this +section as accepting options preceded by +.B \- +accepts +.B \-\- +to signify the end of the options. +The \fB:\fP, \fBtrue\fP, \fBfalse\fP, and \fBtest\fP/\fB[\fP builtins +do not accept options and do not treat \fB\-\-\fP specially. +The \fBexit\fP, \fBlogout\fP, \fBreturn\fP, +\fBbreak\fP, \fBcontinue\fP, \fBlet\fP, +and \fBshift\fP builtins accept and process arguments beginning with +\fB\-\fP without requiring \fB\-\-\fP. +Other builtins that accept arguments but are not specified as accepting +options interpret arguments beginning with \fB\-\fP as invalid options and +require \fB\-\-\fP to prevent this interpretation. +.sp .5 +.PD 0 +.TP +\fB:\fP [\fIarguments\fP] +.PD +No effect; the command does nothing beyond expanding +.I arguments +and performing any specified +redirections. +The return status is zero. +.TP +\fB .\| \fP \fIfilename\fP [\fIarguments\fP] +.PD 0 +.TP +\fBsource\fP \fIfilename\fP [\fIarguments\fP] +.PD +Read and execute commands from +.I filename +in the current +shell environment and return the exit status of the last command +executed from +.IR filename . +If +.I filename +does not contain a slash, filenames in +.SM +.B PATH +are used to find the directory containing +.IR filename , +but \fIfilename\fP does not need to be executable. +The file searched for in +.SM +.B PATH +need not be executable. +When \fBbash\fP is not in \fIposix mode\fP, it searches +the current directory if no file is found in +.SM +.BR PATH . +If the +.B sourcepath +option to the +.B shopt +builtin command is turned off, the +.SM +.B PATH +is not searched. +If any \fIarguments\fP are supplied, they become the positional +parameters when \fIfilename\fP is executed. Otherwise the positional +parameters are unchanged. +If the \fB\-T\fP option is enabled, \fB.\fP inherits any trap on +\fBDEBUG\fP; if it is not, any \fBDEBUG\fP trap string is saved and +restored around the call to \fB.\fP, and \fB.\fP unsets the +\fBDEBUG\fP trap while it executes. +If \fB\-T\fP is not set, and the sourced file changes +the \fBDEBUG\fP trap, the new value is retained when \fB.\fP completes. +The return status is the status of the last command exited within +the script (0 if no commands are executed), and false if +.I filename +is not found or cannot be read. +.TP +\fBalias\fP [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +\fBAlias\fP with no arguments or with the +.B \-p +option prints the list of aliases in the form +\fBalias\fP \fIname\fP=\fIvalue\fP on standard output. +When arguments are supplied, an alias is defined for +each \fIname\fP whose \fIvalue\fP is given. +A trailing space in \fIvalue\fP causes the next word to be +checked for alias substitution when the alias is expanded. +For each \fIname\fP in the argument list for which no \fIvalue\fP +is supplied, the name and value of the alias is printed. +\fBAlias\fP returns true unless a \fIname\fP is given for which +no alias has been defined. +.TP +\fBbg\fP [\fIjobspec\fP ...] +Resume each suspended job \fIjobspec\fP in the background, as if it +had been started with +.BR & . +If +.I jobspec +is not present, the shell's notion of the \fIcurrent job\fP is used. +.B bg +.I jobspec +returns 0 unless run when job control is disabled or, when run with +job control enabled, any specified \fIjobspec\fP was not found +or was started without job control. +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP] +.PD 0 +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP] +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-f\fP \fIfilename\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fB\-x\fP \fIkeyseq\fP:\fIshell\-command\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIfunction\-name\fP +.TP +\fBbind\fP [\fB\-m\fP \fIkeymap\fP] \fIkeyseq\fP:\fIreadline\-command\fP +.TP +\fBbind\fP \fIreadline-command-line\fP +.PD +Display current +.B readline +key and function bindings, bind a key sequence to a +.B readline +function or macro, or set a +.B readline +variable. +Each non-option argument is a command as it would appear in a +.B readline +initialization file such as +.IR .inputrc , +but each binding or command must be passed as a separate argument; +e.g., '"\eC\-x\eC\-r": re\-read\-init\-file'. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-m \fIkeymap\fP +Use +.I keymap +as the keymap to be affected by the subsequent bindings. +Acceptable +.I keymap +names are +\fIemacs, emacs\-standard, emacs\-meta, emacs\-ctlx, vi, +vi\-move, vi\-command\fP, and +.IR vi\-insert . +\fIvi\fP is equivalent to \fIvi\-command\fP (\fIvi\-move\fP is also +a synonym); \fIemacs\fP is +equivalent to \fIemacs\-standard\fP. +.TP +.B \-l +List the names of all \fBreadline\fP functions. +.TP +.B \-p +Display \fBreadline\fP function names and bindings in such a way +that they can be re-read. +.TP +.B \-P +List current \fBreadline\fP function names and bindings. +.TP +.B \-s +Display \fBreadline\fP key sequences bound to macros and the strings +they output in such a way that they can be re-read. +.TP +.B \-S +Display \fBreadline\fP key sequences bound to macros and the strings +they output. +.TP +.B \-v +Display \fBreadline\fP variable names and values in such a way that they +can be re-read. +.TP +.B \-V +List current \fBreadline\fP variable names and values. +.TP +.B \-f \fIfilename\fP +Read key bindings from \fIfilename\fP. +.TP +.B \-q \fIfunction\fP +Query about which keys invoke the named \fIfunction\fP. +.TP +.B \-u \fIfunction\fP +Unbind all keys bound to the named \fIfunction\fP. +.TP +.B \-r \fIkeyseq\fP +Remove any current binding for \fIkeyseq\fP. +.TP +.B \-x \fIkeyseq\fP:\fIshell\-command\fP +Cause \fIshell\-command\fP to be executed whenever \fIkeyseq\fP is +entered. +When \fIshell\-command\fP is executed, the shell sets the +.SM +.B READLINE_LINE +variable to the contents of the \fBreadline\fP line buffer and the +.SM +.B READLINE_POINT +and +.SM +.B READLINE_MARK +variables to the current location of the insertion point and the saved +insertion point (the mark), respectively. +The shell assigns any numeric argument the user supplied to the +.SM +.B READLINE_ARGUMENT +variable. +If there was no argument, that variable is not set. +If the executed command changes the value of any of +.SM +.BR READLINE_LINE , +.SM +.BR READLINE_POINT , +or +.SM +.BR READLINE_MARK , +those new values will be reflected in the editing state. +.TP +.B \-X +List all key sequences bound to shell commands and the associated commands +in a format that can be reused as input. +.PD +.PP +The return value is 0 unless an unrecognized option is given or an +error occurred. +.RE +.TP +\fBbreak\fP [\fIn\fP] +Exit from within a +.BR for , +.BR while , +.BR until , +or +.B select +loop. If \fIn\fP is specified, break \fIn\fP levels. +.I n +must be \(>= 1. If +.I n +is greater than the number of enclosing loops, all enclosing loops +are exited. +The return value is 0 unless \fIn\fP is not greater than or equal to 1. +.TP +\fBbuiltin\fP \fIshell\-builtin\fP [\fIarguments\fP] +Execute the specified shell builtin, passing it +.IR arguments , +and return its exit status. +This is useful when defining a +function whose name is the same as a shell builtin, +retaining the functionality of the builtin within the function. +The \fBcd\fP builtin is commonly redefined this way. +The return status is false if +.I shell\-builtin +is not a shell builtin command. +.TP +\fBcaller\fP [\fIexpr\fP] +Returns the context of any active subroutine call (a shell function or +a script executed with the \fB.\fP or \fBsource\fP builtins). +Without \fIexpr\fP, \fBcaller\fP displays the line number and source +filename of the current subroutine call. +If a non-negative integer is supplied as \fIexpr\fP, \fBcaller\fP +displays the line number, subroutine name, and source file corresponding +to that position in the current execution call stack. This extra +information may be used, for example, to print a stack trace. The +current frame is frame 0. +The return value is 0 unless the shell is not executing a subroutine +call or \fIexpr\fP does not correspond to a valid position in the +call stack. +.TP +\fBcd\fP [\fB\-L\fP|[\fB\-P\fP [\fB\-e\fP]] [\-@]] [\fIdir\fP] +Change the current directory to \fIdir\fP. +if \fIdir\fP is not supplied, the value of the +.SM +.B HOME +shell variable is the default. +The variable +.SM +.B CDPATH +defines the search path for the directory containing +.IR dir : +each directory name in +.SM +.B CDPATH +is searched for \fIdir\fP. +Alternative directory names in +.SM +.B CDPATH +are separated by a colon (:). A null directory name in +.SM +.B CDPATH +is the same as the current directory, i.e., ``\fB.\fP''. If +.I dir +begins with a slash (/), +then +.SM +.B CDPATH +is not used. The +.B \-P +option causes \fBcd\fP to use the physical directory structure +by resolving symbolic links while traversing \fIdir\fP and +before processing instances of \fI..\fP in \fIdir\fP (see also the +.B \-P +option to the +.B set +builtin command); the +.B \-L +option forces symbolic links to be followed by resolving the link +after processing instances of \fI..\fP in \fIdir\fP. +If \fI..\fP appears in \fIdir\fP, it is processed by removing the +immediately previous pathname component from \fIdir\fP, back to a slash +or the beginning of \fIdir\fP. +If the +.B \-e +option is supplied with +.BR \-P , +and the current working directory cannot be successfully determined +after a successful directory change, \fBcd\fP will return an unsuccessful +status. +On systems that support it, the \fB\-@\fP option presents the extended +attributes associated with a file as a directory. +An argument of +.B \- +is converted to +.SM +.B $OLDPWD +before the directory change is attempted. +If a non-empty directory name from +.SM +.B CDPATH +is used, or if +\fB\-\fP is the first argument, and the directory change is +successful, the absolute pathname of the new working directory is +written to the standard output. +If the directory change is successful, \fBcd\fP sets the value of the +\fBPWD\fP environment variable to the new directory name, and sets the +\fBOLDPWD\fP environment variable to the value of the current working +directory before the change. +The return value is true if the directory was successfully changed; +false otherwise. +.TP +\fBcommand\fP [\fB\-pVv\fP] \fIcommand\fP [\fIarg\fP ...] +Run +.I command +with +.I args +suppressing the normal shell function lookup. +Only builtin commands or commands found in the +.SM +.B PATH +are executed. If the +.B \-p +option is given, the search for +.I command +is performed using a default value for +.SM +.B PATH +that is guaranteed to find all of the standard utilities. +If either the +.B \-V +or +.B \-v +option is supplied, a description of +.I command +is printed. The +.B \-v +option causes a single word indicating the command or filename +used to invoke +.I command +to be displayed; the +.B \-V +option produces a more verbose description. +If the +.B \-V +or +.B \-v +option is supplied, the exit status is 0 if +.I command +was found, and 1 if not. If neither option is supplied and +an error occurred or +.I command +cannot be found, the exit status is 127. Otherwise, the exit status of the +.B command +builtin is the exit status of +.IR command . +.TP +\fBcompgen\fP [\fIoption\fP] [\fIword\fP] +Generate possible completion matches for \fIword\fP according to +the \fIoption\fPs, which may be any option accepted by the +.B complete +builtin with the exception of \fB\-p\fP and \fB\-r\fP, and write +the matches to the standard output. +When using the \fB\-F\fP or \fB\-C\fP options, the various shell variables +set by the programmable completion facilities, while available, will not +have useful values. +.sp 1 +The matches will be generated in the same way as if the programmable +completion code had generated them directly from a completion specification +with the same flags. +If \fIword\fP is specified, only those completions matching \fIword\fP +will be displayed. +.sp 1 +The return value is true unless an invalid option is supplied, or no +matches were generated. +.TP +\fBcomplete\fP [\fB\-abcdefgjksuv\fP] [\fB\-o\fP \fIcomp-option\fP] [\fB\-DEI\fP] [\fB\-A\fP \fIaction\fP] [\fB\-G\fP \fIglobpat\fP] [\fB\-W\fP \fIwordlist\fP] +.br +[\fB\-F\fP \fIfunction\fP] [\fB\-C\fP \fIcommand\fP] [\fB\-X\fP \fIfilterpat\fP] [\fB\-P\fP \fIprefix\fP] [\fB\-S\fP \fIsuffix\fP] \fIname\fP [\fIname ...\fP] +.PD 0 +.TP +\fBcomplete\fP \fB\-pr\fP [\fB\-DEI\fP] [\fIname\fP ...] +.PD +Specify how arguments to each \fIname\fP should be completed. +If the \fB\-p\fP 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 \fB\-r\fP option removes a completion specification for +each \fIname\fP, or, if no \fIname\fPs are supplied, all +completion specifications. +The \fB\-D\fP option indicates that other supplied options and actions should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The \fB\-E\fP option indicates that other supplied options and actions should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The \fB\-I\fP option indicates that other supplied options and actions should +apply to completion on the initial non-assignment word on the line, or after +a command delimiter such as \fB;\fP or \fB|\fP, which is usually command +name completion. +If multiple options are supplied, the \fB\-D\fP option takes precedence +over \fB\-E\fP, and both take precedence over \fB\-I\fP. +If any of \fB\-D\fP, \fB\-E\fP, or \fB\-I\fP are supplied, any other +\fIname\fP arguments are ignored; these completions only apply to the case +specified by the option. +.sp 1 +The process of applying these completion specifications when word completion +is attempted is described +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above under \fBProgrammable Completion\fP. +.sp 1 +Other options, if specified, have the following meanings. +The arguments to the \fB\-G\fP, \fB\-W\fP, and \fB\-X\fP options +(and, if necessary, the \fB\-P\fP and \fB\-S\fP options) +should be quoted to protect them from expansion before the +.B complete +builtin is invoked. +.RS +.PD 0 +.TP 8 +\fB\-o\fP \fIcomp-option\fP +The \fIcomp-option\fP controls several aspects of the compspec's behavior +beyond the simple generation of completions. +\fIcomp-option\fP may be one of: +.RS +.TP 8 +.B bashdefault +Perform the rest of the default \fBbash\fP completions if the compspec +generates no matches. +.TP 8 +.B default +Use readline's default filename completion if the compspec generates +no matches. +.TP 8 +.B dirnames +Perform directory name completion if the compspec generates no matches. +.TP 8 +.B filenames +Tell readline that the compspec generates filenames, so it can perform any +filename\-specific processing (like adding a slash to directory names, +quoting special characters, or suppressing trailing spaces). +Intended to be used with shell functions. +.TP 8 +.B noquote +Tell readline not to quote the completed words if they are filenames +(quoting filenames is the default). +.TP 8 +.B nosort +Tell readline not to sort the list of possible completions alphabetically. +.TP 8 +.B nospace +Tell readline not to append a space (the default) to words completed at +the end of the line. +.TP 8 +.B plusdirs +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. +.RE +.TP 8 +\fB\-A\fP \fIaction\fP +The \fIaction\fP may be one of the following to generate a list of possible +completions: +.RS +.TP 8 +.B alias +Alias names. May also be specified as \fB\-a\fP. +.TP 8 +.B arrayvar +Array variable names. +.TP 8 +.B binding +\fBReadline\fP key binding names. +.TP 8 +.B builtin +Names of shell builtin commands. May also be specified as \fB\-b\fP. +.TP 8 +.B command +Command names. May also be specified as \fB\-c\fP. +.TP 8 +.B directory +Directory names. May also be specified as \fB\-d\fP. +.TP 8 +.B disabled +Names of disabled shell builtins. +.TP 8 +.B enabled +Names of enabled shell builtins. +.TP 8 +.B export +Names of exported shell variables. May also be specified as \fB\-e\fP. +.TP 8 +.B file +File names. May also be specified as \fB\-f\fP. +.TP 8 +.B function +Names of shell functions. +.TP 8 +.B group +Group names. May also be specified as \fB\-g\fP. +.TP 8 +.B helptopic +Help topics as accepted by the \fBhelp\fP builtin. +.TP 8 +.B hostname +Hostnames, as taken from the file specified by the +.SM +.B HOSTFILE +shell variable. +.TP 8 +.B job +Job names, if job control is active. May also be specified as \fB\-j\fP. +.TP 8 +.B keyword +Shell reserved words. May also be specified as \fB\-k\fP. +.TP 8 +.B running +Names of running jobs, if job control is active. +.TP 8 +.B service +Service names. May also be specified as \fB\-s\fP. +.TP 8 +.B setopt +Valid arguments for the \fB\-o\fP option to the \fBset\fP builtin. +.TP 8 +.B shopt +Shell option names as accepted by the \fBshopt\fP builtin. +.TP 8 +.B signal +Signal names. +.TP 8 +.B stopped +Names of stopped jobs, if job control is active. +.TP 8 +.B user +User names. May also be specified as \fB\-u\fP. +.TP 8 +.B variable +Names of all shell variables. May also be specified as \fB\-v\fP. +.RE +.TP 8 +\fB\-C\fP \fIcommand\fP +\fIcommand\fP is executed in a subshell environment, and its output is +used as the possible completions. +Arguments are passed as with the \fB\-F\fP option. +.TP 8 +\fB\-F\fP \fIfunction\fP +The shell function \fIfunction\fP is executed in the current shell +environment. +When the function is executed, +the first argument (\fB$1\fP) is the name of the command whose arguments are +being completed, +the second argument (\fB$2\fP) is the word being completed, +and the third argument (\fB$3\fP) 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 +.SM +.B COMPREPLY +array variable. +.TP 8 +\fB\-G\fP \fIglobpat\fP +The pathname expansion pattern \fIglobpat\fP is expanded to generate +the possible completions. +.TP 8 +\fB\-P\fP \fIprefix\fP +\fIprefix\fP is added at the beginning of each possible completion +after all other options have been applied. +.TP 8 +\fB\-S\fP \fIsuffix\fP +\fIsuffix\fP is appended to each possible completion +after all other options have been applied. +.TP 8 +\fB\-W\fP \fIwordlist\fP +The \fIwordlist\fP is split using the characters in the +.SM +.B IFS +special variable as delimiters, and each resultant word is expanded. +Shell quoting is honored within \fIwordlist\fP, +in order to provide a +mechanism for the words to contain shell metacharacters or characters +in the value of +.SM +.BR IFS . +The possible completions are the members of the resultant list which +match the word being completed. +.TP 8 +\fB\-X\fP \fIfilterpat\fP +\fIfilterpat\fP is a pattern as used for pathname expansion. +It is applied to the list of possible completions generated by the +preceding options and arguments, and each completion matching +\fIfilterpat\fP is removed from the list. +A leading \fB!\fP in \fIfilterpat\fP negates the pattern; in this +case, any completion not matching \fIfilterpat\fP is removed. +.PD +.PP +The return value is true unless an invalid option is supplied, an option +other than \fB\-p\fP or \fB\-r\fP is supplied without a \fIname\fP +argument, an attempt is made to remove a completion specification for +a \fIname\fP for which no specification exists, or +an error occurs adding a completion specification. +.RE +.TP +\fBcompopt\fP [\fB\-o\fP \fIoption\fP] [\fB\-DEI\fP] [\fB+o\fP \fIoption\fP] [\fIname\fP] +Modify completion options for each \fIname\fP according to the +\fIoption\fPs, or for the +currently-executing completion if no \fIname\fPs are supplied. +If no \fIoption\fPs are given, display the completion options for each +\fIname\fP or the current completion. +The possible values of \fIoption\fP are those valid for the \fBcomplete\fP +builtin described above. +The \fB\-D\fP 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 \fB\-E\fP option indicates that other supplied options should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The \fB\-I\fP option indicates that other supplied options should +apply to completion on the initial non-assignment word on the line, +or after a command delimiter such as \fB;\fP or \fB|\fP, which is usually +command name completion. +.sp 1 +The return value is true unless an invalid option is supplied, an attempt +is made to modify the options for a \fIname\fP for which no completion +specification exists, or an output error occurs. +.TP +\fBcontinue\fP [\fIn\fP] +Resume the next iteration of the enclosing +.BR for , +.BR while , +.BR until , +or +.B select +loop. +If +.I n +is specified, resume at the \fIn\fPth enclosing loop. +.I n +must be \(>= 1. If +.I 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 \fIn\fP is not greater than or equal to 1. +.TP +\fBdeclare\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +.PD 0 +.TP +\fBtypeset\fP [\fB\-aAfFgiIlnrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +.PD +Declare variables and/or give them attributes. +If no \fIname\fPs are given then display the values of variables. +The +.B \-p +option will display the attributes and values of each +.IR name . +When +.B \-p +is used with \fIname\fP arguments, additional options, +other than \fB\-f\fP and \fB\-F\fP, are ignored. +When +.B \-p +is supplied without \fIname\fP 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 \fB\-p\fP, \fBdeclare\fP will display +the attributes and values of all shell variables. The \fB\-f\fP option +will restrict the display to shell functions. +The +.B \-F +option inhibits the display of function definitions; only the +function name and attributes are printed. +If the \fBextdebug\fP shell option is enabled using \fBshopt\fP, +the source file name and line number where each \fIname\fP +is defined are displayed as well. The +.B \-F +option implies +.BR \-f . +The +.B \-g +option forces variables to be created or modified at the global scope, +even when \fBdeclare\fP is executed in a shell function. +It is ignored in all other cases. +The +.B \-I +option causes local variables to inherit the attributes +(except the \fInameref\fP attribute) +and value of any existing variable with the same +\fIname\fP at a surrounding scope. +If there is no existing variable, the local variable is initially unset. +The following options can +be used to restrict output to variables with the specified attribute or +to give variables attributes: +.RS +.PD 0 +.TP +.B \-a +Each \fIname\fP is an indexed array variable (see +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B \-A +Each \fIname\fP is an associative array variable (see +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B \-f +Use function names only. +.TP +.B \-i +The variable is treated as an integer; arithmetic evaluation (see +.SM +.B "ARITHMETIC EVALUATION" +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +is performed when the variable is assigned a value. +.TP +.B \-l +When the variable is assigned a value, all upper-case characters are +converted to lower-case. +The upper-case attribute is disabled. +.TP +.B \-n +Give each \fIname\fP the \fInameref\fP attribute, making +it a name reference to another variable. +That other variable is defined by the value of \fIname\fP. +All references, assignments, and attribute modifications +to \fIname\fP, except those using or changing the +\fB\-n\fP attribute itself, are performed on the variable referenced by +\fIname\fP's value. +The nameref attribute cannot be applied to array variables. +.TP +.B \-r +Make \fIname\fPs readonly. These names cannot then be assigned values +by subsequent assignment statements or unset. +.TP +.B \-t +Give each \fIname\fP the \fItrace\fP attribute. +Traced functions inherit the \fBDEBUG\fP and \fBRETURN\fP traps from +the calling shell. +The trace attribute has no special meaning for variables. +.TP +.B \-u +When the variable is assigned a value, all lower-case characters are +converted to upper-case. +The lower-case attribute is disabled. +.TP +.B \-x +Mark \fIname\fPs for export to subsequent commands via the environment. +.PD +.PP +Using `+' instead of `\-' +turns off the attribute instead, +with the exceptions that \fB+a\fP and \fB+A\fP +may not be used to destroy array variables and \fB+r\fP will not +remove the readonly attribute. +When used in a function, +.B declare +and +.B typeset +make each +\fIname\fP local, as with the +.B local +command, +unless the \fB\-g\fP option is supplied. +If a variable name is followed by =\fIvalue\fP, the value of +the variable is set to \fIvalue\fP. +When using \fB\-a\fP or \fB\-A\fP and the compound assignment syntax to +create array variables, additional attributes do not take effect until +subsequent assignments. +The return value is 0 unless an invalid option is encountered, +an attempt is made to define a function using +.if n ``\-f foo=bar'', +.if t \f(CW\-f foo=bar\fP, +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 +.B Arrays +.ie \n(zZ=1 in \fIbash(1)\fP), +.el above), +one of the \fInames\fP is not a valid shell variable name, +an attempt is made to turn off readonly status for a readonly variable, +an attempt is made to turn off array status for an array variable, +or an attempt is made to display a non-existent function with \fB\-f\fP. +.RE +.TP +.B dirs [\fB\-clpv\fP] [+\fIn\fP] [\-\fIn\fP] +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 +.B pushd +command; the +.B popd +command removes entries from the list. +The current directory is always the first directory in the stack. +.RS +.PD 0 +.TP +.B \-c +Clears the directory stack by deleting all of the entries. +.TP +.B \-l +Produces a listing using full pathnames; +the default listing format uses a tilde to denote the home directory. +.TP +.B \-p +Print the directory stack with one entry per line. +.TP +.B \-v +Print the directory stack with one entry per line, +prefixing each entry with its index in the stack. +.TP +\fB+\fP\fIn\fP +Displays the \fIn\fPth entry counting from the left of the list +shown by +.B dirs +when invoked without options, starting with zero. +.TP +\fB\-\fP\fIn\fP +Displays the \fIn\fPth entry counting from the right of the list +shown by +.B dirs +when invoked without options, starting with zero. +.PD +.PP +The return value is 0 unless an +invalid option is supplied or \fIn\fP indexes beyond the end +of the directory stack. +.RE +.TP +\fBdisown\fP [\fB\-ar\fP] [\fB\-h\fP] [\fIjobspec\fP ... | \fIpid\fP ... ] +Without options, remove each +.I jobspec +from the table of active jobs. +If +.I jobspec +is not present, and neither the \fB\-a\fP nor the \fB\-r\fP option +is supplied, the \fIcurrent job\fP is used. +If the \fB\-h\fP option is given, each +.I jobspec +is not removed from the table, but is marked so that +.SM +.B SIGHUP +is not sent to the job if the shell receives a +.SM +.BR SIGHUP . +If no +.I jobspec +is supplied, the +.B \-a +option means to remove or mark all jobs; the +.B \-r +option without a +.I jobspec +argument restricts operation to running jobs. +The return value is 0 unless a +.I jobspec +does not specify a valid job. +.TP +\fBecho\fP [\fB\-neE\fP] [\fIarg\fP ...] +Output the \fIarg\fPs, separated by spaces, followed by a newline. +The return status is 0 unless a write error occurs. +If \fB\-n\fP is specified, the trailing newline is +suppressed. If the \fB\-e\fP option is given, interpretation of +the following backslash-escaped characters is enabled. The +.B \-E +option disables the interpretation of these escape characters, +even on systems where they are interpreted by default. +The \fBxpg_echo\fP shell option may be used to +dynamically determine whether or not \fBecho\fP expands these +escape characters by default. +.B echo +does not interpret \fB\-\-\fP to mean the end of options. +.B echo +interprets the following escape sequences: +.RS +.PD 0 +.TP +.B \ea +alert (bell) +.TP +.B \eb +backspace +.TP +.B \ec +suppress further output +.TP +.B \ee +.TP +.B \eE +an escape character +.TP +.B \ef +form feed +.TP +.B \en +new line +.TP +.B \er +carriage return +.TP +.B \et +horizontal tab +.TP +.B \ev +vertical tab +.TP +.B \e\e +backslash +.TP +.B \e0\fInnn\fP +the eight-bit character whose value is the octal value \fInnn\fP +(zero to three octal digits) +.TP +.B \ex\fIHH\fP +the eight-bit character whose value is the hexadecimal value \fIHH\fP +(one or two hex digits) +.TP +.B \eu\fIHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHH\fP (one to four hex digits) +.TP +.B \eU\fIHHHHHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHHHHHH\fP (one to eight hex digits) +.PD +.RE +.TP +\fBenable\fP [\fB\-a\fP] [\fB\-dnps\fP] [\fB\-f\fP \fIfilename\fP] [\fIname\fP ...] +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 \fB\-n\fP is used, each \fIname\fP +is disabled; otherwise, +\fInames\fP are enabled. For example, to use the +.B test +binary found via the +.SM +.B PATH +instead of the shell builtin version, run +.if t \f(CWenable -n test\fP. +.if n ``enable -n test''. +The +.B \-f +option means to load the new builtin command +.I name +from shared object +.IR filename , +on systems that support dynamic loading. +Bash will use the value of the \fBBASH_LOADABLES_PATH\fP variable as a +colon-separated list of directories in which to search for \fIfilename\fP. +The default is system-dependent. +The +.B \-d +option will delete a builtin previously loaded with +.BR \-f . +If no \fIname\fP arguments are given, or if the +.B \-p +option is supplied, a list of shell builtins is printed. +With no other option arguments, the list consists of all enabled +shell builtins. +If \fB\-n\fP is supplied, only disabled builtins are printed. +If \fB\-a\fP is supplied, the list printed includes all builtins, with an +indication of whether or not each is enabled. +If \fB\-s\fP is supplied, the output is restricted to the POSIX +\fIspecial\fP builtins. +If no options are supplied and a \fIname\fP is not a shell builtin, +\fBenable\fP will attempt to load \fIname\fP from a shared object named +\fIname\fP, as if the command were +.if t \f(CWenable \-f\fP \fIname name\fP . +.if n ``enable -f \fIname name\fP . +The return value is 0 unless a +.I name +is not a shell builtin or there is an error loading a new builtin +from a shared object. +.TP +\fBeval\fP [\fIarg\fP ...] +The \fIarg\fPs are read and concatenated together into a single +command. This command is then read and executed by the shell, and +its exit status is returned as the value of +.BR eval . +If there are no +.IR args , +or only null arguments, +.B eval +returns 0. +.TP +\fBexec\fP [\fB\-cl\fP] [\fB\-a\fP \fIname\fP] [\fIcommand\fP [\fIarguments\fP]] +If +.I command +is specified, it replaces the shell. +No new process is created. The +.I arguments +become the arguments to \fIcommand\fP. +If the +.B \-l +option is supplied, +the shell places a dash at the beginning of the zeroth argument passed to +.IR command . +This is what +.IR login (1) +does. The +.B \-c +option causes +.I command +to be executed with an empty environment. If +.B \-a +is supplied, the shell passes +.I name +as the zeroth argument to the executed command. +If +.I command +cannot be executed for some reason, a non-interactive shell exits, +unless the +.B execfail +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 \fBexec\fP fails. +If +.I command +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. +.TP +\fBexit\fP [\fIn\fP] +Cause the shell to exit +with a status of \fIn\fP. If +.I n +is omitted, the exit status +is that of the last command executed. +A trap on +.SM +.B EXIT +is executed before the shell terminates. +.TP +\fBexport\fP [\fB\-fn\fP\^] [\fIname\fP[=\fIword\fP]] ... +.PD 0 +.TP +.B export \-p +.PD +The supplied +.I names +are marked for automatic export to the environment of +subsequently executed commands. If the +.B \-f +option is given, the +.I names +refer to functions. +If no +.I names +are given, or if the +.B \-p +option is supplied, a list +of names of all exported variables is printed. +The +.B \-n +option causes the export property to be removed from each +\fIname\fP. +If a variable name is followed by =\fIword\fP, the value of +the variable is set to \fIword\fP. +.B export +returns an exit status of 0 unless an invalid option is +encountered, +one of the \fInames\fP is not a valid shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +\fBfc\fP [\fB\-e\fP \fIename\fP] [\fB\-lnr\fP] [\fIfirst\fP] [\fIlast\fP] +.PD 0 +.TP +\fBfc\fP \fB\-s\fP [\fIpat\fP=\fIrep\fP] [\fIcmd\fP] +.PD +The first form selects a range of commands from +.I first +to +.I last +from the history list and displays or edits and re-executes them. +.I First +and +.I last +may be specified as a string (to locate the last command beginning +with that string) or as a number (an index into the history list, +where a negative number is used as an offset from the current +command number). +When listing, a \fIfirst\fP or \fIlast\fP of +0 is equivalent to \-1 and \-0 is equivalent to the current +command (usually the \fBfc\fP command); otherwise 0 is equivalent to \-1 +and \-0 is invalid. +If +.I last +is not specified, it is set to +the current command for listing (so that +.if n ``fc \-l \-10'' +.if t \f(CWfc \-l \-10\fP +prints the last 10 commands) and to +.I first +otherwise. +If +.I first +is not specified, it is set to the previous +command for editing and \-16 for listing. +.sp 1 +The +.B \-n +option suppresses +the command numbers when listing. The +.B \-r +option reverses the order of +the commands. If the +.B \-l +option is given, +the commands are listed on +standard output. Otherwise, the editor given by +.I ename +is invoked +on a file containing those commands. If +.I ename +is not given, the +value of the +.SM +.B FCEDIT +variable is used, and +the value of +.SM +.B EDITOR +if +.SM +.B FCEDIT +is not set. If neither variable is set, +.FN vi +is used. When editing is complete, the edited commands are +echoed and executed. +.sp 1 +In the second form, \fIcommand\fP is re-executed after each instance +of \fIpat\fP is replaced by \fIrep\fP. +\fICommand\fP is interpreted the same as \fIfirst\fP above. +A useful alias to use with this is +.if n ``r="fc -s"'', +.if t \f(CWr='fc \-s'\fP, +so that typing +.if n ``r cc'' +.if t \f(CWr cc\fP +runs the last command beginning with +.if n ``cc'' +.if t \f(CWcc\fP +and typing +.if n ``r'' +.if t \f(CWr\fP +re-executes the last command. +.sp 1 +If the first form is used, the return value is 0 unless an invalid +option is encountered or +.I first +or +.I last +specify history lines out of range. +If the +.B \-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 +.I cmd +does not specify a valid history line, in which case +.B fc +returns failure. +.TP +\fBfg\fP [\fIjobspec\fP] +Resume +.I jobspec +in the foreground, and make it the current job. +If +.I jobspec +is not present, the shell's notion of the \fIcurrent job\fP 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 +.I jobspec +does not specify a valid job or +.I jobspec +specifies a job that was started without job control. +.TP +\fBgetopts\fP \fIoptstring\fP \fIname\fP [\fIarg ...\fP] +.B getopts +is used by shell procedures to parse positional parameters. +.I optstring +contains the option characters to be recognized; if a character +is followed by a colon, the option is expected to have an +argument, which should be separated from it by white space. +The colon and question mark characters may not be used as +option characters. +Each time it is invoked, +.B getopts +places the next option in the shell variable +.IR name , +initializing +.I name +if it does not exist, +and the index of the next argument to be processed into the +variable +.SM +.BR OPTIND . +.SM +.B OPTIND +is initialized to 1 each time the shell or a shell script +is invoked. When an option requires an argument, +.B getopts +places that argument into the variable +.SM +.BR OPTARG . +The shell does not reset +.SM +.B OPTIND +automatically; it must be manually reset between multiple +calls to +.B getopts +within the same shell invocation if a new set of parameters +is to be used. +.sp 1 +When the end of options is encountered, \fBgetopts\fP exits with a +return value greater than zero. +.SM +.B OPTIND +is set to the index of the first non-option argument, +and \fIname\fP is set to ?. +.sp 1 +.B getopts +normally parses the positional parameters, but if more arguments are +supplied as +.I arg +values, +.B getopts +parses those instead. +.sp 1 +.B getopts +can report errors in two ways. If the first character of +.I optstring +is a colon, +.I silent +error reporting is used. In normal operation, diagnostic messages +are printed when invalid options or missing option arguments are +encountered. +If the variable +.SM +.B OPTERR +is set to 0, no error messages will be displayed, even if the first +character of +.I optstring +is not a colon. +.sp 1 +If an invalid option is seen, +.B getopts +places ? into +.I name +and, if not silent, +prints an error message and unsets +.SM +.BR OPTARG . +If +.B getopts +is silent, +the option character found is placed in +.SM +.B OPTARG +and no diagnostic message is printed. +.sp 1 +If a required argument is not found, and +.B getopts +is not silent, +a question mark (\^\fB?\fP\^) is placed in +.IR name , +.SM +.B OPTARG +is unset, and a diagnostic message is printed. +If +.B getopts +is silent, then a colon (\^\fB:\fP\^) is placed in +.I name +and +.SM +.B OPTARG +is set to the option character found. +.sp 1 +.B 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. +.TP +\fBhash\fP [\fB\-lr\fP] [\fB\-p\fP \fIfilename\fP] [\fB\-dt\fP] [\fIname\fP] +Each time \fBhash\fP is invoked, +the full pathname of the command +.I name +is determined by searching +the directories in +.B $PATH +and remembered. Any previously-remembered pathname is discarded. +If the +.B \-p +option is supplied, no path search is performed, and +.I filename +is used as the full filename of the command. +The +.B \-r +option causes the shell to forget all +remembered locations. +The +.B \-d +option causes the shell to forget the remembered location of each \fIname\fP. +If the +.B \-t +option is supplied, the full pathname to which each \fIname\fP corresponds +is printed. If multiple \fIname\fP arguments are supplied with \fB\-t\fP, +the \fIname\fP is printed before the hashed full pathname. +The +.B \-l +option causes output to be displayed in a format that may be reused as input. +If no arguments are given, or if only \fB\-l\fP is supplied, +information about remembered commands is printed. +The return status is true unless a +.I name +is not found or an invalid option is supplied. +.TP +\fBhelp\fP [\fB\-dms\fP] [\fIpattern\fP] +Display helpful information about builtin commands. If +.I pattern +is specified, +.B help +gives detailed help on all commands matching +.IR pattern ; +otherwise help for all the builtins and shell control structures +is printed. +.RS +.PD 0 +.TP +.B \-d +Display a short description of each \fIpattern\fP +.TP +.B \-m +Display the description of each \fIpattern\fP in a manpage-like format +.TP +.B \-s +Display only a short usage synopsis for each \fIpattern\fP +.PD +.PP +The return status is 0 unless no command matches +.IR pattern . +.RE +.TP +\fBhistory [\fIn\fP] +.PD 0 +.TP +\fBhistory\fP \fB\-c\fP +.TP +\fBhistory \-d\fP \fIoffset\fP +.TP +\fBhistory \-d\fP \fIstart\fP\-\fIend\fP +.TP +\fBhistory\fP \fB\-anrw\fP [\fIfilename\fP] +.TP +\fBhistory\fP \fB\-p\fP \fIarg\fP [\fIarg ...\fP] +.TP +\fBhistory\fP \fB\-s\fP \fIarg\fP [\fIarg ...\fP] +.PD +With no options, display the command +history list with line numbers. Lines listed +with a +.B * +have been modified. An argument of +.I n +lists only the last +.I n +lines. +If the shell variable +.SM +.B HISTTIMEFORMAT +is set and not null, +it is used as a format string for \fIstrftime\fP(3) to display +the time stamp associated with each displayed history entry. +No intervening blank is printed between the formatted time stamp +and the history line. +If \fIfilename\fP is supplied, it is used as the +name of the history file; if not, the value of +.SM +.B HISTFILE +is used. Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-c +Clear the history list by deleting all the entries. +.TP +\fB\-d\fP \fIoffset\fP +Delete the history entry at position \fIoffset\fP. +If \fIoffset\fP 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 +\fBhistory -d\fP command. +.TP +\fB\-d\fP \fIstart\fP\-\fIend\fP +Delete the range of history entries between positions \fIstart\fP and +\fIend\fP, inclusive. +Positive and negative values for \fIstart\fP and \fIend\fP +are interpreted as described above. +.TP +.B \-a +Append the ``new'' history lines to the history file. +These are history lines entered since the beginning of the current +\fBbash\fP session, but not already appended to the history file. +.TP +.B \-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 \fBbash\fP session. +.TP +.B \-r +Read the contents of the history file +and append them to the current history list. +.TP +.B \-w +Write the current history list to the history file, overwriting the +history file's contents. +.TP +.B \-p +Perform history substitution on the following \fIargs\fP and display +the result on the standard output. +Does not store the results in the history list. +Each \fIarg\fP must be quoted to disable normal history expansion. +.TP +.B \-s +Store the +.I args +in the history list as a single entry. The last command in the +history list is removed before the +.I args +are added. +.PD +.PP +If the +.SM +.B HISTTIMEFORMAT +variable is set, the time stamp information +associated with each history entry is written to the history 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 +\fIoffset\fP or range is supplied as an argument to \fB\-d\fP, or the +history expansion supplied as an argument to \fB\-p\fP fails. +.RE +.TP +\fBjobs\fP [\fB\-lnprs\fP] [ \fIjobspec\fP ... ] +.PD 0 +.TP +\fBjobs\fP \fB\-x\fP \fIcommand\fP [ \fIargs\fP ... ] +.PD +The first form lists the active jobs. The options have the following +meanings: +.RS +.PD 0 +.TP +.B \-l +List process IDs +in addition to the normal information. +.TP +.B \-n +Display information only about jobs that have changed status since +the user was last notified of their status. +.TP +.B \-p +List only the process ID of the job's process group +leader. +.TP +.B \-r +Display only running jobs. +.TP +.B \-s +Display only stopped jobs. +.PD +.PP +If +.I jobspec +is given, output is restricted to information about that job. +The return status is 0 unless an invalid option is encountered +or an invalid +.I jobspec +is supplied. +.PP +If the +.B \-x +option is supplied, +.B jobs +replaces any +.I jobspec +found in +.I command +or +.I args +with the corresponding process group ID, and executes +.I command +passing it +.IR args , +returning its exit status. +.RE +.TP +\fBkill\fP [\fB\-s\fP \fIsigspec\fP | \fB\-n\fP \fIsignum\fP | \fB\-\fP\fIsigspec\fP] [\fIpid\fP | \fIjobspec\fP] ... +.PD 0 +.TP +\fBkill\fP \fB\-l\fP|\fB\-L\fP [\fIsigspec\fP | \fIexit_status\fP] +.PD +Send the signal named by +.I sigspec +or +.I signum +to the processes named by +.I pid +or +.IR jobspec . +.I sigspec +is either a case-insensitive signal name such as +.SM +.B SIGKILL +(with or without the +.SM +.B SIG +prefix) or a signal number; +.I signum +is a signal number. +If +.I sigspec +is not present, then +.SM +.B SIGTERM +is assumed. +An argument of +.B \-l +lists the signal names. +If any arguments are supplied when +.B \-l +is given, the names of the signals corresponding to the arguments are +listed, and the return status is 0. +The \fIexit_status\fP argument to +.B \-l +is a number specifying either a signal number or the exit status of +a process terminated by a signal. +The +.B \-L +option is equivalent to \fB\-l\fP. +.B kill +returns true if at least one signal was successfully sent, or false +if an error occurs or an invalid option is encountered. +.TP +\fBlet\fP \fIarg\fP [\fIarg\fP ...] +Each +.I arg +is an arithmetic expression to be evaluated (see +.SM +.B "ARITHMETIC EVALUATION" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +If the last +.I arg +evaluates to 0, +.B let +returns 1; 0 is returned otherwise. +.TP +\fBlocal\fP [\fIoption\fP] [\fIname\fP[=\fIvalue\fP] ... | \- ] +For each argument, a local variable named +.I name +is created, and assigned +.IR value . +The \fIoption\fP can be any of the options accepted by \fBdeclare\fP. +When +.B local +is used within a function, it causes the variable +.I name +to have a visible scope restricted to that function and its children. +If \fIname\fP is \-, the set of shell options is made local to the function +in which \fBlocal\fP is invoked: shell options changed using the +\fBset\fP builtin inside the function are restored to their original values +when the function returns. +The restore is effected as if a series of \fBset\fP commands were executed +to restore the values that were in place before the function. +With no operands, +.B local +writes a list of local variables to the standard output. It is +an error to use +.B local +when not within a function. The return status is 0 unless +.B local +is used outside a function, an invalid +.I name +is supplied, or +\fIname\fP is a readonly variable. +.TP +.B logout +Exit a login shell. +.TP +\fBmapfile\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP] +.PD 0 +.TP +\fBreadarray\fP [\fB\-d\fP \fIdelim\fP] [\fB\-n\fP \fIcount\fP] [\fB\-O\fP \fIorigin\fP] [\fB\-s\fP \fIcount\fP] [\fB\-t\fP] [\fB\-u\fP \fIfd\fP] [\fB\-C\fP \fIcallback\fP] [\fB\-c\fP \fIquantum\fP] [\fIarray\fP] +.PD +Read lines from the standard input into the indexed array variable +.IR array , +or from file descriptor +.I fd +if the +.B \-u +option is supplied. +The variable +.SM +.B MAPFILE +is the default \fIarray\fP. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-d +The first character of \fIdelim\fP is used to terminate each input line, +rather than newline. +If \fIdelim\fP is the empty string, \fBmapfile\fP will terminate a line +when it reads a NUL character. +.TP +.B \-n +Copy at most +.I count +lines. If \fIcount\fP is 0, all lines are copied. +.TP +.B \-O +Begin assigning to +.I array +at index +.IR origin . +The default index is 0. +.TP +.B \-s +Discard the first \fIcount\fP lines read. +.TP +.B \-t +Remove a trailing \fIdelim\fP (default newline) from each line read. +.TP +.B \-u +Read lines from file descriptor \fIfd\fP instead of the standard input. +.TP +.B \-C +Evaluate +.I callback +each time \fIquantum\fP lines are read. The \fB\-c\fP option specifies +.IR quantum . +.TP +.B \-c +Specify the number of lines read between each call to +.IR callback . +.PD +.PP +If +.B \-C +is specified without +.BR \-c , +the default quantum is 5000. +When \fIcallback\fP 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. +\fIcallback\fP is evaluated after the line is read but before the +array element is assigned. +.PP +If not supplied with an explicit origin, \fBmapfile\fP will clear \fIarray\fP +before assigning to it. +.PP +\fBmapfile\fP returns successfully unless an invalid option or option +argument is supplied, \fIarray\fP is invalid or unassignable, or if +\fIarray\fP is not an indexed array. +.RE +.TP +\fBpopd\fP [\-\fBn\fP] [+\fIn\fP] [\-\fIn\fP] +Removes entries from the directory stack. +The elements are numbered from 0 starting at the first directory +listed by \fBdirs\fP. +With no arguments, \fBpopd\fP +removes the top directory from the stack, and +changes to the new top directory. +Arguments, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-n +Suppresses the normal change of directory when removing directories +from the stack, so that only the stack is manipulated. +.TP +\fB+\fP\fIn\fP +Removes the \fIn\fPth entry counting from the left of the list +shown by +.BR dirs , +starting with zero, from the stack. +For example: +.if n ``popd +0'' +.if t \f(CWpopd +0\fP +removes the first directory, +.if n ``popd +1'' +.if t \f(CWpopd +1\fP +the second. +.TP +\fB\-\fP\fIn\fP +Removes the \fIn\fPth entry counting from the right of the list +shown by +.BR dirs , +starting with zero. For example: +.if n ``popd -0'' +.if t \f(CWpopd -0\fP +removes the last directory, +.if n ``popd -1'' +.if t \f(CWpopd -1\fP +the next to last. +.PD +.PP +If the top element of the directory stack is modified, and +the \fI-n\fP option was not supplied, \fBpopd\fP uses the \fBcd\fP +builtin to change to the directory at the top of the stack. +If the \fBcd\fP fails, \fBpopd\fP returns a non-zero value. +.PP +Otherwise, +.B popd +returns false if an invalid option is encountered, the directory stack +is empty, or a non-existent directory stack entry is specified. +.PP +If the +.B popd +command is successful, +bash runs +.B dirs +to show the final contents of the directory stack, +and the return status is 0. +.RE +.TP +\fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP] +Write the formatted \fIarguments\fP to the standard output under the +control of the \fIformat\fP. +The \fB\-v\fP option causes the output to be assigned to the variable +\fIvar\fP rather than being printed to the standard output. +.sp 1 +The \fIformat\fP 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 +\fIargument\fP. +In addition to the standard \fIprintf\fP(1) format specifications, +\fBprintf\fP interprets the following extensions: +.RS +.PD 0 +.TP +.B %b +causes +\fBprintf\fP to expand backslash escape sequences in the corresponding +\fIargument\fP +in the same way as \fBecho \-e\fP. +.TP +.B %q +causes \fBprintf\fP to output the corresponding +\fIargument\fP in a format that can be reused as shell input. +.TP +.B %Q +like \fB%q\fP, but applies any supplied precision to the \fIargument\fP +before quoting it. +.TP +.B %(\fIdatefmt\fP)T +causes \fBprintf\fP to output the date-time string resulting from using +\fIdatefmt\fP as a format string for \fIstrftime\fP(3). +The corresponding \fIargument\fP 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 \fBprintf\fP behavior. +.PD +.PP +The %b, %q, and %T directives all use the field width and precision +arguments from the format specification and write that many bytes from +(or use that wide a field for) the expanded argument, which usually +contains more characters than the original. +.PP +Arguments to non-string format specifiers are treated as C constants, +except that a leading plus or minus sign is allowed, and if the leading +character is a single or double quote, the value is the ASCII value of +the following character. +.PP +The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP. +If the \fIformat\fP requires more \fIarguments\fP 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. +.RE +.TP +\fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP] +.PD 0 +.TP +\fBpushd\fP [\fB\-n\fP] [\fIdir\fP] +.PD +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, \fBpushd\fP exchanges the top two elements of +the directory stack. +Arguments, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-n +Suppresses the normal change of directory when rotating or +adding directories to the stack, so that only the stack is manipulated. +.TP +\fB+\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the left of the list shown by +.BR dirs , +starting with zero) +is at the top. +.TP +\fB\-\fP\fIn\fP +Rotates the stack so that the \fIn\fPth directory +(counting from the right of the list shown by +.BR dirs , +starting with zero) is at the top. +.TP +.I dir +Adds +.I dir +to the directory stack at the top +.PD +.PP +After the stack has been modified, if the \fB\-n\fP option was not +supplied, \fBpushd\fP uses the \fBcd\fP builtin to change to the +directory at the top of the stack. +If the \fBcd\fP fails, \fBpushd\fP returns a non-zero value. +.PP +Otherwise, if no arguments are supplied, +.B pushd +returns 0 unless the directory stack is empty. +When rotating the directory stack, +.B pushd +returns 0 unless the directory stack is empty or +a non-existent directory stack element is specified. +.PP +If the +.B pushd +command is successful, +bash runs +.B dirs +to show the final contents of the directory stack. +.RE +.TP +\fBpwd\fP [\fB\-LP\fP] +Print the absolute pathname of the current working directory. +The pathname printed contains no symbolic links if the +.B \-P +option is supplied or the +.B \-o physical +option to the +.B set +builtin command is enabled. +If the +.B \-L +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. +.TP +\fBread\fP [\fB\-ers\fP] [\fB\-a\fP \fIaname\fP] [\fB\-d\fP \fIdelim\fP] [\fB\-i\fP \fItext\fP] [\fB\-n\fP \fInchars\fP] [\fB\-N\fP \fInchars\fP] [\fB\-p\fP \fIprompt\fP] [\fB\-t\fP \fItimeout\fP] [\fB\-u\fP \fIfd\fP] [\fIname\fP ...] +One line is read from the standard input, or from the file descriptor +\fIfd\fP supplied as an argument to the \fB\-u\fP option, +split into words as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under \fBWord Splitting\fP, +and the first word +is assigned to the first +.IR name , +the second word to the second +.IR name , +and so on. +If there are more words than names, the remaining words and their +intervening delimiters are assigned to the last +.IR name . +If there are fewer words read from the input stream than names, +the remaining names are assigned empty values. +The characters in +.SM +.B IFS +are used to split the line into words using the same rules the shell +uses for expansion (described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under \fBWord Splitting\fP). +The backslash character (\fB\e\fP) may be used to remove any special +meaning for the next character read and for line continuation. +Options, if supplied, have the following meanings: +.RS +.PD 0 +.TP +.B \-a \fIaname\fP +The words are assigned to sequential indices +of the array variable +.IR aname , +starting at 0. +.I aname +is unset before any new values are assigned. +Other \fIname\fP arguments are ignored. +.TP +.B \-d \fIdelim\fP +The first character of \fIdelim\fP is used to terminate the input line, +rather than newline. +If \fIdelim\fP is the empty string, \fBread\fP will terminate a line +when it reads a NUL character. +.TP +.B \-e +If the standard input +is coming from a terminal, +.B readline +(see +.SM +.B READLINE +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +is used to obtain the line. +Readline uses the current (or default, if line editing was not previously +active) editing settings, but uses readline's default filename completion. +.TP +.B \-i \fItext\fP +If +.B readline +is being used to read the line, \fItext\fP is placed into the editing +buffer before editing begins. +.TP +.B \-n \fInchars\fP +\fBread\fP returns after reading \fInchars\fP characters rather than +waiting for a complete line of input, but honors a delimiter if fewer +than \fInchars\fP characters are read before the delimiter. +.TP +.B \-N \fInchars\fP +\fBread\fP returns after reading exactly \fInchars\fP characters rather +than waiting for a complete line of input, unless EOF is encountered or +\fBread\fP times out. +Delimiter characters encountered in the input are +not treated specially and do not cause \fBread\fP to return until +\fInchars\fP characters are read. +The result is not split on the characters in \fBIFS\fP; the intent is +that the variable is assigned exactly the characters read +(with the exception of backslash; see the \fB\-r\fP option below). +.TP +.B \-p \fIprompt\fP +Display \fIprompt\fP on standard error, without a +trailing newline, before attempting to read any input. The prompt +is displayed only if input is coming from a terminal. +.TP +.B \-r +Backslash does not act as an escape character. +The backslash is considered to be part of the line. +In particular, a backslash-newline pair may not then be used as a line +continuation. +.TP +.B \-s +Silent mode. If input is coming from a terminal, characters are +not echoed. +.TP +.B \-t \fItimeout\fP +Cause \fBread\fP to time out and return failure if a complete line of +input (or a specified number of characters) +is not read within \fItimeout\fP seconds. +\fItimeout\fP may be a decimal number with a fractional portion following +the decimal point. +This option is only effective if \fBread\fP is reading input from a +terminal, pipe, or other special file; it has no effect when reading +from regular files. +If \fBread\fP times out, \fBread\fP saves any partial input read into +the specified variable \fIname\fP. +If \fItimeout\fP is 0, \fBread\fP returns immediately, without trying to +read any data. +The exit status is 0 if input is available on the specified file descriptor, +or the read will return EOF, +non-zero otherwise. +The exit status is greater than 128 if the timeout is exceeded. +.TP +.B \-u \fIfd\fP +Read input from file descriptor \fIfd\fP. +.PD +.PP +If no +.I names +are supplied, the line read, +without the ending delimiter but otherwise unmodified, +is assigned to the variable +.SM +.BR REPLY . +The exit status is zero, unless end-of-file is encountered, \fBread\fP +times out (in which case the status is greater than 128), +a variable assignment error (such as assigning to a readonly variable) occurs, +or an invalid file descriptor is supplied as the argument to \fB\-u\fP. +.RE +.TP +\fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...] +.PD +The given +\fInames\fP are marked readonly; the values of these +.I names +may not be changed by subsequent assignment. +If the +.B \-f +option is supplied, the functions corresponding to the +\fInames\fP are so +marked. +The +.B \-a +option restricts the variables to indexed arrays; the +.B \-A +option restricts the variables to associative arrays. +If both options are supplied, +.B \-A +takes precedence. +If no +.I name +arguments are given, or if the +.B \-p +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 +.B \-p +option causes output to be displayed in a format that +may be reused as input. +If a variable name is followed by =\fIword\fP, the value of +the variable is set to \fIword\fP. +The return status is 0 unless an invalid option is encountered, +one of the +.I names +is not a valid shell variable name, or +.B \-f +is supplied with a +.I name +that is not a function. +.TP +\fBreturn\fP [\fIn\fP] +Causes a function to stop executing and return the value specified by +.I n +to its caller. +If +.I n +is omitted, the return status is that of the last command +executed in the function body. +If \fBreturn\fP is executed by a trap handler, the last command used to +determine the status is the last command executed before the trap handler. +If \fBreturn\fP is executed during a \fBDEBUG\fP trap, the last command +used to determine the status is the last command executed by the trap +handler before \fBreturn\fP was invoked. +If +.B return +is used outside a function, +but during execution of a script by the +.B . +(\fBsource\fP) command, it causes the shell to stop executing +that script and return either +.I n +or the exit status of the last command executed within the +script as the exit status of the script. +If \fIn\fP is supplied, the return value is its least significant +8 bits. +The return status is non-zero if +.B return +is supplied a non-numeric argument, or +is used outside a +function and not during execution of a script by \fB.\fP\^ or \fBsource\fP. +Any command associated with the \fBRETURN\fP trap is executed +before execution resumes after the function or script. +.TP +\fBset\fP [\fB\-abefhkmnptuvxBCEHPT\fP] [\fB\-o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...] +.PD 0 +.TP +\fBset\fP [\fB+abefhkmnptuvxBCEHPT\fP] [\fB+o\fP \fIoption\-name\fP] [\fB\-\-\fP] [\fB\-\fP] [\fIarg\fP ...] +.PD +Without options, display the name and value of each shell variable +in a format that can be reused as input +for setting or resetting the currently-set variables. +Read-only variables cannot be reset. +In \fIposix mode\fP, 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 values for the positional parameters and are assigned, in order, to +.BR $1 , +.BR $2 , +.B ... +.BR $\fIn\fP . +Options, if specified, have the following meanings: +.RS +.PD 0 +.TP 8 +.B \-a +Each variable or function that is created or modified is given the +export attribute and marked for export to the environment of +subsequent commands. +.TP 8 +.B \-b +Report the status of terminated background jobs +immediately, rather than before the next primary prompt. This is +effective only when job control is enabled. +.TP 8 +.B \-e +Exit immediately if a +\fIpipeline\fP (which may consist of a single \fIsimple command\fP), +a \fIlist\fP, +or a \fIcompound command\fP +(see +.SM +.B SHELL GRAMMAR +.ie \n(zZ=1 in \fIbash(1)\fP), +.el 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 +.B while +or +.B until +keyword, +part of the test following the +.B if +or +.B elif +reserved words, part of any command executed in a +.B && +or +.B || +list except the command following the final \fB&&\fP or \fB||\fP, +any command in a pipeline but the last, +or if the command's return value is +being inverted with +.BR ! . +If a compound command other than a subshell +returns a non-zero status because a command failed +while \fB\-e\fP was being ignored, the shell does not exit. +A trap on \fBERR\fP, if set, is executed before the shell exits. +This option applies to the shell environment and each subshell environment +separately (see +.SM +.B "COMMAND EXECUTION ENVIRONMENT" +.ie \n(zZ=1 in \fIbash(1)\fP), +.el above), +and may cause +subshells to exit before executing all the commands in the subshell. +.if t .sp 0.5 +.if n .sp 1 +If a compound command or shell function executes in a context +where \fB\-e\fP is being ignored, +none of the commands executed within the compound command or function body +will be affected by the \fB\-e\fP setting, even if \fB\-e\fP is set +and a command returns a failure status. +If a compound command or shell function sets \fB\-e\fP while executing in +a context where \fB\-e\fP is ignored, that setting will not have any +effect until the compound command or the command containing the function +call completes. +.TP 8 +.B \-f +Disable pathname expansion. +.TP 8 +.B \-h +Remember the location of commands as they are looked up for execution. +This is enabled by default. +.TP 8 +.B \-k +All arguments in the form of assignment statements +are placed in the environment for a command, not just +those that precede the command name. +.TP 8 +.B \-m +Monitor mode. Job control is enabled. This option is on +by default for interactive shells on systems that support +it (see +.SM +.B JOB CONTROL +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +All processes run in a separate process group. +When a background job completes, the shell prints a line +containing its exit status. +.TP 8 +.B \-n +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. +.TP 8 +.B \-o \fIoption\-name\fP +The \fIoption\-name\fP can be one of the following: +.RS +.TP 8 +.B allexport +Same as +.BR \-a . +.TP 8 +.B braceexpand +Same as +.BR \-B . +.TP 8 +.B emacs +Use an emacs-style command line editing interface. This is enabled +by default when the shell is interactive, unless the shell is started +with the +.B \-\-noediting +option. +This also affects the editing interface used for \fBread \-e\fP. +.TP 8 +.B errexit +Same as +.BR \-e . +.TP 8 +.B errtrace +Same as +.BR \-E . +.TP 8 +.B functrace +Same as +.BR \-T . +.TP 8 +.B hashall +Same as +.BR \-h . +.TP 8 +.B histexpand +Same as +.BR \-H . +.TP 8 +.B history +Enable command history, as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR HISTORY . +This option is on by default in interactive shells. +.TP 8 +.B ignoreeof +The effect is as if the shell command +.if t \f(CWIGNOREEOF=10\fP +.if n ``IGNOREEOF=10'' +had been executed +(see +.B Shell Variables +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP 8 +.B keyword +Same as +.BR \-k . +.TP 8 +.B monitor +Same as +.BR \-m . +.TP 8 +.B noclobber +Same as +.BR \-C . +.TP 8 +.B noexec +Same as +.BR \-n . +.TP 8 +.B noglob +Same as +.BR \-f . +.TP 8 +.B nolog +Currently ignored. +.TP 8 +.B notify +Same as +.BR \-b . +.TP 8 +.B nounset +Same as +.BR \-u . +.TP 8 +.B onecmd +Same as +.BR \-t . +.TP 8 +.B physical +Same as +.BR \-P . +.TP 8 +.B pipefail +If set, the return value of a pipeline is the value of the last +(rightmost) command to exit with a non-zero status, or zero if all +commands in the pipeline exit successfully. +This option is disabled by default. +.TP 8 +.B posix +Change the behavior of +.B bash +where the default operation differs +from the POSIX standard to match the standard (\fIposix mode\fP). +See +.SM +.B "SEE ALSO" +.ie \n(zZ=1 in \fIbash(1)\fP +.el below +for a reference to a document that details how posix mode affects +bash's behavior. +.TP 8 +.B privileged +Same as +.BR \-p . +.TP 8 +.B verbose +Same as +.BR \-v . +.TP 8 +.B vi +Use a vi-style command line editing interface. +This also affects the editing interface used for \fBread \-e\fP. +.TP 8 +.B xtrace +Same as +.BR \-x . +.sp .5 +.PP +If +.B \-o +is supplied with no \fIoption\-name\fP, the values of the current options are +printed. +If +.B +o +is supplied with no \fIoption\-name\fP, a series of +.B set +commands to recreate the current option settings is displayed on +the standard output. +.RE +.TP 8 +.B \-p +Turn on +.I privileged +mode. In this mode, the +.SM +.B $ENV +and +.SM +.B $BASH_ENV +files are not processed, shell functions are not inherited from the +environment, and the +.SM +.BR SHELLOPTS , +.SM +.BR BASHOPTS , +.SM +.BR CDPATH , +and +.SM +.B GLOBIGNORE +variables, if they appear in the environment, are ignored. +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the \fB\-p\fP option is not supplied, these actions +are taken and the effective user id is set to the real user id. +If the \fB\-p\fP option is supplied at startup, the effective user id is +not reset. +Turning this option off causes the effective user +and group ids to be set to the real user and group ids. +.TP 8 +.B \-r +Enable restricted shell mode. +This option cannot be unset once it has been set. +.TP 8 +.B \-t +Exit after reading and executing one command. +.TP 8 +.B \-u +Treat unset variables and parameters other than the special +parameters "@" and "*", +or array variables subscripted with "@" or "*", +as an error when performing +parameter expansion. If expansion is attempted on an +unset variable or parameter, the shell prints an error message, and, +if not interactive, exits with a non-zero status. +.TP 8 +.B \-v +Print shell input lines as they are read. +.TP 8 +.B \-x +After expanding each \fIsimple command\fP, +\fBfor\fP command, \fBcase\fP command, \fBselect\fP command, or +arithmetic \fBfor\fP command, display the expanded value of +.SM +.BR PS4 , +followed by the command and its expanded arguments +or associated word list. +.TP 8 +.B \-B +The shell performs brace expansion (see +.B Brace Expansion +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This is on by default. +.TP 8 +.B \-C +If set, +.B bash +does not overwrite an existing file with the +.BR > , +.BR >& , +and +.B <> +redirection operators. This may be overridden when +creating output files by using the redirection operator +.B >| +instead of +.BR > . +.TP 8 +.B \-E +If set, any trap on \fBERR\fP is inherited by shell functions, command +substitutions, and commands executed in a subshell environment. +The \fBERR\fP trap is normally not inherited in such cases. +.TP 8 +.B \-H +Enable +.B ! +style history substitution. This option is on by +default when the shell is interactive. +.TP 8 +.B \-P +If set, the shell does not resolve symbolic links when executing +commands such as +.B cd +that change the current working directory. It uses the +physical directory structure instead. By default, +.B bash +follows the logical chain of directories when performing commands +which change the current directory. +.TP 8 +.B \-T +If set, any traps on \fBDEBUG\fP and \fBRETURN\fP are inherited by shell +functions, command substitutions, and commands executed in a +subshell environment. +The \fBDEBUG\fP and \fBRETURN\fP traps are normally not inherited +in such cases. +.TP 8 +.B \-\- +If no arguments follow this option, then the positional parameters are +unset. Otherwise, the positional parameters are set to the +\fIarg\fPs, even if some of them begin with a +.BR \- . +.TP 8 +.B \- +Signal the end of options, cause all remaining \fIarg\fPs to be +assigned to the positional parameters. The +.B \-x +and +.B \-v +options are turned off. +If there are no \fIarg\fPs, +the positional parameters remain unchanged. +.PD +.PP +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 +.BR $\- . +The return status is always true unless an invalid option is encountered. +.RE +.TP +\fBshift\fP [\fIn\fP] +The positional parameters from \fIn\fP+1 ... are renamed to +.B $1 +.B .... +Parameters represented by the numbers \fB$#\fP +down to \fB$#\fP\-\fIn\fP+1 are unset. +.I n +must be a non-negative number less than or equal to \fB$#\fP. +If +.I n +is 0, no parameters are changed. +If +.I n +is not given, it is assumed to be 1. +If +.I n +is greater than \fB$#\fP, the positional parameters are not changed. +The return status is greater than zero if +.I n +is greater than +.B $# +or less than zero; otherwise 0. +.TP +\fBshopt\fP [\fB\-pqsu\fP] [\fB\-o\fP] [\fIoptname\fP ...] +Toggle the values of settings controlling optional shell behavior. +The settings can be either those listed below, or, if the +.B \-o +option is used, those available with the +.B \-o +option to the \fBset\fP builtin command. +With no options, or with the +.B \-p +option, a list of all settable options is displayed, with +an indication of whether or not each is set; +if \fIoptnames\fP are supplied, the output is restricted to those options. +The \fB\-p\fP option causes output to be displayed in a form that +may be reused as input. +Other options have the following meanings: +.RS +.PD 0 +.TP +.B \-s +Enable (set) each \fIoptname\fP. +.TP +.B \-u +Disable (unset) each \fIoptname\fP. +.TP +.B \-q +Suppresses normal output (quiet mode); the return status indicates +whether the \fIoptname\fP is set or unset. +If multiple \fIoptname\fP arguments are given with +.BR \-q , +the return status is zero if all \fIoptnames\fP are enabled; non-zero +otherwise. +.TP +.B \-o +Restricts the values of \fIoptname\fP to be those defined for the +.B \-o +option to the +.B set +builtin. +.PD +.PP +If either +.B \-s +or +.B \-u +is used with no \fIoptname\fP arguments, +.B shopt +shows only those options which are set or unset, respectively. +Unless otherwise noted, the \fBshopt\fP options are disabled (unset) +by default. +.PP +The return status when listing options is zero if all \fIoptnames\fP +are enabled, non-zero otherwise. When setting or unsetting options, +the return status is zero unless an \fIoptname\fP is not a valid shell +option. +.PP +The list of \fBshopt\fP options is: +.if t .sp .5v +.if n .sp 1v +.PD 0 +.TP 8 +.B assoc_expand_once +If set, the shell suppresses multiple evaluation of associative array +subscripts during arithmetic expression evaluation, while executing +builtins that can perform variable assignments, +and while executing builtins that perform array dereferencing. +.TP 8 +.B autocd +If set, a command name that is the name of a directory is executed as if +it were the argument to the \fBcd\fP command. +This option is only used by interactive shells. +.TP 8 +.B cdable_vars +If set, an argument to the +.B cd +builtin command that +is not a directory is assumed to be the name of a variable whose +value is the directory to change to. +.TP 8 +.B cdspell +If set, minor errors in the spelling of a directory component in a +.B cd +command will be corrected. +The errors checked for are transposed characters, +a missing character, and one character too many. +If a correction is found, the corrected filename is printed, +and the command proceeds. +This option is only used by interactive shells. +.TP 8 +.B checkhash +If set, \fBbash\fP checks that a command found in the hash +table exists before trying to execute it. If a hashed command no +longer exists, a normal path search is performed. +.TP 8 +.B checkjobs +If set, \fBbash\fP 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 +.SM +.B "JOB CONTROL" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +The shell always postpones exiting if any jobs are stopped. +.TP 8 +.B checkwinsize +If set, \fBbash\fP checks the window size after each external (non-builtin) +command and, if necessary, updates the values of +.SM +.B LINES +and +.SM +.BR COLUMNS . +This option is enabled by default. +.TP 8 +.B cmdhist +If set, +.B bash +attempts to save all lines of a multiple-line +command in the same history entry. This allows +easy re-editing of multi-line commands. +This option is enabled by default, but only has an effect if command +history is enabled, as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR HISTORY . +.PD 0 +.TP 8 +.B compat31 +.TP 8 +.B compat32 +.TP 8 +.B compat40 +.TP 8 +.B compat41 +.TP 8 +.B compat42 +.TP 8 +.B compat43 +.TP 8 +.B compat44 +.TP 8 +.B compat50 +.PD +These control aspects of the shell's compatibility mode +(see +.SM +.B "SHELL COMPATIBILITY MODE" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el below). +.TP 8 +.B complete_fullquote +If set, +.B bash +quotes all shell metacharacters in filenames and directory names when +performing completion. +If not set, +.B bash +removes metacharacters such as the dollar sign from the set of +characters that will be quoted in completed filenames +when these metacharacters appear in shell variable references in words to be +completed. +This means that dollar signs in variable names that expand to directories +will not be quoted; +however, any dollar signs appearing in filenames will not be quoted, either. +This is active only when bash is using backslashes to quote completed +filenames. +This variable is set by default, which is the default bash behavior in +versions through 4.2. +.TP 8 +.B direxpand +If set, +.B bash +replaces directory names with the results of word expansion when performing +filename completion. This changes the contents of the readline editing +buffer. +If not set, +.B bash +attempts to preserve what the user typed. +.TP 8 +.B dirspell +If set, +.B bash +attempts spelling correction on directory names during word completion +if the directory name initially supplied does not exist. +.TP 8 +.B dotglob +If set, +.B bash +includes filenames beginning with a `.' in the results of pathname +expansion. +The filenames +.B ``.'' +and +.B ``..'' +must always be matched explicitly, even if +.B dotglob +is set. +.TP 8 +.B execfail +If set, a non-interactive shell will not exit if +it cannot execute the file specified as an argument to the +.B exec +builtin command. An interactive shell does not exit if +.B exec +fails. +.TP 8 +.B expand_aliases +If set, aliases are expanded as described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR ALIASES . +This option is enabled by default for interactive shells. +.TP 8 +.B extdebug +If set at shell invocation, +or in a shell startup file, +arrange to execute the debugger profile +before the shell starts, identical to the \fB\-\-debugger\fP option. +If set after invocation, behavior intended for use by debuggers is enabled: +.RS +.TP +.B 1. +The \fB\-F\fP option to the \fBdeclare\fP builtin displays the source +file name and line number corresponding to each function name supplied +as an argument. +.TP +.B 2. +If the command run by the \fBDEBUG\fP trap returns a non-zero value, the +next command is skipped and not executed. +.TP +.B 3. +If the command run by the \fBDEBUG\fP trap returns a value of 2, and the +shell is executing in a subroutine (a shell function or a shell script +executed by the \fB.\fP or \fBsource\fP builtins), the shell simulates +a call to \fBreturn\fP. +.TP +.B 4. +.SM +.B BASH_ARGC +and +.SM +.B BASH_ARGV +are updated as described in their descriptions +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP +.B 5. +Function tracing is enabled: command substitution, shell functions, and +subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the +\fBDEBUG\fP and \fBRETURN\fP traps. +.TP +.B 6. +Error tracing is enabled: command substitution, shell functions, and +subshells invoked with \fB(\fP \fIcommand\fP \fB)\fP inherit the +\fBERR\fP trap. +.RE +.TP 8 +.B extglob +If set, the extended pattern matching features described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +\fBPathname Expansion\fP are enabled. +.TP 8 +.B extquote +If set, \fB$\fP\(aq\fIstring\fP\(aq and \fB$\fP"\fIstring\fP" quoting is +performed within \fB${\fP\fIparameter\fP\fB}\fP expansions +enclosed in double quotes. This option is enabled by default. +.TP 8 +.B failglob +If set, patterns which fail to match filenames during pathname expansion +result in an expansion error. +.TP 8 +.B force_fignore +If set, the suffixes specified by the +.SM +.B FIGNORE +shell variable +cause words to be ignored when performing word completion even if +the ignored words are the only possible completions. +See +.SM +\fBSHELL VARIABLES\fP +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +for a description of +.SM +.BR FIGNORE . +This option is enabled by default. +.TP 8 +.B globasciiranges +If set, range expressions used in pattern matching bracket expressions (see +.SM +.B Pattern Matching +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +behave as if in the traditional C locale when performing +comparisons. That is, the current locale's collating sequence +is not taken into account, so +.B b +will not collate between +.B A +and +.BR B , +and upper-case and lower-case ASCII characters will collate together. +.TP 8 +.B globskipdots +If set, pathname expansion will never match the filenames +.B ``.'' +and +.BR ``..'' , +even if the pattern begins with a +.BR ``.'' . +This option is enabled by default. +.TP 8 +.B globstar +If set, the pattern \fB**\fP used in a pathname expansion context will +match all files and zero or more directories and subdirectories. +If the pattern is followed by a \fB/\fP, only directories and +subdirectories match. +.TP 8 +.B gnu_errfmt +If set, shell error messages are written in the standard GNU error +message format. +.TP 8 +.B histappend +If set, the history list is appended to the file named by the value +of the +.SM +.B HISTFILE +variable when the shell exits, rather than overwriting the file. +.TP 8 +.B histreedit +If set, and +.B readline +is being used, a user is given the opportunity to re-edit a +failed history substitution. +.TP 8 +.B histverify +If set, and +.B readline +is being used, the results of history substitution are not immediately +passed to the shell parser. Instead, the resulting line is loaded into +the \fBreadline\fP editing buffer, allowing further modification. +.TP 8 +.B hostcomplete +If set, and +.B readline +is being used, \fBbash\fP will attempt to perform hostname completion when a +word containing a \fB@\fP is being completed (see +.B Completing +under +.SM +.B READLINE +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This is enabled by default. +.TP 8 +.B huponexit +If set, \fBbash\fP will send +.SM +.B SIGHUP +to all jobs when an interactive login shell exits. +.TP 8 +.B inherit_errexit +If set, command substitution inherits the value of the \fBerrexit\fP option, +instead of unsetting it in the subshell environment. +This option is enabled when \fIposix mode\fP is enabled. +.TP 8 +.B interactive_comments +If set, allow a word beginning with +.B # +to cause that word and all remaining characters on that +line to be ignored in an interactive shell (see +.SM +.B COMMENTS +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +This option is enabled by default. +.TP 8 +.B lastpipe +If set, and job control is not active, the shell runs the last command of +a pipeline not executed in the background in the current shell environment. +.TP 8 +.B lithist +If set, and the +.B cmdhist +option is enabled, multi-line commands are saved to the history with +embedded newlines rather than using semicolon separators where possible. +.TP 8 +.B localvar_inherit +If set, local variables inherit the value and attributes of a variable of +the same name that exists at a previous scope before any new value is +assigned. The nameref attribute is not inherited. +.TP 8 +.B localvar_unset +If set, calling \fBunset\fP on local variables in previous function scopes +marks them so subsequent lookups find them unset until that function +returns. This is identical to the behavior of unsetting local variables +at the current function scope. +.TP 8 +.B login_shell +The shell sets this option if it is started as a login shell (see +.SM +.B "INVOCATION" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +The value may not be changed. +.TP 8 +.B mailwarn +If set, and a file that \fBbash\fP is checking for mail has been +accessed since the last time it was checked, the message ``The mail in +\fImailfile\fP has been read'' is displayed. +.TP 8 +.B no_empty_cmd_completion +If set, and +.B readline +is being used, +.B bash +will not attempt to search the +.SM +.B PATH +for possible completions when +completion is attempted on an empty line. +.TP 8 +.B nocaseglob +If set, +.B bash +matches filenames in a case\-insensitive fashion when performing pathname +expansion (see +.B Pathname Expansion +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +.TP 8 +.B nocasematch +If set, +.B bash +matches patterns in a case\-insensitive fashion when performing matching +while executing \fBcase\fP or \fB[[\fP conditional commands, +when performing pattern substitution word expansions, +or when filtering possible completions as part of programmable completion. +.TP 8 +.B noexpand_translation +If set, +.B bash +encloses the translated results of $"..." quoting in single quotes +instead of double quotes. +If the string is not translated, this has no effect. +.TP 8 +.B nullglob +If set, +.B bash +allows patterns which match no +files (see +.B Pathname Expansion +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +to expand to a null string, rather than themselves. +.TP 8 +.B patsub_replacement +If set, \fBbash\fP +expands occurrences of \fB&\fP in the replacement string of pattern +substitution to the text matched by the pattern, as described +under \fBParameter Expansion\fP +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +This option is enabled by default. +.TP 8 +.B progcomp +If set, the programmable completion facilities (see +\fBProgrammable Completion\fP +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +are enabled. +This option is enabled by default. +.TP 8 +.B progcomp_alias +If set, and programmable completion is enabled, \fBbash\fP treats a command +name that doesn't have any completions as a possible alias and attempts +alias expansion. If it has an alias, \fBbash\fP attempts programmable +completion using the command word resulting from the expanded alias. +.TP 8 +.B promptvars +If set, prompt strings undergo +parameter expansion, command substitution, arithmetic +expansion, and quote removal after being expanded as described in +.SM +.B PROMPTING +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +This option is enabled by default. +.TP 8 +.B restricted_shell +The shell sets this option if it is started in restricted mode +(see +.SM +.B "RESTRICTED SHELL" +.ie \n(zZ=1 in \fIbash(1)\fP). +.el below). +The value may not be changed. +This is not reset when the startup files are executed, allowing +the startup files to discover whether or not a shell is restricted. +.TP 8 +.B shift_verbose +If set, the +.B shift +builtin prints an error message when the shift count exceeds the +number of positional parameters. +.TP 8 +.B sourcepath +If set, the +\fB.\fP (\fBsource\fP) builtin uses the value of +.SM +.B PATH +to find the directory containing the file supplied as an argument. +This option is enabled by default. +.TP 8 +.B varredir_close +If set, the shell automatically closes file descriptors assigned using the +\fI{varname}\fP redirection syntax (see +.SM +.B REDIRECTION +.ie \n(zZ=1 in \fIbash(1)\fP) +.el above) +instead of leaving them open when the command completes. +.TP 8 +.B xpg_echo +If set, the \fBecho\fP builtin expands backslash-escape sequences +by default. +.RE +.PD +.TP +\fBsuspend\fP [\fB\-f\fP] +Suspend the execution of this shell until it receives a +.SM +.B SIGCONT +signal. A login shell, +or a shell without job control enabled, +cannot be suspended; the +.B \-f +option can be used to override this and force the suspension. +The return status is 0 unless the shell is a login shell +or job control is not enabled +and +.B \-f +is not supplied. +.TP +\fBtest\fP \fIexpr\fP +.PD 0 +.TP +\fB[\fP \fIexpr\fP \fB]\fP +Return a status of 0 (true) or 1 (false) depending on +the evaluation of the conditional expression +.IR expr . +Each operator and operand must be a separate argument. +Expressions are composed of the primaries described +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" . +\fBtest\fP does not accept any options, nor does it accept and ignore +an argument of \fB\-\-\fP as signifying the end of options. +.if t .sp 0.5 +.if n .sp 1 +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 precedence is used when there are five or more arguments. +.RS +.PD 0 +.TP +.B ! \fIexpr\fP +True if +.I expr +is false. +.TP +.B ( \fIexpr\fP ) +Returns the value of \fIexpr\fP. +This may be used to override the normal precedence of operators. +.TP +\fIexpr1\fP \-\fBa\fP \fIexpr2\fP +True if both +.I expr1 +and +.I expr2 +are true. +.TP +\fIexpr1\fP \-\fBo\fP \fIexpr2\fP +True if either +.I expr1 +or +.I expr2 +is true. +.PD +.PP +\fBtest\fP and \fB[\fP evaluate conditional +expressions using a set of rules based on the number of arguments. +.if t .sp 0.5 +.if n .sp 1 +.PD 0 +.TP +0 arguments +The expression is false. +.TP +1 argument +The expression is true if and only if the argument is not null. +.TP +2 arguments +If the first argument is \fB!\fP, the expression is true if and +only if the second argument is null. +If the first argument is one of the unary conditional operators listed +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" , +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. +.TP +3 arguments +The following conditions are applied in the order listed. +If the second argument is one of the binary conditional operators listed +.ie \n(zZ=1 in \fIbash(1)\fP +.el above +under +.SM +.BR "CONDITIONAL EXPRESSIONS" , +the result of the expression is the result of the binary test using +the first and third arguments as operands. +The \fB\-a\fP and \fB\-o\fP operators are considered binary operators +when there are three arguments. +If the first argument is \fB!\fP, the value is the negation of +the two-argument test using the second and third arguments. +If the first argument is exactly \fB(\fP and the third argument is +exactly \fB)\fP, the result is the one-argument test of the second +argument. +Otherwise, the expression is false. +.TP +4 arguments +The following conditions are applied in the order listed. +If the first argument is \fB!\fP, the result is the negation of +the three-argument expression composed of the remaining arguments. +the two-argument test using the second and third arguments. +If the first argument is exactly \fB(\fP and the fourth argument is +exactly \fB)\fP, the result is the two-argument test of the second +and third arguments. +Otherwise, the expression is parsed and evaluated according to +precedence using the rules listed above. +.TP +5 or more arguments +The expression is parsed and evaluated according to precedence +using the rules listed above. +.if t .sp 0.5 +.if n .sp 1 +.LP +When used with \fBtest\fP or \fB[\fP, the \fB<\fP and \fB>\fP operators +sort lexicographically using ASCII ordering. +.RE +.PD +.TP +.B times +Print the accumulated user and system times for the shell and +for processes run from the shell. The return status is 0. +.TP +\fBtrap\fP [\fB\-lp\fP] [[\fIarg\fP] \fIsigspec\fP ...] +The command +.I arg +is to be read and executed when the shell receives +signal(s) +.IR sigspec . +If +.I arg +is absent (and there is a single \fIsigspec\fP) or +.BR \- , +each specified signal is +reset to its original disposition (the value it had +upon entrance to the shell). +If +.I arg +is the null string the signal specified by each +.I sigspec +is ignored by the shell and by the commands it invokes. +If +.I arg +is not present and +.B \-p +has been supplied, then the trap commands associated with each +.I sigspec +are displayed. +If no arguments are supplied or if only +.B \-p +is given, +.B trap +prints the list of commands associated with each signal. +The +.B \-l +option causes the shell to print a list of signal names and +their corresponding numbers. +Each +.I sigspec +is either +a signal name defined in <\fIsignal.h\fP>, or a signal number. +Signal names are case insensitive and the +.SM +.B SIG +prefix is optional. +.if t .sp 0.5 +.if n .sp 1 +If a +.I sigspec +is +.SM +.B EXIT +(0) the command +.I arg +is executed on exit from the shell. +If a +.I sigspec +is +.SM +.BR DEBUG , +the command +.I arg +is executed before every \fIsimple command\fP, \fIfor\fP command, +\fIcase\fP command, \fIselect\fP command, every arithmetic \fIfor\fP +command, and before the first command executes in a shell function (see +.SM +.B SHELL GRAMMAR +.ie \n(zZ=1 in \fIbash(1)\fP). +.el above). +Refer to the description of the \fBextdebug\fP option to the +\fBshopt\fP builtin for details of its effect on the \fBDEBUG\fP trap. +If a +.I sigspec +is +.SM +.BR RETURN , +the command +.I arg +is executed each time a shell function or a script executed with +the \fB.\fP or \fBsource\fP builtins finishes executing. +.if t .sp 0.5 +.if n .sp 1 +If a +.I sigspec +is +.SM +.BR ERR , +the command +.I arg +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 +.SM +.B ERR +trap is not executed if the failed +command is part of the command list immediately following a +.B while +or +.B until +keyword, +part of the test in an +.I if +statement, part of a command executed in a +.B && +or +.B || +list except the command following the final \fB&&\fP or \fB||\fP, +any command in a pipeline but the last, +or if the command's return value is +being inverted using +.BR ! . +These are the same conditions obeyed by the \fBerrexit\fP (\fB\-e\fP) option. +.if t .sp 0.5 +.if n .sp 1 +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 +.I sigspec +is invalid; otherwise +.B trap +returns true. +.TP +\fBtype\fP [\fB\-aftpP\fP] \fIname\fP [\fIname\fP ...] +With no options, +indicate how each +.I name +would be interpreted if used as a command name. +If the +.B \-t +option is used, +.B type +prints a string which is one of +.IR alias , +.IR keyword , +.IR function , +.IR builtin , +or +.I file +if +.I name +is an alias, shell reserved word, function, builtin, or disk file, +respectively. +If the +.I name +is not found, then nothing is printed, and an exit status of false +is returned. +If the +.B \-p +option is used, +.B type +either returns the name of the disk file +that would be executed if +.I name +were specified as a command name, +or nothing if +.if t \f(CWtype -t name\fP +.if n ``type -t name'' +would not return +.IR file . +The +.B \-P +option forces a +.SM +.B PATH +search for each \fIname\fP, even if +.if t \f(CWtype -t name\fP +.if n ``type -t name'' +would not return +.IR file . +If a command is hashed, +.B \-p +and +.B \-P +print the hashed value, which is not necessarily the file that appears +first in +.SM +.BR PATH . +If the +.B \-a +option is used, +.B type +prints all of the places that contain +an executable named +.IR name . +This includes aliases and functions, +if and only if the +.B \-p +option is not also used. +The table of hashed commands is not consulted +when using +.BR \-a . +The +.B \-f +option suppresses shell function lookup, as with the \fBcommand\fP builtin. +.B type +returns true if all of the arguments are found, false if +any are not found. +.TP +\fBulimit\fP [\fB\-HS\fP] \fB\-a\fP +.PD 0 +.TP +\fBulimit\fP [\fB\-HS\fP] [\fB\-bcdefiklmnpqrstuvxPRT\fP [\fIlimit\fP]] +.PD +Provides control over the resources available to the shell and to +processes started by it, on systems that allow such control. +The \fB\-H\fP and \fB\-S\fP 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 \fB\-H\fP nor \fB\-S\fP is specified, both the soft and hard +limits are set. +The value of +.I limit +can be a number in the unit specified for the resource +or one of the special values +.BR hard , +.BR soft , +or +.BR unlimited , +which stand for the current hard limit, the current soft limit, and +no limit, respectively. +If +.I limit +is omitted, the current value of the soft limit of the resource is +printed, unless the \fB\-H\fP option is given. When more than one +resource is specified, the limit name and unit, if appropriate, +are printed before the value. +Other options are interpreted as follows: +.RS +.PD 0 +.TP +.B \-a +All current limits are reported; no limits are set +.TP +.B \-b +The maximum socket buffer size +.TP +.B \-c +The maximum size of core files created +.TP +.B \-d +The maximum size of a process's data segment +.TP +.B \-e +The maximum scheduling priority ("nice") +.TP +.B \-f +The maximum size of files written by the shell and its children +.TP +.B \-i +The maximum number of pending signals +.TP +.B \-k +The maximum number of kqueues that may be allocated +.TP +.B \-l +The maximum size that may be locked into memory +.TP +.B \-m +The maximum resident set size (many systems do not honor this limit) +.TP +.B \-n +The maximum number of open file descriptors (most systems do not +allow this value to be set) +.TP +.B \-p +The pipe size in 512-byte blocks (this may not be set) +.TP +.B \-q +The maximum number of bytes in POSIX message queues +.TP +.B \-r +The maximum real-time scheduling priority +.TP +.B \-s +The maximum stack size +.TP +.B \-t +The maximum amount of cpu time in seconds +.TP +.B \-u +The maximum number of processes available to a single user +.TP +.B \-v +The maximum amount of virtual memory available to the shell and, on +some systems, to its children +.TP +.B \-x +The maximum number of file locks +.TP +.B \-P +The maximum number of pseudoterminals +.TP +.B \-R +The maximum time a real-time process can run before blocking, in microseconds +.TP +.B \-T +The maximum number of threads +.PD +.PP +If +.I limit +is given, and the +.B \-a +option is not used, +\fIlimit\fP is the new value of the specified resource. +If no option is given, then +.B \-f +is assumed. Values are in 1024-byte increments, except for +.BR \-t , +which is in seconds; +.BR \-R , +which is in microseconds; +.BR \-p , +which is in units of 512-byte blocks; +.BR \-P , +.BR \-T , +.BR \-b , +.BR \-k , +.BR \-n , +and +.BR \-u , +which are unscaled values; +and, when in posix mode, +.B \-c +and +.BR \-f , +which are in 512-byte increments. +The return status is 0 unless an invalid option or argument is supplied, +or an error occurs while setting a new limit. +.RE +.TP +\fBumask\fP [\fB\-p\fP] [\fB\-S\fP] [\fImode\fP] +The user file-creation mask is set to +.IR mode . +If +.I mode +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 +.IR chmod (1). +If +.I mode +is omitted, the current value of the mask is printed. +The +.B \-S +option causes the mask to be printed in symbolic form; the +default output is an octal number. +If the +.B \-p +option is supplied, and +.I mode +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 \fImode\fP argument was supplied, and false otherwise. +.TP +\fBunalias\fP [\-\fBa\fP] [\fIname\fP ...] +Remove each \fIname\fP from the list of defined aliases. If +.B \-a +is supplied, all alias definitions are removed. The return +value is true unless a supplied +.I name +is not a defined alias. +.TP +\fBunset\fP [\-\fBfv\fP] [\-\fBn\fP] [\fIname\fP ...] +For each +.IR name , +remove the corresponding variable or function. +If the +.B \-v +option is given, each +.I name +refers to a shell variable, and that variable is removed. +Read-only variables may not be unset. +If +.B \-f +is specified, each +.I name +refers to a shell function, and the function definition +is removed. +If the +.B \-n +option is supplied, and \fIname\fP is a variable with the \fInameref\fP +attribute, \fIname\fP will be unset rather than the variable it +references. +\fB\-n\fP has no effect if the \fB\-f\fP option is supplied. +If no options are supplied, each \fIname\fP refers to a variable; if +there is no variable by that name, a function with that name, if any, is +unset. +Each unset variable or function is removed from the environment +passed to subsequent commands. +If any of +.SM +.BR BASH_ALIASES , +.SM +.BR BASH_ARGV0 , +.SM +.BR BASH_CMDS , +.SM +.BR BASH_COMMAND , +.SM +.BR BASH_SUBSHELL , +.SM +.BR BASHPID , +.SM +.BR COMP_WORDBREAKS , +.SM +.BR DIRSTACK , +.SM +.BR EPOCHREALTIME , +.SM +.BR EPOCHSECONDS , +.SM +.BR FUNCNAME , +.SM +.BR GROUPS , +.SM +.BR HISTCMD , +.SM +.BR LINENO , +.SM +.BR RANDOM , +.SM +.BR SECONDS , +or +.SM +.B SRANDOM +are unset, they lose their special properties, even if they are +subsequently reset. The exit status is true unless a +.I name +is readonly or may not be unset. +.TP +\fBwait\fP [\fB\-fn\fP] [\fP\-p\fP \fIvarname\fP] [\fIid ...\fP] +Wait for each specified child process and return its termination status. +Each +.I id +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 id +is not given, +\fBwait\fP waits for all running background jobs and +the last-executed process substitution, if its process id is the same as +\fB$!\fP, +and the return status is zero. +If the \fB\-n\fP option is supplied, +\fBwait\fP waits for a single job +from the list of \fIid\fPs or, if no \fIid\fPs are supplied, any job, +to complete and returns its exit status. +If none of the supplied arguments is a child of the shell, or if no arguments +are supplied and the shell has no unwaited-for children, the exit status +is 127. +If the \fB\-p\fP option is supplied, the process or job identifier of the job +for which the exit status is returned is assigned to the variable +\fIvarname\fP named by the option argument. +The variable will be unset initially, before any assignment. +This is useful only when the \fB\-n\fP option is supplied. +Supplying the \fB\-f\fP option, when job control is enabled, +forces \fBwait\fP to wait for \fIid\fP to terminate before returning +its status, instead of returning when it changes status. +If +.I id +specifies a non-existent process or job, the return status is 127. +If \fBwait\fP is interrupted by a signal, the return status will be greater +than 128, as described under +.B SIGNALS +.ie \n(zZ=1 in \fIbash(1)\fP. +.el above. +Otherwise, the return status is the exit status of the last +process or job waited for. +.SH "SHELL COMPATIBILITY MODE" +Bash-4.0 introduced the concept of a \fIshell compatibility level\fP, +specified as a set of options to the shopt builtin ( +.BR compat31 , +.BR compat32 , +.BR compat40 , +.BR compat41 , +and so on). +There is only one current +compatibility level -- each option is mutually exclusive. +The compatibility level is intended to allow users to select behavior +from previous versions that is incompatible with newer versions +while they migrate scripts to use current features and +behavior. It's intended to be a temporary solution. +.PP +This section does not mention behavior that is standard for a particular +version (e.g., setting \fBcompat32\fP means that quoting the rhs of the regexp +matching operator quotes special regexp characters in the word, which is +default behavior in bash-3.2 and subsequent versions). +.PP +If a user enables, say, \fBcompat32\fP, it may affect the behavior of other +compatibility levels up to and including the current compatibility level. +The idea is that each compatibility level controls behavior that changed +in that version of \fBbash\fP, +but that behavior may have been present in earlier versions. +For instance, the change to use locale-based comparisons with the \fB[[\fP +command came in bash-4.1, and earlier versions used ASCII-based comparisons, +so enabling \fBcompat32\fP will enable ASCII-based comparisons as well. +That granularity may not be sufficient for +all uses, and as a result users should employ compatibility levels carefully. +Read the documentation for a particular feature to find out the +current behavior. +.PP +Bash-4.3 introduced a new shell variable: +.SM +.BR BASH_COMPAT . +The value assigned +to this variable (a decimal version number like 4.2, or an integer +corresponding to the \fBcompat\fP\fINN\fP option, like 42) determines the +compatibility level. +.PP +Starting with bash-4.4, Bash has begun deprecating older compatibility +levels. +Eventually, the options will be removed in favor of +.SM +.BR BASH_COMPAT . +.PP +Bash-5.0 is the final version for which there will be an individual shopt +option for the previous version. Users should use +.SM +.B BASH_COMPAT +on bash-5.0 and later versions. +.PP +The following table describes the behavior changes controlled by each +compatibility level setting. +The \fBcompat\fP\fINN\fP tag is used as shorthand for setting the +compatibility level +to \fINN\fP using one of the following mechanisms. +For versions prior to bash-5.0, the compatibility level may be set using +the corresponding \fBcompat\fP\fINN\fP shopt option. +For bash-4.3 and later versions, the +.SM +.B BASH_COMPAT +variable is preferred, +and it is required for bash-5.1 and later versions. +.TP +\fBcompat31\fP +.PD 0 +.RS +.IP \(bu +quoting the rhs of the \fB[[\fP command's regexp matching operator (=~) +has no special effect +.RE +.PD +.TP +\fBcompat32\fP +.PD 0 +.RS +.IP \(bu +interrupting a command list such as "a ; b ; c" causes the execution +of the next command in the list (in bash-4.0 and later versions, +the shell acts as if it received the interrupt, so +interrupting one command in a list aborts the execution of the +entire list) +.RE +.PD +.TP +\fBcompat40\fP +.PD 0 +.RS +.IP \(bu +the \fB<\fP and \fB>\fP operators to the \fB[[\fP command do not +consider the current locale when comparing strings; they use ASCII +ordering. +Bash versions prior to bash-4.1 use ASCII collation and +.IR strcmp (3); +bash-4.1 and later use the current locale's collation sequence and +.IR strcoll (3). +.RE +.PD +.TP +\fBcompat41\fP +.PD 0 +.RS +.IP \(bu +in \fIposix\fP mode, \fBtime\fP may be followed by options and still be +recognized as a reserved word (this is POSIX interpretation 267) +.IP \(bu +in \fIposix\fP mode, the parser requires that an even number of single +quotes occur in the \fIword\fP portion of a double-quoted +parameter expansion and treats them specially, so that characters within +the single quotes are considered quoted +(this is POSIX interpretation 221) +.RE +.PD +.TP +\fBcompat42\fP +.PD 0 +.RS +.IP \(bu +the replacement string in double-quoted pattern substitution does not +undergo quote removal, as it does in versions after bash-4.2 +.IP \(bu +in posix mode, single quotes are considered special when expanding +the \fIword\fP portion of a double-quoted parameter expansion +and can be used to quote a closing brace or other special character +(this is part of POSIX interpretation 221); +in later versions, single quotes +are not special within double-quoted word expansions +.RE +.PD +.TP +\fBcompat43\fP +.PD 0 +.RS +.IP \(bu +the shell does not print a warning message if an attempt is made to +use a quoted compound assignment as an argument to declare +(e.g., declare -a foo=\(aq(1 2)\(aq). Later versions warn that this usage is +deprecated +.IP \(bu +word expansion errors are considered non-fatal errors that cause the +current command to fail, even in posix mode +(the default behavior is to make them fatal errors that cause the shell +to exit) +.IP \(bu +when executing a shell function, the loop state (while/until/etc.) +is not reset, so \fBbreak\fP or \fBcontinue\fP in that function will break +or continue loops in the calling context. Bash-4.4 and later reset +the loop state to prevent this +.RE +.PD +.TP +\fBcompat44\fP +.PD 0 +.RS +.IP \(bu +the shell sets up the values used by +.SM +.B BASH_ARGV +and +.SM +.B BASH_ARGC +so they can expand to the shell's positional parameters even if extended +debugging mode is not enabled +.IP \(bu +a subshell inherits loops from its parent context, so \fBbreak\fP +or \fBcontinue\fP will cause the subshell to exit. +Bash-5.0 and later reset the loop state to prevent the exit +.IP \(bu +variable assignments preceding builtins like \fBexport\fP and \fBreadonly\fP +that set attributes continue to affect variables with the same +name in the calling environment even if the shell is not in posix +mode +.RE +.PD +.TP +\fBcompat50\fP +.PD 0 +.RS +.IP \(bu +Bash-5.1 changed the way +.SM +.B $RANDOM +is generated to introduce slightly +more randomness. If the shell compatibility level is set to 50 or +lower, it reverts to the method from bash-5.0 and previous versions, +so seeding the random number generator by assigning a value to +.SM +.B RANDOM +will produce the same sequence as in bash-5.0 +.IP \(bu +If the command hash table is empty, bash versions prior to bash-5.1 +printed an informational message to that effect, even when producing +output that can be reused as input. Bash-5.1 suppresses that message +when the \fB\-l\fP option is supplied. +.RE +.PD +.TP +\fBcompat51\fP +.PD 0 +.RS +.IP \(bu +The \fBunset\fP builtin treats attempts to unset array subscripts \fB@\fP +and \fB*\fP differently depending on whether the array is indexed or +associative, and differently than in previous versions. +.RE +.PD +.\" bash_builtins +.zY +.lf 23 ./builtins.1 +.SH SEE ALSO +bash(1), sh(1) |