[PATCHv4,01/12] gdb/doc: extended documentation for inferior function calls

Message ID dc3089f874825f8015bc70ce83f81aa84c8a0f51.1677602051.git.aburgess@redhat.com
State New
Series Infcalls from B/P conditions in multi-threaded inferiors |

Commit Message

Andrew Burgess Feb. 28, 2023, 4:42 p.m. UTC
  Eli already approved these docs changes:



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 c1ca45521ea..1170a2dacc3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -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:
+(@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