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: Objfiles In Python</title> 18 19<meta name="description" content="Debugging with GDB: Objfiles In Python"> 20<meta name="keywords" content="Debugging with GDB: Objfiles In Python"> 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="Python-API.html#Python-API" rel="up" title="Python API"> 29<link href="Frames-In-Python.html#Frames-In-Python" rel="next" title="Frames In Python"> 30<link href="Progspaces-In-Python.html#Progspaces-In-Python" rel="previous" title="Progspaces In Python"> 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="Objfiles-In-Python"></a> 65<div class="header"> 66<p> 67Next: <a href="Frames-In-Python.html#Frames-In-Python" accesskey="n" rel="next">Frames In Python</a>, Previous: <a href="Progspaces-In-Python.html#Progspaces-In-Python" accesskey="p" rel="previous">Progspaces In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python 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="Objfiles-In-Python-1"></a> 71<h4 class="subsubsection">23.2.2.24 Objfiles In Python</h4> 72 73<a name="index-objfiles-in-python"></a> 74<a name="index-gdb_002eObjfile"></a> 75<a name="index-Objfile"></a> 76<p><small>GDB</small> loads symbols for an inferior from various 77symbol-containing files (see <a href="Files.html#Files">Files</a>). These include the primary 78executable file, any shared libraries used by the inferior, and any 79separate debug info files (see <a href="Separate-Debug-Files.html#Separate-Debug-Files">Separate Debug Files</a>). 80<small>GDB</small> calls these symbol-containing files <em>objfiles</em>. 81</p> 82<p>The following objfile-related functions are available in the 83<code>gdb</code> module: 84</p> 85<a name="index-gdb_002ecurrent_005fobjfile"></a> 86<dl> 87<dt><a name="index-gdb_002ecurrent_005fobjfile-1"></a>Function: <strong>gdb.current_objfile</strong> <em>()</em></dt> 88<dd><p>When auto-loading a Python script (see <a href="Python-Auto_002dloading.html#Python-Auto_002dloading">Python Auto-loading</a>), <small>GDB</small> 89sets the “current objfile” to the corresponding objfile. This 90function returns the current objfile. If there is no current objfile, 91this function returns <code>None</code>. 92</p></dd></dl> 93 94<a name="index-gdb_002eobjfiles"></a> 95<dl> 96<dt><a name="index-gdb_002eobjfiles-1"></a>Function: <strong>gdb.objfiles</strong> <em>()</em></dt> 97<dd><p>Return a sequence of objfiles referenced by the current program space. 98See <a href="#Objfiles-In-Python">Objfiles In Python</a>, and <a href="Progspaces-In-Python.html#Progspaces-In-Python">Progspaces In Python</a>. This is identical 99to <code>gdb.selected_inferior().progspace.objfiles()</code> and is included for 100historical compatibility. 101</p></dd></dl> 102 103<a name="index-gdb_002elookup_005fobjfile"></a> 104<dl> 105<dt><a name="index-gdb_002elookup_005fobjfile-1"></a>Function: <strong>gdb.lookup_objfile</strong> <em>(name <span class="roman">[</span>, by_build_id])</em></dt> 106<dd><p>Look up <var>name</var>, a file name or build ID, in the list of objfiles 107for the current program space (see <a href="Progspaces-In-Python.html#Progspaces-In-Python">Progspaces In Python</a>). 108If the objfile is not found throw the Python <code>ValueError</code> exception. 109</p> 110<p>If <var>name</var> is a relative file name, then it will match any 111source file name with the same trailing components. For example, if 112<var>name</var> is ‘<samp>gcc/expr.c</samp>’, then it will match source file 113name of <samp>/build/trunk/gcc/expr.c</samp>, but not 114<samp>/build/trunk/libcpp/expr.c</samp> or <samp>/build/trunk/gcc/x-expr.c</samp>. 115</p> 116<p>If <var>by_build_id</var> is provided and is <code>True</code> then <var>name</var> 117is the build ID of the objfile. Otherwise, <var>name</var> is a file name. 118This is supported only on some operating systems, notably those which use 119the ELF format for binary files and the <small>GNU</small> Binutils. For more details 120about this feature, see the description of the <samp>--build-id</samp> 121command-line option in <a href="http://sourceware.org/binutils/docs/ld/Options.html#Options">Command Line Options</a> in <cite>The GNU Linker</cite>. 122</p></dd></dl> 123 124<p>Each objfile is represented by an instance of the <code>gdb.Objfile</code> 125class. 126</p> 127<dl> 128<dt><a name="index-Objfile_002efilename"></a>Variable: <strong>Objfile.filename</strong></dt> 129<dd><p>The file name of the objfile as a string, with symbolic links resolved. 130</p> 131<p>The value is <code>None</code> if the objfile is no longer valid. 132See the <code>gdb.Objfile.is_valid</code> method, described below. 133</p></dd></dl> 134 135<dl> 136<dt><a name="index-Objfile_002eusername"></a>Variable: <strong>Objfile.username</strong></dt> 137<dd><p>The file name of the objfile as specified by the user as a string. 138</p> 139<p>The value is <code>None</code> if the objfile is no longer valid. 140See the <code>gdb.Objfile.is_valid</code> method, described below. 141</p></dd></dl> 142 143<dl> 144<dt><a name="index-Objfile_002eowner"></a>Variable: <strong>Objfile.owner</strong></dt> 145<dd><p>For separate debug info objfiles this is the corresponding <code>gdb.Objfile</code> 146object that debug info is being provided for. 147Otherwise this is <code>None</code>. 148Separate debug info objfiles are added with the 149<code>gdb.Objfile.add_separate_debug_file</code> method, described below. 150</p></dd></dl> 151 152<dl> 153<dt><a name="index-Objfile_002ebuild_005fid"></a>Variable: <strong>Objfile.build_id</strong></dt> 154<dd><p>The build ID of the objfile as a string. 155If the objfile does not have a build ID then the value is <code>None</code>. 156</p> 157<p>This is supported only on some operating systems, notably those which use 158the ELF format for binary files and the <small>GNU</small> Binutils. For more details 159about this feature, see the description of the <samp>--build-id</samp> 160command-line option in <a href="http://sourceware.org/binutils/docs/ld/Options.html#Options">Command Line Options</a> in <cite>The GNU Linker</cite>. 161</p></dd></dl> 162 163<dl> 164<dt><a name="index-Objfile_002eprogspace"></a>Variable: <strong>Objfile.progspace</strong></dt> 165<dd><p>The containing program space of the objfile as a <code>gdb.Progspace</code> 166object. See <a href="Progspaces-In-Python.html#Progspaces-In-Python">Progspaces In Python</a>. 167</p></dd></dl> 168 169<dl> 170<dt><a name="index-Objfile_002epretty_005fprinters"></a>Variable: <strong>Objfile.pretty_printers</strong></dt> 171<dd><p>The <code>pretty_printers</code> attribute is a list of functions. It is 172used to look up pretty-printers. A <code>Value</code> is passed to each 173function in order; if the function returns <code>None</code>, then the 174search continues. Otherwise, the return value should be an object 175which is used to format the value. See <a href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>, for more 176information. 177</p></dd></dl> 178 179<dl> 180<dt><a name="index-Objfile_002etype_005fprinters"></a>Variable: <strong>Objfile.type_printers</strong></dt> 181<dd><p>The <code>type_printers</code> attribute is a list of type printer objects. 182See <a href="Type-Printing-API.html#Type-Printing-API">Type Printing API</a>, for more information. 183</p></dd></dl> 184 185<dl> 186<dt><a name="index-Objfile_002eframe_005ffilters"></a>Variable: <strong>Objfile.frame_filters</strong></dt> 187<dd><p>The <code>frame_filters</code> attribute is a dictionary of frame filter 188objects. See <a href="Frame-Filter-API.html#Frame-Filter-API">Frame Filter API</a>, for more information. 189</p></dd></dl> 190 191<p>One may add arbitrary attributes to <code>gdb.Objfile</code> objects 192in the usual Python way. 193This is useful if, for example, one needs to do some extra record keeping 194associated with the objfile. 195</p> 196<p>In this contrived example we record the time when <small>GDB</small> 197loaded the objfile. 198</p> 199<div class="smallexample"> 200<pre class="smallexample">(gdb) python 201import datetime 202def new_objfile_handler(event): 203 # Set the time_loaded attribute of the new objfile. 204 event.new_objfile.time_loaded = datetime.datetime.today() 205gdb.events.new_objfile.connect(new_objfile_handler) 206end 207(gdb) file ./hello 208Reading symbols from ./hello... 209(gdb) python print gdb.objfiles()[0].time_loaded 2102014-10-09 11:41:36.770345 211</pre></div> 212 213<p>A <code>gdb.Objfile</code> object has the following methods: 214</p> 215<dl> 216<dt><a name="index-Objfile_002eis_005fvalid"></a>Function: <strong>Objfile.is_valid</strong> <em>()</em></dt> 217<dd><p>Returns <code>True</code> if the <code>gdb.Objfile</code> object is valid, 218<code>False</code> if not. A <code>gdb.Objfile</code> object can become invalid 219if the object file it refers to is not loaded in <small>GDB</small> any 220longer. All other <code>gdb.Objfile</code> methods will throw an exception 221if it is invalid at the time the method is called. 222</p></dd></dl> 223 224<dl> 225<dt><a name="index-Objfile_002eadd_005fseparate_005fdebug_005ffile"></a>Function: <strong>Objfile.add_separate_debug_file</strong> <em>(file)</em></dt> 226<dd><p>Add <var>file</var> to the list of files that <small>GDB</small> will search for 227debug information for the objfile. 228This is useful when the debug info has been removed from the program 229and stored in a separate file. <small>GDB</small> has built-in support for 230finding separate debug info files (see <a href="Separate-Debug-Files.html#Separate-Debug-Files">Separate Debug Files</a>), but if 231the file doesn’t live in one of the standard places that <small>GDB</small> 232searches then this function can be used to add a debug info file 233from a different place. 234</p></dd></dl> 235 236<dl> 237<dt><a name="index-Objfile_002elookup_005fglobal_005fsymbol"></a>Function: <strong>Objfile.lookup_global_symbol</strong> <em>(name <span class="roman">[</span>, domain<span class="roman">]</span>)</em></dt> 238<dd><p>Search for a global symbol named <var>name</var> in this objfile. Optionally, the 239search scope can be restricted with the <var>domain</var> argument. 240The <var>domain</var> argument must be a domain constant defined in the <code>gdb</code> 241module and described in <a href="Symbols-In-Python.html#Symbols-In-Python">Symbols In Python</a>. This function is similar to 242<code>gdb.lookup_global_symbol</code>, except that the search is limited to this 243objfile. 244</p> 245<p>The result is a <code>gdb.Symbol</code> object or <code>None</code> if the symbol 246is not found. 247</p></dd></dl> 248 249<dl> 250<dt><a name="index-Objfile_002elookup_005fstatic_005fsymbol"></a>Function: <strong>Objfile.lookup_static_symbol</strong> <em>(name <span class="roman">[</span>, domain<span class="roman">]</span>)</em></dt> 251<dd><p>Like <code>Objfile.lookup_global_symbol</code>, but searches for a global 252symbol with static linkage named <var>name</var> in this objfile. 253</p></dd></dl> 254 255<hr> 256<div class="header"> 257<p> 258Next: <a href="Frames-In-Python.html#Frames-In-Python" accesskey="n" rel="next">Frames In Python</a>, Previous: <a href="Progspaces-In-Python.html#Progspaces-In-Python" accesskey="p" rel="previous">Progspaces In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python 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> 259</div> 260 261 262 263</body> 264</html> 265