[binutils-gdb] gdb/doc: extended documentation for inferior function calls

[Andrew Burgess]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=eef174f6a97e3f52a84e4c94a4c710b2e7082176

commit eef174f6a97e3f52a84e4c94a4c710b2e7082176
Author: Andrew Burgess <aburgess@redhat.com>
Date:   Mon Jan 16 17:38:10 2023 +0000

    gdb/doc: extended documentation for inferior function calls
    
    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.

Diff:
---
 gdb/doc/gdb.texinfo | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 98b7c984aa7..6c811b8be2e 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -20790,6 +20790,7 @@ seek for exception handlers outside of this dummy-frame.  What happens
 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
@@ -20847,6 +20848,37 @@ Show permission to call functions in the program.
 
 @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