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