Next: , Previous: Languages, Up: Top


16 Examining the Symbol Table

The commands described in this chapter allow you to inquire about the symbols (names of variables, functions and types) defined in your program. This information is inherent in the text of your program and does not change as your program executes. gdb finds it in your program's symbol table, in the file indicated when you started gdb (see Choosing Files), or by one of the file-management commands (see Commands to Specify Files).

Occasionally, you may need to refer to symbols that contain unusual characters, which gdb ordinarily treats as word delimiters. The most frequent case is in referring to static variables in other source files (see Program Variables). File names are recorded in object files as debugging symbols, but gdb would ordinarily parse a typical file name, like foo.c, as the three words ‘foo’ ‘.’ ‘c’. To allow gdb to recognize ‘foo.c’ as a single symbol, enclose it in single quotes; for example,

     p 'foo.c'::x

looks up the value of x in the scope of the file foo.c.

set case-sensitive on
set case-sensitive off
set case-sensitive auto
Normally, when gdb looks up symbols, it matches their names with case sensitivity determined by the current source language. Occasionally, you may wish to control that. The command set case-sensitive lets you do that by specifying on for case-sensitive matches or off for case-insensitive ones. If you specify auto, case sensitivity is reset to the default suitable for the source language. The default is case-sensitive matches for all languages except for Fortran, for which the default is case-insensitive matches.


show case-sensitive
This command shows the current setting of case sensitivity for symbols lookups.


set print type methods
set print type methods on
set print type methods off
Normally, when gdb prints a class, it displays any methods declared in that class. You can control this behavior either by passing the appropriate flag to ptype, or using set print type methods. Specifying on will cause gdb to display the methods; this is the default. Specifying off will cause gdb to omit the methods.


show print type methods
This command shows the current setting of method display when printing classes.


set print type typedefs
set print type typedefs on
set print type typedefs off
Normally, when gdb prints a class, it displays any typedefs defined in that class. You can control this behavior either by passing the appropriate flag to ptype, or using set print type typedefs. Specifying on will cause gdb to display the typedef definitions; this is the default. Specifying off will cause gdb to omit the typedef definitions. Note that this controls whether the typedef definition itself is printed, not whether typedef names are substituted when printing other types.


show print type typedefs
This command shows the current setting of typedef display when printing classes.


info address symbol
Describe where the data for symbol is stored. For a register variable, this says which register it is kept in. For a non-register local variable, this prints the stack-frame offset at which the variable is always stored.

Note the contrast with ‘print &symbol’, which does not work at all for a register variable, and for a stack local variable prints the exact address of the current instantiation of the variable.


info symbol addr
Print the name of a symbol which is stored at the address addr. If no symbol is stored exactly at addr, gdb prints the nearest symbol and an offset from it:
          (gdb) info symbol 0x54320
          _initialize_vx + 396 in section .text

This is the opposite of the info address command. You can use it to find out the name of a variable or a function given its address.

For dynamically linked executables, the name of executable or shared library containing the symbol is also printed:

          (gdb) info symbol 0x400225
          _start + 5 in section .text of /tmp/a.out
          (gdb) info symbol 0x2aaaac2811cf
          __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6


whatis[/flags] [arg]
Print the data type of arg, which can be either an expression or a name of a data type. With no argument, print the data type of $, the last value in the value history.

If arg is an expression (see Expressions), it is not actually evaluated, and any side-effecting operations (such as assignments or function calls) inside it do not take place.

If arg is a variable or an expression, whatis prints its literal type as it is used in the source code. If the type was defined using a typedef, whatis will not print the data type underlying the typedef. If the type of the variable or the expression is a compound data type, such as struct or class, whatis never prints their fields or methods. It just prints the struct/class name (a.k.a. its tag). If you want to see the members of such a compound data type, use ptype.

If arg is a type name that was defined using typedef, whatis unrolls only one level of that typedef. Unrolling means that whatis will show the underlying type used in the typedef declaration of arg. However, if that underlying type is also a typedef, whatis will not unroll it.

For C code, the type names may also have the form ‘class class-name’, ‘struct struct-tag’, ‘union union-tag’ or ‘enum enum-tag’.

flags can be used to modify how the type is displayed. Available flags are:

