Linux Command Reference ยท Shell Builtins
Bash local and readonly commands
Reference for the Bash local and readonly builtins: function-scoped variables, dynamic scoping, constants, readonly -f and -a, and common mistakes.
local declares a variable that exists only inside the function that declares it (and in functions that function calls). When the function returns, the variable is gone and any variable of the same name outside is visible again. Without local, every variable in a Bash function is global, which is the source of countless hard-to-find bugs.
readonly marks a variable or function as constant: it can no longer be reassigned or unset in that shell. Use it for configuration values that must not change.
local [OPTION] NAME[=VALUE] ... readonly [-aAf] [NAME[=VALUE] ...] readonly -p
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
local [option] name[=value] ... readonly [-aAf] [name[=value] ...] readonly -p
| Name | Description |
|---|---|
local name |
Create a local variable with no value (unset until assigned). |
local name=value |
Create and assign. The value is evaluated before local runs, so local x=$(false) hides the failure status. |
local -i, -a, -A, -n, -r, -x, -l, -u |
Same attribute options as declare. |
readonly name[=value] |
Mark as read-only, optionally assigning first. |
readonly -a / -A |
Mark arrays / associative arrays. |
readonly -f name |
Make a function read-only. |
readonly -p |
Print all read-only variables in reusable form. |
Returns: 0 on success. local outside a function returns 1 with an error; changing a read-only variable returns 1.
Errors and edge cases: "readonly variable" errors in a non-interactive shell abort the script when it happens in an assignment statement under POSIX mode and just return a failed status otherwise. Read-only status cannot be removed; it ends with the shell.
Usage notes
- Declare and assign separately when you need the exit status of a command substitution:
local out; out=$(cmd) || return 1. The one-steplocal out=$(cmd)always returns local's status (0). - Dynamic scope. Bash uses dynamic scoping, not lexical: a function called from another function can see and modify the caller's locals. Name locals distinctively or keep helper functions pure.
- Shadowing.
local xcreates a new empty variable, even whenxis global. It does not inherit the outer value; uselocal x="$x"for that. - Arrays.
local -a list=()andlocal -A mapkeep them out of the global namespace. Without-A,local mapcreates a scalar. - Constants at the top. Set configuration with
readonly NAME=valueearly, so later code (or sourced files) cannot change it. Environment variables passed from outside can still be markedreadonlyafterwards. - No
localin POSIX sh. dash and other POSIX shells acceptlocalonly as an extension (dash does), so#!/bin/shscripts should avoid it or check carefully (Portability). - Interaction with
unset. You cannotunseta read-only variable; anunsetof a local one reveals the global again in some cases. - Loop variables are not local automatically: declare
local ibeforefor i in ...inside functions. declare -randreadonlyare equivalent.typesetis accepted for both.