1<html lang="en"> 2<head> 3<title>Frame Decorator API - 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="Frame-Filter-API.html#Frame-Filter-API" title="Frame Filter API"> 10<link rel="next" href="Writing-a-Frame-Filter.html#Writing-a-Frame-Filter" title="Writing a Frame Filter"> 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="Frame-Decorator-API"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Writing-a-Frame-Filter.html#Writing-a-Frame-Filter">Writing a Frame Filter</a>, 45Previous: <a rel="previous" accesskey="p" href="Frame-Filter-API.html#Frame-Filter-API">Frame Filter API</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.10 Decorating Frames.</h5> 51 52<p><a name="index-frame-decorator-api-1888"></a> 53Frame decorators are sister objects to frame filters (see <a href="Frame-Filter-API.html#Frame-Filter-API">Frame Filter API</a>). Frame decorators are applied by a frame filter and can 54only be used in conjunction with frame filters. 55 56 <p>The purpose of a frame decorator is to customize the printed content 57of each <code>gdb.Frame</code> in commands where frame filters are executed. 58This concept is called decorating a frame. Frame decorators decorate 59a <code>gdb.Frame</code> with Python code contained within each API call. 60This separates the actual data contained in a <code>gdb.Frame</code> from 61the decorated data produced by a frame decorator. This abstraction is 62necessary to maintain integrity of the data contained in each 63<code>gdb.Frame</code>. 64 65 <p>Frame decorators have a mandatory interface, defined below. 66 67 <p><span class="sc">gdb</span> already contains a frame decorator called 68<code>FrameDecorator</code>. This contains substantial amounts of 69boilerplate code to decorate the content of a <code>gdb.Frame</code>. It is 70recommended that other frame decorators inherit and extend this 71object, and only to override the methods needed. 72 73<div class="defun"> 74— Function: <b>FrameDecorator.elided</b> (<var>self</var>)<var><a name="index-FrameDecorator_002eelided-1889"></a></var><br> 75<blockquote> 76 <p>The <code>elided</code> method groups frames together in a hierarchical 77system. An example would be an interpreter, where multiple low-level 78frames make up a single call in the interpreted language. In this 79example, the frame filter would elide the low-level frames and present 80a single high-level frame, representing the call in the interpreted 81language, to the user. 82 83 <p>The <code>elided</code> function must return an iterable and this iterable 84must contain the frames that are being elided wrapped in a suitable 85frame decorator. If no frames are being elided this function may 86return an empty iterable, or <code>None</code>. Elided frames are indented 87from normal frames in a <code>CLI</code> backtrace, or in the case of 88<code>GDB/MI</code>, are placed in the <code>children</code> field of the eliding 89frame. 90 91 <p>It is the frame filter's task to also filter out the elided frames from 92the source iterator. This will avoid printing the frame twice. 93</p></blockquote></div> 94 95<div class="defun"> 96— Function: <b>FrameDecorator.function</b> (<var>self</var>)<var><a name="index-FrameDecorator_002efunction-1890"></a></var><br> 97<blockquote> 98 <p>This method returns the name of the function in the frame that is to 99be printed. 100 101 <p>This method must return a Python string describing the function, or 102<code>None</code>. 103 104 <p>If this function returns <code>None</code>, <span class="sc">gdb</span> will not print any 105data for this field. 106</p></blockquote></div> 107 108<div class="defun"> 109— Function: <b>FrameDecorator.address</b> (<var>self</var>)<var><a name="index-FrameDecorator_002eaddress-1891"></a></var><br> 110<blockquote> 111 <p>This method returns the address of the frame that is to be printed. 112 113 <p>This method must return a Python numeric integer type of sufficient 114size to describe the address of the frame, or <code>None</code>. 115 116 <p>If this function returns a <code>None</code>, <span class="sc">gdb</span> will not print 117any data for this field. 118</p></blockquote></div> 119 120<div class="defun"> 121— Function: <b>FrameDecorator.filename</b> (<var>self</var>)<var><a name="index-FrameDecorator_002efilename-1892"></a></var><br> 122<blockquote> 123 <p>This method returns the filename and path associated with this frame. 124 125 <p>This method must return a Python string containing the filename and 126the path to the object file backing the frame, or <code>None</code>. 127 128 <p>If this function returns a <code>None</code>, <span class="sc">gdb</span> will not print 129any data for this field. 130</p></blockquote></div> 131 132<div class="defun"> 133— Function: <b>FrameDecorator.line</b> (<var>self</var>)<var>:<a name="index-FrameDecorator_002eline-1893"></a></var><br> 134<blockquote> 135 <p>This method returns the line number associated with the current 136position within the function addressed by this frame. 137 138 <p>This method must return a Python integer type, or <code>None</code>. 139 140 <p>If this function returns a <code>None</code>, <span class="sc">gdb</span> will not print 141any data for this field. 142</p></blockquote></div> 143 144<div class="defun"> 145— Function: <b>FrameDecorator.frame_args</b> (<var>self</var>)<var><a name="index-FrameDecorator_002eframe_005fargs-1894"></a></var><br> 146<blockquote><p><a name="frame_005fargs"></a>This method must return an iterable, or <code>None</code>. Returning an 147empty iterable, or <code>None</code> means frame arguments will not be 148printed for this frame. This iterable must contain objects that 149implement two methods, described here. 150 151 <p>This object must implement a <code>argument</code> method which takes a 152single <code>self</code> parameter and must return a <code>gdb.Symbol</code> 153(see <a href="Symbols-In-Python.html#Symbols-In-Python">Symbols In Python</a>), or a Python string. The object must also 154implement a <code>value</code> method which takes a single <code>self</code> 155parameter and must return a <code>gdb.Value</code> (see <a href="Values-From-Inferior.html#Values-From-Inferior">Values From Inferior</a>), a Python value, or <code>None</code>. If the <code>value</code> 156method returns <code>None</code>, and the <code>argument</code> method returns a 157<code>gdb.Symbol</code>, <span class="sc">gdb</span> will look-up and print the value of 158the <code>gdb.Symbol</code> automatically. 159 160 <p>A brief example: 161 162 <pre class="smallexample"> class SymValueWrapper(): 163 164 def __init__(self, symbol, value): 165 self.sym = symbol 166 self.val = value 167 168 def value(self): 169 return self.val 170 171 def symbol(self): 172 return self.sym 173 174 class SomeFrameDecorator() 175 ... 176 ... 177 def frame_args(self): 178 args = [] 179 try: 180 block = self.inferior_frame.block() 181 except: 182 return None 183 184 # Iterate over all symbols in a block. Only add 185 # symbols that are arguments. 186 for sym in block: 187 if not sym.is_argument: 188 continue 189 args.append(SymValueWrapper(sym,None)) 190 191 # Add example synthetic argument. 192 args.append(SymValueWrapper(``foo'', 42)) 193 194 return args 195</pre> 196 </blockquote></div> 197 198<div class="defun"> 199— Function: <b>FrameDecorator.frame_locals</b> (<var>self</var>)<var><a name="index-FrameDecorator_002eframe_005flocals-1895"></a></var><br> 200<blockquote> 201 <p>This method must return an iterable or <code>None</code>. Returning an 202empty iterable, or <code>None</code> means frame local arguments will not be 203printed for this frame. 204 205 <p>The object interface, the description of the various strategies for 206reading frame locals, and the example are largely similar to those 207described in the <code>frame_args</code> function, (see <a href="frame_005fargs.html#frame_005fargs">The frame filter frame_args function</a>). Below is a modified example: 208 209 <pre class="smallexample"> class SomeFrameDecorator() 210 ... 211 ... 212 def frame_locals(self): 213 vars = [] 214 try: 215 block = self.inferior_frame.block() 216 except: 217 return None 218 219 # Iterate over all symbols in a block. Add all 220 # symbols, except arguments. 221 for sym in block: 222 if sym.is_argument: 223 continue 224 vars.append(SymValueWrapper(sym,None)) 225 226 # Add an example of a synthetic local variable. 227 vars.append(SymValueWrapper(``bar'', 99)) 228 229 return vars 230</pre> 231 </blockquote></div> 232 233<div class="defun"> 234— Function: <b>FrameDecorator.inferior_frame</b> (<var>self</var>)<var>:<a name="index-FrameDecorator_002einferior_005fframe-1896"></a></var><br> 235<blockquote> 236 <p>This method must return the underlying <code>gdb.Frame</code> that this 237frame decorator is decorating. <span class="sc">gdb</span> requires the underlying 238frame for internal frame information to determine how to print certain 239values when printing a frame. 240</p></blockquote></div> 241 242 </body></html> 243 244