Linux Command Reference ยท Bash Syntax
Bash namerefs (declare -n)
Reference for Bash namerefs: create a variable that refers to another variable by name with declare -n, pass arrays to functions, and avoid circular references.
A nameref is a variable whose value is the name of another variable. After you declare it with declare -n (or local -n inside a function), every read and write of the nameref is silently redirected to the variable it points at. It works like a reference or alias in other languages, and it needs Bash 4.3 or newer.
Namerefs solve a classic shell problem: how to let a function return several values, or modify an array that belongs to the caller, without eval and without printing the result and capturing it in a subshell.
declare -n ref=target_variable local -n ref="$1" # inside a function: refer to the variable named by $1 unset -n ref # remove the nameref itself, not the target
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
declare -n NAME[=TARGET] local -n NAME[=TARGET] typeset -n NAME[=TARGET] unset -n NAME
| Name | Description |
|---|---|
NAME |
The nameref variable. Its value is the name of the variable (or array element) it refers to. |
TARGET |
The name of the variable to refer to. It does not have to exist yet. |
-n (declare) |
Turns the attribute on. declare +n NAME turns it off again, leaving a plain variable that holds the target name as text. |
unset -n |
Removes the nameref itself. Without -n, unset acts on the target. |
Returns: declare -n returns 0 on success and a non-zero status for an invalid target name.
Errors and edge cases: a nameref whose name equals its target (declare -n x=x) is a circular reference and produces a warning; inside functions, a caller variable with the same name as the function's own nameref causes the same problem (see the notes below).
Usage notes
- Version. Namerefs arrived in Bash 4.3 (2014). The macOS system Bash 3.2 does not have them. Bash 5.0, used by our examples, supports them fully.
- Name clashes are the main bug. If the function declares
local -n list="$1"and the caller passed a variable that is itself calledlist, the nameref ends up pointing at itself and Bash reports a circular reference. Give nameref names an unlikely prefix such as_outorref_. - Use
local -nin functions. A plaindeclare -ninside a function is also local (as with anydeclare), but writinglocal -nstates the intent. A nameref that leaks into the caller's scope is rarely what you want. - Assignment target.
declare -n ref=otherchanges whatrefpoints at. Laterref=valueassigns toother. To retarget an existing nameref, usedeclare -n ref=anotheragain, notref=another. - Array elements work. The target may be
arr[2], and with an associative arraymap[key]. A nameref to a whole array is read with"${ref[@]}"as usual. ${!ref}is special. For a nameref it expands to the target's name; for a normal variable it performs indirect expansion. See Parameter expansion.- Prefer namerefs to
eval. The older trickeval "$1=\$value"breaks on odd values and invites injection. A nameref is safe because the target name is never parsed as code, although it must still be a valid identifier. - Cost. Each access resolves the name, which is slower than a plain variable but negligible next to starting a process.