From eef174f6a97e3f52a84e4c94a4c710b2e7082176 Mon Sep 17 00:00:00 2001
From: Andrew Burgess <aburgess@redhat.com>
Date: Mon, 16 Jan 2023 17:38:10 +0000
Subject: 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.
---
 gdb/doc/gdb.texinfo | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 98b7c98..6c811b8 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
-- 
cgit v1.1