Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash A nameref follows its target

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.

Bash Returning values and passing arrays to functions

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

Terminal
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 called list, the nameref ends up pointing at itself and Bash reports a circular reference. Give nameref names an unlikely prefix such as _out or ref_.
  • Use local -n in functions. A plain declare -n inside a function is also local (as with any declare), but writing local -n states the intent. A nameref that leaks into the caller's scope is rarely what you want.
  • Assignment target. declare -n ref=other changes what ref points at. Later ref=value assigns to other. To retarget an existing nameref, use declare -n ref=another again, not ref=another.
  • Array elements work. The target may be arr[2], and with an associative array map[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 trick eval "$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.