mingw/info/gdb/Symbols.html

   1 <html lang="en">
   2 <head>
   3 <title>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.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Symbols">Symbols</a>,
  13 Next:<a rel="next" accesskey="n" href="Altering.html#Altering">Altering</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Languages.html#Languages">Languages</a>,
  15 Up:<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  16 <hr><br>
  17 </div>
  18
  19 <h2 class="chapter">Examining the Symbol Table</h2>
  20
  21    <p>The commands described in this chapter allow you to inquire about the
  22 symbols (names of variables, functions and types) defined in your
  23 program.  This information is inherent in the text of your program and
  24 does not change as your program executes.  GDB finds it in your
  25 program's symbol table, in the file indicated when you started GDB
  26 (see <a href="File-Options.html#File%20Options">Choosing files</a>), or by one of the
  27 file-management commands (see <a href="Files.html#Files">Commands to specify files</a>).
  28
  29    <p>Occasionally, you may need to refer to symbols that contain unusual
  30 characters, which GDB ordinarily treats as word delimiters.  The
  31 most frequent case is in referring to static variables in other
  32 source files (see <a href="Variables.html#Variables">Program variables</a>).  File names
  33 are recorded in object files as debugging symbols, but GDB would
  34 ordinarily parse a typical file name, like <code>foo.c</code>, as the three words
  35 <code>foo</code> <code>.</code> <code>c</code>.  To allow GDB to recognize
  36 <code>foo.c</code> as a single symbol, enclose it in single quotes; for example,
  37
  38 <pre class="example">     p 'foo.c'::x
  39      </pre>
  40
  41 <p>looks up the value of <code>x</code> in the scope of the file <code>foo.c</code>.
  42
  43      <dl>
  44 <dt><code>info address </code><var>symbol</var><code></code>
  45      <dd>Describe where the data for <var>symbol</var> is stored.  For a register
  46 variable, this says which register it is kept in.  For a non-register
  47 local variable, this prints the stack-frame offset at which the variable
  48 is always stored.
  49
  50      <p>Note the contrast with <code>print &amp;</code><var>symbol</var><code></code>, which does not work
  51 at all for a register variable, and for a stack local variable prints
  52 the exact address of the current instantiation of the variable.
  53
  54      <br><dt><code>info symbol </code><var>addr</var><code></code>
  55      <dd>Print the name of a symbol which is stored at the address <var>addr</var>.
  56 If no symbol is stored exactly at <var>addr</var>, GDB prints the
  57 nearest symbol and an offset from it:
  58
  59      <pre class="example">          (gdb) info symbol 0x54320
  60           _initialize_vx + 396 in section .text
  61           </pre>
  62
  63      <p>This is the opposite of the <code>info address</code> command.  You can use
  64 it to find out the name of a variable or a function given its address.
  65
  66      <br><dt><code>whatis </code><var>expr</var><code></code>
  67      <dd>Print the data type of expression <var>expr</var>.  <var>expr</var> is not
  68 actually evaluated, and any side-effecting operations (such as
  69 assignments or function calls) inside it do not take place.
  70 See <a href="Expressions.html#Expressions">Expressions</a>.
  71
  72      <br><dt><code>whatis</code>
  73      <dd>Print the data type of <code>$</code>, the last value in the value history.
  74
  75      <br><dt><code>ptype </code><var>typename</var><code></code>
  76      <dd>Print a description of data type <var>typename</var>.  <var>typename</var> may be
  77 the name of a type, or for C code it may have the form <code>class
  78 </code><var>class-name</var><code></code>, <code>struct </code><var>struct-tag</var><code></code>, <code>union
  79 </code><var>union-tag</var><code></code> or <code>enum </code><var>enum-tag</var><code></code>.
  80
  81      <br><dt><code>ptype </code><var>expr</var><code></code>
  82      <dd><dt><code>ptype</code>
  83      <dd>Print a description of the type of expression <var>expr</var>.  <code>ptype</code>
  84 differs from <code>whatis</code> by printing a detailed description, instead
  85 of just the name of the type.
  86
  87      <p>For example, for this variable declaration:
  88
  89      <pre class="example">          struct complex {double real; double imag;} v;
  90           </pre>
  91
  92      <p>the two commands give this output:
  93
  94      <pre class="example">          (gdb) whatis v
  95           type = struct complex
  96           (gdb) ptype v
  97           type = struct complex {
  98               double real;
  99               double imag;
 100           }
 101           </pre>
 102
 103      <p>As with <code>whatis</code>, using <code>ptype</code> without an argument refers to
 104 the type of <code>$</code>, the last value in the value history.
 105
 106      <br><dt><code>info types </code><var>regexp</var><code></code>
 107      <dd><dt><code>info types</code>
 108      <dd>Print a brief description of all types whose names match <var>regexp</var>
 109 (or all types in your program, if you supply no argument).  Each
 110 complete typename is matched as though it were a complete line; thus,
 111 <code>i type value</code> gives information on all types in your program whose
 112 names include the string <code>value</code>, but <code>i type ^value$</code> gives
 113 information only on types whose complete name is <code>value</code>.
 114
 115      <p>This command differs from <code>ptype</code> in two ways: first, like
 116 <code>whatis</code>, it does not print a detailed description; second, it
 117 lists all source files where a type is defined.
 118
 119      <br><dt><code>info scope </code><var>addr</var><code></code>
 120      <dd>List all the variables local to a particular scope.  This command
 121 accepts a location--a function name, a source line, or an address
 122 preceded by a <code>*</code>, and prints all the variables local to the
 123 scope defined by that location.  For example:
 124
 125      <pre class="smallexample">          (gdb) <b>info scope command_line_handler</b>
 126           Scope for command_line_handler:
 127           Symbol rl is an argument at stack/frame offset 8, length 4.
 128           Symbol linebuffer is in static storage at address 0x150a18, length 4.
 129           Symbol linelength is in static storage at address 0x150a1c, length 4.
 130           Symbol p is a local variable in register $esi, length 4.
 131           Symbol p1 is a local variable in register $ebx, length 4.
 132           Symbol nline is a local variable in register $edx, length 4.
 133           Symbol repeat is a local variable at frame offset -8, length 4.
 134           </pre>
 135
 136      <p>This command is especially useful for determining what data to collect
 137 during a <dfn>trace experiment</dfn>, see <a href="Tracepoint-Actions.html#Tracepoint%20Actions">collect</a>.
 138
 139      <br><dt><code>info source</code>
 140      <dd>Show the name of the current source file--that is, the source file for
 141 the function containing the current point of execution--and the language
 142 it was written in.
 143
 144      <br><dt><code>info sources</code>
 145      <dd>Print the names of all source files in your program for which there is
 146 debugging information, organized into two lists: files whose symbols
 147 have already been read, and files whose symbols will be read when needed.
 148
 149      <br><dt><code>info functions</code>
 150      <dd>Print the names and data types of all defined functions.
 151
 152      <br><dt><code>info functions </code><var>regexp</var><code></code>
 153      <dd>Print the names and data types of all defined functions
 154 whose names contain a match for regular expression <var>regexp</var>.
 155 Thus, <code>info fun step</code> finds all functions whose names
 156 include <code>step</code>; <code>info fun ^step</code> finds those whose names
 157 start with <code>step</code>.  If a function name contains characters
 158 that conflict with the regular expression language (eg.
 159 <code>operator*()</code>), they may be quoted with a backslash.
 160
 161      <br><dt><code>info variables</code>
 162      <dd>Print the names and data types of all variables that are declared
 163 outside of functions (i.e. excluding local variables).
 164
 165      <br><dt><code>info variables </code><var>regexp</var><code></code>
 166      <dd>Print the names and data types of all variables (except for local
 167 variables) whose names contain a match for regular expression
 168 <var>regexp</var>.
 169
 170      <p>Some systems allow individual object files that make up your program to
 171 be replaced without stopping and restarting your program.  For example,
 172 in VxWorks you can simply recompile a defective object file and keep on
 173 running.  If you are running on one of these systems, you can allow
 174 GDB to reload the symbols for automatically relinked modules:
 175
 176           <dl>
 177 <dt><code>set symbol-reloading on</code>
 178           <dd>Replace symbol definitions for the corresponding source file when an
 179 object file with a particular name is seen again.
 180
 181           <br><dt><code>set symbol-reloading off</code>
 182           <dd>Do not replace symbol definitions when encountering object files of the
 183 same name more than once.  This is the default state; if you are not
 184 running on a system that permits automatic relinking of modules, you
 185 should leave <code>symbol-reloading</code> off, since otherwise GDB
 186 may discard symbols when linking large programs, that may contain
 187 several modules (from different directories or libraries) with the same
 188 name.
 189
 190           <br><dt><code>show symbol-reloading</code>
 191           <dd>Show the current <code>on</code> or <code>off</code> setting.
 192 </dl>
 193
 194      <br><dt><code>set opaque-type-resolution on</code>
 195      <dd>Tell GDB to resolve opaque types.  An opaque type is a type
 196 declared as a pointer to a <code>struct</code>, <code>class</code>, or
 197 <code>union</code>--for example, <code>struct MyType *</code>--that is used in one
 198 source file although the full declaration of <code>struct MyType</code> is in
 199 another source file.  The default is on.
 200
 201      <p>A change in the setting of this subcommand will not take effect until
 202 the next time symbols for a file are loaded.
 203
 204      <br><dt><code>set opaque-type-resolution off</code>
 205      <dd>Tell GDB not to resolve opaque types.  In this case, the type
 206 is printed as follows:
 207      <pre class="smallexample">          {&lt;no data fields&gt;}
 208           </pre>
 209
 210      <br><dt><code>show opaque-type-resolution</code>
 211      <dd>Show whether opaque types are resolved or not.
 212
 213      <br><dt><code>maint print symbols </code><var>filename</var><code></code>
 214      <dd><dt><code>maint print psymbols </code><var>filename</var><code></code>
 215      <dd><dt><code>maint print msymbols </code><var>filename</var><code></code>
 216      <dd>Write a dump of debugging symbol data into the file <var>filename</var>.
 217 These commands are used to debug the GDB symbol-reading code.  Only
 218 symbols with debugging data are included.  If you use <code>maint print
 219 symbols</code>, GDB includes all the symbols for which it has already
 220 collected full details: that is, <var>filename</var> reflects symbols for
 221 only those files whose symbols GDB has read.  You can use the
 222 command <code>info sources</code> to find out which files these are.  If you
 223 use <code>maint print psymbols</code> instead, the dump shows information about
 224 symbols that GDB only knows partially--that is, symbols defined in
 225 files that GDB has skimmed, but not yet read completely.  Finally,
 226 <code>maint print msymbols</code> dumps just the minimal symbol information
 227 required for each object file from which GDB has read some symbols.
 228 See <a href="Files.html#Files">Commands to specify files</a>, for a discussion of how
 229 GDB reads symbols (in the description of <code>symbol-file</code>).
 230 </dl>
 231
 232    </body></html>
 233