[PATCHv4,01/12] gdb/doc: extended documentation for inferior function calls
Commit Message
Eli already approved these docs changes:
https://sourceware.org/pipermail/gdb-patches/2023-January/195869.html
---
I noticed that the documentation for inferior function calls doesn't
say much about what happens if/when an inferior function call is
interrupted, i.e. it doesn't describe what the dummy frame looks like
on the stack, or how GDB behaves when the inferior is continued and
reaches the dummy frame.
This commit aims to add some of this missing information.
---
gdb/doc/gdb.texinfo | 32 ++++++++++++++++++++++++++++++++
1 file changed, 32 insertions(+)
Comments
On 2/28/23 17:42, Andrew Burgess via Gdb-patches wrote:
> +If a called function is interrupted for any reason, including hitting
> +a breakpoint, or triggering a watchpoint, and the stack is not unwound
Hi Andrew,
I read this bit and went investigating why a watchpoint didn't trigger
during a called function (PR31485), and found that in fact we explicitly
disable watchpoints during a called function.
I suppose we should either drop mentioning the watchpoint here, or
perhaps better, mention that they are disabled.
And perhaps eventually, allow watchpoints to be triggered.
Thanks,
- Tom
On 3/21/24 10:03, Tom de Vries wrote:
> On 2/28/23 17:42, Andrew Burgess via Gdb-patches wrote:
>> +If a called function is interrupted for any reason, including hitting
>> +a breakpoint, or triggering a watchpoint, and the stack is not unwound
>
> Hi Andrew,
>
> I read this bit and went investigating why a watchpoint didn't trigger
> during a called function (PR31485), and found that in fact we explicitly
> disable watchpoints during a called function.
>
> I suppose we should either drop mentioning the watchpoint here, or
> perhaps better, mention that they are disabled.
>
Ah, I found that the behaviour is documented at the watchpoints side (
https://sourceware.org/gdb/current/onlinedocs/gdb.html/Set-Watchpoints.html
):
...
If you call a function interactively using print or call, any
watchpoints you have set will be inactive until GDB reaches another kind
of breakpoint or the call completes.
...
Thanks,
- Tom
> And perhaps eventually, allow watchpoints to be triggered.
>
> Thanks,
> - Tom
@@ -20779,6 +20779,7 @@
in that case is controlled by the
@code{set unwind-on-terminating-exception} command.
+@anchor{stack unwind settings}
@table @code
@item set unwindonsignal
@kindex set unwindonsignal
@@ -20836,6 +20837,37 @@
@end table
+When calling a function within a program, it is possible that the
+program could enter a state from which the called function may never
+return. If this happens then it is possible to interrupt the function
+call by typing the interrupt character (often @kbd{Ctrl-c}).
+
+If a called function is interrupted for any reason, including hitting
+a breakpoint, or triggering a watchpoint, and the stack is not unwound
+due to @code{set unwind-on-terminating-exception on} or @code{set
+unwindonsignal on} (@pxref{stack unwind settings}),
+then the dummy-frame, created by @value{GDBN} to facilitate the call
+to the program function, will be visible in the backtrace, for example
+frame @code{#3} in the following backtrace:
+
+@smallexample
+(@value{GDBP}) backtrace
+#0 0x00007ffff7b3d1e7 in nanosleep () from /lib64/libc.so.6
+#1 0x00007ffff7b3d11e in sleep () from /lib64/libc.so.6
+#2 0x000000000040113f in deadlock () at test.cc:13
+#3 <function called from gdb>
+#4 breakpt () at test.cc:20
+#5 0x0000000000401151 in main () at test.cc:25
+@end smallexample
+
+At this point it is possible to examine the state of the inferior just
+like any other stop.
+
+Depending on why the function was interrupted then it may be possible
+to resume the inferior (using commands like @code{continue},
+@code{step}, etc). In this case, when the inferior finally returns to
+the dummy-frame, @value{GDBN} will once again halt the inferior.
+
@subsection Calling functions with no debug info
@cindex no debug info functions