1<html lang="en"> 2<head> 3<title>Symbols 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="Blocks-In-Python.html#Blocks-In-Python" title="Blocks In Python"> 10<link rel="next" href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python" title="Symbol Tables 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="Symbols-In-Python"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Symbol-Tables-In-Python.html#Symbol-Tables-In-Python">Symbol Tables In Python</a>, 45Previous: <a rel="previous" accesskey="p" href="Blocks-In-Python.html#Blocks-In-Python">Blocks 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.22 Python representation of Symbols.</h5> 51 52<p><a name="index-symbols-in-python-2070"></a><a name="index-gdb_002eSymbol-2071"></a> 53<span class="sc">gdb</span> represents every variable, function and type as an 54entry in a symbol table. See <a href="Symbols.html#Symbols">Examining the Symbol Table</a>. 55Similarly, Python represents these symbols in <span class="sc">gdb</span> with the 56<code>gdb.Symbol</code> object. 57 58 <p>The following symbol-related functions are available in the <code>gdb</code> 59module: 60 61 <p><a name="index-gdb_002elookup_005fsymbol-2072"></a> 62 63<div class="defun"> 64— Function: <b>gdb.lookup_symbol</b> (<var>name </var><span class="roman">[</span><var>, block </var><span class="roman">[</span><var>, domain</var><span class="roman">]]</span>)<var><a name="index-gdb_002elookup_005fsymbol-2073"></a></var><br> 65<blockquote><p>This function searches for a symbol by name. The search scope can be 66restricted to the parameters defined in the optional domain and block 67arguments. 68 69 <p><var>name</var> is the name of the symbol. It must be a string. The 70optional <var>block</var> argument restricts the search to symbols visible 71in that <var>block</var>. The <var>block</var> argument must be a 72<code>gdb.Block</code> object. If omitted, the block for the current frame 73is used. The optional <var>domain</var> argument restricts 74the search to the domain type. The <var>domain</var> argument must be a 75domain constant defined in the <code>gdb</code> module and described later 76in this chapter. 77 78 <p>The result is a tuple of two elements. 79The first element is a <code>gdb.Symbol</code> object or <code>None</code> if the symbol 80is not found. 81If the symbol is found, the second element is <code>True</code> if the symbol 82is a field of a method's object (e.g., <code>this</code> in C<tt>++</tt>), 83otherwise it is <code>False</code>. 84If the symbol is not found, the second element is <code>False</code>. 85</p></blockquote></div> 86 87 <p><a name="index-gdb_002elookup_005fglobal_005fsymbol-2074"></a> 88 89<div class="defun"> 90— Function: <b>gdb.lookup_global_symbol</b> (<var>name </var><span class="roman">[</span><var>, domain</var><span class="roman">]</span>)<var><a name="index-gdb_002elookup_005fglobal_005fsymbol-2075"></a></var><br> 91<blockquote><p>This function searches for a global symbol by name. 92The search scope can be restricted to by the domain argument. 93 94 <p><var>name</var> is the name of the symbol. It must be a string. 95The optional <var>domain</var> argument restricts the search to the domain type. 96The <var>domain</var> argument must be a domain constant defined in the <code>gdb</code> 97module and described later in this chapter. 98 99 <p>The result is a <code>gdb.Symbol</code> object or <code>None</code> if the symbol 100is not found. 101</p></blockquote></div> 102 103 <p>A <code>gdb.Symbol</code> object has the following attributes: 104 105<div class="defun"> 106— Variable: <b>Symbol.type</b><var><a name="index-Symbol_002etype-2076"></a></var><br> 107<blockquote><p>The type of the symbol or <code>None</code> if no type is recorded. 108This attribute is represented as a <code>gdb.Type</code> object. 109See <a href="Types-In-Python.html#Types-In-Python">Types In Python</a>. This attribute is not writable. 110</p></blockquote></div> 111 112<div class="defun"> 113— Variable: <b>Symbol.symtab</b><var><a name="index-Symbol_002esymtab-2077"></a></var><br> 114<blockquote><p>The symbol table in which the symbol appears. This attribute is 115represented 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. 116</p></blockquote></div> 117 118<div class="defun"> 119— Variable: <b>Symbol.line</b><var><a name="index-Symbol_002eline-2078"></a></var><br> 120<blockquote><p>The line number in the source code at which the symbol was defined. 121This is an integer. 122</p></blockquote></div> 123 124<div class="defun"> 125— Variable: <b>Symbol.name</b><var><a name="index-Symbol_002ename-2079"></a></var><br> 126<blockquote><p>The name of the symbol as a string. This attribute is not writable. 127</p></blockquote></div> 128 129<div class="defun"> 130— Variable: <b>Symbol.linkage_name</b><var><a name="index-Symbol_002elinkage_005fname-2080"></a></var><br> 131<blockquote><p>The name of the symbol, as used by the linker (i.e., may be mangled). 132This attribute is not writable. 133</p></blockquote></div> 134 135<div class="defun"> 136— Variable: <b>Symbol.print_name</b><var><a name="index-Symbol_002eprint_005fname-2081"></a></var><br> 137<blockquote><p>The name of the symbol in a form suitable for output. This is either 138<code>name</code> or <code>linkage_name</code>, depending on whether the user 139asked <span class="sc">gdb</span> to display demangled or mangled names. 140</p></blockquote></div> 141 142<div class="defun"> 143— Variable: <b>Symbol.addr_class</b><var><a name="index-Symbol_002eaddr_005fclass-2082"></a></var><br> 144<blockquote><p>The address class of the symbol. This classifies how to find the value 145of a symbol. Each address class is a constant defined in the 146<code>gdb</code> module and described later in this chapter. 147</p></blockquote></div> 148 149<div class="defun"> 150— Variable: <b>Symbol.needs_frame</b><var><a name="index-Symbol_002eneeds_005fframe-2083"></a></var><br> 151<blockquote><p>This is <code>True</code> if evaluating this symbol's value requires a frame 152(see <a href="Frames-In-Python.html#Frames-In-Python">Frames In Python</a>) and <code>False</code> otherwise. Typically, 153local variables will require a frame, but other symbols will not. 154</p></blockquote></div> 155 156<div class="defun"> 157— Variable: <b>Symbol.is_argument</b><var><a name="index-Symbol_002eis_005fargument-2084"></a></var><br> 158<blockquote><p><code>True</code> if the symbol is an argument of a function. 159</p></blockquote></div> 160 161<div class="defun"> 162— Variable: <b>Symbol.is_constant</b><var><a name="index-Symbol_002eis_005fconstant-2085"></a></var><br> 163<blockquote><p><code>True</code> if the symbol is a constant. 164</p></blockquote></div> 165 166<div class="defun"> 167— Variable: <b>Symbol.is_function</b><var><a name="index-Symbol_002eis_005ffunction-2086"></a></var><br> 168<blockquote><p><code>True</code> if the symbol is a function or a method. 169</p></blockquote></div> 170 171<div class="defun"> 172— Variable: <b>Symbol.is_variable</b><var><a name="index-Symbol_002eis_005fvariable-2087"></a></var><br> 173<blockquote><p><code>True</code> if the symbol is a variable. 174</p></blockquote></div> 175 176 <p>A <code>gdb.Symbol</code> object has the following methods: 177 178<div class="defun"> 179— Function: <b>Symbol.is_valid</b> ()<var><a name="index-Symbol_002eis_005fvalid-2088"></a></var><br> 180<blockquote><p>Returns <code>True</code> if the <code>gdb.Symbol</code> object is valid, 181<code>False</code> if not. A <code>gdb.Symbol</code> object can become invalid if 182the symbol it refers to does not exist in <span class="sc">gdb</span> any longer. 183All other <code>gdb.Symbol</code> methods will throw an exception if it is 184invalid at the time the method is called. 185</p></blockquote></div> 186 187<div class="defun"> 188— Function: <b>Symbol.value</b> (<span class="roman">[</span><var>frame</var><span class="roman">]</span>)<var><a name="index-Symbol_002evalue-2089"></a></var><br> 189<blockquote><p>Compute the value of the symbol, as a <code>gdb.Value</code>. For 190functions, this computes the address of the function, cast to the 191appropriate type. If the symbol requires a frame in order to compute 192its value, then <var>frame</var> must be given. If <var>frame</var> is not 193given, or if <var>frame</var> is invalid, then this method will throw an 194exception. 195</p></blockquote></div> 196 197 <p>The available domain categories in <code>gdb.Symbol</code> are represented 198as constants in the <code>gdb</code> module: 199 200 201<a name="index-SYMBOL_005fUNDEF_005fDOMAIN-2090"></a> 202<a name="index-gdb_002eSYMBOL_005fUNDEF_005fDOMAIN-2091"></a> 203<dl><dt><code>gdb.SYMBOL_UNDEF_DOMAIN</code><dd>This is used when a domain has not been discovered or none of the 204following domains apply. This usually indicates an error either 205in the symbol information or in <span class="sc">gdb</span>'s handling of symbols. 206<a name="index-SYMBOL_005fVAR_005fDOMAIN-2092"></a><a name="index-gdb_002eSYMBOL_005fVAR_005fDOMAIN-2093"></a><br><dt><code>gdb.SYMBOL_VAR_DOMAIN</code><dd>This domain contains variables, function names, typedef names and enum 207type values. 208<a name="index-SYMBOL_005fSTRUCT_005fDOMAIN-2094"></a><a name="index-gdb_002eSYMBOL_005fSTRUCT_005fDOMAIN-2095"></a><br><dt><code>gdb.SYMBOL_STRUCT_DOMAIN</code><dd>This domain holds struct, union and enum type names. 209<a name="index-SYMBOL_005fLABEL_005fDOMAIN-2096"></a><a name="index-gdb_002eSYMBOL_005fLABEL_005fDOMAIN-2097"></a><br><dt><code>gdb.SYMBOL_LABEL_DOMAIN</code><dd>This domain contains names of labels (for gotos). 210<a name="index-SYMBOL_005fVARIABLES_005fDOMAIN-2098"></a><a name="index-gdb_002eSYMBOL_005fVARIABLES_005fDOMAIN-2099"></a><br><dt><code>gdb.SYMBOL_VARIABLES_DOMAIN</code><dd>This domain holds a subset of the <code>SYMBOLS_VAR_DOMAIN</code>; it 211contains everything minus functions and types. 212<a name="index-SYMBOL_005fFUNCTIONS_005fDOMAIN-2100"></a><a name="index-gdb_002eSYMBOL_005fFUNCTIONS_005fDOMAIN-2101"></a><br><dt><code>gdb.SYMBOL_FUNCTION_DOMAIN</code><dd>This domain contains all functions. 213<a name="index-SYMBOL_005fTYPES_005fDOMAIN-2102"></a><a name="index-gdb_002eSYMBOL_005fTYPES_005fDOMAIN-2103"></a><br><dt><code>gdb.SYMBOL_TYPES_DOMAIN</code><dd>This domain contains all types. 214</dl> 215 216 <p>The available address class categories in <code>gdb.Symbol</code> are represented 217as constants in the <code>gdb</code> module: 218 219 220<a name="index-SYMBOL_005fLOC_005fUNDEF-2104"></a> 221<a name="index-gdb_002eSYMBOL_005fLOC_005fUNDEF-2105"></a> 222<dl><dt><code>gdb.SYMBOL_LOC_UNDEF</code><dd>If this is returned by address class, it indicates an error either in 223the symbol information or in <span class="sc">gdb</span>'s handling of symbols. 224<a name="index-SYMBOL_005fLOC_005fCONST-2106"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fCONST-2107"></a><br><dt><code>gdb.SYMBOL_LOC_CONST</code><dd>Value is constant int. 225<a name="index-SYMBOL_005fLOC_005fSTATIC-2108"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fSTATIC-2109"></a><br><dt><code>gdb.SYMBOL_LOC_STATIC</code><dd>Value is at a fixed address. 226<a name="index-SYMBOL_005fLOC_005fREGISTER-2110"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fREGISTER-2111"></a><br><dt><code>gdb.SYMBOL_LOC_REGISTER</code><dd>Value is in a register. 227<a name="index-SYMBOL_005fLOC_005fARG-2112"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fARG-2113"></a><br><dt><code>gdb.SYMBOL_LOC_ARG</code><dd>Value is an argument. This value is at the offset stored within the 228symbol inside the frame's argument list. 229<a name="index-SYMBOL_005fLOC_005fREF_005fARG-2114"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fREF_005fARG-2115"></a><br><dt><code>gdb.SYMBOL_LOC_REF_ARG</code><dd>Value address is stored in the frame's argument list. Just like 230<code>LOC_ARG</code> except that the value's address is stored at the 231offset, not the value itself. 232<a name="index-SYMBOL_005fLOC_005fREGPARM_005fADDR-2116"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fREGPARM_005fADDR-2117"></a><br><dt><code>gdb.SYMBOL_LOC_REGPARM_ADDR</code><dd>Value is a specified register. Just like <code>LOC_REGISTER</code> except 233the register holds the address of the argument instead of the argument 234itself. 235<a name="index-SYMBOL_005fLOC_005fLOCAL-2118"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fLOCAL-2119"></a><br><dt><code>gdb.SYMBOL_LOC_LOCAL</code><dd>Value is a local variable. 236<a name="index-SYMBOL_005fLOC_005fTYPEDEF-2120"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fTYPEDEF-2121"></a><br><dt><code>gdb.SYMBOL_LOC_TYPEDEF</code><dd>Value not used. Symbols in the domain <code>SYMBOL_STRUCT_DOMAIN</code> all 237have this class. 238<a name="index-SYMBOL_005fLOC_005fBLOCK-2122"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fBLOCK-2123"></a><br><dt><code>gdb.SYMBOL_LOC_BLOCK</code><dd>Value is a block. 239<a name="index-SYMBOL_005fLOC_005fCONST_005fBYTES-2124"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fCONST_005fBYTES-2125"></a><br><dt><code>gdb.SYMBOL_LOC_CONST_BYTES</code><dd>Value is a byte-sequence. 240<a name="index-SYMBOL_005fLOC_005fUNRESOLVED-2126"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fUNRESOLVED-2127"></a><br><dt><code>gdb.SYMBOL_LOC_UNRESOLVED</code><dd>Value is at a fixed address, but the address of the variable has to be 241determined from the minimal symbol table whenever the variable is 242referenced. 243<a name="index-SYMBOL_005fLOC_005fOPTIMIZED_005fOUT-2128"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fOPTIMIZED_005fOUT-2129"></a><br><dt><code>gdb.SYMBOL_LOC_OPTIMIZED_OUT</code><dd>The value does not actually exist in the program. 244<a name="index-SYMBOL_005fLOC_005fCOMPUTED-2130"></a><a name="index-gdb_002eSYMBOL_005fLOC_005fCOMPUTED-2131"></a><br><dt><code>gdb.SYMBOL_LOC_COMPUTED</code><dd>The value's address is a computed location. 245</dl> 246 247 </body></html> 248 249