1<html lang="en"> 2<head> 3<title>Frames In Python - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Python-API.html#Python-API" title="Python API"> 9<link rel="prev" href="Objfiles-In-Python.html#Objfiles-In-Python" title="Objfiles In Python"> 10<link rel="next" href="Blocks-In-Python.html#Blocks-In-Python" title="Blocks In Python"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Free Software'' and ``Free Software Needs 19Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 20and with the Back-Cover Texts as in (a) below. 21 22(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 23this GNU Manual. Buying copies from GNU Press supports the FSF in 24developing GNU and promoting software freedom.'' 25--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Frames-In-Python"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Blocks-In-Python.html#Blocks-In-Python">Blocks In Python</a>, 45Previous: <a rel="previous" accesskey="p" href="Objfiles-In-Python.html#Objfiles-In-Python">Objfiles In Python</a>, 46Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 47<hr> 48</div> 49 50<h5 class="subsubsection">23.2.2.20 Accessing inferior stack frames from Python.</h5> 51 52<p><a name="index-frames-in-python-2038"></a>When the debugged program stops, <span class="sc">gdb</span> is able to analyze its call 53stack (see <a href="Frames.html#Frames">Stack frames</a>). The <code>gdb.Frame</code> class 54represents a frame in the stack. A <code>gdb.Frame</code> object is only valid 55while its corresponding frame exists in the inferior's stack. If you try 56to use an invalid frame object, <span class="sc">gdb</span> will throw a <code>gdb.error</code> 57exception (see <a href="Exception-Handling.html#Exception-Handling">Exception Handling</a>). 58 59 <p>Two <code>gdb.Frame</code> objects can be compared for equality with the <code>==</code> 60operator, like: 61 62<pre class="smallexample"> (gdb) python print gdb.newest_frame() == gdb.selected_frame () 63 True 64</pre> 65 <p>The following frame-related functions are available in the <code>gdb</code> module: 66 67 <p><a name="index-gdb_002eselected_005fframe-2039"></a> 68 69<div class="defun"> 70— Function: <b>gdb.selected_frame</b> ()<var><a name="index-gdb_002eselected_005fframe-2040"></a></var><br> 71<blockquote><p>Return the selected frame object. (see <a href="Selection.html#Selection">Selecting a Frame</a>). 72</p></blockquote></div> 73 74 <p><a name="index-gdb_002enewest_005fframe-2041"></a> 75 76<div class="defun"> 77— Function: <b>gdb.newest_frame</b> ()<var><a name="index-gdb_002enewest_005fframe-2042"></a></var><br> 78<blockquote><p>Return the newest frame object for the selected thread. 79</p></blockquote></div> 80 81<div class="defun"> 82— Function: <b>gdb.frame_stop_reason_string</b> (<var>reason</var>)<var><a name="index-gdb_002eframe_005fstop_005freason_005fstring-2043"></a></var><br> 83<blockquote><p>Return a string explaining the reason why <span class="sc">gdb</span> stopped unwinding 84frames, as expressed by the given <var>reason</var> code (an integer, see the 85<code>unwind_stop_reason</code> method further down in this section). 86</p></blockquote></div> 87 88 <p>A <code>gdb.Frame</code> object has the following methods: 89 90<div class="defun"> 91— Function: <b>Frame.is_valid</b> ()<var><a name="index-Frame_002eis_005fvalid-2044"></a></var><br> 92<blockquote><p>Returns true if the <code>gdb.Frame</code> object is valid, false if not. 93A frame object can become invalid if the frame it refers to doesn't 94exist anymore in the inferior. All <code>gdb.Frame</code> methods will throw 95an exception if it is invalid at the time the method is called. 96</p></blockquote></div> 97 98<div class="defun"> 99— Function: <b>Frame.name</b> ()<var><a name="index-Frame_002ename-2045"></a></var><br> 100<blockquote><p>Returns the function name of the frame, or <code>None</code> if it can't be 101obtained. 102</p></blockquote></div> 103 104<div class="defun"> 105— Function: <b>Frame.architecture</b> ()<var><a name="index-Frame_002earchitecture-2046"></a></var><br> 106<blockquote><p>Returns the <code>gdb.Architecture</code> object corresponding to the frame's 107architecture. See <a href="Architectures-In-Python.html#Architectures-In-Python">Architectures In Python</a>. 108</p></blockquote></div> 109 110<div class="defun"> 111— Function: <b>Frame.type</b> ()<var><a name="index-Frame_002etype-2047"></a></var><br> 112<blockquote><p>Returns the type of the frame. The value can be one of: 113 <dl> 114<dt><code>gdb.NORMAL_FRAME</code><dd>An ordinary stack frame. 115 116 <br><dt><code>gdb.DUMMY_FRAME</code><dd>A fake stack frame that was created by <span class="sc">gdb</span> when performing an 117inferior function call. 118 119 <br><dt><code>gdb.INLINE_FRAME</code><dd>A frame representing an inlined function. The function was inlined 120into a <code>gdb.NORMAL_FRAME</code> that is older than this one. 121 122 <br><dt><code>gdb.TAILCALL_FRAME</code><dd>A frame representing a tail call. See <a href="Tail-Call-Frames.html#Tail-Call-Frames">Tail Call Frames</a>. 123 124 <br><dt><code>gdb.SIGTRAMP_FRAME</code><dd>A signal trampoline frame. This is the frame created by the OS when 125it calls into a signal handler. 126 127 <br><dt><code>gdb.ARCH_FRAME</code><dd>A fake stack frame representing a cross-architecture call. 128 129 <br><dt><code>gdb.SENTINEL_FRAME</code><dd>This is like <code>gdb.NORMAL_FRAME</code>, but it is only used for the 130newest frame. 131</dl> 132 </p></blockquote></div> 133 134<div class="defun"> 135— Function: <b>Frame.unwind_stop_reason</b> ()<var><a name="index-Frame_002eunwind_005fstop_005freason-2048"></a></var><br> 136<blockquote><p>Return an integer representing the reason why it's not possible to find 137more frames toward the outermost frame. Use 138<code>gdb.frame_stop_reason_string</code> to convert the value returned by this 139function to a string. The value can be one of: 140 141 <dl> 142<dt><code>gdb.FRAME_UNWIND_NO_REASON</code><dd>No particular reason (older frames should be available). 143 144 <br><dt><code>gdb.FRAME_UNWIND_NULL_ID</code><dd>The previous frame's analyzer returns an invalid result. 145 146 <br><dt><code>gdb.FRAME_UNWIND_OUTERMOST</code><dd>This frame is the outermost. 147 148 <br><dt><code>gdb.FRAME_UNWIND_UNAVAILABLE</code><dd>Cannot unwind further, because that would require knowing the 149values of registers or memory that have not been collected. 150 151 <br><dt><code>gdb.FRAME_UNWIND_INNER_ID</code><dd>This frame ID looks like it ought to belong to a NEXT frame, 152but we got it for a PREV frame. Normally, this is a sign of 153unwinder failure. It could also indicate stack corruption. 154 155 <br><dt><code>gdb.FRAME_UNWIND_SAME_ID</code><dd>This frame has the same ID as the previous one. That means 156that unwinding further would almost certainly give us another 157frame with exactly the same ID, so break the chain. Normally, 158this is a sign of unwinder failure. It could also indicate 159stack corruption. 160 161 <br><dt><code>gdb.FRAME_UNWIND_NO_SAVED_PC</code><dd>The frame unwinder did not find any saved PC, but we needed 162one to unwind further. 163 164 <br><dt><code>gdb.FRAME_UNWIND_FIRST_ERROR</code><dd>Any stop reason greater or equal to this value indicates some kind 165of error. This special value facilitates writing code that tests 166for errors in unwinding in a way that will work correctly even if 167the list of the other values is modified in future <span class="sc">gdb</span> 168versions. Using it, you could write: 169 <pre class="smallexample"> reason = gdb.selected_frame().unwind_stop_reason () 170 reason_str = gdb.frame_stop_reason_string (reason) 171 if reason >= gdb.FRAME_UNWIND_FIRST_ERROR: 172 print "An error occured: %s" % reason_str 173</pre> 174 </dl> 175 176 </blockquote></div> 177 178<div class="defun"> 179— Function: <b>Frame.pc</b> ()<var><a name="index-Frame_002epc-2049"></a></var><br> 180<blockquote><p>Returns the frame's resume address. 181</p></blockquote></div> 182 183<div class="defun"> 184— Function: <b>Frame.block</b> ()<var><a name="index-Frame_002eblock-2050"></a></var><br> 185<blockquote><p>Return the frame's code block. See <a href="Blocks-In-Python.html#Blocks-In-Python">Blocks In Python</a>. 186</p></blockquote></div> 187 188<div class="defun"> 189— Function: <b>Frame.function</b> ()<var><a name="index-Frame_002efunction-2051"></a></var><br> 190<blockquote><p>Return the symbol for the function corresponding to this frame. 191See <a href="Symbols-In-Python.html#Symbols-In-Python">Symbols In Python</a>. 192</p></blockquote></div> 193 194<div class="defun"> 195— Function: <b>Frame.older</b> ()<var><a name="index-Frame_002eolder-2052"></a></var><br> 196<blockquote><p>Return the frame that called this frame. 197</p></blockquote></div> 198 199<div class="defun"> 200— Function: <b>Frame.newer</b> ()<var><a name="index-Frame_002enewer-2053"></a></var><br> 201<blockquote><p>Return the frame called by this frame. 202</p></blockquote></div> 203 204<div class="defun"> 205— Function: <b>Frame.find_sal</b> ()<var><a name="index-Frame_002efind_005fsal-2054"></a></var><br> 206<blockquote><p>Return the frame's symtab and line object. 207See <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>. 208</p></blockquote></div> 209 210<div class="defun"> 211— Function: <b>Frame.read_var</b> (<var>variable </var><span class="roman">[</span><var>, block</var><span class="roman">]</span>)<var><a name="index-Frame_002eread_005fvar-2055"></a></var><br> 212<blockquote><p>Return the value of <var>variable</var> in this frame. If the optional 213argument <var>block</var> is provided, search for the variable from that 214block; otherwise start at the frame's current block (which is 215determined by the frame's current program counter). <var>variable</var> 216must be a string or a <code>gdb.Symbol</code> object. <var>block</var> must be a 217<code>gdb.Block</code> object. 218</p></blockquote></div> 219 220<div class="defun"> 221— Function: <b>Frame.select</b> ()<var><a name="index-Frame_002eselect-2056"></a></var><br> 222<blockquote><p>Set this frame to be the selected frame. See <a href="Stack.html#Stack">Examining the Stack</a>. 223</p></blockquote></div> 224 225 </body></html> 226 227