1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Frames In Guile</title> 18 19<meta name="description" content="Debugging with GDB: Frames In Guile"> 20<meta name="keywords" content="Debugging with GDB: Frames In Guile"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Guile-API.html#Guile-API" rel="up" title="Guile API"> 29<link href="Blocks-In-Guile.html#Blocks-In-Guile" rel="next" title="Blocks In Guile"> 30<link href="Objfiles-In-Guile.html#Objfiles-In-Guile" rel="previous" title="Objfiles In Guile"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Frames-In-Guile"></a> 65<div class="header"> 66<p> 67Next: <a href="Blocks-In-Guile.html#Blocks-In-Guile" accesskey="n" rel="next">Blocks In Guile</a>, Previous: <a href="Objfiles-In-Guile.html#Objfiles-In-Guile" accesskey="p" rel="previous">Objfiles In Guile</a>, Up: <a href="Guile-API.html#Guile-API" accesskey="u" rel="up">Guile API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Accessing-inferior-stack-frames-from-Guile_002e"></a> 71<h4 class="subsubsection">23.3.3.15 Accessing inferior stack frames from Guile.</h4> 72 73<a name="index-frames-in-guile"></a> 74<p>When the debugged program stops, <small>GDB</small> is able to analyze its call 75stack (see <a href="Frames.html#Frames">Stack frames</a>). The <code><gdb:frame></code> class 76represents a frame in the stack. A <code><gdb:frame></code> object is only valid 77while its corresponding frame exists in the inferior’s stack. If you try 78to use an invalid frame object, <small>GDB</small> will throw a 79<code>gdb:invalid-object</code> exception (see <a href="Guile-Exception-Handling.html#Guile-Exception-Handling">Guile Exception Handling</a>). 80</p> 81<p>Two <code><gdb:frame></code> objects can be compared for equality with the 82<code>equal?</code> function, like: 83</p> 84<div class="smallexample"> 85<pre class="smallexample">(gdb) guile (equal? (newest-frame) (selected-frame)) 86#t 87</pre></div> 88 89<p>The following frame-related procedures are provided by the 90<code>(gdb)</code> module: 91</p> 92<dl> 93<dt><a name="index-frame_003f"></a>Scheme Procedure: <strong>frame?</strong> <em>object</em></dt> 94<dd><p>Return <code>#t</code> if <var>object</var> is a <code><gdb:frame></code> object. 95Otherwise return <code>#f</code>. 96</p></dd></dl> 97 98<dl> 99<dt><a name="index-frame_002dvalid_003f"></a>Scheme Procedure: <strong>frame-valid?</strong> <em>frame</em></dt> 100<dd><p>Returns <code>#t</code> if <var>frame</var> is valid, <code>#f</code> if not. 101A frame object can become invalid if the frame it refers to doesn’t 102exist anymore in the inferior. All <code><gdb:frame></code> procedures will throw 103an exception if the frame is invalid at the time the procedure is called. 104</p></dd></dl> 105 106<dl> 107<dt><a name="index-frame_002dname"></a>Scheme Procedure: <strong>frame-name</strong> <em>frame</em></dt> 108<dd><p>Return the function name of <var>frame</var>, or <code>#f</code> if it can’t be 109obtained. 110</p></dd></dl> 111 112<dl> 113<dt><a name="index-frame_002darch"></a>Scheme Procedure: <strong>frame-arch</strong> <em>frame</em></dt> 114<dd><p>Return the <code><gdb:architecture></code> object corresponding to <var>frame</var>’s 115architecture. See <a href="Architectures-In-Guile.html#Architectures-In-Guile">Architectures In Guile</a>. 116</p></dd></dl> 117 118<dl> 119<dt><a name="index-frame_002dtype"></a>Scheme Procedure: <strong>frame-type</strong> <em>frame</em></dt> 120<dd><p>Return the type of <var>frame</var>. The value can be one of: 121</p> 122<dl compact="compact"> 123<dt><code>NORMAL_FRAME</code></dt> 124<dd><p>An ordinary stack frame. 125</p> 126</dd> 127<dt><code>DUMMY_FRAME</code></dt> 128<dd><p>A fake stack frame that was created by <small>GDB</small> when performing an 129inferior function call. 130</p> 131</dd> 132<dt><code>INLINE_FRAME</code></dt> 133<dd><p>A frame representing an inlined function. The function was inlined 134into a <code>NORMAL_FRAME</code> that is older than this one. 135</p> 136</dd> 137<dt><code>TAILCALL_FRAME</code></dt> 138<dd><p>A frame representing a tail call. See <a href="Tail-Call-Frames.html#Tail-Call-Frames">Tail Call Frames</a>. 139</p> 140</dd> 141<dt><code>SIGTRAMP_FRAME</code></dt> 142<dd><p>A signal trampoline frame. This is the frame created by the OS when 143it calls into a signal handler. 144</p> 145</dd> 146<dt><code>ARCH_FRAME</code></dt> 147<dd><p>A fake stack frame representing a cross-architecture call. 148</p> 149</dd> 150<dt><code>SENTINEL_FRAME</code></dt> 151<dd><p>This is like <code>NORMAL_FRAME</code>, but it is only used for the 152newest frame. 153</p></dd> 154</dl> 155</dd></dl> 156 157<dl> 158<dt><a name="index-frame_002dunwind_002dstop_002dreason"></a>Scheme Procedure: <strong>frame-unwind-stop-reason</strong> <em>frame</em></dt> 159<dd><p>Return an integer representing the reason why it’s not possible to find 160more frames toward the outermost frame. Use 161<code>unwind-stop-reason-string</code> to convert the value returned by this 162function to a string. The value can be one of: 163</p> 164<dl compact="compact"> 165<dt><code>FRAME_UNWIND_NO_REASON</code></dt> 166<dd><p>No particular reason (older frames should be available). 167</p> 168</dd> 169<dt><code>FRAME_UNWIND_NULL_ID</code></dt> 170<dd><p>The previous frame’s analyzer returns an invalid result. 171</p> 172</dd> 173<dt><code>FRAME_UNWIND_OUTERMOST</code></dt> 174<dd><p>This frame is the outermost. 175</p> 176</dd> 177<dt><code>FRAME_UNWIND_UNAVAILABLE</code></dt> 178<dd><p>Cannot unwind further, because that would require knowing the 179values of registers or memory that have not been collected. 180</p> 181</dd> 182<dt><code>FRAME_UNWIND_INNER_ID</code></dt> 183<dd><p>This frame ID looks like it ought to belong to a NEXT frame, 184but we got it for a PREV frame. Normally, this is a sign of 185unwinder failure. It could also indicate stack corruption. 186</p> 187</dd> 188<dt><code>FRAME_UNWIND_SAME_ID</code></dt> 189<dd><p>This frame has the same ID as the previous one. That means 190that unwinding further would almost certainly give us another 191frame with exactly the same ID, so break the chain. Normally, 192this is a sign of unwinder failure. It could also indicate 193stack corruption. 194</p> 195</dd> 196<dt><code>FRAME_UNWIND_NO_SAVED_PC</code></dt> 197<dd><p>The frame unwinder did not find any saved PC, but we needed 198one to unwind further. 199</p> 200</dd> 201<dt><code>FRAME_UNWIND_MEMORY_ERROR</code></dt> 202<dd><p>The frame unwinder caused an error while trying to access memory. 203</p> 204</dd> 205<dt><code>FRAME_UNWIND_FIRST_ERROR</code></dt> 206<dd><p>Any stop reason greater or equal to this value indicates some kind 207of error. This special value facilitates writing code that tests 208for errors in unwinding in a way that will work correctly even if 209the list of the other values is modified in future <small>GDB</small> 210versions. Using it, you could write: 211</p> 212<div class="smallexample"> 213<pre class="smallexample">(define reason (frame-unwind-stop-readon (selected-frame))) 214(define reason-str (unwind-stop-reason-string reason)) 215(if (>= reason FRAME_UNWIND_FIRST_ERROR) 216 (format #t "An error occured: ~s\n" reason-str)) 217</pre></div> 218</dd> 219</dl> 220</dd></dl> 221 222<dl> 223<dt><a name="index-frame_002dpc"></a>Scheme Procedure: <strong>frame-pc</strong> <em>frame</em></dt> 224<dd><p>Return the frame’s resume address. 225</p></dd></dl> 226 227<dl> 228<dt><a name="index-frame_002dblock"></a>Scheme Procedure: <strong>frame-block</strong> <em>frame</em></dt> 229<dd><p>Return the frame’s code block as a <code><gdb:block></code> object. 230See <a href="Blocks-In-Guile.html#Blocks-In-Guile">Blocks In Guile</a>. 231</p></dd></dl> 232 233<dl> 234<dt><a name="index-frame_002dfunction"></a>Scheme Procedure: <strong>frame-function</strong> <em>frame</em></dt> 235<dd><p>Return the symbol for the function corresponding to this frame 236as a <code><gdb:symbol></code> object, or <code>#f</code> if there isn’t one. 237See <a href="Symbols-In-Guile.html#Symbols-In-Guile">Symbols In Guile</a>. 238</p></dd></dl> 239 240<dl> 241<dt><a name="index-frame_002dolder"></a>Scheme Procedure: <strong>frame-older</strong> <em>frame</em></dt> 242<dd><p>Return the frame that called <var>frame</var>. 243</p></dd></dl> 244 245<dl> 246<dt><a name="index-frame_002dnewer"></a>Scheme Procedure: <strong>frame-newer</strong> <em>frame</em></dt> 247<dd><p>Return the frame called by <var>frame</var>. 248</p></dd></dl> 249 250<dl> 251<dt><a name="index-frame_002dsal"></a>Scheme Procedure: <strong>frame-sal</strong> <em>frame</em></dt> 252<dd><p>Return the frame’s <code><gdb:sal></code> (symtab and line) object. 253See <a href="Symbol-Tables-In-Guile.html#Symbol-Tables-In-Guile">Symbol Tables In Guile</a>. 254</p></dd></dl> 255 256<dl> 257<dt><a name="index-frame_002dread_002dregister"></a>Scheme Procedure: <strong>frame-read-register</strong> <em>frame register</em></dt> 258<dd><p>Return the value of <var>register</var> in <var>frame</var>. <var>register</var> 259should be a string, like ‘<samp>pc</samp>’. 260</p></dd></dl> 261 262<dl> 263<dt><a name="index-frame_002dread_002dvar"></a>Scheme Procedure: <strong>frame-read-var</strong> <em>frame variable <span class="roman">[</span>#:block block<span class="roman">]</span></em></dt> 264<dd><p>Return the value of <var>variable</var> in <var>frame</var>. If the optional 265argument <var>block</var> is provided, search for the variable from that 266block; otherwise start at the frame’s current block (which is 267determined by the frame’s current program counter). The 268<var>variable</var> must be given as a string or a <code><gdb:symbol></code> 269object, and <var>block</var> must be a <code><gdb:block></code> object. 270</p></dd></dl> 271 272<dl> 273<dt><a name="index-frame_002dselect"></a>Scheme Procedure: <strong>frame-select</strong> <em>frame</em></dt> 274<dd><p>Set <var>frame</var> to be the selected frame. See <a href="Stack.html#Stack">Examining the 275Stack</a>. 276</p></dd></dl> 277 278<dl> 279<dt><a name="index-selected_002dframe"></a>Scheme Procedure: <strong>selected-frame</strong></dt> 280<dd><p>Return the selected frame object. See <a href="Selection.html#Selection">Selecting a Frame</a>. 281</p></dd></dl> 282 283<dl> 284<dt><a name="index-newest_002dframe"></a>Scheme Procedure: <strong>newest-frame</strong></dt> 285<dd><p>Return the newest frame object for the selected thread. 286</p></dd></dl> 287 288<dl> 289<dt><a name="index-unwind_002dstop_002dreason_002dstring"></a>Scheme Procedure: <strong>unwind-stop-reason-string</strong> <em>reason</em></dt> 290<dd><p>Return a string explaining the reason why <small>GDB</small> stopped unwinding 291frames, as expressed by the given <var>reason</var> code (an integer, see the 292<code>frame-unwind-stop-reason</code> procedure above in this section). 293</p></dd></dl> 294 295<hr> 296<div class="header"> 297<p> 298Next: <a href="Blocks-In-Guile.html#Blocks-In-Guile" accesskey="n" rel="next">Blocks In Guile</a>, Previous: <a href="Objfiles-In-Guile.html#Objfiles-In-Guile" accesskey="p" rel="previous">Objfiles In Guile</a>, Up: <a href="Guile-API.html#Guile-API" accesskey="u" rel="up">Guile API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 299</div> 300 301 302 303</body> 304</html> 305