Bourne Shell Builtins
=====================
The following shell builtin commands are inherited from the Bourne
Shell. These commands are implemented as specified by the POSIX 1003.2
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. 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 [-LP] [DIRECTORY]
Change the current working directory to DIRECTORY. If DIRECTORY
is not given, the value of the `HOME' shell variable is used. If
the shell variable `CDPATH' exists, it is used as a search path.
If DIRECTORY begins with a slash, `CDPATH' is not used. The `-P'
option means to not follow symbolic links; symbolic links are
followed by default or with the `-L' option. If DIRECTORY is `-',
it is equivalent to `$OLDPWD'. 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 arg 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 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 exported
names is displayed. The `-p' option displays output in a form
that may be reused as input. 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 white space. 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] [-t] [NAME]
Remember the full pathnames of 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'. 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. 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. If
no arguments are given, 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 [-apf] [NAME] ...
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 array variable. If no NAME arguments are given,
or if the `-p' option is supplied, a list of all readonly names is
printed. The `-p' option causes output to be displayed in a
format that may be reused as input. 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 exit with the return value N. If N is
not supplied, the return value is the exit status of the last
command executed in the function. This may also be used to
terminate execution of a script being executed with the `.' (or
`source') builtin, returning either N or the exit status of the
last command executed within the script as the exit status of the
script. The return status is non-zero if `return' 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+1.
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'
`['
Evaluate a conditional expression EXPR. Each operator and operand
must be a separate argument. Expressions are composed of the
primaries described below in Note:Bash Conditional Expressions.
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.
`! 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 (Note: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
If the second argument is one of the binary conditional
operators (Note:Bash Conditional Expressions), the result
of the expression is the result of the binary test using the
first and third arguments as operands. 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. The `-a' and `-o'
operators are considered binary operators in this case.
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.
`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 or equal to `-', all
specified signals are reset to the values they 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. Each SIGSPEC is either a signal
name such as `SIGINT' (with or without the `SIG' prefix) or a
signal number. If a SIGSPEC is `0' or `EXIT', ARG is executed
when the shell exits. If a SIGSPEC is `DEBUG', the command ARG is
executed after every simple command. If a SIGSPEC is `ERR', the
command ARG is executed whenever a simple command has a non-zero
exit status. The `ERR' trap is not executed if the failed command
is part of an `until' or `while' loop, part of an `if' statement,
part of a `&&' or `||' list, or if the command's return status is
being inverted using `!'. The `-l' option causes the shell to
print a list of signal names and their corresponding numbers.
Signals ignored upon entry to the shell cannot be trapped or reset.
Trapped signals are reset to their original values in a child
process when it is created.
The return status is 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 [-fv] [NAME]
Each variable or function NAME is removed. If no options are
supplied, or the `-v' option is given, each NAME refers to a shell
variable. If the `-f' option is given, the NAMEs refer to shell
functions, and the function definition is removed. Readonly
variables and functions may not be unset. The return status is
zero unless a NAME does not exist or is readonly.