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 onset case-sensitive offset case-sensitive autoNormally, 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-sensitiveThis command shows the current setting of case sensitivity for symbols lookups.
set print type methodsset print type methods onset print type methods offNormally, 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 methodsThis command shows the current setting of method display when printing classes.
set print type nested-type-limit limitset print type nested-type-limit unlimitedSet 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-limitThis command shows the current display limit of nested types when printing classes.
set print type typedefsset print type typedefs onset print type typedefs offNormally, 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 typedefsThis command shows the current setting of typedef display when printing classes.
info address symbolDescribe 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 addrPrint 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] [--] nameDemangle 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. See 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 (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:
rDisplay in “raw” form. Normally, GDB substitutes template
parameters and typedefs defined in a class when printing the class’
members. The /r flag disables this.
mDo not print methods defined in the class.
MPrint methods defined in the class. This is the default, but the flag
exists in case you change the default with set print type methods.
tDo 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.
TPrint typedefs defined in the class. This is the default, but the flag
exists in case you change the default with set print type typedefs.
oPrint 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: 0 | 4 */ int a6 : 5;
/* 16: 5 | 8 */ int64_t a7 : 3;
"/* XXX 7-byte padding */
/* total size (bytes): 24 */
}
Note how the offset information is now extended to also include the first bit of the 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.
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.
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>
See no debug info variables, for how to print the values of such variables.
info types [-q] [regexp]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) means to use the language of the type, other values mean to use the manually specified language (see Set Language 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.
The output from ‘into types’ is proceeded with a header line describing what types are being listed. The optional flag ‘-q’, which stands for ‘quiet’, disables printing this header information.
info type-printersVersions 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 locationList 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 sourceShow information about the current source file—that is, the source file for the function containing the current point of execution:
info sourcesPrint 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 sources [-dirname | -basename] [--] [regexp]Like ‘info sources’, but only print the names of the files
matching the provided regexp.
By default, the regexp is used to match anywhere in the filename.
If -dirname, only files having a dirname matching regexp are shown.
If -basename, only files having a basename matching regexp
are shown.
The matching is case-sensitive, except on operating systems that
have case-insensitive filesystem (e.g., MS-Windows).
info functions [-q] [-n]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) means to use the language of the function, other values mean to use the manually specified language (see Set Language Manually).
The ‘-n’ flag excludes non-debugging symbols from the results. A non-debugging symbol is a symbol that comes from the executable’s symbol table, not from the debug information (for example, DWARF) associated with the executable.
The optional flag ‘-q’, which stands for ‘quiet’, disables printing header information and messages explaining why no functions have been printed.
info functions [-q] [-n] [-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] [-n]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) means to use the language of the variable, other values mean to use the manually specified language (see Set Language Manually).
The ‘-n’ flag excludes non-debugging symbols from the results.
The optional flag ‘-q’, which stands for ‘quiet’, disables printing header information and messages explaining why no variables have been printed.
info variables [-q] [-n] [-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 modules [-q] [regexp]List all Fortran modules in the program, or all modules matching the optional regular expression regexp.
The optional flag ‘-q’, which stands for ‘quiet’, disables printing header information and messages explaining why no modules have been printed.
info module functions [-q] [-m module-regexp] [-t type-regexp] [regexp]info module variables [-q] [-m module-regexp] [-t type-regexp] [regexp]List all functions or variables within all Fortran modules. The set of functions or variables listed can be limited by providing some or all of the optional regular expressions. If module-regexp is provided, then only Fortran modules matching module-regexp will be searched. Only functions or variables whose type matches the optional regular expression type-regexp will be listed. And only functions or variables whose name matches the optional regular expression regexp will be listed.
The optional flag ‘-q’, which stands for ‘quiet’, disables printing header information and messages explaining why no functions or variables have been printed.
info classesinfo classes regexpDisplay all Objective-C classes in your program, or (with the regexp argument) all those matching a particular regular expression.
info selectorsinfo selectors regexpDisplay all Objective-C selectors in your program, or (with the regexp argument) all those matching a particular regular expression.
set opaque-type-resolution onTell 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 offTell GDB not to resolve opaque types. In this case, the type is printed as follows:
{<no data fields>}
show opaque-type-resolutionShow whether opaque types are resolved or not.
set print symbol-loadingset print symbol-loading fullset print symbol-loading briefset print symbol-loading offThe 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-loadingShow 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”.
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)
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 sizeSet 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-sizeShow the size of the symbol cache.
maint print symbol-cachePrint the contents of the symbol cache. This is useful when debugging symbol cache issues.
maint print symbol-cache-statisticsPrint symbol cache usage statistics. This helps determine how well the cache is being utilized.
maint flush-symbol-cacheFlush 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.