path: root/devdocs/bash/bourne-shell-builtins.html

<h1 class="section">Bourne Shell Builtins</h1> <p>The following shell builtin commands are inherited from the Bourne Shell. These commands are implemented as specified by the <small>POSIX</small> standard. </p> <dl compact> <dt id="index-_003a"><span><code>:    <span class="roman">(a colon)</span></code></span></dt> <dd>
<div class="example"> <pre class="example">: [arguments]
</pre>
</div> <p>Do nothing beyond expanding <var>arguments</var> and performing redirections. The return status is zero. </p> </dd> <dt id="index-_002e"><span><code>.    <span class="roman">(a period)</span></code></span></dt> <dd>
<div class="example"> <pre class="example">. filename [arguments]
</pre>
</div> <p>Read and execute commands from the <var>filename</var> argument in the current shell context. If <var>filename</var> does not contain a slash, the <code>PATH</code> variable is used to find <var>filename</var>, but <var>filename</var> does not need to be executable. When Bash is not in <small>POSIX</small> mode, it searches the current directory if <var>filename</var> is not found in <code>$PATH</code>. If any <var>arguments</var> are supplied, they become the positional parameters when <var>filename</var> is executed. Otherwise the positional parameters are unchanged. If the <samp>-T</samp> option is enabled, <code>.</code> inherits any trap on <code>DEBUG</code>; if it is not, any <code>DEBUG</code> trap string is saved and restored around the call to <code>.</code>, and <code>.</code> unsets the <code>DEBUG</code> trap while it executes. If <samp>-T</samp> is not set, and the sourced file changes the <code>DEBUG</code> trap, the new value is retained when <code>.</code> completes. The return status is the exit status of the last command executed, or zero if no commands are executed. If <var>filename</var> is not found, or cannot be read, the return status is non-zero. This builtin is equivalent to <code>source</code>. </p> </dd> <dt id="index-break"><span><code>break</code></span></dt> <dd>
<div class="example"> <pre class="example">break [n]
</pre>
</div> <p>Exit from a <code>for</code>, <code>while</code>, <code>until</code>, or <code>select</code> loop. If <var>n</var> is supplied, the <var>n</var>th enclosing loop is exited. <var>n</var> must be greater than or equal to 1. The return status is zero unless <var>n</var> is not greater than or equal to 1. </p> </dd> <dt id="index-cd"><span><code>cd</code></span></dt> <dd>
<div class="example"> <pre class="example">cd [-L|[-P [-e]] [-@] [directory]
</pre>
</div> <p>Change the current working directory to <var>directory</var>. If <var>directory</var> is not supplied, the value of the <code>HOME</code> shell variable is used. If the shell variable <code>CDPATH</code> exists, it is used as a search path: each directory name in <code>CDPATH</code> is searched for <var>directory</var>, with alternative directory names in <code>CDPATH</code> separated by a colon (‘<samp>:</samp>’). If <var>directory</var> begins with a slash, <code>CDPATH</code> is not used. </p> <p>The <samp>-P</samp> option means to not follow symbolic links: symbolic links are resolved while <code>cd</code> is traversing <var>directory</var> and before processing an instance of ‘<samp>..</samp>’ in <var>directory</var>. </p> <p>By default, or when the <samp>-L</samp> option is supplied, symbolic links in <var>directory</var> are resolved after <code>cd</code> processes an instance of ‘<samp>..</samp>’ in <var>directory</var>. </p> <p>If ‘<samp>..</samp>’ appears in <var>directory</var>, it is processed by removing the immediately preceding pathname component, back to a slash or the beginning of <var>directory</var>. </p> <p>If the <samp>-e</samp> option is supplied with <samp>-P</samp> and the current working directory cannot be successfully determined after a successful directory change, <code>cd</code> will return an unsuccessful status. </p> <p>On systems that support it, the <samp>-@</samp> option presents the extended attributes associated with a file as a directory. </p> <p>If <var>directory</var> is ‘<samp>-</samp>’, it is converted to <code>$OLDPWD</code> before the directory change is attempted. </p> <p>If a non-empty directory name from <code>CDPATH</code> is used, or if ‘<samp>-</samp>’ is the first argument, and the directory change is successful, the absolute pathname of the new working directory is written to the standard output. </p> <p>If the directory change is successful, <code>cd</code> sets the value of the <code>PWD</code> environment variable to the new directory name, and sets the <code>OLDPWD</code> environment variable to the value of the current working directory before the change. </p> <p>The return status is zero if the directory is successfully changed, non-zero otherwise. </p> </dd> <dt id="index-continue"><span><code>continue</code></span></dt> <dd>
<div class="example"> <pre class="example">continue [n]
</pre>
</div> <p>Resume the next iteration of an enclosing <code>for</code>, <code>while</code>, <code>until</code>, or <code>select</code> loop. If <var>n</var> is supplied, the execution of the <var>n</var>th enclosing loop is resumed. <var>n</var> must be greater than or equal to 1. The return status is zero unless <var>n</var> is not greater than or equal to 1. </p> </dd> <dt id="index-eval"><span><code>eval</code></span></dt> <dd>
<div class="example"> <pre class="example">eval [arguments]
</pre>
</div> <p>The arguments are concatenated together into a single command, which is then read and executed, and its exit status returned as the exit status of <code>eval</code>. If there are no arguments or only empty arguments, the return status is zero. </p> </dd> <dt id="index-exec"><span><code>exec</code></span></dt> <dd>
<div class="example"> <pre class="example">exec [-cl] [-a name] [command [arguments]]
</pre>
</div> <p>If <var>command</var> is supplied, it replaces the shell without creating a new process. If the <samp>-l</samp> option is supplied, the shell places a dash at the beginning of the zeroth argument passed to <var>command</var>. This is what the <code>login</code> program does. The <samp>-c</samp> option causes <var>command</var> to be executed with an empty environment. If <samp>-a</samp> is supplied, the shell passes <var>name</var> as the zeroth argument to <var>command</var>. If <var>command</var> cannot be executed for some reason, a non-interactive shell exits, unless the <code>execfail</code> 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 <code>exec</code> fails. If no <var>command</var> is specified, redirections may be used to affect the current shell environment. If there are no redirection errors, the return status is zero; otherwise the return status is non-zero. </p> </dd> <dt id="index-exit"><span><code>exit</code></span></dt> <dd>
<div class="example"> <pre class="example">exit [n]
</pre>
</div> <p>Exit the shell, returning a status of <var>n</var> to the shell’s parent. If <var>n</var> is omitted, the exit status is that of the last command executed. Any trap on <code>EXIT</code> is executed before the shell terminates. </p> </dd> <dt id="index-export"><span><code>export</code></span></dt> <dd>
<div class="example"> <pre class="example">export [-fn] [-p] [name[=value]]
</pre>
</div> <p>Mark each <var>name</var> to be passed to child processes in the environment. If the <samp>-f</samp> option is supplied, the <var>name</var>s refer to shell functions; otherwise the names refer to shell variables. The <samp>-n</samp> option means to no longer mark each <var>name</var> for export. If no <var>name</var>s are supplied, or if the <samp>-p</samp> option is given, a list of names of all exported variables is displayed. The <samp>-p</samp> option displays output in a form that may be reused as input. If a variable name is followed by =<var>value</var>, the value of the variable is set to <var>value</var>. </p> <p>The return status is zero unless an invalid option is supplied, one of the names is not a valid shell variable name, or <samp>-f</samp> is supplied with a name that is not a shell function. </p> </dd> <dt id="index-getopts"><span><code>getopts</code></span></dt> <dd>
<div class="example"> <pre class="example">getopts optstring name [arg …]
</pre>
</div> <p><code>getopts</code> is used by shell scripts to parse positional parameters. <var>optstring</var> 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 whitespace. The colon (‘<samp>:</samp>’) and question mark (‘<samp>?</samp>’) may not be used as option characters. Each time it is invoked, <code>getopts</code> places the next option in the shell variable <var>name</var>, initializing <var>name</var> if it does not exist, and the index of the next argument to be processed into the variable <code>OPTIND</code>. <code>OPTIND</code> is initialized to 1 each time the shell or a shell script is invoked. When an option requires an argument, <code>getopts</code> places that argument into the variable <code>OPTARG</code>. The shell does not reset <code>OPTIND</code> automatically; it must be manually reset between multiple calls to <code>getopts</code> within the same shell invocation if a new set of parameters is to be used. </p> <p>When the end of options is encountered, <code>getopts</code> exits with a return value greater than zero. <code>OPTIND</code> is set to the index of the first non-option argument, and <var>name</var> is set to ‘<samp>?</samp>’. </p> <p><code>getopts</code> normally parses the positional parameters, but if more arguments are supplied as <var>arg</var> values, <code>getopts</code> parses those instead. </p> <p><code>getopts</code> can report errors in two ways. If the first character of <var>optstring</var> is a colon, <var>silent</var> error reporting is used. In normal operation, diagnostic messages are printed when invalid options or missing option arguments are encountered. If the variable <code>OPTERR</code> is set to 0, no error messages will be displayed, even if the first character of <code>optstring</code> is not a colon. </p> <p>If an invalid option is seen, <code>getopts</code> places ‘<samp>?</samp>’ into <var>name</var> and, if not silent, prints an error message and unsets <code>OPTARG</code>. If <code>getopts</code> is silent, the option character found is placed in <code>OPTARG</code> and no diagnostic message is printed. </p> <p>If a required argument is not found, and <code>getopts</code> is not silent, a question mark (‘<samp>?</samp>’) is placed in <var>name</var>, <code>OPTARG</code> is unset, and a diagnostic message is printed. If <code>getopts</code> is silent, then a colon (‘<samp>:</samp>’) is placed in <var>name</var> and <code>OPTARG</code> is set to the option character found. </p> </dd> <dt id="index-hash"><span><code>hash</code></span></dt> <dd>
<div class="example"> <pre class="example">hash [-r] [-p filename] [-dt] [name]
</pre>
</div> <p>Each time <code>hash</code> is invoked, it remembers the full pathnames of the commands specified as <var>name</var> arguments, so they need not be searched for on subsequent invocations. The commands are found by searching through the directories listed in <code>$PATH</code>. Any previously-remembered pathname is discarded. The <samp>-p</samp> option inhibits the path search, and <var>filename</var> is used as the location of <var>name</var>. The <samp>-r</samp> option causes the shell to forget all remembered locations. The <samp>-d</samp> option causes the shell to forget the remembered location of each <var>name</var>. If the <samp>-t</samp> option is supplied, the full pathname to which each <var>name</var> corresponds is printed. If multiple <var>name</var> arguments are supplied with <samp>-t</samp>, the <var>name</var> is printed before the hashed full pathname. The <samp>-l</samp> option causes output to be displayed in a format that may be reused as input. If no arguments are given, or if only <samp>-l</samp> is supplied, information about remembered commands is printed. The return status is zero unless a <var>name</var> is not found or an invalid option is supplied. </p> </dd> <dt id="index-pwd"><span><code>pwd</code></span></dt> <dd>
<div class="example"> <pre class="example">pwd [-LP]
</pre>
</div> <p>Print the absolute pathname of the current working directory. If the <samp>-P</samp> option is supplied, the pathname printed will not contain symbolic links. If the <samp>-L</samp> option is supplied, the pathname printed may contain symbolic links. The return status is zero unless an error is encountered while determining the name of the current directory or an invalid option is supplied. </p> </dd> <dt id="index-readonly"><span><code>readonly</code></span></dt> <dd>
<div class="example"> <pre class="example">readonly [-aAf] [-p] [name[=value]] …
</pre>
</div> <p>Mark each <var>name</var> as readonly. The values of these names may not be changed by subsequent assignment. If the <samp>-f</samp> option is supplied, each <var>name</var> refers to a shell function. The <samp>-a</samp> option means each <var>name</var> refers to an indexed array variable; the <samp>-A</samp> option means each <var>name</var> refers to an associative array variable. If both options are supplied, <samp>-A</samp> takes precedence. If no <var>name</var> arguments are given, or if the <samp>-p</samp> 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 <samp>-p</samp> option causes output to be displayed in a format that may be reused as input. If a variable name is followed by =<var>value</var>, the value of the variable is set to <var>value</var>. The return status is zero unless an invalid option is supplied, one of the <var>name</var> arguments is not a valid shell variable or function name, or the <samp>-f</samp> option is supplied with a name that is not a shell function. </p> </dd> <dt id="index-return"><span><code>return</code></span></dt> <dd>
<div class="example"> <pre class="example">return [n]
</pre>
</div> <p>Cause a shell function to stop executing and return the value <var>n</var> to its caller. If <var>n</var> is not supplied, the return value is the exit status of the last command executed in the function. If <code>return</code> is executed by a trap handler, the last command used to determine the status is the last command executed before the trap handler. If <code>return</code> is executed during a <code>DEBUG</code> trap, the last command used to determine the status is the last command executed by the trap handler before <code>return</code> was invoked. <code>return</code> may also be used to terminate execution of a script being executed with the <code>.</code> (<code>source</code>) builtin, returning either <var>n</var> or the exit status of the last command executed within the script as the exit status of the script. If <var>n</var> is supplied, the return value is its least significant 8 bits. Any command associated with the <code>RETURN</code> trap is executed before execution resumes after the function or script. The return status is non-zero if <code>return</code> is supplied a non-numeric argument or is used outside a function and not during the execution of a script by <code>.</code> or <code>source</code>. </p> </dd> <dt id="index-shift"><span><code>shift</code></span></dt> <dd>
<div class="example"> <pre class="example">shift [n]
</pre>
</div> <p>Shift the positional parameters to the left by <var>n</var>. The positional parameters from <var>n</var>+1 … <code>$#</code> are renamed to <code>$1</code> … <code>$#</code>-<var>n</var>. Parameters represented by the numbers <code>$#</code> down to <code>$#</code>-<var>n</var>+1 are unset. <var>n</var> must be a non-negative number less than or equal to <code>$#</code>. If <var>n</var> is zero or greater than <code>$#</code>, the positional parameters are not changed. If <var>n</var> is not supplied, it is assumed to be 1. The return status is zero unless <var>n</var> is greater than <code>$#</code> or less than zero, non-zero otherwise. </p> </dd> <dt id="index-test"><span><code>test</code></span></dt> <dt><span><code>[</code></span></dt> <dd>
 <div class="example"> <pre class="example">test expr
</pre>
</div> <p>Evaluate a conditional expression <var>expr</var> and return a status of 0 (true) or 1 (false). Each operator and operand must be a separate argument. Expressions are composed of the primaries described below in <a href="bash-conditional-expressions">Bash Conditional Expressions</a>. <code>test</code> does not accept any options, nor does it accept and ignore an argument of <samp>--</samp> as signifying the end of options. </p> <p>When the <code>[</code> form is used, the last argument to the command must be a <code>]</code>. </p> <p>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. </p> <dl compact> <dt><span><code>! <var>expr</var></code></span></dt> <dd>
<p>True if <var>expr</var> is false. </p> </dd> <dt><span><code>( <var>expr</var> )</code></span></dt> <dd>
<p>Returns the value of <var>expr</var>. This may be used to override the normal precedence of operators. </p> </dd> <dt><span><code><var>expr1</var> -a <var>expr2</var></code></span></dt> <dd>
<p>True if both <var>expr1</var> and <var>expr2</var> are true. </p> </dd> <dt><span><code><var>expr1</var> -o <var>expr2</var></code></span></dt> <dd><p>True if either <var>expr1</var> or <var>expr2</var> is true. </p></dd> </dl> <p>The <code>test</code> and <code>[</code> builtins evaluate conditional expressions using a set of rules based on the number of arguments. </p> <dl compact> <dt><span>0 arguments</span></dt> <dd>
<p>The expression is false. </p> </dd> <dt><span>1 argument</span></dt> <dd>
<p>The expression is true if, and only if, the argument is not null. </p> </dd> <dt><span>2 arguments</span></dt> <dd>
<p>If the first argument is ‘<samp>!</samp>’, the expression is true if and only if the second argument is null. If the first argument is one of the unary conditional operators (see <a href="bash-conditional-expressions">Bash Conditional Expressions</a>), the expression is true if the unary test is true. If the first argument is not a valid unary operator, the expression is false. </p> </dd> <dt><span>3 arguments</span></dt> <dd>
<p>The following conditions are applied in the order listed. </p> <ol> <li> If the second argument is one of the binary conditional operators (see <a href="bash-conditional-expressions">Bash Conditional Expressions</a>), the result of the expression is the result of the binary test using the first and third arguments as operands. The ‘<samp>-a</samp>’ and ‘<samp>-o</samp>’ operators are considered binary operators when there are three arguments. </li>
<li> If the first argument is ‘<samp>!</samp>’, the value is the negation of the two-argument test using the second and third arguments. </li>
<li> If the first argument is exactly ‘<samp>(</samp>’ and the third argument is exactly ‘<samp>)</samp>’, the result is the one-argument test of the second argument. </li>
<li> Otherwise, the expression is false. </li>
</ol> </dd> <dt><span>4 arguments</span></dt> <dd>
<p>The following conditions are applied in the order listed. </p> <ol> <li> If the first argument is ‘<samp>!</samp>’, the result is the negation of the three-argument expression composed of the remaining arguments. </li>
<li> If the first argument is exactly ‘<samp>(</samp>’ and the fourth argument is exactly ‘<samp>)</samp>’, the result is the two-argument test of the second and third arguments. </li>
<li> Otherwise, the expression is parsed and evaluated according to precedence using the rules listed above. </li>
</ol> </dd> <dt><span>5 or more arguments</span></dt> <dd><p>The expression is parsed and evaluated according to precedence using the rules listed above. </p></dd> </dl> <p>When used with <code>test</code> or ‘<samp>[</samp>’, the ‘<samp>&lt;</samp>’ and ‘<samp>&gt;</samp>’ operators sort lexicographically using ASCII ordering. </p> </dd> <dt id="index-times"><span><code>times</code></span></dt> <dd>
<div class="example"> <pre class="example">times
</pre>
</div> <p>Print out the user and system times used by the shell and its children. The return status is zero. </p> </dd> <dt id="index-trap"><span><code>trap</code></span></dt> <dd>
<div class="example"> <pre class="example">trap [-lp] [arg] [sigspec …]
</pre>
</div> <p>The commands in <var>arg</var> are to be read and executed when the shell receives signal <var>sigspec</var>. If <var>arg</var> is absent (and there is a single <var>sigspec</var>) or equal to ‘<samp>-</samp>’, each specified signal’s disposition is reset to the value it had when the shell was started. If <var>arg</var> is the null string, then the signal specified by each <var>sigspec</var> is ignored by the shell and commands it invokes. If <var>arg</var> is not present and <samp>-p</samp> has been supplied, the shell displays the trap commands associated with each <var>sigspec</var>. If no arguments are supplied, or only <samp>-p</samp> is given, <code>trap</code> prints the list of commands associated with each signal number in a form that may be reused as shell input. The <samp>-l</samp> option causes the shell to print a list of signal names and their corresponding numbers. Each <var>sigspec</var> is either a signal name or a signal number. Signal names are case insensitive and the <code>SIG</code> prefix is optional. </p> <p>If a <var>sigspec</var> is <code>0</code> or <code>EXIT</code>, <var>arg</var> is executed when the shell exits. If a <var>sigspec</var> is <code>DEBUG</code>, the command <var>arg</var> is executed before every simple command, <code>for</code> command, <code>case</code> command, <code>select</code> command, every arithmetic <code>for</code> command, and before the first command executes in a shell function. Refer to the description of the <code>extdebug</code> option to the <code>shopt</code> builtin (see <a href="the-shopt-builtin">The Shopt Builtin</a>) for details of its effect on the <code>DEBUG</code> trap. If a <var>sigspec</var> is <code>RETURN</code>, the command <var>arg</var> is executed each time a shell function or a script executed with the <code>.</code> or <code>source</code> builtins finishes executing. </p> <p>If a <var>sigspec</var> is <code>ERR</code>, the command <var>arg</var> 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 <code>ERR</code> trap is not executed if the failed command is part of the command list immediately following an <code>until</code> or <code>while</code> keyword, part of the test following the <code>if</code> or <code>elif</code> reserved words, part of a command executed in a <code>&amp;&amp;</code> or <code>||</code> list except the command following the final <code>&amp;&amp;</code> or <code>||</code>, any command in a pipeline but the last, or if the command’s return status is being inverted using <code>!</code>. These are the same conditions obeyed by the <code>errexit</code> (<samp>-e</samp>) option. </p> <p>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. </p> <p>The return status is zero unless a <var>sigspec</var> does not specify a valid signal. </p> </dd> <dt id="index-umask"><span><code>umask</code></span></dt> <dd>
<div class="example"> <pre class="example">umask [-p] [-S] [mode]
</pre>
</div> <p>Set the shell process’s file creation mask to <var>mode</var>. If <var>mode</var> begins with a digit, it is interpreted as an octal number; if not, it is interpreted as a symbolic mode mask similar to that accepted by the <code>chmod</code> command. If <var>mode</var> is omitted, the current value of the mask is printed. If the <samp>-S</samp> option is supplied without a <var>mode</var> argument, the mask is printed in a symbolic format. If the <samp>-p</samp> option is supplied, and <var>mode</var> is omitted, the output is in a form that may be reused as input. The return status is zero if the mode is successfully changed or if no <var>mode</var> argument is supplied, and non-zero otherwise. </p> <p>Note that when the mode is interpreted as an octal number, each number of the umask is subtracted from <code>7</code>. Thus, a umask of <code>022</code> results in permissions of <code>755</code>. </p> </dd> <dt id="index-unset"><span><code>unset</code></span></dt> <dd>
<div class="example"> <pre class="example">unset [-fnv] [name]
</pre>
</div> <p>Remove each variable or function <var>name</var>. If the <samp>-v</samp> option is given, each <var>name</var> refers to a shell variable and that variable is removed. If the <samp>-f</samp> option is given, the <var>name</var>s refer to shell functions, and the function definition is removed. If the <samp>-n</samp> option is supplied, and <var>name</var> is a variable with the <code>nameref</code> attribute, <var>name</var> will be unset rather than the variable it references. <samp>-n</samp> has no effect if the <samp>-f</samp> option is supplied. If no options are supplied, each <var>name</var> refers to a variable; if there is no variable by that name, a function with that name, if any, is unset. Readonly variables and functions may not be unset. Some shell variables lose their special behavior if they are unset; such behavior is noted in the description of the individual variables. The return status is zero unless a <var>name</var> is readonly or may not be unset. </p>
</dd> </dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 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/Bourne-Shell-Builtins.html" class="_attribution-link">https://www.gnu.org/software/bash/manual/html_node/Bourne-Shell-Builtins.html</a>
  </p>
</div>