Re: return [n] documentation.
On 2/6/25 12:59 PM, Greg Wooledge wrote: If extdebug really does imply functrace, then that's missing from the documentation. The rest appears to be working as intended. Look at item 5. extdebug If set at shell invocation, or in a shell startup file, arrange to execute the debugger profile before the shell starts, identical to the --debugger option. If set af- ter invocation, behavior intended for use by debuggers is enabled: 1. The -F option to the declare builtin displays the source file name and line number corresponding to each function name supplied as an argument. 2. If the command run by the DEBUG trap returns a non-zero value, the next command is skipped and not executed. 3. If the command run by the DEBUG trap returns a value of 2, and the shell is executing in a sub- routine (a shell function or a shell script exe- cuted by the . or source builtins), the shell simulates a call to return. 4. BASH_ARGC and BASH_ARGV are updated as described in their descriptions above). 5. Function tracing is enabled: command substitu- tion, shell functions, and subshells invoked with ( command ) inherit the DEBUG and RETURN traps. -- ``The lyf so short, the craft so long to lerne.'' - Chaucer ``Ars longa, vita brevis'' - Hippocrates Chet Ramey, UTech, CWRUc...@case.eduhttp://tiswww.cwru.edu/~chet/ OpenPGP_signature.asc Description: OpenPGP digital signature
Re: return [n] documentation.
On Thu, Feb 06, 2025 at 14:54:29 -0500, Chet Ramey wrote: > On 2/6/25 12:59 PM, Greg Wooledge wrote: > > > If extdebug really does imply functrace, then that's missing from the > > documentation. The rest appears to be working as intended. > > Look at item 5. > > extdebug > [...] > 5. Function tracing is enabled: command substitu- > tion, shell functions, and subshells invoked with > ( command ) inherit the DEBUG and RETURN traps. OK, fair. But it would be easier to find it if it actually said "functrace" somewhere, because that's what I was searching for.
return [n] documentation.
Hi,
I find the docco for return [n] not easy to interpret. Here is what can be read.
return [n]
Stop executing a shell function or sourced file and
return the value specified by n to its caller.
...
Any command associated with the RETURN trap is exe‐
cuted before execution resumes after the function or
script.
The later sentence is not true, and this lead to time consuming research with
some occurences in SO as well as bash-help list back in 2018.
As some are refining the documentation may be it is worth some more precision
Here is a test case.
$ echo $BASH_VERSION
5.2.21(1)-release
$ function f { :; }
$ trap "echo catch return" RETURN
$ . /dev/null # Hurray!
catch return
$ f # huh ?
$ shopt -s extdebug
$ f # ha!
catch return
As any gurus out there knows the function return trap is only available with
shopt -s extdebug, that is not explicitly stated in the documentation, and its
a pain.
I don't know the impact on perf of this extdebug thing and I am a bit reluctant
to have all my prod script turning extdebug on for the sake of trapping the
return.
So may be instead of cheating and fixing the docco with a mention of this
extdebug thing, a real fix could be better.
What do you think?
Cheers
Documentation inconsistency (?)
Hello,
This concern:
https://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion
In the bash documentation, section “shell parameter expansion,” in the
paragraph “${parameter:-word},” the example given uses
${parameter-word}
which is a Bourne Shell compatible expansion but behaves differently
for defined but empty parameters. For greater clarity, shouldn't we
write the following documentation (Please excuse the RST syntax):
``${parameter:-word}``
--
If parameter is unset or null, the expansion of word is substituted.
Otherwise, the value of parameter is substituted.
::
$ v=123
$ echo ${v:-unset}
123
$ e=''
$ echo ${e:-unset}
unset
$ echo ${u:-unset}
unset
``${parameter-word}``
-
If parameter is unset, the expansion of word is substituted. Otherwise,
the value of parameter is substituted.
This differs from ``${parameter:-word}`` in the case where
``parameter`` is set but not null.
This expansion comes from Bourne-Shell.
::
$ v=123
$ echo ${v:-unset}
123
$ e=''
$ echo ${e:-unset}
$ echo ${u:-unset}
unset
P.-S. This is my first report to a GNU project. Please point out any
important best practices that I have not followed.
--
Alexis Reynouard
Re: Documentation inconsistency (?)
Je Thu, Feb 06, 2025 at 11:26:08AM +0100, Alexis Reynouard skribis:
> Hello,
>
> This concern:
> https://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion
>
> In the bash documentation, section “shell parameter expansion,” in the
> paragraph “${parameter:-word},” the example given uses
>${parameter-word}
> which is a Bourne Shell compatible expansion but behaves differently
> for defined but empty parameters. For greater clarity, shouldn't we
> write the following documentation (Please excuse the RST syntax):
>
> ``${parameter:-word}``
> --
[cut]
This was recently discussed:
https://lists.gnu.org/archive/html/bug-bash/2025-01/msg00144.html
--
Andreas (Kusalananda) Kähäri
Uppsala, Sweden
.
Re: return [n] documentation.
On Thu, Feb 06, 2025 at 18:41:14 +0100, Phi wrote:
> I find the docco for return [n] not easy to interpret. Here is what can be
> read.
>
>return [n]
> Stop executing a shell function or sourced file and
> return the value specified by n to its caller.
> ...
> Any command associated with the RETURN trap is exe‐
> cuted before execution resumes after the function or
> script.
In the FUNCTIONS section, there is some additional wording:
All other aspects of the shell execution environment are identical be‐
tween a function and its caller with these exceptions: the DEBUG and
RETURN traps (see the description of the trap builtin under SHELL
BUILTIN COMMANDS below) are not inherited unless the function has been
given the trace attribute (see the description of the declare builtin
below) or the -o functrace shell option has been enabled with the set
builtin (in which case all functions inherit the DEBUG and RETURN
traps), and the ERR trap is not inherited unless the -o errtrace shell
option has been enabled.
> $ function f { :; }
> $ trap "echo catch return" RETURN
> $ . /dev/null # Hurray!
> catch return
The RETURN trap fired upon "returning" from a . command, because the
trap was set within the main script, not within the function f.
> $ f # huh ?
The RETURN trap was not inherited by the function f, because the function
was not "given the trace attribute", and the functrace shell option is not
enabled.
> $ shopt -s extdebug
> $ f # ha!
> catch return
I suppose extdebug must imply functrace, then.
> As any gurus out there knows the function return trap is only available with
> shopt -s extdebug, that is not explicitly stated in the documentation, and
> its a pain.
I guess I'm not a guru.
Anyway, based on the part of the documentation that I cited, the RETURN
trap seems to work fine if it's defined within the function.
hobbit:~$ f1() { echo f1; }
hobbit:~$ f2() { trap 'echo TRAP' RETURN; echo f2; }
hobbit:~$ f1
f1
hobbit:~$ f2
f2
TRAP
hobbit:~$ f1
f1
hobbit:~$ f2
f2
TRAP
If extdebug really does imply functrace, then that's missing from the
documentation. The rest appears to be working as intended.
Re: return [n] documentation.
I still don't know the impact (implication) of extdebug, does it impact perf ?
Re: return [n] documentation.
It was not obvious from the reading that it would work when trap is inside the function but that is exactly what I need. Again, may be it is just me, but the reading with the back and forth reading and long distance jump in the docco to figure out how it works looks complicated, but that's good enough, I can proceed :-) Thanx tons @greg @chet
Re: Documentation inconsistency (?)
On 2/6/25 5:26 AM, Alexis Reynouard wrote:
Hello,
This concern:
https://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion
In the bash documentation, section “shell parameter expansion,” in the
paragraph “${parameter:-word},” the example given uses
${parameter-word}
which is a Bourne Shell compatible expansion but behaves differently
for defined but empty parameters. For greater clarity, shouldn't we
write the following documentation (Please excuse the RST syntax):
This is the paragraph immediately before the part you quoted:
"When not performing substring expansion, using the form described below
(e.g., ‘:-’), Bash tests for a parameter that is unset or null. Omitting
the colon results in a test only for a parameter that is unset. Put another
way, if the colon is included, the operator tests for both parameter’s
existence and that its value is not null; if the colon is omitted, the
operator tests only for existence."
--
``The lyf so short, the craft so long to lerne.'' - Chaucer
``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRUc...@case.eduhttp://tiswww.cwru.edu/~chet/
OpenPGP_signature.asc
Description: OpenPGP digital signature
