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: Symbols In Python</title> 18 19<meta name="description" content="Debugging with GDB: Symbols In Python"> 20<meta name="keywords" content="Debugging with GDB: Symbols 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="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python" rel="next" title="Symbol Tables In Python"> 30<link href="Blocks-In-Python.html#Blocks-In-Python" rel="previous" title="Blocks 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="Symbols-In-Python"></a> 65<div class="header"> 66<p> 67Next: <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python" accesskey="n" rel="next">Symbol Tables In Python</a>, Previous: <a href="Blocks-In-Python.html#Blocks-In-Python" accesskey="p" rel="previous">Blocks 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="Python-representation-of-Symbols"></a> 71<h4 class="subsubsection">23.2.2.27 Python representation of Symbols</h4> 72 73<a name="index-symbols-in-python"></a> 74<a name="index-gdb_002eSymbol"></a> 75 76<p><small>GDB</small> represents every variable, function and type as an 77entry in a symbol table. See <a href="Symbols.html#Symbols">Examining the Symbol Table</a>. 78Similarly, Python represents these symbols in <small>GDB</small> with the 79<code>gdb.Symbol</code> object. 80</p> 81<p>The following symbol-related functions are available in the <code>gdb</code> 82module: 83</p> 84<a name="index-gdb_002elookup_005fsymbol"></a> 85<dl> 86<dt><a name="index-gdb_002elookup_005fsymbol-1"></a>Function: <strong>gdb.lookup_symbol</strong> <em>(name <span class="roman">[</span>, block <span class="roman">[</span>, domain<span class="roman">]]</span>)</em></dt> 87<dd><p>This function searches for a symbol by name. The search scope can be 88restricted to the parameters defined in the optional domain and block 89arguments. 90</p> 91<p><var>name</var> is the name of the symbol. It must be a string. The 92optional <var>block</var> argument restricts the search to symbols visible 93in that <var>block</var>. The <var>block</var> argument must be a 94<code>gdb.Block</code> object. If omitted, the block for the current frame 95is used. The optional <var>domain</var> argument restricts 96the search to the domain type. The <var>domain</var> argument must be a 97domain constant defined in the <code>gdb</code> module and described later 98in this chapter. 99</p> 100<p>The result is a tuple of two elements. 101The first element is a <code>gdb.Symbol</code> object or <code>None</code> if the symbol 102is not found. 103If the symbol is found, the second element is <code>True</code> if the symbol 104is a field of a method’s object (e.g., <code>this</code> in C<tt>++</tt>), 105otherwise it is <code>False</code>. 106If the symbol is not found, the second element is <code>False</code>. 107</p></dd></dl> 108 109<a name="index-gdb_002elookup_005fglobal_005fsymbol"></a> 110<dl> 111<dt><a name="index-gdb_002elookup_005fglobal_005fsymbol-1"></a>Function: <strong>gdb.lookup_global_symbol</strong> <em>(name <span class="roman">[</span>, domain<span class="roman">]</span>)</em></dt> 112<dd><p>This function searches for a global symbol by name. 113The search scope can be restricted to by the domain argument. 114</p> 115<p><var>name</var> is the name of the symbol. It must be a string. 116The optional <var>domain</var> argument restricts the search to the domain type. 117The <var>domain</var> argument must be a domain constant defined in the <code>gdb</code> 118module and described later in this chapter. 119</p> 120<p>The result is a <code>gdb.Symbol</code> object or <code>None</code> if the symbol 121is not found. 122</p></dd></dl> 123 124<a name="index-gdb_002elookup_005fstatic_005fsymbol"></a> 125<dl> 126<dt><a name="index-gdb_002elookup_005fstatic_005fsymbol-1"></a>Function: <strong>gdb.lookup_static_symbol</strong> <em>(name <span class="roman">[</span>, domain<span class="roman">]</span>)</em></dt> 127<dd><p>This function searches for a global symbol with static linkage by name. 128The search scope can be restricted to by the domain argument. 129</p> 130<p><var>name</var> is the name of the symbol. It must be a string. 131The optional <var>domain</var> argument restricts the search to the domain type. 132The <var>domain</var> argument must be a domain constant defined in the <code>gdb</code> 133module and described later in this chapter. 134</p> 135<p>The result is a <code>gdb.Symbol</code> object or <code>None</code> if the symbol 136is not found. 137</p> 138<p>Note that this function will not find function-scoped static variables. To look 139up such variables, iterate over the variables of the function’s 140<code>gdb.Block</code> and check that <code>block.addr_class</code> is 141<code>gdb.SYMBOL_LOC_STATIC</code>. 142</p> 143<p>There can be multiple global symbols with static linkage with the same 144name. This function will only return the first matching symbol that 145it finds. Which symbol is found depends on where <small>GDB</small> is 146currently stopped, as <small>GDB</small> will first search for matching 147symbols in the current object file, and then search all other object 148files. If the application is not yet running then <small>GDB</small> will 149search all object files in the order they appear in the debug 150information. 151</p></dd></dl> 152 153<a name="index-gdb_002elookup_005fstatic_005fsymbols"></a> 154<dl> 155<dt><a name="index-gdb_002elookup_005fstatic_005fsymbols-1"></a>Function: <strong>gdb.lookup_static_symbols</strong> <em>(name <span class="roman">[</span>, domain<span class="roman">]</span>)</em></dt> 156<dd><p>Similar to <code>gdb.lookup_static_symbol</code>, this function searches for 157global symbols with static linkage by name, and optionally restricted 158by the domain argument. However, this function returns a list of all 159matching symbols found, not just the first one. 160</p> 161<p><var>name</var> is the name of the symbol. It must be a string. 162The optional <var>domain</var> argument restricts the search to the domain type. 163The <var>domain</var> argument must be a domain constant defined in the <code>gdb</code> 164module and described later in this chapter. 165</p> 166<p>The result is a list of <code>gdb.Symbol</code> objects which could be empty 167if no matching symbols were found. 168</p> 169<p>Note that this function will not find function-scoped static variables. To look 170up such variables, iterate over the variables of the function’s 171<code>gdb.Block</code> and check that <code>block.addr_class</code> is 172<code>gdb.SYMBOL_LOC_STATIC</code>. 173</p></dd></dl> 174 175<p>A <code>gdb.Symbol</code> object has the following attributes: 176</p> 177<dl> 178<dt><a name="index-Symbol_002etype"></a>Variable: <strong>Symbol.type</strong></dt> 179<dd><p>The type of the symbol or <code>None</code> if no type is recorded. 180This attribute is represented as a <code>gdb.Type</code> object. 181See <a href="Types-In-Python.html#Types-In-Python">Types In Python</a>. This attribute is not writable. 182</p></dd></dl> 183 184<dl> 185<dt><a name="index-Symbol_002esymtab"></a>Variable: <strong>Symbol.symtab</strong></dt> 186<dd><p>The symbol table in which the symbol appears. This attribute is 187represented as a <code>gdb.Symtab</code> object. See <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>. This attribute is not writable. 188</p></dd></dl> 189 190<dl> 191<dt><a name="index-Symbol_002eline"></a>Variable: <strong>Symbol.line</strong></dt> 192<dd><p>The line number in the source code at which the symbol was defined. 193This is an integer. 194</p></dd></dl> 195 196<dl> 197<dt><a name="index-Symbol_002ename"></a>Variable: <strong>Symbol.name</strong></dt> 198<dd><p>The name of the symbol as a string. This attribute is not writable. 199</p></dd></dl> 200 201<dl> 202<dt><a name="index-Symbol_002elinkage_005fname"></a>Variable: <strong>Symbol.linkage_name</strong></dt> 203<dd><p>The name of the symbol, as used by the linker (i.e., may be mangled). 204This attribute is not writable. 205</p></dd></dl> 206 207<dl> 208<dt><a name="index-Symbol_002eprint_005fname"></a>Variable: <strong>Symbol.print_name</strong></dt> 209<dd><p>The name of the symbol in a form suitable for output. This is either 210<code>name</code> or <code>linkage_name</code>, depending on whether the user 211asked <small>GDB</small> to display demangled or mangled names. 212</p></dd></dl> 213 214<dl> 215<dt><a name="index-Symbol_002eaddr_005fclass"></a>Variable: <strong>Symbol.addr_class</strong></dt> 216<dd><p>The address class of the symbol. This classifies how to find the value 217of a symbol. Each address class is a constant defined in the 218<code>gdb</code> module and described later in this chapter. 219</p></dd></dl> 220 221<dl> 222<dt><a name="index-Symbol_002eneeds_005fframe"></a>Variable: <strong>Symbol.needs_frame</strong></dt> 223<dd><p>This is <code>True</code> if evaluating this symbol’s value requires a frame 224(see <a href="Frames-In-Python.html#Frames-In-Python">Frames In Python</a>) and <code>False</code> otherwise. Typically, 225local variables will require a frame, but other symbols will not. 226</p></dd></dl> 227 228<dl> 229<dt><a name="index-Symbol_002eis_005fargument"></a>Variable: <strong>Symbol.is_argument</strong></dt> 230<dd><p><code>True</code> if the symbol is an argument of a function. 231</p></dd></dl> 232 233<dl> 234<dt><a name="index-Symbol_002eis_005fconstant"></a>Variable: <strong>Symbol.is_constant</strong></dt> 235<dd><p><code>True</code> if the symbol is a constant. 236</p></dd></dl> 237 238<dl> 239<dt><a name="index-Symbol_002eis_005ffunction"></a>Variable: <strong>Symbol.is_function</strong></dt> 240<dd><p><code>True</code> if the symbol is a function or a method. 241</p></dd></dl> 242 243<dl> 244<dt><a name="index-Symbol_002eis_005fvariable"></a>Variable: <strong>Symbol.is_variable</strong></dt> 245<dd><p><code>True</code> if the symbol is a variable. 246</p></dd></dl> 247 248<p>A <code>gdb.Symbol</code> object has the following methods: 249</p> 250<dl> 251<dt><a name="index-Symbol_002eis_005fvalid"></a>Function: <strong>Symbol.is_valid</strong> <em>()</em></dt> 252<dd><p>Returns <code>True</code> if the <code>gdb.Symbol</code> object is valid, 253<code>False</code> if not. A <code>gdb.Symbol</code> object can become invalid if 254the symbol it refers to does not exist in <small>GDB</small> any longer. 255All other <code>gdb.Symbol</code> methods will throw an exception if it is 256invalid at the time the method is called. 257</p></dd></dl> 258 259<dl> 260<dt><a name="index-Symbol_002evalue"></a>Function: <strong>Symbol.value</strong> <em>(<span class="roman">[</span>frame<span class="roman">]</span>)</em></dt> 261<dd><p>Compute the value of the symbol, as a <code>gdb.Value</code>. For 262functions, this computes the address of the function, cast to the 263appropriate type. If the symbol requires a frame in order to compute 264its value, then <var>frame</var> must be given. If <var>frame</var> is not 265given, or if <var>frame</var> is invalid, then this method will throw an 266exception. 267</p></dd></dl> 268 269<p>The available domain categories in <code>gdb.Symbol</code> are represented 270as constants in the <code>gdb</code> module: 271</p> 272<dl compact="compact"> 273<dd><a name="index-SYMBOL_005fUNDEF_005fDOMAIN"></a> 274</dd> 275<dt><code>gdb.SYMBOL_UNDEF_DOMAIN</code> 276<a name="index-gdb_002eSYMBOL_005fUNDEF_005fDOMAIN"></a> 277</dt> 278<dd><p>This is used when a domain has not been discovered or none of the 279following domains apply. This usually indicates an error either 280in the symbol information or in <small>GDB</small>’s handling of symbols. 281</p> 282<a name="index-SYMBOL_005fVAR_005fDOMAIN"></a> 283</dd> 284<dt><code>gdb.SYMBOL_VAR_DOMAIN</code> 285<a name="index-gdb_002eSYMBOL_005fVAR_005fDOMAIN"></a> 286</dt> 287<dd><p>This domain contains variables, function names, typedef names and enum 288type values. 289</p> 290<a name="index-SYMBOL_005fSTRUCT_005fDOMAIN"></a> 291</dd> 292<dt><code>gdb.SYMBOL_STRUCT_DOMAIN</code> 293<a name="index-gdb_002eSYMBOL_005fSTRUCT_005fDOMAIN"></a> 294</dt> 295<dd><p>This domain holds struct, union and enum type names. 296</p> 297<a name="index-SYMBOL_005fLABEL_005fDOMAIN"></a> 298</dd> 299<dt><code>gdb.SYMBOL_LABEL_DOMAIN</code> 300<a name="index-gdb_002eSYMBOL_005fLABEL_005fDOMAIN"></a> 301</dt> 302<dd><p>This domain contains names of labels (for gotos). 303</p> 304<a name="index-SYMBOL_005fMODULE_005fDOMAIN"></a> 305</dd> 306<dt><code>gdb.SYMBOL_MODULE_DOMAIN</code> 307<a name="index-gdb_002eSYMBOL_005fMODULE_005fDOMAIN"></a> 308</dt> 309<dd><p>This domain contains names of Fortran module types. 310</p> 311<a name="index-SYMBOL_005fCOMMON_005fBLOCK_005fDOMAIN"></a> 312</dd> 313<dt><code>gdb.SYMBOL_COMMON_BLOCK_DOMAIN</code> 314<a name="index-gdb_002eSYMBOL_005fCOMMON_005fBLOCK_005fDOMAIN"></a> 315</dt> 316<dd><p>This domain contains names of Fortran common blocks. 317</p></dd> 318</dl> 319 320<p>The available address class categories in <code>gdb.Symbol</code> are represented 321as constants in the <code>gdb</code> module: 322</p> 323<dl compact="compact"> 324<dd><a name="index-SYMBOL_005fLOC_005fUNDEF"></a> 325</dd> 326<dt><code>gdb.SYMBOL_LOC_UNDEF</code> 327<a name="index-gdb_002eSYMBOL_005fLOC_005fUNDEF"></a> 328</dt> 329<dd><p>If this is returned by address class, it indicates an error either in 330the symbol information or in <small>GDB</small>’s handling of symbols. 331</p> 332<a name="index-SYMBOL_005fLOC_005fCONST"></a> 333</dd> 334<dt><code>gdb.SYMBOL_LOC_CONST</code> 335<a name="index-gdb_002eSYMBOL_005fLOC_005fCONST"></a> 336</dt> 337<dd><p>Value is constant int. 338</p> 339<a name="index-SYMBOL_005fLOC_005fSTATIC"></a> 340</dd> 341<dt><code>gdb.SYMBOL_LOC_STATIC</code> 342<a name="index-gdb_002eSYMBOL_005fLOC_005fSTATIC"></a> 343</dt> 344<dd><p>Value is at a fixed address. 345</p> 346<a name="index-SYMBOL_005fLOC_005fREGISTER"></a> 347</dd> 348<dt><code>gdb.SYMBOL_LOC_REGISTER</code> 349<a name="index-gdb_002eSYMBOL_005fLOC_005fREGISTER"></a> 350</dt> 351<dd><p>Value is in a register. 352</p> 353<a name="index-SYMBOL_005fLOC_005fARG"></a> 354</dd> 355<dt><code>gdb.SYMBOL_LOC_ARG</code> 356<a name="index-gdb_002eSYMBOL_005fLOC_005fARG"></a> 357</dt> 358<dd><p>Value is an argument. This value is at the offset stored within the 359symbol inside the frame’s argument list. 360</p> 361<a name="index-SYMBOL_005fLOC_005fREF_005fARG"></a> 362</dd> 363<dt><code>gdb.SYMBOL_LOC_REF_ARG</code> 364<a name="index-gdb_002eSYMBOL_005fLOC_005fREF_005fARG"></a> 365</dt> 366<dd><p>Value address is stored in the frame’s argument list. Just like 367<code>LOC_ARG</code> except that the value’s address is stored at the 368offset, not the value itself. 369</p> 370<a name="index-SYMBOL_005fLOC_005fREGPARM_005fADDR"></a> 371</dd> 372<dt><code>gdb.SYMBOL_LOC_REGPARM_ADDR</code> 373<a name="index-gdb_002eSYMBOL_005fLOC_005fREGPARM_005fADDR"></a> 374</dt> 375<dd><p>Value is a specified register. Just like <code>LOC_REGISTER</code> except 376the register holds the address of the argument instead of the argument 377itself. 378</p> 379<a name="index-SYMBOL_005fLOC_005fLOCAL"></a> 380</dd> 381<dt><code>gdb.SYMBOL_LOC_LOCAL</code> 382<a name="index-gdb_002eSYMBOL_005fLOC_005fLOCAL"></a> 383</dt> 384<dd><p>Value is a local variable. 385</p> 386<a name="index-SYMBOL_005fLOC_005fTYPEDEF"></a> 387</dd> 388<dt><code>gdb.SYMBOL_LOC_TYPEDEF</code> 389<a name="index-gdb_002eSYMBOL_005fLOC_005fTYPEDEF"></a> 390</dt> 391<dd><p>Value not used. Symbols in the domain <code>SYMBOL_STRUCT_DOMAIN</code> all 392have this class. 393</p> 394<a name="index-SYMBOL_005fLOC_005fBLOCK"></a> 395</dd> 396<dt><code>gdb.SYMBOL_LOC_BLOCK</code> 397<a name="index-gdb_002eSYMBOL_005fLOC_005fBLOCK"></a> 398</dt> 399<dd><p>Value is a block. 400</p> 401<a name="index-SYMBOL_005fLOC_005fCONST_005fBYTES"></a> 402</dd> 403<dt><code>gdb.SYMBOL_LOC_CONST_BYTES</code> 404<a name="index-gdb_002eSYMBOL_005fLOC_005fCONST_005fBYTES"></a> 405</dt> 406<dd><p>Value is a byte-sequence. 407</p> 408<a name="index-SYMBOL_005fLOC_005fUNRESOLVED"></a> 409</dd> 410<dt><code>gdb.SYMBOL_LOC_UNRESOLVED</code> 411<a name="index-gdb_002eSYMBOL_005fLOC_005fUNRESOLVED"></a> 412</dt> 413<dd><p>Value is at a fixed address, but the address of the variable has to be 414determined from the minimal symbol table whenever the variable is 415referenced. 416</p> 417<a name="index-SYMBOL_005fLOC_005fOPTIMIZED_005fOUT"></a> 418</dd> 419<dt><code>gdb.SYMBOL_LOC_OPTIMIZED_OUT</code> 420<a name="index-gdb_002eSYMBOL_005fLOC_005fOPTIMIZED_005fOUT"></a> 421</dt> 422<dd><p>The value does not actually exist in the program. 423</p> 424<a name="index-SYMBOL_005fLOC_005fCOMPUTED"></a> 425</dd> 426<dt><code>gdb.SYMBOL_LOC_COMPUTED</code> 427<a name="index-gdb_002eSYMBOL_005fLOC_005fCOMPUTED"></a> 428</dt> 429<dd><p>The value’s address is a computed location. 430</p> 431<a name="index-SYMBOL_005fLOC_005fCOMPUTED-1"></a> 432</dd> 433<dt><code>gdb.SYMBOL_LOC_COMPUTED</code> 434<a name="index-gdb_002eSYMBOL_005fLOC_005fCOMPUTED-1"></a> 435</dt> 436<dd><p>The value’s address is a symbol. This is only used for Fortran common 437blocks. 438</p></dd> 439</dl> 440 441<hr> 442<div class="header"> 443<p> 444Next: <a href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python" accesskey="n" rel="next">Symbol Tables In Python</a>, Previous: <a href="Blocks-In-Python.html#Blocks-In-Python" accesskey="p" rel="previous">Blocks 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> 445</div> 446 447 448 449</body> 450</html> 451