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