Why does setting a variable readonly in the outer scope prevent defining a local variable with the same name?

Question

I've found nothing about this in all my searching.

In the code below, Bar1 acts like I'd expect a "regular" variable to act (since help declare says that -g is only "seen" in function calls): it changes value depending on the scope (outer or inner).

Bar2, being "plainly" declared, also acts like I expect (being gfhjnfd in the outer scope, and blat in the inner scope.

But Foo is a globally unchanging variable. help declare only says "to make NAMEs readonly". Where is this extended (and unwanted) feature documented?

$ cat test.sh
#!/bin/bash

declare -r Foo=bar
declare -g Bar1=fdhtbn
declare Bar2=gfhjnfd

X()
{
    local Foo=$1
    local Bar1=snorkel
    local Bar2=$2
    echo Foo in X = $Foo
    echo Bar1 in X = $Bar1
    echo Bar2 in X = $Bar2
}

echo Foo, above X, = $Foo
echo Bar1, above X = $Bar1
echo Bar2, above X = $Bar2
echo
X baz blat
echo
echo Foo, below X, = $Foo
echo Bar1, below X = $Bar1
echo Bar2, below X = $Bar2

$ ./test.sh
Foo, above X, = bar
Bar1, above X = fdhtbn
Bar2, above X = gfhjnfd

./test.sh: line 9: local: Foo: readonly variable
Foo in X = bar
Bar1 in X = snorkel
Bar2 in X = blat

Foo, below X, = bar
Bar1, below X = fdhtbn
Bar2, below X = gfhjnfd

Answer 1

Whether readonly in one scope will prevent a variable with the same name to be declared in child scopes (in those shells that have dynamic scoping such as bash) varies between shells¹.

That came up during Austin group discussions about specifying local scope for variables in POSIX sh (an effort now abandoned as getting a consensus (on that an many other aspects) prove impossible).

In bash, that's by design and the maintainer said they wouldn't budge on that (at least not in the default environment), as it's considered there a security measure.

readonly can be used for two not fully-compatible purposes:

1. as a development tool to define global constants expected not to change, so you're warned when your code tries to and you can then fix your code (a bit like the const of C though here it happens at runtime).
2. as a security measure in restricted shells (a very poor sandboxing security feature) where some special variables such as $PATH, $HISTFILE (though an administrator wanting to provide a restricted shell environment would likely want to set more variables read-only such as LD_PRELOAD, PERL5LIB...) would need to remain read-only to prevent users bypassing the restrictions.

In bash, modifications of $PATH (which has the only allowed commands) in restricted shells relies on the readonly attribute, so it's important those variables cannot be modified (including their list of attributes or scopes) even in child scopes.

In zsh, $PATH and a few other variables (including LD_PRELOAD, but not PERL5LIB, PYTHONPATH...) are restricted, but not via the read-only attribute, so readonly can be used reliably for the first usage mentioned above, but that means that if your restricted-environment has some commands written in perl or python, users may be able to bypass restrictions via the PERL5LIB/PYTHONPATH environment variables for instance and making those readonly won't help as the users can do typeset +r PERL5LIB to remove that readonly attribute or shadow it in a child scope with a non-readonly one.

---

^{¹ See List of shells that support `local` keyword for defining local variables for more details about local scope in various POSIX-like shells.}

Answer 2

The underlying problem here is that the local keyword doesn't really create a local variable, or at least, not in the sense that you're expecting.

Per the Bash Reference Manual:

Variables local to the function may be declared with the local builtin (local variables). Ordinarily, variables and their values are shared between a function and its caller. These variables are visible only to the function and the commands it invokes. This is particularly important when a shell function calls other functions.

and

local can only be used within a function; it makes the variable name have a visible scope restricted to that function and its children.

(where boldface represents my emphasis).

In computer science terms, Bash uses dynamic scope instead of lexical scope; but from the standpoint of a typical programmer living in the year 2024, what this really means is that local doesn't create a local variable, it just temporarily modifies the global variable. Its special magic is that it automatically restores the variable's original value (and other properties) when the function returns, which is useful, but is not a full implementation of "local variables" in the sense that you expect.

So if local could override readonly, then something like this:

readonly three=3

print_three() {
  echo "$three"
}

print_four() {
  local three=4

  print_three
}

print_four

would print 4 instead of 3 — the variable three wouldn't really be readonly.

---

As Stéphane Chazelas points out in his answer, some shells do let local override readonly. But I would argue that this is a mistake in any shell where local has the same basic behavior as in Bash (namely, temporarily modifying a global variable instead of creating a separate local variable), and that behavior genuinely conflicts with the intention of readonly. I can only assume that their motivation was to have local variables be slightly more like true local variables, but that's not helpful so long as they're not truly local.

Answer 3

This is documented under local in

www.gnu.org/software/bash/manual/bash.html#Bash-Builtins

The return status is zero unless local is used outside a function, an invalid name is supplied, or name is a readonly variable.

I do find this surprising, as the first sentence there says:

For each argument, a local variable named name is created, and assigned value.

That implies a new variable is created with scope restricted to that function. There is an argument that a global constant should be reliably preserved.