gdb: Symbols
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
(
Choosing Files File Options.), or by one of the file-management
commands (Commands to Specify Files 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
(Program Variables 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 nested-type-limit LIMIT'
'set print type nested-type-limit unlimited'
Set the limit of displayed nested types that the type printer will
show. A LIMIT of 'unlimited' or '-1' will show all nested
definitions. By default, the type printer will not show any nested
types defined in classes.
'show print type nested-type-limit'
This command shows the current display limit of nested types 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
'demangle [-l LANGUAGE] [--] NAME'
Demangle NAME. If LANGUAGE is provided it is the name of the
language to demangle NAME in. Otherwise NAME is demangled in the
current language.
The '--' option specifies the end of options, and is useful when
NAME begins with a dash.
The parameter 'demangle-style' specifies how to interpret the kind
of mangling used. Print Settings.
'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 (Expressions 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'.
'o'
Print the offsets and sizes of fields in a struct, similar to
what the 'pahole' tool does. This option implies the '/tm'
flags.
For example, given the following declarations:
struct tuv
{
int a1;
char *a2;
int a3;
};
struct xyz
{
int f1;
char f2;
void *f3;
struct tuv f4;
};
union qwe
{
struct tuv fff1;
struct xyz fff2;
};
struct tyu
{
int a1 : 1;
int a2 : 3;
int a3 : 23;
char a4 : 2;
int64_t a5;
int a6 : 5;
int64_t a7 : 3;
};
Issuing a 'ptype /o struct tuv' command would print:
(gdb) ptype /o struct tuv
/* offset | size */ type = struct tuv {
/* 0 | 4 */ int a1;
/* XXX 4-byte hole */
/* 8 | 8 */ char *a2;
/* 16 | 4 */ int a3;
/* total size (bytes): 24 */
}
Notice the format of the first column of comments. There, you
can find two parts separated by the '|' character: the
_offset_, which indicates where the field is located inside
the struct, in bytes, and the _size_ of the field. Another
interesting line is the marker of a _hole_ in the struct,
indicating that it may be possible to pack the struct and make
it use less space by reorganizing its fields.
It is also possible to print offsets inside an union:
(gdb) ptype /o union qwe
/* offset | size */ type = union qwe {
/* 24 */ struct tuv {
/* 0 | 4 */ int a1;
/* XXX 4-byte hole */
/* 8 | 8 */ char *a2;
/* 16 | 4 */ int a3;
/* total size (bytes): 24 */
} fff1;
/* 40 */ struct xyz {
/* 0 | 4 */ int f1;
/* 4 | 1 */ char f2;
/* XXX 3-byte hole */
/* 8 | 8 */ void *f3;
/* 16 | 24 */ struct tuv {
/* 16 | 4 */ int a1;
/* XXX 4-byte hole */
/* 24 | 8 */ char *a2;
/* 32 | 4 */ int a3;
/* total size (bytes): 24 */
} f4;
/* total size (bytes): 40 */
} fff2;
/* total size (bytes): 40 */
}
In this case, since 'struct tuv' and 'struct xyz' occupy the
same space (because we are dealing with an union), the offset
is not printed for them. However, you can still examine the
offset of each of these structures' fields.
Another useful scenario is printing the offsets of a struct
containing bitfields:
(gdb) ptype /o struct tyu
/* offset | size */ type = struct tyu {
/* 0:31 | 4 */ int a1 : 1;
/* 0:28 | 4 */ int a2 : 3;
/* 0: 5 | 4 */ int a3 : 23;
/* 3: 3 | 1 */ signed char a4 : 2;
/* XXX 3-bit hole */
/* XXX 4-byte hole */
/* 8 | 8 */ int64_t a5;
/* 16:27 | 4 */ int a6 : 5;
/* 16:56 | 8 */ int64_t a7 : 3;
/* total size (bytes): 24 */
}
Note how the offset information is now extended to also
include how many bits are left to be used in each bitfield.
'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. Expressions Expressions.
Contrary to 'whatis', 'ptype' always unrolls any 'typedef's 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. 'typedef's at the pointer
or reference targets are also unrolled. Only 'typedef's of fields,
methods and inner 'class typedef's of 'struct's, 'class'es and
'union's 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.
Othertimes, information about a variable's type is completely
absent from the debug information included in the program. This
most often happens when the program or library where the variable
is defined includes no debug information at all. GDB knows the
variable exists from inspecting the linker/loader symbol table
(e.g., the ELF dynamic symbol table), but such symbols do not
contain type information. Inspecting the type of a (global)
variable for which GDB has no type information shows:
(gdb) ptype var
type = <data variable, no debug info>
no debug info variables Variables, for how to print the
values of such variables.
'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'.
In programs using different languages, GDB chooses the syntax to
print the type description according to the 'set language' value:
using 'set language auto' (see Set Language Automatically
Automatically.) means to use the language of the type, other values
mean to use the manually specified language (see Set Language
Manually Manually.).
This command differs from 'ptype' in two ways: first, like
'whatis', it does not print a detailed description; second, it
lists all source files and line numbers 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.
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. (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 Tracepoint
Actions.
'info source'
Show information about the current source file--that is, the source
file for the function containing the current point of execution:
* the name of the source file, and the directory containing it,
* the directory it was compiled in,
* its length, in lines,
* which programming language it is written in,
* if the debug information provides it, the program that
compiled the file (which may include, e.g., the compiler
version and command line arguments),
* whether the executable includes debugging information for that
file, and if so, what format the information is in (e.g.,
STABS, Dwarf 2, etc.), and
* whether the debugging information includes information about
preprocessor macros.
'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 [-q]'
Print the names and data types of all defined functions. Similarly
to 'info types', this command groups its output by source files and
annotates each function definition with its source line number.
In programs using different languages, GDB chooses the syntax to
print the function name and type according to the 'set language'
value: using 'set language auto' (see Set Language
Automatically Automatically.) means to use the language of the
function, other values mean to use the manually specified language
(see Set Language Manually Manually.).
The optional flag '-q', which stands for 'quiet', disables printing
header information and messages explaining why no functions have
been printed.
'info functions [-q] [-t TYPE_REGEXP] [REGEXP]'
Like 'info functions', but only print the names and data types of
the functions selected with the provided regexp(s).
If REGEXP is provided, print only the functions whose names match
the 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.
If TYPE_REGEXP is provided, print only the functions whose types,
as printed by the 'whatis' command, match the regular expression
TYPE_REGEXP. If TYPE_REGEXP contains space(s), it should be
enclosed in quote characters. If needed, use backslash to escape
the meaning of special characters or quotes. Thus, 'info fun -t
'^int ('' finds the functions that return an integer; 'info fun -t
'(.*int.*'' finds the functions that have an argument type
containing int; 'info fun -t '^int (' ^step' finds the functions
whose names start with 'step' and that return int.
If both REGEXP and TYPE_REGEXP are provided, a function is printed
only if its name matches REGEXP and its type matches TYPE_REGEXP.
'info variables [-q]'
Print the names and data types of all variables that are defined
outside of functions (i.e. excluding local variables). The printed
variables are grouped by source files and annotated with their
respective source line numbers.
In programs using different languages, GDB chooses the syntax to
print the variable name and type according to the 'set language'
value: using 'set language auto' (see Set Language
Automatically Automatically.) means to use the language of the
variable, other values mean to use the manually specified language
(see Set Language Manually Manually.).
The optional flag '-q', which stands for 'quiet', disables printing
header information and messages explaining why no variables have
been printed.
'info variables [-q] [-t TYPE_REGEXP] [REGEXP]'
Like 'info variables', but only print the variables selected with
the provided regexp(s).
If REGEXP is provided, print only the variables whose names match
the regular expression REGEXP.
If TYPE_REGEXP is provided, print only the variables whose types,
as printed by the 'whatis' command, match the regular expression
TYPE_REGEXP. If TYPE_REGEXP contains space(s), it should be
enclosed in quote characters. If needed, use backslash to escape
the meaning of special characters or quotes.
If both REGEXP and TYPE_REGEXP are provided, an argument is printed
only if its name matches REGEXP and its type matches TYPE_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 [-pc ADDRESS] [FILENAME]'
'maint print symbols [-objfile OBJFILE] [-source SOURCE] [--] [FILENAME]'
'maint print psymbols [-objfile OBJFILE] [-pc ADDRESS] [--] [FILENAME]'
'maint print psymbols [-objfile OBJFILE] [-source SOURCE] [--] [FILENAME]'
'maint print msymbols [-objfile OBJFILE] [--] [FILENAME]'
Write a dump of debugging symbol data into the file FILENAME or the
terminal if FILENAME is unspecified. If '-objfile OBJFILE' is
specified, only dump symbols for that objfile. If '-pc ADDRESS' is
specified, only dump symbols for the file with code at that
address. Note that ADDRESS may be a symbol like 'main'. If
'-source SOURCE' is specified, only dump symbols for that source
file.
These commands are used to debug the GDB symbol-reading code.
These commands do not modify internal GDB state, therefore 'maint
print symbols' will only print symbols for already expanded symbol
tables. 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' just
dumps "minimal symbols", e.g., "ELF symbols".
Commands to Specify Files 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)
'maint info line-table [ REGEXP ]'
List the 'struct linetable' from all 'struct symtab' instances
whose name matches REGEXP. If REGEXP is not given, list the
'struct linetable' from all 'struct symtab'.
'maint set symbol-cache-size SIZE'
Set the size of the symbol cache to SIZE. The default size is
intended to be good enough for debugging most applications. This
option exists to allow for experimenting with different sizes.
'maint show symbol-cache-size'
Show the size of the symbol cache.
'maint print symbol-cache'
Print the contents of the symbol cache. This is useful when
debugging symbol cache issues.
'maint print symbol-cache-statistics'
Print symbol cache usage statistics. This helps determine how well
the cache is being utilized.
'maint flush-symbol-cache'
Flush the contents of the symbol cache, all entries are removed.
This command is useful when debugging the symbol cache. It is also
useful when collecting performance data.
Info Catalog
gdb: Languages
gdb: Top
gdb: Altering