[PATCHv2,01/13] gdb/doc: extended documentation for inferior function calls
Commit Message
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 | 30 ++++++++++++++++++++++++++++++
1 file changed, 30 insertions(+)
Comments
> Cc: Andrew Burgess <aburgess@redhat.com>
> Date: Wed, 18 Jan 2023 16:17:57 +0000
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>
> 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.
Thanks.
> +If a called function is interrupted for any reason, and the stack is
> +not unwound (due to @code{set unwind-on-terminating-exception on} or
> +@code{set unwindonsignal on}),
Please add here a cross-reference to here these settings are described
in the manual.
Otherwise, this is OK.
On Wednesday, January 18, 2023 5:18 PM, Andrew Burgess wrote:
> 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 | 30 ++++++++++++++++++++++++++++++
> 1 file changed, 30 insertions(+)
>
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 9c0018ea5c1..e05813ff502 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -20731,6 +20731,36 @@
>
> @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}).
It may help, as a reminder to the reader, to additionally state that
the called function may hit a breakpoint. That's another interesting
(and arguably common) reason for why an infcall could stop.
Thanks
-Baris
Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de>
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928
Eli Zaretskii <eliz@gnu.org> writes:
>> Cc: Andrew Burgess <aburgess@redhat.com>
>> Date: Wed, 18 Jan 2023 16:17:57 +0000
>> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>>
>> 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.
>
> Thanks.
>
>> +If a called function is interrupted for any reason, and the stack is
>> +not unwound (due to @code{set unwind-on-terminating-exception on} or
>> +@code{set unwindonsignal on}),
>
> Please add here a cross-reference to here these settings are described
> in the manual.
>
> Otherwise, this is OK.
I made this fix and pushed this patch.
Thanks,
Andrew
@@ -20731,6 +20731,36 @@
@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, and the stack is
+not unwound (due to @code{set unwind-on-terminating-exception on} or
+@code{set unwindonsignal on}), 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