Bash Reference Manual Reference Documentation for Bash

Chapter 3: Basic Shell Features
18
function has been given the trace attribute using the declare builtin or the -o functrace
option has been enabled with the set builtin, (in which case all functions inherit the DEBUG
and RETURN traps), and the ERR trap is not inherited unless the -o errtrace shell option
has been enabled. See Section 4.1 [Bourne Shell Builtins], page 42, for the description of
the trap builtin.
The FUNCNEST variable, if set to a numeric value greater than 0, defines a maximum
function nesting level. Function invocations that exceed the limit cause the entire command
to abort.
If the builtin command return is executed in a function, the function completes and
execution resumes with the next command after the function call. Any command associated
with the RETURN trap is executed before execution resumes. When a function completes,
the values of the positional parameters and the special parameter ‘#’ are restored to the
values they had prior to the function’s execution. If a numeric argument is given to return,
that is the function’s return status; otherwise the function’s return status is the exit status
of the last command executed before the return.
Variables local to the function may be declared with the local builtin. These variables
are visible only to the function and the commands it invokes.
Function names and definitions may be listed with the -f option to the declare
(typeset) builtin command (see Section 4.2 [Bash Builtins], page 49). The -F option to
declare or typeset will list the function names only (and optionally the source file and
line number, if the extdebug shell option is enabled). Functions may be exported so that
subshells automatically have them defined with the -f option to the export builtin (see
Section 4.1 [Bourne Shell Builtins], page 42). Note that shell functions and variables with
the same name may result in multiple identically-named entries in the environment passed
to the shell’s children. Care should be taken in cases where this may cause a problem.
Functions may be recursive. The FUNCNEST variable may be used to limit the depth of
the function call stack and restrict the number of function invocations. By default, no limit
is placed on the number of recursive calls.
3.4 Shell Parameters
A parameter is an entity that stores values. It can be a name, a number, or one of the special
characters listed below. A variable is a parameter denoted by a name. A variable has a value
and zero or more attributes. Attributes are assigned using the declare builtin command
(see the description of the declare builtin in Section 4.2 [Bash Builtins], page 49).
A parameter is set if it has been assigned a value. The null string is a valid value. Once
a variable is set, it may be unset only by using the unset builtin command.
A variable may be assigned to by a statement of the form
name=[value]
If value is not given, the variable is assigned the null string. All values undergo tilde ex-
pansion, parameter and variable expansion, command substitution, arithmetic expansion,
and quote removal (detailed below). If the variable has its integer attribute set, then
value is evaluated as an arithmetic expression even if the $((...)) expansion is not used
(see Section 3.5.5 [Arithmetic Expansion], page 29). Word splitting is not performed, with

---

Chapter 3: Basic Shell Features
19
the exception of "$@" as explained below. Filename expansion is not performed. Assign-
ment statements may also appear as arguments to the alias, declare, typeset, export,
readonly, and local builtin commands (declaration commands). When in posix mode
(see Section 6.11 [Bash POSIX Mode], page 96), these builtins may appear in a command
after one or more instances of the command builtin and retain these assignment statement
properties.
In the context where an assignment statement is assigning a value to a shell variable or
array index (see Section 6.7 [Arrays], page 91), the ‘+=’ operator can be used to append to or
add to the variable’s previous value. This includes arguments to builtin commands such as
declare that accept assignment statements (declaration commands). When ‘+=’ is applied
to a variable for which the integer attribute has been set, value is evaluated as an arithmetic
expression and added to the variable’s current value, which is also evaluated. When ‘+=’ is
applied to an array variable using compound assignment (see Section 6.7 [Arrays], page 91),
the variable’s value is not unset (as it is when using ‘=’), and new values are appended to
the array beginning at one greater than the array’s maximum index (for indexed arrays), or
added as additional key-value pairs in an associative array. When applied to a string-valued
variable, value is expanded and appended to the variable’s value.
A variable can be assigned the nameref attribute using the -n option to the declare or
local builtin commands (see Section 4.2 [Bash Builtins], page 49) to create a nameref, or a
reference to another variable. This allows variables to be manipulated indirectly. Whenever
the nameref variable is referenced, assigned to, unset, or has its attributes modified (other
than using or changing the nameref attribute itself), the operation is actually performed on
the variable specified by the nameref variable’s value. A nameref is commonly used within
shell functions to refer to a variable whose name is passed as an argument to the function.
For instance, if a variable name is passed to a shell function as its first argument, running
declare -n ref=$1
inside the function creates a nameref variable ref whose value is the variable name passed
as the first argument. References and assignments to ref, and changes to its attributes, are
treated as references, assignments, and attribute modifications to the variable whose name
was passed as $1.
If the control variable in a for loop has the nameref attribute, the list of words can be
a list of shell variables, and a name reference will be established for each word in the list,
in turn, when the loop is executed. Array variables cannot be given the nameref attribute.
However, nameref variables can reference array variables and subscripted array variables.
Namerefs can be unset using the -n option to the unset builtin (see Section 4.1 [Bourne
Shell Builtins], page 42). Otherwise, if unset is executed with the name of a nameref
variable as an argument, the variable referenced by the nameref variable will be unset.
3.4.1 Positional Parameters
A positional parameter is a parameter denoted by one or more digits, other than the single
digit 0. Positional parameters are assigned from the shell’s arguments when it is invoked,
and may be reassigned using the set builtin command. Positional parameter N may be
referenced as ${N}, or as $N when N consists of a single digit. Positional parameters may
not be assigned to with assignment statements. The set and shift builtins are used to
set and unset them (see Chapter 4 [Shell Builtin Commands], page 42). The positional

---