r
Display in “raw” form. Normally, gdb substitutes template parameters and typedefs defined in a class when printing the class' members. The /r flag disables this.
m
Do not print methods defined in the class.
M
Print methods defined in the class. This is the default, but the flag exists in case you change the default with set print type methods.
t
Do not print typedefs defined in the class. Note that this controls whether the typedef definition itself is printed, not whether typedef names are substituted when printing other types.
T
Print typedefs defined in the class. This is the default, but the flag exists in case you change the default with set print type typedefs.


ptype[/flags] [arg]
ptype accepts the same arguments as whatis, but prints a detailed description of the type, instead of just the name of the type. See Expressions.

Contrary to whatis, ptype always unrolls any typedefs in its argument declaration, whether the argument is a variable, expression, or a data type. This means that ptype of a variable or an expression will not print literally its type as present in the source code—use whatis for that. typedefs at the pointer or reference targets are also unrolled. Only typedefs of fields, methods and inner class typedefs of structs, classes and unions are not unrolled even with ptype.

For example, for this variable declaration:

          typedef double real_t;
          struct complex { real_t real; double imag; };
          typedef struct complex complex_t;
          complex_t var;
          real_t *real_pointer_var;

the two commands give this output:

          (gdb) whatis var
          type = complex_t
          (gdb) ptype var
          type = struct complex {
              real_t real;
              double imag;
          }
          (gdb) whatis complex_t
          type = struct complex
          (gdb) whatis struct complex
          type = struct complex
          (gdb) ptype struct complex
          type = struct complex {
              real_t real;
              double imag;
          }
          (gdb) whatis real_pointer_var
          type = real_t *
          (gdb) ptype real_pointer_var
          type = double *

As with whatis, using ptype without an argument refers to the type of $, the last value in the value history.

Sometimes, programs use opaque data types or incomplete specifications of complex data structure. If the debug information included in the program does not allow gdb to display a full declaration of the data type, it will say ‘<incomplete type>’. For example, given these declarations:

              struct foo;
              struct foo *fooptr;

but no definition for struct foo itself, gdb will say:

            (gdb) ptype foo
            $1 = <incomplete type>

“Incomplete type” is C terminology for data types that are not completely specified.


info types regexp
info types
Print a brief description of all types whose names match the regular expression regexp (or all types in your program, if you supply no argument). Each complete typename is matched as though it were a complete line; thus, ‘i type value’ gives information on all types in your program whose names include the string value, but ‘i type ^value$’ gives information only on types whose complete name is value.

This command differs from ptype in two ways: first, like whatis, it does not print a detailed description; second, it lists all source files where a type is defined.


info type-printers
Versions of gdb that ship with Python scripting enabled may have “type printers” available. When using ptype or whatis, these printers are consulted when the name of a type is needed. See Type Printing API, for more information on writing type printers.

info type-printers displays all the available type printers.


enable type-printer name...
disable type-printer name...
These commands can be used to enable or disable type printers.


info scope location
List all the variables local to a particular scope. This command accepts a location argument—a function name, a source line, or an address preceded by a ‘*’, and prints all the variables local to the scope defined by that location. (See Specify Location, for details about supported forms of location.) For example:
          (gdb) info scope command_line_handler
          Scope for command_line_handler:
          Symbol rl is an argument at stack/frame offset 8, length 4.
          Symbol linebuffer is in static storage at address 0x150a18, length 4.
          Symbol linelength is in static storage at address 0x150a1c, length 4.
          Symbol p is a local variable in register $esi, length 4.
          Symbol p1 is a local variable in register $ebx, length 4.
          Symbol nline is a local variable in register $edx, length 4.
          Symbol repeat is a local variable at frame offset -8, length 4.

This command is especially useful for determining what data to collect during a trace experiment, see collect.


info source
Show information about the current source file—that is, the source file for the function containing the current point of execution:


info sources
Print the names of all source files in your program for which there is debugging information, organized into two lists: files whose symbols have already been read, and files whose symbols will be read when needed.


info functions
Print the names and data types of all defined functions.
info functions regexp
Print the names and data types of all defined functions whose names contain a match for regular expression regexp. Thus, ‘info fun step’ finds all functions whose names include step; ‘info fun ^step’ finds those whose names start with step. If a function name contains characters that conflict with the regular expression language (e.g. ‘operator*()’), they may be quoted with a backslash.


