This section describes features unique to Bash.
bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o option] [argument ...] bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o option] -c string [argument ...] bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o option] [argument ...]
In addition to the single-character shell command-line options (see section The Set Builtin), there are several multi-character options that you can use. These options must appear on the command line before the single-character options in order for them to be recognized.
--dump-strings
--help
--login
csh
. If you wanted to replace your
current login shell with a Bash login shell, you would say
`exec bash --login'.
--noediting
--noprofile
--norc
sh
.
--posix
--rcfile filename
--restricted
--verbose
--version
There are several single-character options you can give which are
not available with the set
builtin.
-c string
$0
.
-i
-r
-s
-D
C
or POSIX
(see section Locale-Specific Translation).
This implies the `-n' option; no commands will be executed.
An interactive shell is one whose input and output are both
connected to terminals (as determined by isatty()
), or one
started with the `-i' option.
If arguments remain after option processing, and neither the
`-c' nor the `-s'
option has been supplied, the first argument is assumed to
be the name of a file containing shell commands (see section Shell Scripts).
When Bash is invoked in this fashion, $0
is set to the name of the file, and the positional parameters
are set to the remaining arguments.
Bash reads and executes commands from this file, then exits.
Bash's exit status is the exit status of the last command executed
in the script. If no commands are executed, the exit status is 0.
This section describs how Bash executes its startup files. If any of the files exist but cannot be read, Bash reports an error. Tildes are expanded in file names as described above under Tilde Expansion (see section Tilde Expansion).
When Bash is invoked as an interactive login shell, it first reads and executes commands from the file `/etc/profile', if that file exists. After reading that file, it looks for `~/.bash_profile', `~/.bash_login', and `~/.profile', in that order, and reads and executes commands from the first one that exists and is readable. The `--noprofile' option may be used when the shell is started to inhibit this behavior.
When a login shell exits, Bash reads and executes commands from the file `~/.bash_logout', if it exists.
When an interactive shell that is not a login shell is started, Bash reads and executes commands from `~/.bashrc', if that file exists. This may be inhibited by using the `--norc' option. The `--rcfile file' option will force Bash to read and execute commands from file instead of `~/.bashrc'.
So, typically, your `~/.bash_profile' contains the line
if [ -f `~/.bashrc' ]; then . `~/.bashrc'; fi
after (or before) any login-specific initializations.
When Bash is started non-interactively, to run a shell script,
for example, it looks for the variable BASH_ENV
in the environment,
expands its value if it appears there, and uses the expanded value as
the name of a file to read and execute. Bash behaves as if the
following command were executed:
if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
but the value of the PATH
variable is not used to search for the
file name.
If Bash is invoked with the name sh
, it tries to mimic the
startup behavior of historical versions of sh
as closely as
possible, while conforming to the POSIX standard as well.
When invoked as a login shell, it first attempts to read and execute
commands from `/etc/profile' and `~/.profile', in that order.
The `--noprofile' option may be used to inhibit this behavior.
When invoked as an interactive shell with the name sh
,
bash
looks for the variable ENV
,
expands its value if it is defined, and uses the
expanded value as the name of a file to read and execute.
Since a shell invoked as sh
does not attempt to read and execute
commands from any other startup files, the `--rcfile' option has
no effect.
A non-interactive shell invoked with the name sh
does not attempt
to read any startup files.
When invoked as sh
, Bash enters POSIX mode after
the startup files are read.
When Bash is started in POSIX mode, as with the
`--posix' command line option, it follows the POSIX standard
for startup files.
In this mode, the ENV
variable is expanded and commands are read
and executed from the file whose name is the expanded value.
No other startup files are read.
This is done by interactive shells only.
Bash attempts to determine when it is being run by the remote shell
daemon, usually rshd
. If Bash determines it is being run by
rshd, it reads and executes commands from `~/.bashrc', if that
file exists and is readable.
It will not do this if invoked as sh
.
The `--norc' option may be used to inhibit this behavior, and the
`--rcfile' option may be used to force another file to be read, but
rshd does not generally invoke the shell with those options or allow
them to be specified.
As defined in section Invoking Bash, an interactive shell
is one whose input and output are both
connected to terminals (as determined by isatty(3)
),
or one started with the `-i' option.
You may wish to determine within a startup script whether Bash is
running interactively or not. To do this, examine the variable
$PS1
; it is unset in non-interactive shells, and set in
interactive shells. Thus:
if [ -z "$PS1" ]; then echo This shell is not interactive else echo This shell is interactive fi
Alternatively, you may test the value of the `-' special parameter.
It contains i
when the shell is interactive. For example:
case "$-" in *i*) echo This shell is interactive ;; *) echo This shell is not interactive ;; esac
This section describes builtin commands which are unique to or have been extended in Bash.
bind
bind [-m keymap] [-lpsvPSV] [-q name] [-r keyseq] bind [-m keymap] -f filename bind [-m keymap] keyseq:function-nameDisplay current Readline (see section 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 `.inputrc' (@xref{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
emacs
,
emacs-standard
,
emacs-meta
,
emacs-ctlx
,
vi
,
vi-command
, and
vi-insert
.
vi
is equivalent to vi-command
;
emacs
is equivalent to emacs-standard
.
-l
-p
-P
-v
-V
-s
-S
-f filename
-q
-r keyseq
builtin
builtin [shell-builtin [args]]Run a shell builtin. This is useful when you wish to define a shell function with the same name as a shell builtin, but need the functionality of the builtin within the function itself.
command
command [-pVv] command [args ...]Runs command with arg ignoring shell functions. If you have a shell function called
ls
, and you wish to call
the command ls
, you can say `command ls'. The
`-p' option means to use a default value for $PATH
that is guaranteed to find all of the standard utilities.
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 printed; the `-V' option produces
a more verbose description.
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
-f
-i
-r
-x
declare
makes each name local, as with the
local
command.
echo
echo [-neE] [arg ...]Output the
arg
s, 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.
echo
interprets the following escape sequences:
\a
\b
\c
\e
\f
\n
\r
\t
\v
\\
\nnn
nnn
(octal)
enable
enable [-n] [-p] [-f filename] [-ads] [name ...]Enable and disable builtin shell commands. This allows you to use a disk command which has the same name as a shell builtin. 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.2 special
builtins. If `-s' is used with `-f', the new builtin becomes
a special builtin.
help
help [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.
local
local name[=value]For each argument, create a local variable called name, and give it value.
local
can only be used within a function; it makes the variable
name have a visible scope restricted to that function and its
children.
logout
logout [n]Exit a login shell, returning a status of n to the shell's parent.
read
read [-a aname] [-p prompt] [-er] [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 assigned to the last name. Only the characters in the value of the
IFS
variable
are recognized as word delimiters. 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. Options,
if supplied, have the following meanings:
-r
-p prompt
prompt
, without a
trailing newline, before attempting to read any input. The prompt
is displayed only if input is coming from a terminal.
-a aname
-e
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. Other options have the following meanings:
-s
-u
-q
-o
set
builtin (see section The Set Builtin).
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 legal shell
option.
The list of shopt
options is:
cdable_vars
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
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
checkwinsize
LINES
and COLUMNS
.
cmdhist
dotglob
execfail
exec
builtin command. An interactive shell does not exit if exec
fails.
histappend
HISTFILE
variable when the shell exits, rather than overwriting the file.
histreedit
histverify
hostcomplete
interactive_comments
lithist
cmdhist
option is enabled, multi-line commands are saved to the history with
embedded newlines rather than using semicolon separators where possible.
mailwarn
"The mail in mailfile has been read"
is displayed.
nullglob
promptvars
shift_verbose
shift
builtin prints an error message when the shift count exceeds the
number of positional parameters.
sourcepath
source
builtin uses the value of PATH
to find the directory containing the file supplied as an argument.
This is enabled by default.
type
type [-all] [-type | -path] [name ...]For each name, indicate how it would be interpreted if used as a command name. If the `-type' flag is used,
type
returns 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 `-path' flag is used, type
either returns the name
of the disk file that would be executed, or nothing if `-type'
would not return `file'.
If the `-all' flag is used, returns all of the places that contain
an executable named file. This includes aliases and functions,
if and only if the `-path' flag is not also used.
type
accepts `-a', `-t', and `-p' as equivalent to
`-all', `-type', and `-path', respectively.
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
-H
-a
-c
-d
-f
-l
-m
-n
-p
-s
-t
-u
-v
This builtin is so overloaded that it deserves its own section.
set
set [-abefhkmnptuvxdBCHP] [-o option] [argument ...]
-a
-b
-e
-f
-h
-k
-m
-n
-o option-name
allexport
-a
.
braceexpand
-B
.
emacs
emacs
-style line editing interface (see section Command Line Editing).
errexit
-e
.
hashall
-h
.
histexpand
-H
.
history
ignoreeof
keyword
-k
.
monitor
-m
.
noclobber
-C
.
noexec
-n
.
noglob
-f
.
notify
-b
.
nounset
-u
.
onecmd
-t
.
physical
-P
.
posix
privileged
-p
.
verbose
-v
.
vi
vi
-style line editing interface.
xtrace
-x
.
-p
$BASH_ENV
file is not processed, and shell functions
are not inherited from the environment. This is enabled automatically
on startup if the effective user (group) id is not equal to the real
user (group) id. Turning this option off causes the effective user
and group ids to be set to the real user and group ids.
-t
-u
-v
-x
-B
-C
-H
-P
cd
which change the current directory. The physical directory
is used instead. By default, Bash follows
the logical chain of directories when performing commands
which change the current directory.
For example, if `/usr/sys' is a link to `/usr/local/sys' then:
$ cd /usr/sys; echo $PWD /usr/sys $ cd ..; pwd /usrIf
set -P
is on, then:
$ cd /usr/sys; echo $PWD /usr/local/sys $ cd ..; pwd /usr/local
--
-
$-
.
The remaining N arguments are positional parameters and are
assigned, in order, to $1
, $2
, ... $N
. If
no arguments are given, all shell variables are printed.
Conditional expressions are used by the test
and [
builtins.
Expressions may be unary or binary. Unary expressions are often used to examine the status of a file. There are string operators and numeric comparison operators as well. Each operator and operand must be a separate argument. If file is of the form `/dev/fd/N', then file descriptor N is checked. Expressions are composed of the following primaries:
-b file
-c file
-d file
-e file
-f file
-g file
-k file
-L file
-p file
-r file
-s file
-S file
-t fd
-u file
-w file
-x file
-O file
-G file
file1 -nt file2
file1 -ot file2
file1 -ef file2
-o optname
set
builtin (see section The Set Builtin).
-z string
-n string
string
string1 = string2
string1 != string2
string1 < string2
string1 > string2
! expr
expr1 -a expr2
expr1 -o expr2
arg1 OP arg2
OP
is one of
`-eq', `-ne', `-lt', `-le', `-gt', or `-ge'.
These arithmetic binary operators return true if arg1
is equal to, not equal to, less than, less than or equal to,
greater than, or greater than or equal to arg2,
respectively. Arg1 and arg2
may be positive or negative integers.
The Bash test
and [
builtins evaluate conditional
expressions using a set of rules based on the number of arguments.
These are the rules:
These variables are set or used by Bash, but other shells do not normally treat them specially.
BASH_ENV
TIMEFORMAT
time
reserved word should be displayed.
The `%' character introduces an
escape sequence that is expanded to a time value or other
information.
The escape sequences and their meanings are as
follows; the braces denote optional portions.
%%
%[p][l]R
%[p][l]U
%[p][l]S
%P
l
specifies a longer format, including minutes, of
the form MMmSS.FFs.
The value of p determines whether or not the fraction is included.
If this variable is not set, bash acts as if it had the value
$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'
.
If the value is null, no timing information is displayed.
A trailing newline is added when the format string is displayed.
HISTCONTROL
HISTIGNORE
HISTCONTROL
are applied. In addition to the normal shell pattern matching
characters, `&' matches the previous history line. `&'
may be escaped using a backslash. The backslash is removed
before attempting a match.
HISTIGNORE
subsumes the function of HISTCONTROL
. A
pattern of `&' is identical to ignoredups
, and a
pattern of `[ ]*' is identical to ignorespace
.
Combining these two patterns, separating them with a colon,
provides the functionality of ignoreboth
.
HISTFILE
HISTSIZE
HISTFILESIZE
histchars
HISTCMD
HISTCMD
is unset, it loses its special properties,
even if it is subsequently reset.
HOSTFILE
MAILCHECK
MAILPATH
.
PROMPT_COMMAND
$PS1
).
UID
EUID
GROUPS
PPID
HOSTNAME
HOSTTYPE
OSTYPE
MACHTYPE
SHELLOPTS
set
builtin command (see section The Set Builtin).
The options appearing in SHELLOPTS
are those reported
as `on' by `set -o'.
If this variable is in the environment when Bash
starts up, each shell option in the list will be enabled before
reading any startup files. This variable is readonly.
FIGNORE
FIGNORE
is excluded from the list of matched file names. A sample
value is `.o:~'
GLOBIGNORE
GLOBIGNORE
, it is removed from the list
of matches.
DIRSTACK
dirs
builtin.
Assigning to members of this array variable may be used to modify
directories already in the stack, but the pushd
and popd
builtins must be used to add and remove directories.
Assignment to this variable will not change the current directory.
If DIRSTACK
is unset, it loses its special properties, even if
it is subsequently reset.
PIPESTATUS
INPUTRC
BASH
BASH_VERSION
BASH_VERSINFO
BASH_VERSINFO[0]
BASH_VERSINFO[1]
BASH_VERSINFO[2]
BASH_VERSINFO[3]
BASH_VERSINFO[4]
BASH_VERSINFO[5]
MACHTYPE
.
SHLVL
OPTERR
getopts
builtin command.
LANG
LC_
.
LC_ALL
LANG
and any other
LC_
variable specifying a locale category.
LC_COLLATE
LC_MESSAGES
IGNOREEOF
EOF
character
as the sole input. If set, then the value of it is the number
of consecutive EOF
characters that can be read as the
first character on an input line
before the shell will exit. If the variable exists but does not
have a numeric value (or has no value) then the default is 10.
If the variable does not exist, then EOF
signifies the end of
input to the shell. This is only in effect for interactive shells.
Bash includes several mechanisms to evaluate arithmetic expressions and display the result or use it as part of a command.
The shell allows arithmetic expressions to be evaluated, as one of
the shell expansions or by the let
builtin.
Evaluation is done in long integers with no check for overflow, though division by 0 is trapped and flagged as an error. The following list of operators is grouped into levels of equal-precedence operators. The levels are listed in order of decreasing precedence.
- +
! ~
* / %
+ -
<< >>
<= >= < >
== !=
&
^
|
&&
||
expr ? expr : expr
= *= /= %= += -= <<= >>= &= ^= |=
Shell variables are allowed as operands; parameter expansion is performed before the expression is evaluated. The value of a parameter is coerced to a long integer within an expression. A shell variable need not have its integer attribute turned on to be used in an expression.
Constants with a leading 0 are interpreted as octal numbers.
A leading `0x' or `0X' denotes hexadecimal. Otherwise,
numbers take the form [base#
]n, where base
is a decimal number between 2 and 64 representing the arithmetic
base, and n is a number in that base. If base is
omitted, then base 10 is used.
The digits greater than 9 are represented by the lowercase letters,
the uppercase letters, `_', and `@', in that order.
If base is less than or equal to 36, lowercase and uppercase
letters may be used interchangably to represent numbers between 10
and 35.
Operators are evaluated in order of precedence. Sub-expressions in parentheses are evaluated first and may override the precedence rules above.
Arithmetic expansion allows the evaluation of an arithmetic expression and the substitution of the result. The format for arithmetic expansion is:
$(( expression ))
The expression is treated as if it were within double quotes, but a double quote inside the braces or parentheses is not treated specially. All tokens in the expression undergo parameter expansion, command substitution, and quote removal. Arithmetic substitutions may be nested.
The evaluation is performed according to the rules listed above. If the expression is invalid, Bash prints a message indicating failure and no substitution occurs.
let
let expression [expression]The
let
builtin allows arithmetic to be performed on shell
variables. Each expression is evaluated according to the
rules given previously (see section Arithmetic Evaluation). If the
last expression evaluates to 0, let
returns 1;
otherwise 0 is returned.
Bash provides one-dimensional array variables. Any variable may be used as
an array; the declare
builtin will explicitly declare an array.
There is no maximum
limit on the size of an array, nor any requirement that members
be indexed or assigned contiguously. Arrays are zero-based.
An array is created automatically if any variable is assigned to using the syntax
name[subscript]=value
The subscript is treated as an arithmetic expression that must evaluate to a number greater than or equal to zero. To explicitly declare an array, use
declare -a name
The syntax
declare -a name[subscript]
is also accepted; the subscript is ignored. Attributes may be
specified for an array variable using the declare
and
readonly
builtins. Each attribute applies to all members of
an array.
Arrays are assigned to using compound assignments of the form
name=(value1 ... valuen)
where each
value is of the form [[subscript]=]
string. If
the optional subscript is supplied, that index is assigned to;
otherwise the index of the element assigned is the last index assigned
to by the statement plus one. Indexing starts at zero.
This syntax is also accepted by the declare
builtin. Individual array elements may be assigned to using the
name[
subscript]=
value syntax introduced above.
Any element of an array may be referenced using
${name[
subscript]}
.
The braces are required to avoid
conflicts with the shell's filename expansion operators. If the
subscript is `@' or `*', the word expands to all members
of the array name. These subscripts differ only when the word
appears within double quotes. If the word is double-quoted,
${name[*]}
expands to a single word with
the value of each array member separated by the first character of the
IFS
variable, and ${name[@]}
expands each element of
name to a separate word. When there are no array members,
${name[@]}
expands to nothing. This is analogous to the
expansion of the special parameters `@' and `*'.
${#name[
subscript]}
expands to the length of
${name[
subscript]}
.
If subscript is `@' or
`*', the expansion is the number of elements in the array.
Referencing an array variable without a subscript is equivalent to
referencing element zero.
The unset
builtin is used to destroy arrays.
unset
name[subscript]
destroys the array element at index subscript.
unset
name, where name is an array, removes the
entire array. A subscript of `*' or `@' also removes the
entire array.
The declare
, local
, and readonly
builtins each accept a `-a'
option to specify an array. The read
builtin accepts a `-a'
option to assign a list of words read from the standard input
to an array, and can read values from the standard input into
individual array elements. The set
and declare
builtins display array values in a way that allows them to be
reused as input.
The value of the variable PROMPT_COMMAND
is examined just before
Bash prints each primary prompt. If it is set and non-null, then the
value is executed just as if you had typed it on the command line.
In addition, the following table describes the special characters which can appear in the prompt variables:
\a
\d
\e
\h
\H
\n
\s
$0
(the portion
following the final slash).
\t
\T
\@
\v
\V
\w
\W
$PWD
.
\u
\!
\#
\$
#
, otherwise $
.
\nnn
nnn
.
\\
\[
\]
If Bash is started with the name rbash
, or the
`--restricted'
option is supplied at invocation, the shell becomes restricted.
A restricted shell is used to
set up an environment more controlled than the standard shell.
A restricted shell behaves identically to bash
with the exception that the following are disallowed:
cd
builtin.
SHELL
or PATH
variables.
.
builtin command.
exec
builtin to replace the shell with another command.
enable
builtin.
command
builtin.
Starting Bash with the `--posix' command-line option or executing `set -o posix' while Bash is running will cause Bash to conform more closely to the POSIX.2 standard by changing the behavior to match that specified by POSIX.2 in areas where the Bash default differs.
The following list is what's changed when `POSIX mode' is in effect:
$PATH
to find the new location. This is also available with
`shopt -s checkhash'.
PS1
and PS2
expansions of `!' to
the history number and `!!' to `!' are enabled,
and parameter expansion is performed on
the value regardless of the setting of the promptvars
option.
$ENV
) rather than
the normal Bash files.
$HISTFILE
).
.
filename
is not found.
name
s. That is, they may not
contain characters other than letters, digits, and underscores, and
may not start with a digit. Declaring a function with an illegal name
causes a fatal syntax error in non-interactive shells.
cd
builtin finds a directory to change to
using $CDPATH
, the
value it assigns to the PWD
variable does not contain any
symbolic links, as if `cd -P' had been executed.
for
statement or the selection variable in a
select
statement is a read-only variable.
special
builtins
persist in the shell environment after the builtin completes.
export
and readonly
builtin commands display their
output in the format required by POSIX.2.
There is other POSIX.2 behavior that Bash does not implement. Specifically:
Go to the first, previous, next, last section, table of contents.