|GNU Bash Reference Manual|
by Chet Ramey and Brian Fox
Paperback (6"x9"), 180 pages
RRP £19.95 ($29.95)
"An essential resource .... the most detailed coverage available for all aspects of Bash" --- Linux User and Developer Magazine (Issue 37, Mar 2004) Get a printed copy>>>
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
PATHvariable 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
break [n]Exit from a
selectloop. 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 [-L|-P] [directory]Change the current working directory to directory. If directory is not given, the value of the
HOMEshell variable is used. If the shell variable
CDPATHexists, it is used as a search path. If directory begins with a slash,
CDPATHis not used. The
-Poption means to not follow symbolic links; symbolic links are followed by default or with the
-Loption. If directory is ‘-’, it is equivalent to
$OLDPWD. If a non-empty directory name from
CDPATHis 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 [n]Resume the next iteration of an enclosing
selectloop. 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 [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 [-cl] [-a name] [command [arguments]]If command is supplied, it replaces the shell without creating a new process. If the
-loption is supplied, the shell places a dash at the beginning of the zeroth argument passed to command. This is what the
loginprogram does. The
-coption causes command to be executed with an empty environment. If
-ais 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 [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
EXITis executed before the shell terminates.
export [-fn] [-p] [name[=value]]Mark each name to be passed to child processes in the environment. If the
-foption is supplied, the names refer to shell functions; otherwise the names refer to shell variables. The
-noption means to no longer mark each name for export. If no names are supplied, or if the
-poption is given, a list of exported names is displayed. The
-poption 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
-fis supplied with a name that is not a shell function.
getopts optstring name [args]
getoptsis 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,
getoptsplaces 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
OPTINDis initialized to 1 each time the shell or a shell script is invoked. When an option requires an argument,
getoptsplaces that argument into the variable
OPTARG. The shell does not reset
OPTINDautomatically; it must be manually reset between multiple calls to
getoptswithin the same shell invocation if a new set of parameters is to be used. When the end of options is encountered,
getoptsexits with a return value greater than zero.
OPTINDis set to the index of the first non-option argument, and
nameis set to ‘?’.
getoptsnormally parses the positional parameters, but if more arguments are given in args,
getoptsparses those instead.
getoptscan 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
OPTERRis set to 0, no error messages will be displayed, even if the first character of
optstringis not a colon. If an invalid option is seen,
getoptsplaces ‘?’ into name and, if not silent, prints an error message and unsets
getoptsis silent, the option character found is placed in
OPTARGand no diagnostic message is printed. If a required argument is not found, and
getoptsis not silent, a question mark (‘?’) is placed in name,
OPTARGis unset, and a diagnostic message is printed. If
getoptsis silent, then a colon (‘:’) is placed in name and
OPTARGis set to the option character found.
hash [-r] [-p filename] [-dt] [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
-poption inhibits the path search, and filename is used as the location of name. The
-roption causes the shell to forget all remembered locations. The
-doption causes the shell to forget the remembered location of each name. If the
-toption is supplied, the full pathname to which each name corresponds is printed. If multiple name arguments are supplied with
-tthe name is printed before the hashed full pathname. The
-loption causes output to be displayed in a format that may be reused as input. If no arguments are given, or if only
-lis 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 [-LP]Print the absolute pathname of the current working directory. If the
-Poption is supplied, the pathname printed will not contain symbolic links. If the
-Loption 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 [-apf] [name[=value]] ...Mark each name as readonly. The values of these names may not be changed by subsequent assignment. If the
-foption is supplied, each name refers to a shell function. The
-aoption means each name refers to an array variable. If no name arguments are given, or if the
-poption is supplied, a list of all readonly names is printed. The
-poption 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
-foption is supplied with a name that is not a shell function.
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
source) builtin, returning either n or the exit status of the last command executed within the script as the exit status of the script. Any command associated with the
RETURNtrap is executed before execution resumes after the function or script. The return status is non-zero if
returnis used outside a function and not during the execution of a script by
shift [n]Shift the positional parameters to the left by n. The positional parameters from n+1 ...
$#are renamed to
$#-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.
Evaluate a conditional expression expr.
Each operator and operand must be a separate argument.
Expressions are composed of the primaries described below in
section 6.4 Bash Conditional Expressions.
testdoes 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.
- 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.
[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 (see section 6.4 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 (see section 6.4 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.
timesPrint out the user and system times used by the shell and its children. The return status is zero.
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
-phas been supplied, the shell displays the trap commands associated with each sigspec. If no arguments are supplied, or only
trapprints the list of commands associated with each signal number in a form that may be reused as shell input. The
-loption 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
SIGprefix is optional. If a sigspec is
EXIT, arg is executed when the shell exits. If a sigspec is
DEBUG, the command arg is executed before every simple command,
selectcommand, every arithmetic
forcommand, and before the first command executes in a shell function. Refer to the description of the
extgloboption to the
shoptbuiltin (see section 4.2 Bash Builtin Commands) for details of its effect on the
DEBUGtrap. If a sigspec is
ERR, the command arg is executed whenever a simple command has a non-zero exit status, subject to the following conditions. The
ERRtrap is not executed if the failed command is part of the command list immediately following an
whilekeyword, part of the test in an
ifstatement, part of a
||list, or if the command's return status is being inverted using
!. These are the same conditions obeyed by the
errexitoption. If a sigspec is
RETURN, the command arg is executed each time a shell function or a script executed with the
sourcebuiltins finishes executing. 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 child process when it is created. The return status is zero unless a sigspec does not specify a valid signal.
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
chmodcommand. If mode is omitted, the current value of the mask is printed. If the
-Soption is supplied without a mode argument, the mask is printed in a symbolic format. If the
-poption 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
022results in permissions of
unset [-fv] [name]Each variable or function name is removed. If no options are supplied, or the
-voption is given, each name refers to a shell variable. If the
-foption 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 is readonly.
|ISBN 0954161777||GNU Bash Reference Manual||See the print edition|