info variables
Print the names and data types of all variables that are defined outside of functions (i.e. excluding local variables).
info variables regexp
Print the names and data types of all variables (except for local variables) whose names contain a match for regular expression regexp.


info classes
info classes regexp
Display all Objective-C classes in your program, or (with the regexp argument) all those matching a particular regular expression.


info selectors
info selectors regexp
Display all Objective-C selectors in your program, or (with the regexp argument) all those matching a particular regular expression.


set opaque-type-resolution on
Tell gdb to resolve opaque types. An opaque type is a type declared as a pointer to a struct, class, or union—for example, struct MyType *—that is used in one source file although the full declaration of struct MyType is in another source file. The default is on.

A change in the setting of this subcommand will not take effect until the next time symbols for a file are loaded.

set opaque-type-resolution off
Tell gdb not to resolve opaque types. In this case, the type is printed as follows:
          {<no data fields>}


show opaque-type-resolution
Show whether opaque types are resolved or not.


set print symbol-loading
set print symbol-loading full
set print symbol-loading brief
set print symbol-loading off
The set print symbol-loading command allows you to control the printing of messages when gdb loads symbol information. By default a message is printed for the executable and one for each shared library, and normally this is what you want. However, when debugging apps with large numbers of shared libraries these messages can be annoying. When set to brief a message is printed for each executable, and when gdb loads a collection of shared libraries at once it will only print one message regardless of the number of shared libraries. When set to off no messages are printed.


show print symbol-loading
Show whether messages will be printed when a gdb command entered from the keyboard causes symbol information to be loaded.


maint print symbols filename
maint print psymbols filename
maint print msymbols filename
Write a dump of debugging symbol data into the file filename. These commands are used to debug the gdb symbol-reading code. Only symbols with debugging data are included. If you use ‘maint print symbols’, gdb includes all the symbols for which it has already collected full details: that is, filename reflects symbols for only those files whose symbols gdb has read. You can use the command info sources to find out which files these are. If you use ‘maint print psymbols’ instead, the dump shows information about symbols that gdb only knows partially—that is, symbols defined in files that gdb has skimmed, but not yet read completely. Finally, ‘maint print msymbols’ dumps just the minimal symbol information required for each object file from which gdb has read some symbols. See Commands to Specify Files, for a discussion of how gdb reads symbols (in the description of symbol-file).


maint info symtabs [ regexp ]
maint info psymtabs [ regexp ]
List the struct symtab or struct partial_symtab structures whose names match regexp. If regexp is not given, list them all. The output includes expressions which you can copy into a gdb debugging this one to examine a particular structure in more detail. For example:
          (gdb) maint info psymtabs dwarf2read
          { objfile /home/gnu/build/gdb/gdb
            ((struct objfile *) 0x82e69d0)
            { psymtab /home/gnu/src/gdb/dwarf2read.c
              ((struct partial_symtab *) 0x8474b10)
              readin no
              fullname (null)
              text addresses 0x814d3c8 -- 0x8158074
              globals (* (struct partial_symbol **) 0x8507a08 @ 9)
              statics (* (struct partial_symbol **) 0x40e95b78 @ 2882)
              dependencies (none)
            }
          }
          (gdb) maint info symtabs
          (gdb)

We see that there is one partial symbol table whose filename contains the string ‘dwarf2read’, belonging to the ‘gdb’ executable; and we see that gdb has not read in any symtabs yet at all. If we set a breakpoint on a function, that will cause gdb to read the symtab for the compilation unit containing that function:

          (gdb) break dwarf2_psymtab_to_symtab
          Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c,
          line 1574.
          (gdb) maint info symtabs
          { objfile /home/gnu/build/gdb/gdb
            ((struct objfile *) 0x82e69d0)
            { symtab /home/gnu/src/gdb/dwarf2read.c
              ((struct symtab *) 0x86c1f38)
              dirname (null)
              fullname (null)
              blockvector ((struct blockvector *) 0x86c1bd0) (primary)
              linetable ((struct linetable *) 0x8370fa0)
              debugformat DWARF 2
            }
          }
          (gdb)