Re: local failure

[Robert Elz]

    Date:        Sun, 31 May 2020 10:29:27 +0100
    From:        Laurent Picquet <lpicquet@gmail.com>
    Message-ID:  
<CAH+roKX-H_PjDu+UBPDiVUQjnd2eKK0E=L1r=0wg33X5paJpEg@mail.gmail.com>

  | This behaviour is not fully documented

Nothing is ever "fully" documented, as it is always possible to
write even more text about anything at all - and if that were done
then it is clear that what existed before was not "full".

So, instead of "fully documented" let's use "adequately documented"
and for that it is.

But you do need to understand how things fit together to follow.

First, the exit status is only ever set as the result of executing
a command - and only a command in the current execution environment.

       ?      Expands to the exit status of the most recently executed
              foreground pipeline.

[elsewhere it is noted that a simple command is a degenerate pipeline,
so is a compound command for that matter.]

"local" is such a command, and like all such commands, its exit status
is documented...

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

(that text has been previously quoted in this thread).

Command substitutions execute in a different shell execution environment
(nothing that happens in one has any effect upon the shell that contains
them - except that stdout from the command substitution is inserted into
the current command line (and then potentially subject to field splitting,
pathname expansion, ...) -- it becomes a part of some other command.

There is one exception to the case that only commands in the current
execution environment ever set the exit status, which is documented in
bash(1) as ...

       If there is a command name left after expansion, execution proceeds as
       described below.  Otherwise, the command exits.  If one of the
       expansions contained a command substitution, the exit status of the
       command is the exit status of the last command substitution performed.
       If there were no command substitutions, the command exits with a status
       of zero.

None that neither redirects nor variable assignments are commands (but
almost everything else that you would write in a sh script is, including
"local").   The "as described below" involves locating the command, running
it, and obtaining its exit status - and is what is done when there is a
command.

When there isn't - which is what happens when all there was was
variable assignments &/or redirects - then, and only then, does the:

        If one of the expansions contained a command substitution, the
        exit status of the command is the exit status of the last command
        substitution performed.

This is the only way that the exit status of a command substitution can
ever be observed in the parent shell.   But you have to read the entire
man page to observe that nowhere else is the status of a command substitution
ever reported.

So, the doc is all there, and it is possible to work out what happens.

As above, it is always possible to write more - but write too much, and
instead of a manual page, what would be left would be a tutorial, or perhaps
even a book (but there's already one, perhaps more than one, of those).

There is certainly nothing special about the local command in this context,
any command where there happens to be a command substitution on the command
line somewhere works exactly the same way, so it would be wrong to make any
special note of this in the doc for "local" without also putting the same
extra info in the descriptions of every other command.

kre