diff options
Diffstat (limited to 'devdocs/bash/bash-builtins.html')
| -rw-r--r-- | devdocs/bash/bash-builtins.html | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/devdocs/bash/bash-builtins.html b/devdocs/bash/bash-builtins.html new file mode 100644 index 00000000..caa33521 --- /dev/null +++ b/devdocs/bash/bash-builtins.html @@ -0,0 +1,136 @@ +<h1 class="section">Bash Builtin Commands</h1> <p>This section describes builtin commands which are unique to or have been extended in Bash. Some of these commands are specified in the <small>POSIX</small> standard. </p> <dl compact> <dt id="index-alias"><span><code>alias</code></span></dt> <dd> +<div class="example"> <pre class="example">alias [-p] [name[=value] …] +</pre> +</div> <p>Without arguments or with the <samp>-p</samp> option, <code>alias</code> prints the list of aliases on the standard output in a form that allows them to be reused as input. If arguments are supplied, an alias is defined for each <var>name</var> whose <var>value</var> is given. If no <var>value</var> is given, the name and value of the alias is printed. Aliases are described in <a href="aliases">Aliases</a>. </p> </dd> <dt id="index-bind"><span><code>bind</code></span></dt> <dd> +<div class="example"> <pre class="example">bind [-m keymap] [-lpsvPSVX] +bind [-m keymap] [-q function] [-u function] [-r keyseq] +bind [-m keymap] -f filename +bind [-m keymap] -x keyseq:shell-command +bind [-m keymap] keyseq:function-name +bind [-m keymap] keyseq:readline-command +bind readline-command-line +</pre> +</div> <p>Display current Readline (see <a href="command-line-editing">Command Line Editing</a>) key and function bindings, bind a key sequence to a Readline function or macro, or set a Readline variable. Each non-option argument is a command as it would appear in a Readline initialization file (see <a href="readline-init-file">Readline Init File</a>), but each binding or command must be passed as a separate argument; e.g., ‘<samp>"\C-x\C-r":re-read-init-file</samp>’. </p> <p>Options, if supplied, have the following meanings: </p> <dl compact> <dt><span><code>-m <var>keymap</var></code></span></dt> <dd> +<p>Use <var>keymap</var> as the keymap to be affected by the subsequent bindings. Acceptable <var>keymap</var> names are <code>emacs</code>, <code>emacs-standard</code>, <code>emacs-meta</code>, <code>emacs-ctlx</code>, <code>vi</code>, <code>vi-move</code>, <code>vi-command</code>, and <code>vi-insert</code>. <code>vi</code> is equivalent to <code>vi-command</code> (<code>vi-move</code> is also a synonym); <code>emacs</code> is equivalent to <code>emacs-standard</code>. </p> </dd> <dt><span><code>-l</code></span></dt> <dd> +<p>List the names of all Readline functions. </p> </dd> <dt><span><code>-p</code></span></dt> <dd> +<p>Display Readline function names and bindings in such a way that they can be used as input or in a Readline initialization file. </p> </dd> <dt><span><code>-P</code></span></dt> <dd> +<p>List current Readline function names and bindings. </p> </dd> <dt><span><code>-v</code></span></dt> <dd> +<p>Display Readline variable names and values in such a way that they can be used as input or in a Readline initialization file. </p> </dd> <dt><span><code>-V</code></span></dt> <dd> +<p>List current Readline variable names and values. </p> </dd> <dt><span><code>-s</code></span></dt> <dd> +<p>Display Readline key sequences bound to macros and the strings they output in such a way that they can be used as input or in a Readline initialization file. </p> </dd> <dt><span><code>-S</code></span></dt> <dd> +<p>Display Readline key sequences bound to macros and the strings they output. </p> </dd> <dt><span><code>-f <var>filename</var></code></span></dt> <dd> +<p>Read key bindings from <var>filename</var>. </p> </dd> <dt><span><code>-q <var>function</var></code></span></dt> <dd> +<p>Query about which keys invoke the named <var>function</var>. </p> </dd> <dt><span><code>-u <var>function</var></code></span></dt> <dd> +<p>Unbind all keys bound to the named <var>function</var>. </p> </dd> <dt><span><code>-r <var>keyseq</var></code></span></dt> <dd> +<p>Remove any current binding for <var>keyseq</var>. </p> </dd> <dt><span><code>-x <var>keyseq:shell-command</var></code></span></dt> <dd> +<p>Cause <var>shell-command</var> to be executed whenever <var>keyseq</var> is entered. When <var>shell-command</var> is executed, the shell sets the <code>READLINE_LINE</code> variable to the contents of the Readline line buffer and the <code>READLINE_POINT</code> and <code>READLINE_MARK</code> variables to the current location of the insertion point and the saved insertion point (the <var>mark</var>), respectively. The shell assigns any numeric argument the user supplied to the <code>READLINE_ARGUMENT</code> variable. If there was no argument, that variable is not set. If the executed command changes the value of any of <code>READLINE_LINE</code>, <code>READLINE_POINT</code>, or <code>READLINE_MARK</code>, those new values will be reflected in the editing state. </p> </dd> <dt><span><code>-X</code></span></dt> <dd><p>List all key sequences bound to shell commands and the associated commands in a format that can be reused as input. </p></dd> </dl> <p>The return status is zero unless an invalid option is supplied or an error occurs. </p> </dd> <dt id="index-builtin"><span><code>builtin</code></span></dt> <dd> +<div class="example"> <pre class="example">builtin [shell-builtin [args]] +</pre> +</div> <p>Run a shell builtin, passing it <var>args</var>, and return its exit status. This is useful when defining a shell function with the same name as a shell builtin, retaining the functionality of the builtin within the function. The return status is non-zero if <var>shell-builtin</var> is not a shell builtin command. </p> </dd> <dt id="index-caller"><span><code>caller</code></span></dt> <dd> +<div class="example"> <pre class="example">caller [expr] +</pre> +</div> <p>Returns the context of any active subroutine call (a shell function or a script executed with the <code>.</code> or <code>source</code> builtins). </p> <p>Without <var>expr</var>, <code>caller</code> displays the line number and source filename of the current subroutine call. If a non-negative integer is supplied as <var>expr</var>, <code>caller</code> 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. </p> <p>The return value is 0 unless the shell is not executing a subroutine call or <var>expr</var> does not correspond to a valid position in the call stack. </p> </dd> <dt id="index-command"><span><code>command</code></span></dt> <dd> +<div class="example"> <pre class="example">command [-pVv] command [arguments …] +</pre> +</div> <p>Runs <var>command</var> with <var>arguments</var> ignoring any shell function named <var>command</var>. Only shell builtin commands or commands found by searching the <code>PATH</code> are executed. If there is a shell function named <code>ls</code>, running ‘<samp>command ls</samp>’ within the function will execute the external command <code>ls</code> instead of calling the function recursively. The <samp>-p</samp> option means to use a default value for <code>PATH</code> that is guaranteed to find all of the standard utilities. The return status in this case is 127 if <var>command</var> cannot be found or an error occurred, and the exit status of <var>command</var> otherwise. </p> <p>If either the <samp>-V</samp> or <samp>-v</samp> option is supplied, a description of <var>command</var> is printed. The <samp>-v</samp> option causes a single word indicating the command or file name used to invoke <var>command</var> to be displayed; the <samp>-V</samp> option produces a more verbose description. In this case, the return status is zero if <var>command</var> is found, and non-zero if not. </p> </dd> <dt id="index-declare"><span><code>declare</code></span></dt> <dd> +<div class="example"> <pre class="example">declare [-aAfFgiIlnrtux] [-p] [name[=value] …] +</pre> +</div> <p>Declare variables and give them attributes. If no <var>name</var>s are given, then display the values of variables instead. </p> <p>The <samp>-p</samp> option will display the attributes and values of each <var>name</var>. When <samp>-p</samp> is used with <var>name</var> arguments, additional options, other than <samp>-f</samp> and <samp>-F</samp>, are ignored. </p> <p>When <samp>-p</samp> is supplied without <var>name</var> arguments, <code>declare</code> will display the attributes and values of all variables having the attributes specified by the additional options. If no other options are supplied with <samp>-p</samp>, <code>declare</code> will display the attributes and values of all shell variables. The <samp>-f</samp> option will restrict the display to shell functions. </p> <p>The <samp>-F</samp> option inhibits the display of function definitions; only the function name and attributes are printed. If the <code>extdebug</code> shell option is enabled using <code>shopt</code> (see <a href="the-shopt-builtin">The Shopt Builtin</a>), the source file name and line number where each <var>name</var> is defined are displayed as well. <samp>-F</samp> implies <samp>-f</samp>. </p> <p>The <samp>-g</samp> option forces variables to be created or modified at the global scope, even when <code>declare</code> is executed in a shell function. It is ignored in all other cases. </p> <p>The <samp>-I</samp> option causes local variables to inherit the attributes (except the <code>nameref</code> attribute) and value of any existing variable with the same <var>name</var> at a surrounding scope. If there is no existing variable, the local variable is initially unset. </p> <p>The following options can be used to restrict output to variables with the specified attributes or to give variables attributes: </p> <dl compact> <dt><span><code>-a</code></span></dt> <dd> +<p>Each <var>name</var> is an indexed array variable (see <a href="arrays">Arrays</a>). </p> </dd> <dt><span><code>-A</code></span></dt> <dd> +<p>Each <var>name</var> is an associative array variable (see <a href="arrays">Arrays</a>). </p> </dd> <dt><span><code>-f</code></span></dt> <dd> +<p>Use function names only. </p> </dd> <dt><span><code>-i</code></span></dt> <dd> +<p>The variable is to be treated as an integer; arithmetic evaluation (see <a href="shell-arithmetic">Shell Arithmetic</a>) is performed when the variable is assigned a value. </p> </dd> <dt><span><code>-l</code></span></dt> <dd> +<p>When the variable is assigned a value, all upper-case characters are converted to lower-case. The upper-case attribute is disabled. </p> </dd> <dt><span><code>-n</code></span></dt> <dd> +<p>Give each <var>name</var> the <code>nameref</code> attribute, making it a name reference to another variable. That other variable is defined by the value of <var>name</var>. All references, assignments, and attribute modifications to <var>name</var>, except for those using or changing the <samp>-n</samp> attribute itself, are performed on the variable referenced by <var>name</var>’s value. The nameref attribute cannot be applied to array variables. </p> </dd> <dt><span><code>-r</code></span></dt> <dd> +<p>Make <var>name</var>s readonly. These names cannot then be assigned values by subsequent assignment statements or unset. </p> </dd> <dt><span><code>-t</code></span></dt> <dd> +<p>Give each <var>name</var> the <code>trace</code> attribute. Traced functions inherit the <code>DEBUG</code> and <code>RETURN</code> traps from the calling shell. The trace attribute has no special meaning for variables. </p> </dd> <dt><span><code>-u</code></span></dt> <dd> +<p>When the variable is assigned a value, all lower-case characters are converted to upper-case. The lower-case attribute is disabled. </p> </dd> <dt><span><code>-x</code></span></dt> <dd><p>Mark each <var>name</var> for export to subsequent commands via the environment. </p></dd> </dl> <p>Using ‘<samp>+</samp>’ instead of ‘<samp>-</samp>’ turns off the attribute instead, with the exceptions that ‘<samp>+a</samp>’ and ‘<samp>+A</samp>’ may not be used to destroy array variables and ‘<samp>+r</samp>’ will not remove the readonly attribute. When used in a function, <code>declare</code> makes each <var>name</var> local, as with the <code>local</code> command, unless the <samp>-g</samp> option is used. If a variable name is followed by =<var>value</var>, the value of the variable is set to <var>value</var>. </p> <p>When using <samp>-a</samp> or <samp>-A</samp> and the compound assignment syntax to create array variables, additional attributes do not take effect until subsequent assignments. </p> <p>The return status is zero unless an invalid option is encountered, an attempt is made to define a function using ‘<samp>-f foo=bar</samp>’, 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 <a href="arrays">Arrays</a>), one of the <var>name</var>s 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 <samp>-f</samp>. </p> </dd> <dt id="index-echo"><span><code>echo</code></span></dt> <dd> +<div class="example"> <pre class="example">echo [-neE] [arg …] +</pre> +</div> <p>Output the <var>arg</var>s, separated by spaces, terminated with a newline. The return status is 0 unless a write error occurs. If <samp>-n</samp> is specified, the trailing newline is suppressed. If the <samp>-e</samp> option is given, interpretation of the following backslash-escaped characters is enabled. The <samp>-E</samp> option disables the interpretation of these escape characters, even on systems where they are interpreted by default. The <code>xpg_echo</code> shell option may be used to dynamically determine whether or not <code>echo</code> expands these escape characters by default. <code>echo</code> does not interpret <samp>--</samp> to mean the end of options. </p> <p><code>echo</code> interprets the following escape sequences: </p> +<dl compact> <dt><span><code>\a</code></span></dt> <dd><p>alert (bell) </p></dd> <dt><span><code>\b</code></span></dt> <dd><p>backspace </p></dd> <dt><span><code>\c</code></span></dt> <dd><p>suppress further output </p></dd> <dt><span><code>\e</code></span></dt> <dt><span><code>\E</code></span></dt> <dd><p>escape </p></dd> <dt><span><code>\f</code></span></dt> <dd><p>form feed </p></dd> <dt><span><code>\n</code></span></dt> <dd><p>new line </p></dd> <dt><span><code>\r</code></span></dt> <dd><p>carriage return </p></dd> <dt><span><code>\t</code></span></dt> <dd><p>horizontal tab </p></dd> <dt><span><code>\v</code></span></dt> <dd><p>vertical tab </p></dd> <dt><span><code>\\</code></span></dt> <dd><p>backslash </p></dd> <dt><span><code>\0<var>nnn</var></code></span></dt> <dd><p>the eight-bit character whose value is the octal value <var>nnn</var> (zero to three octal digits) </p></dd> <dt><span><code>\x<var>HH</var></code></span></dt> <dd><p>the eight-bit character whose value is the hexadecimal value <var>HH</var> (one or two hex digits) </p></dd> <dt><span><code>\u<var>HHHH</var></code></span></dt> <dd><p>the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value <var>HHHH</var> (one to four hex digits) </p></dd> <dt><span><code>\U<var>HHHHHHHH</var></code></span></dt> <dd><p>the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value <var>HHHHHHHH</var> (one to eight hex digits) </p></dd> </dl> </dd> <dt id="index-enable"><span><code>enable</code></span></dt> <dd> +<div class="example"> <pre class="example">enable [-a] [-dnps] [-f filename] [name …] +</pre> +</div> <p>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 <samp>-n</samp> is used, the <var>name</var>s become disabled. Otherwise <var>name</var>s are enabled. For example, to use the <code>test</code> binary found via <code>$PATH</code> instead of the shell builtin version, type ‘<samp>enable -n test</samp>’. </p> <p>If the <samp>-p</samp> option is supplied, or no <var>name</var> arguments appear, a list of shell builtins is printed. With no other arguments, the list consists of all enabled shell builtins. The <samp>-a</samp> option means to list each builtin with an indication of whether or not it is enabled. </p> <p>The <samp>-f</samp> option means to load the new builtin command <var>name</var> from shared object <var>filename</var>, on systems that support dynamic loading. Bash will use the value of the <code>BASH_LOADABLES_PATH</code> variable as a colon-separated list of directories in which to search for <var>filename</var>. The default is system-dependent. The <samp>-d</samp> option will delete a builtin loaded with <samp>-f</samp>. </p> <p>If there are no options, a list of the shell builtins is displayed. The <samp>-s</samp> option restricts <code>enable</code> to the <small>POSIX</small> special builtins. If <samp>-s</samp> is used with <samp>-f</samp>, the new builtin becomes a special builtin (see <a href="special-builtins">Special Builtins</a>). </p> <p>If no options are supplied and a <var>name</var> is not a shell builtin, <code>enable</code> will attempt to load <var>name</var> from a shared object named <var>name</var>, as if the command were ‘<samp>enable -f <var>name</var> <var>name</var></samp>’. </p> <p>The return status is zero unless a <var>name</var> is not a shell builtin or there is an error loading a new builtin from a shared object. </p> </dd> <dt id="index-help"><span><code>help</code></span></dt> <dd> +<div class="example"> <pre class="example">help [-dms] [pattern] +</pre> +</div> <p>Display helpful information about builtin commands. If <var>pattern</var> is specified, <code>help</code> gives detailed help on all commands matching <var>pattern</var>, otherwise a list of the builtins is printed. </p> <p>Options, if supplied, have the following meanings: </p> <dl compact> <dt><span><code>-d</code></span></dt> <dd><p>Display a short description of each <var>pattern</var> </p></dd> <dt><span><code>-m</code></span></dt> <dd><p>Display the description of each <var>pattern</var> in a manpage-like format </p></dd> <dt><span><code>-s</code></span></dt> <dd><p>Display only a short usage synopsis for each <var>pattern</var> </p></dd> </dl> <p>The return status is zero unless no command matches <var>pattern</var>. </p> </dd> <dt id="index-let"><span><code>let</code></span></dt> <dd> +<div class="example"> <pre class="example">let expression [expression …] +</pre> +</div> <p>The <code>let</code> builtin allows arithmetic to be performed on shell variables. Each <var>expression</var> is evaluated according to the rules given below in <a href="shell-arithmetic">Shell Arithmetic</a>. If the last <var>expression</var> evaluates to 0, <code>let</code> returns 1; otherwise 0 is returned. </p> </dd> <dt id="index-local"><span><code>local</code></span></dt> <dd> +<div class="example"> <pre class="example">local [option] name[=value] … +</pre> +</div> <p>For each argument, a local variable named <var>name</var> is created, and assigned <var>value</var>. The <var>option</var> can be any of the options accepted by <code>declare</code>. <code>local</code> can only be used within a function; it makes the variable <var>name</var> have a visible scope restricted to that function and its children. If <var>name</var> is ‘<samp>-</samp>’, the set of shell options is made local to the function in which <code>local</code> is invoked: shell options changed using the <code>set</code> builtin inside the function are restored to their original values when the function returns. The restore is effected as if a series of <code>set</code> commands were executed to restore the values that were in place before the function. The return status is zero unless <code>local</code> is used outside a function, an invalid <var>name</var> is supplied, or <var>name</var> is a readonly variable. </p> </dd> <dt id="index-logout"><span><code>logout</code></span></dt> <dd> +<div class="example"> <pre class="example">logout [n] +</pre> +</div> <p>Exit a login shell, returning a status of <var>n</var> to the shell’s parent. </p> </dd> <dt id="index-mapfile"><span><code>mapfile</code></span></dt> <dd> +<div class="example"> <pre class="example">mapfile [-d delim] [-n count] [-O origin] [-s count] + [-t] [-u fd] [-C callback] [-c quantum] [array] +</pre> +</div> <p>Read lines from the standard input into the indexed array variable <var>array</var>, or from file descriptor <var>fd</var> if the <samp>-u</samp> option is supplied. The variable <code>MAPFILE</code> is the default <var>array</var>. Options, if supplied, have the following meanings: </p> <dl compact> <dt><span><code>-d</code></span></dt> <dd><p>The first character of <var>delim</var> is used to terminate each input line, rather than newline. If <var>delim</var> is the empty string, <code>mapfile</code> will terminate a line when it reads a NUL character. </p></dd> <dt><span><code>-n</code></span></dt> <dd><p>Copy at most <var>count</var> lines. If <var>count</var> is 0, all lines are copied. </p></dd> <dt><span><code>-O</code></span></dt> <dd><p>Begin assigning to <var>array</var> at index <var>origin</var>. The default index is 0. </p></dd> <dt><span><code>-s</code></span></dt> <dd><p>Discard the first <var>count</var> lines read. </p></dd> <dt><span><code>-t</code></span></dt> <dd><p>Remove a trailing <var>delim</var> (default newline) from each line read. </p></dd> <dt><span><code>-u</code></span></dt> <dd><p>Read lines from file descriptor <var>fd</var> instead of the standard input. </p></dd> <dt><span><code>-C</code></span></dt> <dd><p>Evaluate <var>callback</var> each time <var>quantum</var> lines are read. The <samp>-c</samp> option specifies <var>quantum</var>. </p></dd> <dt><span><code>-c</code></span></dt> <dd><p>Specify the number of lines read between each call to <var>callback</var>. </p></dd> </dl> <p>If <samp>-C</samp> is specified without <samp>-c</samp>, the default quantum is 5000. When <var>callback</var> 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. <var>callback</var> is evaluated after the line is read but before the array element is assigned. </p> <p>If not supplied with an explicit origin, <code>mapfile</code> will clear <var>array</var> before assigning to it. </p> <p><code>mapfile</code> returns successfully unless an invalid option or option argument is supplied, <var>array</var> is invalid or unassignable, or <var>array</var> is not an indexed array. </p> </dd> <dt id="index-printf"><span><code>printf</code></span></dt> <dd> +<div class="example"> <pre class="example">printf [-v var] format [arguments] +</pre> +</div> <p>Write the formatted <var>arguments</var> to the standard output under the control of the <var>format</var>. The <samp>-v</samp> option causes the output to be assigned to the variable <var>var</var> rather than being printed to the standard output. </p> <p>The <var>format</var> 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 <var>argument</var>. In addition to the standard <code>printf(1)</code> formats, <code>printf</code> interprets the following extensions: </p> <dl compact> <dt><span><code>%b</code></span></dt> <dd><p>Causes <code>printf</code> to expand backslash escape sequences in the corresponding <var>argument</var> in the same way as <code>echo -e</code> (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). </p></dd> <dt><span><code>%q</code></span></dt> <dd><p>Causes <code>printf</code> to output the corresponding <var>argument</var> in a format that can be reused as shell input. </p></dd> <dt><span><code>%Q</code></span></dt> <dd><p>like <code>%q</code>, but applies any supplied precision to the <var>argument</var> before quoting it. </p></dd> <dt><span><code>%(<var>datefmt</var>)T</code></span></dt> <dd><p>Causes <code>printf</code> to output the date-time string resulting from using <var>datefmt</var> as a format string for <code>strftime</code>(3). The corresponding <var>argument</var> 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 <code>printf</code> behavior. </p></dd> </dl> <p>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. </p> <p>Arguments to non-string format specifiers are treated as C language 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. </p> <p>The <var>format</var> is reused as necessary to consume all of the <var>arguments</var>. If the <var>format</var> requires more <var>arguments</var> 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. </p> </dd> <dt id="index-read"><span><code>read</code></span></dt> <dd> +<div class="example"> <pre class="example">read [-ers] [-a aname] [-d delim] [-i text] [-n nchars] + [-N nchars] [-p prompt] [-t timeout] [-u fd] [name …] +</pre> +</div> <p>One line is read from the standard input, or from the file descriptor <var>fd</var> supplied as an argument to the <samp>-u</samp> option, split into words as described above in <a href="word-splitting">Word Splitting</a>, and the first word is assigned to the first <var>name</var>, the second word to the second <var>name</var>, and so on. If there are more words than names, the remaining words and their intervening delimiters are assigned to the last <var>name</var>. If there are fewer words read from the input stream than names, the remaining names are assigned empty values. The characters in the value of the <code>IFS</code> variable are used to split the line into words using the same rules the shell uses for expansion (described above in <a href="word-splitting">Word Splitting</a>). The backslash character ‘<samp>\</samp>’ may be used to remove any special meaning for the next character read and for line continuation. </p> <p>Options, if supplied, have the following meanings: </p> <dl compact> <dt><span><code>-a <var>aname</var></code></span></dt> <dd> +<p>The words are assigned to sequential indices of the array variable <var>aname</var>, starting at 0. All elements are removed from <var>aname</var> before the assignment. Other <var>name</var> arguments are ignored. </p> </dd> <dt><span><code>-d <var>delim</var></code></span></dt> <dd> +<p>The first character of <var>delim</var> is used to terminate the input line, rather than newline. If <var>delim</var> is the empty string, <code>read</code> will terminate a line when it reads a NUL character. </p> </dd> <dt><span><code>-e</code></span></dt> <dd> +<p>Readline (see <a href="command-line-editing">Command Line Editing</a>) 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. </p> </dd> <dt><span><code>-i <var>text</var></code></span></dt> <dd> +<p>If Readline is being used to read the line, <var>text</var> is placed into the editing buffer before editing begins. </p> </dd> <dt><span><code>-n <var>nchars</var></code></span></dt> <dd> +<p><code>read</code> returns after reading <var>nchars</var> characters rather than waiting for a complete line of input, but honors a delimiter if fewer than <var>nchars</var> characters are read before the delimiter. </p> </dd> <dt><span><code>-N <var>nchars</var></code></span></dt> <dd> +<p><code>read</code> returns after reading exactly <var>nchars</var> characters rather than waiting for a complete line of input, unless EOF is encountered or <code>read</code> times out. Delimiter characters encountered in the input are not treated specially and do not cause <code>read</code> to return until <var>nchars</var> characters are read. The result is not split on the characters in <code>IFS</code>; the intent is that the variable is assigned exactly the characters read (with the exception of backslash; see the <samp>-r</samp> option below). </p> </dd> <dt><span><code>-p <var>prompt</var></code></span></dt> <dd> +<p>Display <var>prompt</var>, without a trailing newline, before attempting to read any input. The prompt is displayed only if input is coming from a terminal. </p> </dd> <dt><span><code>-r</code></span></dt> <dd> +<p>If this option is given, 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. </p> </dd> <dt><span><code>-s</code></span></dt> <dd> +<p>Silent mode. If input is coming from a terminal, characters are not echoed. </p> </dd> <dt><span><code>-t <var>timeout</var></code></span></dt> <dd> +<p>Cause <code>read</code> to time out and return failure if a complete line of input (or a specified number of characters) is not read within <var>timeout</var> seconds. <var>timeout</var> may be a decimal number with a fractional portion following the decimal point. This option is only effective if <code>read</code> is reading input from a terminal, pipe, or other special file; it has no effect when reading from regular files. If <code>read</code> times out, <code>read</code> saves any partial input read into the specified variable <var>name</var>. If <var>timeout</var> is 0, <code>read</code> 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. </p> </dd> <dt><span><code>-u <var>fd</var></code></span></dt> <dd><p>Read input from file descriptor <var>fd</var>. </p></dd> </dl> <p>If no <var>name</var>s are supplied, the line read, without the ending delimiter but otherwise unmodified, is assigned to the variable <code>REPLY</code>. The exit status is zero, unless end-of-file is encountered, <code>read</code> 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 <samp>-u</samp>. </p> </dd> <dt id="index-readarray"><span><code>readarray</code></span></dt> <dd> +<div class="example"> <pre class="example">readarray [-d delim] [-n count] [-O origin] [-s count] + [-t] [-u fd] [-C callback] [-c quantum] [array] +</pre> +</div> <p>Read lines from the standard input into the indexed array variable <var>array</var>, or from file descriptor <var>fd</var> if the <samp>-u</samp> option is supplied. </p> <p>A synonym for <code>mapfile</code>. </p> </dd> <dt id="index-source"><span><code>source</code></span></dt> <dd> +<div class="example"> <pre class="example">source filename +</pre> +</div> <p>A synonym for <code>.</code> (see <a href="bourne-shell-builtins">Bourne Shell Builtins</a>). </p> </dd> <dt id="index-type"><span><code>type</code></span></dt> <dd> +<div class="example"> <pre class="example">type [-afptP] [name …] +</pre> +</div> <p>For each <var>name</var>, indicate how it would be interpreted if used as a command name. </p> <p>If the <samp>-t</samp> option is used, <code>type</code> prints a single word which is one of ‘<samp>alias</samp>’, ‘<samp>function</samp>’, ‘<samp>builtin</samp>’, ‘<samp>file</samp>’ or ‘<samp>keyword</samp>’, if <var>name</var> is an alias, shell function, shell builtin, disk file, or shell reserved word, respectively. If the <var>name</var> is not found, then nothing is printed, and <code>type</code> returns a failure status. </p> <p>If the <samp>-p</samp> option is used, <code>type</code> either returns the name of the disk file that would be executed, or nothing if <samp>-t</samp> would not return ‘<samp>file</samp>’. </p> <p>The <samp>-P</samp> option forces a path search for each <var>name</var>, even if <samp>-t</samp> would not return ‘<samp>file</samp>’. </p> <p>If a command is hashed, <samp>-p</samp> and <samp>-P</samp> print the hashed value, which is not necessarily the file that appears first in <code>$PATH</code>. </p> <p>If the <samp>-a</samp> option is used, <code>type</code> returns all of the places that contain an executable named <var>file</var>. This includes aliases and functions, if and only if the <samp>-p</samp> option is not also used. </p> <p>If the <samp>-f</samp> option is used, <code>type</code> does not attempt to find shell functions, as with the <code>command</code> builtin. </p> <p>The return status is zero if all of the <var>name</var>s are found, non-zero if any are not found. </p> </dd> <dt id="index-typeset"><span><code>typeset</code></span></dt> <dd> +<div class="example"> <pre class="example">typeset [-afFgrxilnrtux] [-p] [name[=value] …] +</pre> +</div> <p>The <code>typeset</code> command is supplied for compatibility with the Korn shell. It is a synonym for the <code>declare</code> builtin command. </p> </dd> <dt id="index-ulimit"><span><code>ulimit</code></span></dt> <dd> +<div class="example"> <pre class="example">ulimit [-HS] -a +ulimit [-HS] [-bcdefiklmnpqrstuvxPRT] [limit] +</pre> +</div> <p><code>ulimit</code> provides control over the resources available to processes started by the shell, on systems that allow such control. If an option is given, it is interpreted as follows: </p> <dl compact> <dt><span><code>-S</code></span></dt> <dd> +<p>Change and report the soft limit associated with a resource. </p> </dd> <dt><span><code>-H</code></span></dt> <dd> +<p>Change and report the hard limit associated with a resource. </p> </dd> <dt><span><code>-a</code></span></dt> <dd> +<p>All current limits are reported; no limits are set. </p> </dd> <dt><span><code>-b</code></span></dt> <dd> +<p>The maximum socket buffer size. </p> </dd> <dt><span><code>-c</code></span></dt> <dd> +<p>The maximum size of core files created. </p> </dd> <dt><span><code>-d</code></span></dt> <dd> +<p>The maximum size of a process’s data segment. </p> </dd> <dt><span><code>-e</code></span></dt> <dd> +<p>The maximum scheduling priority ("nice"). </p> </dd> <dt><span><code>-f</code></span></dt> <dd> +<p>The maximum size of files written by the shell and its children. </p> </dd> <dt><span><code>-i</code></span></dt> <dd> +<p>The maximum number of pending signals. </p> </dd> <dt><span><code>-k</code></span></dt> <dd> +<p>The maximum number of kqueues that may be allocated. </p> </dd> <dt><span><code>-l</code></span></dt> <dd> +<p>The maximum size that may be locked into memory. </p> </dd> <dt><span><code>-m</code></span></dt> <dd> +<p>The maximum resident set size (many systems do not honor this limit). </p> </dd> <dt><span><code>-n</code></span></dt> <dd> +<p>The maximum number of open file descriptors (most systems do not allow this value to be set). </p> </dd> <dt><span><code>-p</code></span></dt> <dd> +<p>The pipe buffer size. </p> </dd> <dt><span><code>-q</code></span></dt> <dd> +<p>The maximum number of bytes in <small>POSIX</small> message queues. </p> </dd> <dt><span><code>-r</code></span></dt> <dd> +<p>The maximum real-time scheduling priority. </p> </dd> <dt><span><code>-s</code></span></dt> <dd> +<p>The maximum stack size. </p> </dd> <dt><span><code>-t</code></span></dt> <dd> +<p>The maximum amount of cpu time in seconds. </p> </dd> <dt><span><code>-u</code></span></dt> <dd> +<p>The maximum number of processes available to a single user. </p> </dd> <dt><span><code>-v</code></span></dt> <dd> +<p>The maximum amount of virtual memory available to the shell, and, on some systems, to its children. </p> </dd> <dt><span><code>-x</code></span></dt> <dd> +<p>The maximum number of file locks. </p> </dd> <dt><span><code>-P</code></span></dt> <dd> +<p>The maximum number of pseudoterminals. </p> </dd> <dt><span><code>-R</code></span></dt> <dd> +<p>The maximum time a real-time process can run before blocking, in microseconds. </p> </dd> <dt><span><code>-T</code></span></dt> <dd><p>The maximum number of threads. </p></dd> </dl> <p>If <var>limit</var> is given, and the <samp>-a</samp> option is not used, <var>limit</var> is the new value of the specified resource. The special <var>limit</var> values <code>hard</code>, <code>soft</code>, and <code>unlimited</code> stand for the current hard limit, the current soft limit, and no limit, respectively. 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. Otherwise, the current value of the soft limit for the specified resource is printed, unless the <samp>-H</samp> option is supplied. When more than one resource is specified, the limit name and unit, if appropriate, are printed before the value. When setting new limits, if neither <samp>-H</samp> nor <samp>-S</samp> is supplied, both the hard and soft limits are set. If no option is given, then <samp>-f</samp> is assumed. Values are in 1024-byte increments, except for <samp>-t</samp>, which is in seconds; <samp>-R</samp>, which is in microseconds; <samp>-p</samp>, which is in units of 512-byte blocks; <samp>-P</samp>, <samp>-T</samp>, <samp>-b</samp>, <samp>-k</samp>, <samp>-n</samp> and <samp>-u</samp>, which are unscaled values; and, when in <small>POSIX</small> Mode (see <a href="bash-posix-mode">Bash POSIX Mode</a>), <samp>-c</samp> and <samp>-f</samp>, which are in 512-byte increments. </p> <p>The return status is zero unless an invalid option or argument is supplied, or an error occurs while setting a new limit. </p> </dd> <dt id="index-unalias"><span><code>unalias</code></span></dt> <dd> +<div class="example"> <pre class="example">unalias [-a] [name … ] +</pre> +</div> <p>Remove each <var>name</var> from the list of aliases. If <samp>-a</samp> is supplied, all aliases are removed. Aliases are described in <a href="aliases">Aliases</a>. </p> +</dd> </dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.<br>Licensed under the GNU Free Documentation License.<br> + <a href="https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html" class="_attribution-link">https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html</a> + </p> +</div> |