In bash, a function needs to fill an array that its caller declared, but arrays cannot be exported or passed by value. How does `declare -n` (or `local -n`) let the caller pass the array by name, and what naming pitfall comes with it?

## The problem namerefs solve Shell functions do not have parameters in the usual sense: they receive positional strings, and arrays are not strings. You cannot export an array, and `f "${arr[@]}"` flattens it into separate words that the function has to reassemble — and which loses the distinction between an empty array and an array holding one empty string. Returning an array is worse still, since `return` carries only an exit status. Before bash 4.3 the usual answers were a global variable by convention, printing the values and having the caller re-split them, or `eval` string-building. A nameref replaces all three with a language feature. ## How a nameref works ```bash add_all() { local -n _out=$1 # _out is now an alias for the caller's variable shift local item for item in "$@"; do _out+=("$item"); done } files=() add_all files a.txt b.txt declare -p files # declare -a files=([0]="a.txt" [1]="b.txt") ``` `declare -n name=target` (or `local -n` inside a function, which additionally scopes the nameref itself) gives `name` the nameref attribute. From then on, every expansion, assignment, subscripted assignment, `+=` append, and even `unset` performed through `name` is applied to `target` instead. The alias is on the *variable*, not on a value: it survives across statements for as long as the nameref is in scope. This works for scalars, indexed arrays and associative arrays alike, which is what makes it the standard way to hand a map into a helper: ```bash put() { local -n _m=$1 _m[$2]=$3 } declare -A cfg put cfg region eu-west-1 ``` ## The circular-reference pitfall Bash uses dynamic scoping: a `local` inside a function shadows the caller's variable of the same name for the duration of the call. So if the parameter name and the caller's variable name coincide, the nameref would have to point at itself. Bash detects that and reports a circular name reference warning rather than aliasing, and the function does not update what the caller expected. ```bash broken() { local -n arr=$1; arr+=(x); } arr=(); broken arr # circular name reference ``` The defence is purely conventional: name every nameref parameter something a caller would never choose — a leading underscore (`_out`, `_map`) or a function-specific prefix (`__addall_out`). It looks ugly, and the ugliness is the point: it is the visible marker of a bash limitation, and reviewers should treat a nameref parameter named `arr`, `out` or `result` as a latent bug. ## Unsetting through a nameref One more asymmetry worth knowing: `unset ref` follows the reference and unsets the *target* variable, while `unset -n ref` removes the nameref itself and leaves the target alone. Getting these backwards silently destroys the caller's data. ## When not to use one Namerefs make a function's contract implicit — you have to read the body to learn that argument one is an output parameter — and they are bash 4.3+, so they are unavailable on macOS's stock bash 3.2 and are not POSIX. For a small helper that produces a single string, printing to stdout and letting the caller capture it is simpler and portable. Namerefs earn their keep when the data is genuinely an array or a map, when the helper must both read and update it, or when copying a large structure would be wasteful. A reasonable house rule: name the array explicitly in the function's doc comment, use `_`-prefixed nameref parameters, and never take more than one or two output parameters. If a function needs three, that is usually the signal that the script has outgrown the shape you are forcing it into. ## What interviewers listen for Saying "pass the name and bind with `local -n`" answers the question; adding *why* the underscore prefix exists — dynamic scoping producing a circular reference — is what shows you have actually shipped a bash library rather than read about one.