I think the underlying question here is not exactly "how do I gather this from the docs" as much as it is "how was I supposed to know about this and act on it before I had to debug it?" The bash manual is always "adequate" in the sense that almost any question can be answered by carefully consulting it -- but that doesn't help the person who either is unpracticed at the occasionally arcane art of *reading* the bash manual, or who doesn't even know they need to ask a question (let alone how to articulate it). I've been consulting the bash manual for nearly a decade but I still find myself in this position every now and then.
That's why I want to plug linting your shell scripts, preferably in your text editor. You'll catch a lot of problems before they happen and just get better at shell scripting. My preferred tool, ShellCheck ( https://github.com/koalaman/shellcheck), alerted me to this problem a couple of years ago, and lots, lots, lots more. It incorporates into Vim easily via the plugin "Syntastic"; I'm sure it's easy to incorporate for other text editors as well. On Sun, May 31, 2020 at 12:37 PM Robert Elz <k...@munnari.oz.au> wrote: > Date: Sun, 31 May 2020 10:29:27 +0100 > From: Laurent Picquet <lpicq...@gmail.com> > Message-ID: <CAH+roKX-H_PjDu+UBPDiVUQjnd2eKK0E=L1r= > 0wg33x5paj...@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 > > >
