GNU Info
(bashref.info)Bash Builtins
Bash Builtin Commands
=====================
This section describes builtin commands which are unique to or have
been extended in Bash. Some of these commands are specified in the
POSIX 1003.2 standard.
`alias'
alias [`-p'] [NAME[=VALUE] ...]
Without arguments or with the `-p' option, `alias' prints the list
of aliases on the standard output in a form that allows them to be
reused as input. If arguments are supplied, an alias is defined
for each NAME whose VALUE is given. If no VALUE is given, the name
and value of the alias is printed. Aliases are described in Note:
Aliases.
`bind'
bind [-m KEYMAP] [-lpsvPSV]
bind [-m KEYMAP] [-q FUNCTION] [-u FUNCTION] [-r KEYSEQ]
bind [-m KEYMAP] -f FILENAME
bind [-m KEYMAP] -x KEYSEQ:SHELL-COMMAND
bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME
Display current Readline (Note: Command Line Editing) key and
function bindings, or bind a key sequence to a Readline function
or macro. The binding syntax accepted is identical to that of a
Readline initialization file (Note: Readline Init File), but
each binding must be passed as a separate argument: e.g.,
`"\C-x\C-r":re-read-init-file'. Options, if supplied, have the
following meanings:
`-m KEYMAP'
Use KEYMAP as the keymap to be affected by the subsequent
bindings. Acceptable KEYMAP names are `emacs',
`emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
`vi-command', and `vi-insert'. `vi' is equivalent to
`vi-command'; `emacs' is equivalent to `emacs-standard'.
`-l'
List the names of all Readline functions.
`-p'
Display Readline function names and bindings in such a way
that they can be used as input or in a Readline
initialization file.
`-P'
List current Readline function names and bindings.
`-v'
Display Readline variable names and values in such a way that
they can be used as input or in a Readline initialization
file.
`-V'
List current Readline variable names and values.
`-s'
Display Readline key sequences bound to macros and the
strings they output in such a way that they can be used as
input or in a Readline initialization file.
`-S'
Display Readline key sequences bound to macros and the
strings they output.
`-f FILENAME'
Read key bindings from FILENAME.
`-q FUNCTION'
Query about which keys invoke the named FUNCTION.
`-u FUNCTION'
Unbind all keys bound to the named FUNCTION.
`-r KEYSEQ'
Remove any current binding for KEYSEQ.
`-x KEYSEQ:SHELL-COMMAND'
Cause SHELL-COMMAND to be executed whenever KEYSEQ is entered.
The return status is zero unless an invalid option is supplied or
an error occurs.
`builtin'
builtin [SHELL-BUILTIN [ARGS]]
Run a shell builtin, passing it ARGS, and return its exit status.
This is useful when defining a shell function with the same name
as a shell builtin, retaining the functionality of the builtin
within the function. The return status is non-zero if
SHELL-BUILTIN is not a shell builtin command.
`command'
command [-pVv] COMMAND [ARGUMENTS ...]
Runs COMMAND with ARGUMENTS ignoring any shell function named
COMMAND. Only shell builtin commands or commands found by
searching the `PATH' are executed. If there is a shell function
named `ls', running `command ls' within the function will execute
the external command `ls' instead of calling the function
recursively. The `-p' option means to use a default value for
`PATH' that is guaranteed to find all of the standard utilities.
The return status in this case is 127 if COMMAND cannot be found
or an error occurred, and the exit status of COMMAND otherwise.
If either the `-V' or `-v' option is supplied, a description of
COMMAND is printed. The `-v' option causes a single word
indicating the command or file name used to invoke COMMAND to be
displayed; the `-V' option produces a more verbose description.
In this case, the return status is zero if COMMAND is found, and
non-zero if not.
`declare'
declare [-afFrxi] [-p] [NAME[=VALUE]]
Declare variables and give them attributes. If no NAMEs are
given, then display the values of variables instead.
The `-p' option will display the attributes and values of each
NAME. When `-p' is used, additional options are ignored. The
`-F' option inhibits the display of function definitions; only the
function name and attributes are printed. `-F' implies `-f'. The
following options can be used to restrict output to variables with
the specified attributes or to give variables attributes:
`-a'
Each NAME is an array variable (Note: Arrays).
`-f'
Use function names only.
`-i'
The variable is to be treated as an integer; arithmetic
evaluation (Note: Shell Arithmetic) is performed when the
variable is assigned a value.
`-r'
Make NAMEs readonly. These names cannot then be assigned
values by subsequent assignment statements or unset.
`-x'
Mark each NAME for export to subsequent commands via the
environment.
Using `+' instead of `-' turns off the attribute instead. When
used in a function, `declare' makes each NAME local, as with the
`local' command.
The return status is zero unless an invalid option is encountered,
an attempt is made to define a function using `-f foo=bar', an
attempt is made to assign a value to a readonly variable, an
attempt is made to assign a value to an array variable without
using the compound assignment syntax (Note: Arrays), one of the
NAMES is not a valid shell variable name, an attempt is made to
turn off readonly status for a readonly variable, an attempt is
made to turn off array status for an array variable, or an attempt
is made to display a non-existent function with `-f'.
`echo'
echo [-neE] [ARG ...]
Output the ARGs, separated by spaces, terminated with a newline.
The return status is always 0. If `-n' is specified, the trailing
newline is suppressed. If the `-e' option is given,
interpretation of the following backslash-escaped characters is
enabled. The `-E' option disables the interpretation of these
escape characters, even on systems where they are interpreted by
default. The `xpg_echo' shell option may be used to dynamically
determine whether or not `echo' expands these escape characters by
default. `echo' interprets the following escape sequences:
`\a'
alert (bell)
`\b'
backspace
`\c'
suppress trailing newline
`\e'
escape
`\f'
form feed
`\n'
new line
`\r'
carriage return
`\t'
horizontal tab
`\v'
vertical tab
`\\'
backslash
`\NNN'
the eight-bit character whose value is the octal value NNN
(one to three digits)
`\xHH'
the eight-bit character whose value is the hexadecimal value
HH (one or two hex digits)
`enable'
enable [-n] [-p] [-f FILENAME] [-ads] [NAME ...]
Enable and disable builtin shell commands. Disabling a builtin
allows a disk command which has the same name as a shell builtin
to be executed without specifying a full pathname, even though the
shell normally searches for builtins before disk commands. If
`-n' is used, the NAMEs become disabled. Otherwise NAMEs are
enabled. For example, to use the `test' binary found via `$PATH'
instead of the shell builtin version, type `enable -n test'.
If the `-p' option is supplied, or no NAME arguments appear, a
list of shell builtins is printed. With no other arguments, the
list consists of all enabled shell builtins. The `-a' option
means to list each builtin with an indication of whether or not it
is enabled.
The `-f' option means to load the new builtin command NAME from
shared object FILENAME, on systems that support dynamic loading.
The `-d' option will delete a builtin loaded with `-f'.
If there are no options, a list of the shell builtins is displayed.
The `-s' option restricts `enable' to the POSIX special builtins.
If `-s' is used with `-f', the new builtin becomes a special
builtin (Note: Special Builtins).
The return status is zero unless a NAME is not a shell builtin or
there is an error loading a new builtin from a shared object.
`help'
help [-s] [PATTERN]
Display helpful information about builtin commands. If PATTERN is
specified, `help' gives detailed help on all commands matching
PATTERN, otherwise a list of the builtins is printed. The `-s'
option restricts the information displayed to a short usage
synopsis. The return status is zero unless no command matches
PATTERN.
`let'
let EXPRESSION [EXPRESSION]
The `let' builtin allows arithmetic to be performed on shell
variables. Each EXPRESSION is evaluated according to the rules
given below in Note: Shell Arithmetic. If the last EXPRESSION
evaluates to 0, `let' returns 1; otherwise 0 is returned.
`local'
local [OPTION] NAME[=VALUE]
For each argument, a local variable named NAME is created, and
assigned VALUE. The OPTION can be any of the options accepted by
`declare'. `local' can only be used within a function; it makes
the variable NAME have a visible scope restricted to that function
and its children. The return status is zero unless `local' is
used outside a function, an invalid NAME is supplied, or NAME is a
readonly variable.
`logout'
logout [N]
Exit a login shell, returning a status of N to the shell's parent.
`printf'
`printf' FORMAT [ARGUMENTS]
Write the formatted ARGUMENTS to the standard output under the
control of the FORMAT. The FORMAT is a character string which
contains three types of objects: plain characters, which are
simply copied to standard output, character escape sequences,
which are converted and copied to the standard output, and format
specifications, each of which causes printing of the next
successive ARGUMENT. In addition to the standard `printf(1)'
formats, `%b' causes `printf' to expand backslash escape sequences
in the corresponding ARGUMENT, and `%q' causes `printf' to output
the corresponding ARGUMENT in a format that can be reused as shell
input.
The FORMAT is reused as necessary to consume all of the ARGUMENTS.
If the FORMAT requires more ARGUMENTS than are supplied, the extra
format specifications behave as if a zero value or null string, as
appropriate, had been supplied. The return value is zero on
success, non-zero on failure.
`read'
read [-ers] [-a ANAME] [-p PROMPT] [-t TIMEOUT] [-n NCHARS] [-d DELIM] [NAME ...]
One line is read from the standard input, and the first word is
assigned to the first NAME, the second word to the second NAME,
and so on, with leftover words and their intervening separators
assigned to the last NAME. If there are fewer words read from the
standard input than names, the remaining names are assigned empty
values. The characters in the value of the `IFS' variable are
used to split the line into words. The backslash character `\'
may be used to remove any special meaning for the next character
read and for line continuation. If no names are supplied, the
line read is assigned to the variable `REPLY'. The return code is
zero, unless end-of-file is encountered or `read' times out.
Options, if supplied, have the following meanings:
`-a ANAME'
The words are assigned to sequential indices of the array
variable ANAME, starting at 0. All elements are removed from
ANAME before the assignment. Other NAME arguments are
ignored.
`-d DELIM'
The first character of DELIM is used to terminate the input
line, rather than newline.
`-e'
Readline (Note: Command Line Editing) is used to obtain the
line.
`-n NCHARS'
`read' returns after reading NCHARS characters rather than
waiting for a complete line of input.
`-p PROMPT'
Display PROMPT, without a trailing newline, before attempting
to read any input. The prompt is displayed only if input is
coming from a terminal.
`-r'
If this option is given, backslash does not act as an escape
character. The backslash is considered to be part of the
line. In particular, a backslash-newline pair may not be
used as a line continuation.
`-s'
Silent mode. If input is coming from a terminal, characters
are not echoed.
`-t TIMEOUT'
Cause `read' to time out and return failure if a complete
line of input is not read within TIMEOUT seconds. This
option has no effect if `read' is not reading input from the
terminal or a pipe.
`shopt'
shopt [-pqsu] [-o] [OPTNAME ...]
Toggle the values of variables controlling optional shell behavior.
With no options, or with the `-p' option, a list of all settable
options is displayed, with an indication of whether or not each is
set. The `-p' option causes output to be displayed in a form that
may be reused as input. Other options have the following meanings:
`-s'
Enable (set) each OPTNAME.
`-u'
Disable (unset) each OPTNAME.
`-q'
Suppresses normal output; the return status indicates whether
the OPTNAME is set or unset. If multiple OPTNAME arguments
are given with `-q', the return status is zero if all
OPTNAMES are enabled; non-zero otherwise.
`-o'
Restricts the values of OPTNAME to be those defined for the
`-o' option to the `set' builtin (Note: The Set Builtin).
If either `-s' or `-u' is used with no OPTNAME arguments, the
display is limited to those options which are set or unset,
respectively.
Unless otherwise noted, the `shopt' options are disabled (off) by
default.
The return status when listing options is zero if all OPTNAMES are
enabled, non-zero otherwise. When setting or unsetting options,
the return status is zero unless an OPTNAME is not a valid shell
option.
The list of `shopt' options is:
`cdable_vars'
If this is set, an argument to the `cd' builtin command that
is not a directory is assumed to be the name of a variable
whose value is the directory to change to.
`cdspell'
If set, minor errors in the spelling of a directory component
in a `cd' command will be corrected. The errors checked for
are transposed characters, a missing character, and a
character too many. If a correction is found, the corrected
path is printed, and the command proceeds. This option is
only used by interactive shells.
`checkhash'
If this is set, Bash checks that a command found in the hash
table exists before trying to execute it. If a hashed
command no longer exists, a normal path search is performed.
`checkwinsize'
If set, Bash checks the window size after each command and,
if necessary, updates the values of `LINES' and `COLUMNS'.
`cmdhist'
If set, Bash attempts to save all lines of a multiple-line
command in the same history entry. This allows easy
re-editing of multi-line commands.
`dotglob'
If set, Bash includes filenames beginning with a `.' in the
results of filename expansion.
`execfail'
If this is set, a non-interactive shell will not exit if it
cannot execute the file specified as an argument to the `exec'
builtin command. An interactive shell does not exit if `exec'
fails.
`expand_aliases'
If set, aliases are expanded as described below under Aliases,
Note: Aliases. This option is enabled by default for
interactive shells.
`extglob'
If set, the extended pattern matching features described above
(Note: Pattern Matching) are enabled.
`histappend'
If set, the history list is appended to the file named by the
value of the `HISTFILE' variable when the shell exits, rather
than overwriting the file.
`histreedit'
If set, and Readline is being used, a user is given the
opportunity to re-edit a failed history substitution.
`histverify'
If set, and Readline is being used, the results of history
substitution are not immediately passed to the shell parser.
Instead, the resulting line is loaded into the Readline
editing buffer, allowing further modification.
`hostcomplete'
If set, and Readline is being used, Bash will attempt to
perform hostname completion when a word containing a `@' is
being completed (Note: Commands For Completion). This
option is enabled by default.
`huponexit'
If set, Bash will send `SIGHUP' to all jobs when an
interactive login shell exits (Note: Signals).
`interactive_comments'
Allow a word beginning with `#' to cause that word and all
remaining characters on that line to be ignored in an
interactive shell. This option is enabled by default.
`lithist'
If enabled, and the `cmdhist' option is enabled, multi-line
commands are saved to the history with embedded newlines
rather than using semicolon separators where possible.
`login_shell'
The shell sets this option if it is started as a login shell
(Note: Invoking Bash). The value may not be changed.
`mailwarn'
If set, and a file that Bash is checking for mail has been
accessed since the last time it was checked, the message
`"The mail in MAILFILE has been read"' is displayed.
`no_empty_cmd_completion'
If set, and Readline is being used, Bash will not attempt to
search the `PATH' for possible completions when completion is
attempted on an empty line.
`nocaseglob'
If set, Bash matches filenames in a case-insensitive fashion
when performing filename expansion.
`nullglob'
If set, Bash allows filename patterns which match no files to
expand to a null string, rather than themselves.
`progcomp'
If set, the programmable completion facilities (Note:
Programmable Completion) are enabled. This option is
enabled by default.
`promptvars'
If set, prompt strings undergo variable and parameter
expansion after being expanded (Note: Printing a Prompt).
This option is enabled by default.
`restricted_shell'
The shell sets this option if it is started in restricted mode
(Note: The Restricted Shell). The value may not be changed.
This is not reset when the startup files are executed,
allowing the startup files to discover whether or not a shell
is restricted.
`shift_verbose'
If this is set, the `shift' builtin prints an error message
when the shift count exceeds the number of positional
parameters.
`sourcepath'
If set, the `source' builtin uses the value of `PATH' to find
the directory containing the file supplied as an argument.
This option is enabled by default.
`xpg_echo'
If set, the `echo' builtin expands backslash-escape sequences
by default.
The return status when listing options is zero if all OPTNAMES are
enabled, non-zero otherwise. When setting or unsetting options,
the return status is zero unless an OPTNAME is not a valid shell
option.
`source'
source FILENAME
A synonym for `.' (Note: Bourne Shell Builtins).
`type'
type [-atp] [NAME ...]
For each NAME, indicate how it would be interpreted if used as a
command name.
If the `-t' option is used, `type' prints a single word which is
one of `alias', `function', `builtin', `file' or `keyword', if
NAME is an alias, shell function, shell builtin, disk file, or
shell reserved word, respectively. If the NAME is not found, then
nothing is printed, and `type' returns a failure status.
If the `-p' option is used, `type' either returns the name of the
disk file that would be executed, or nothing if `-t' would not
return `file'.
If the `-a' option is used, `type' returns all of the places that
contain an executable named FILE. This includes aliases and
functions, if and only if the `-p' option is not also used.
The return status is zero if any of the NAMES are found, non-zero
if none are found.
`typeset'
typeset [-afFrxi] [-p] [NAME[=VALUE]]
The `typeset' command is supplied for compatibility with the Korn
shell; however, it has been deprecated in favor of the `declare'
builtin command.
`ulimit'
ulimit [-acdflmnpstuvSH] [LIMIT]
`ulimit' provides control over the resources available to processes
started by the shell, on systems that allow such control. If an
option is given, it is interpreted as follows:
`-S'
Change and report the soft limit associated with a resource.
`-H'
Change and report the hard limit associated with a resource.
`-a'
All current limits are reported.
`-c'
The maximum size of core files created.
`-d'
The maximum size of a process's data segment.
`-f'
The maximum size of files created by the shell.
`-l'
The maximum size that may be locked into memory.
`-m'
The maximum resident set size.
`-n'
The maximum number of open file descriptors.
`-p'
The pipe buffer size.
`-s'
The maximum stack size.
`-t'
The maximum amount of cpu time in seconds.
`-u'
The maximum number of processes available to a single user.
`-v'
The maximum amount of virtual memory available to the process.
If LIMIT is given, it is the new value of the specified resource;
the special LIMIT values `hard', `soft', and `unlimited' stand for
the current hard limit, the current soft limit, and no limit,
respectively. Otherwise, the current value of the soft limit for
the specified resource is printed, unless the `-H' option is
supplied. When setting new limits, if neither `-H' nor `-S' is
supplied, both the hard and soft limits are set. If no option is
given, then `-f' is assumed. Values are in 1024-byte increments,
except for `-t', which is in seconds, `-p', which is in units of
512-byte blocks, and `-n' and `-u', which are unscaled values.
The return status is zero unless an invalid option or argument is
supplied, or an error occurs while setting a new limit.
`unalias'
unalias [-a] [NAME ... ]
Remove each NAME from the list of aliases. If `-a' is supplied,
all aliases are removed. Aliases are described in Note: Aliases.
automatically generated by info2www version 1.2.2.9