Bash/Bourne-Shell-Builtins
Next: Bash Builtins, Up: Shell Builtin Commands [Contents][Index]
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. Iffilename
does not contain a slash, thePATH
variable is used to findfilename
. When Bash is not in POSIX mode, the current directory is searched iffilename
is not found in$PATH
. If anyarguments
are supplied, they become the positional parameters whenfilename
is executed. Otherwise the positional parameters are unchanged. If the-T
option is enabled,source
inherits any trap onDEBUG
; if it is not, anyDEBUG
trap string is saved and restored around the call tosource
, andsource
unsets theDEBUG
trap while it executes. If-T
is not set, and the sourced file changes theDEBUG
trap, the new value is retained whensource
completes. The return status is the exit status of the last command executed, or zero if no commands are executed. Iffilename
is not found, or cannot be read, the return status is non-zero. This builtin is equivalent tosource
.break
break [n]
Exit from a
for
,while
,until
, orselect
loop. Ifn
is supplied, then
th enclosing loop is exited.n
must be greater than or equal to 1. The return status is zero unlessn
is not greater than or equal to 1.cd
cd [-L|[-P [-e]] [-@] [directory]
Change the current working directory to
directory
. Ifdirectory
is not supplied, the value of theHOME
shell variable is used. Any additional arguments followingdirectory
are ignored. If the shell variableCDPATH
exists, it is used as a search path: each directory name inCDPATH
is searched fordirectory
, with alternative directory names inCDPATH
separated by a colon (‘:
’). Ifdirectory
begins with a slash,CDPATH
is not used.The
-P
option means to not follow symbolic links: symbolic links are resolved whilecd
is traversingdirectory
and before processing an instance of ‘..
’ indirectory
.By default, or when the
-L
option is supplied, symbolic links indirectory
are resolved aftercd
processes an instance of ‘..
’ indirectory
.If ‘
..
’ appears indirectory
, it is processed by removing the immediately preceding pathname component, back to a slash or the beginning ofdirectory
.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
, orselect
loop. Ifn
is supplied, the execution of then
th enclosing loop is resumed.n
must be greater than or equal to 1. The return status is zero unlessn
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 tocommand
. This is what thelogin
program does. The-c
option causescommand
to be executed with an empty environment. If-a
is supplied, the shell passesname
as the zeroth argument tocommand
. Ifcommand
cannot be executed for some reason, a non-interactive shell exits, unless theexecfail
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 ifexec
fails. If nocommand
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. Ifn
is omitted, the exit status is that of the last command executed. Any trap onEXIT
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, thename
s refer to shell functions; otherwise the names refer to shell variables. The-n
option means to no longer mark eachname
for export. If nonames
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 tovalue
.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 variablename
, initializingname
if it does not exist, and the index of the next argument to be processed into the variableOPTIND
.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 variableOPTARG
. The shell does not resetOPTIND
automatically; it must be manually reset between multiple calls togetopts
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, andname
is set to ‘?
’.getopts
normally parses the positional parameters, but if more arguments are given inargs
,getopts
parses those instead.getopts
can report errors in two ways. If the first character ofoptstring
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 variableOPTERR
is set to 0, no error messages will be displayed, even if the first character ofoptstring
is not a colon.If an invalid option is seen,
getopts
places ‘?
’ intoname
and, if not silent, prints an error message and unsetsOPTARG
. Ifgetopts
is silent, the option character found is placed inOPTARG
and no diagnostic message is printed.If a required argument is not found, and
getopts
is not silent, a question mark (‘?
’) is placed inname
,OPTARG
is unset, and a diagnostic message is printed. Ifgetopts
is silent, then a colon (‘:
’) is placed inname
andOPTARG
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 asname
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, andfilename
is used as the location ofname
. The-r
option causes the shell to forget all remembered locations. The-d
option causes the shell to forget the remembered location of eachname
. If the-t
option is supplied, the full pathname to which eachname
corresponds is printed. If multiplename
arguments are supplied with-t
, thename
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 aname
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, eachname
refers to a shell function. The-a
option means eachname
refers to an indexed array variable; the-A
option means eachname
refers to an associative array variable. If both options are supplied,-A
takes precedence. If noname
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 tovalue
. The return status is zero unless an invalid option is supplied, one of thename
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. Ifn
is not supplied, the return value is the exit status of the last command executed in the function. Ifreturn
is executed by a trap handler, the last command used to determine the status is the last command executed before the trap handler. Ifreturn
is executed during aDEBUG
trap, the last command used to determine the status is the last command executed by the trap handler beforereturn
was invoked.return
may also be used to terminate execution of a script being executed with the.
(source
) builtin, returning eithern
or the exit status of the last command executed within the script as the exit status of the script. Ifn
is supplied, the return value is its least significant 8 bits. Any command associated with theRETURN
trap is executed before execution resumes after the function or script. The return status is non-zero ifreturn
is supplied a non-numeric argument or is used outside a function and not during the execution of a script by.
orsource
.shift
shift [n]
Shift the positional parameters to the left by
n
. The positional parameters fromn
+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$#
. Ifn
is zero or greater than$#
, the positional parameters are not changed. Ifn
is not supplied, it is assumed to be 1. The return status is zero unlessn
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
andexpr2
are true.expr1 -o expr2
True if either
expr1
orexpr2
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 (see 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 (see 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.
- If the second argument is one of the binary conditional
operators (see Bash Conditional Expressions), the
result of the expression is the result of the binary test using the
first and third arguments as operands.
The ‘
- 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 signalsigspec
. Ifarg
is absent (and there is a singlesigspec
) or equal to ‘-
’, each specified signal’s disposition is reset to the value it had when the shell was started. Ifarg
is the null string, then the signal specified by eachsigspec
is ignored by the shell and commands it invokes. Ifarg
is not present and-p
has been supplied, the shell displays the trap commands associated with eachsigspec
. 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. Eachsigspec
is either a signal name or a signal number. Signal names are case insensitive and theSIG
prefix is optional.If a
sigspec
is0
orEXIT
,arg
is executed when the shell exits. If asigspec
isDEBUG
, the commandarg
is executed before every simple command,for
command,case
command,select
command, every arithmeticfor
command, and before the first command executes in a shell function. Refer to the description of theextdebug
option to theshopt
builtin (see The Shopt Builtin) for details of its effect on theDEBUG
trap. If asigspec
isRETURN
, the commandarg
is executed each time a shell function or a script executed with the.
orsource
builtins finishes executing.If a
sigspec
isERR
, the commandarg
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. TheERR
trap is not executed if the failed command is part of the command list immediately following anuntil
orwhile
keyword, part of the test following theif
orelif
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 theerrexit
(-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
. Ifmode
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 thechmod
command. Ifmode
is omitted, the current value of the mask is printed. If the-S
option is supplied without amode
argument, the mask is printed in a symbolic format. If the-p
option is supplied, andmode
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 nomode
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 of022
results in permissions of755
.unset
unset [-fnv] [name]
Remove each variable or function
name
. If the-v
option is given, eachname
refers to a shell variable and that variable is removed. If the-f
option is given, thename
s refer to shell functions, and the function definition is removed. If the-n
option is supplied, andname
is a variable with thenameref
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, eachname
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 aname
is readonly.
Next: Bash Builtins, Up: Shell Builtin Commands [Contents][Index]