gdb: Maintenance Commands
Appendix D Maintenance Commands
*******************************
In addition to commands intended for GDB users, GDB includes a number of
commands intended for GDB developers, that are not documented elsewhere
in this manual. These commands are provided here for reference. (For
commands that turn on debugging messages, see 
Debugging Output.)
'maint agent [-at LOCATION,] EXPRESSION'
'maint agent-eval [-at LOCATION,] EXPRESSION'
Translate the given EXPRESSION into remote agent bytecodes. This
command is useful for debugging the Agent Expression mechanism
(Agent Expressions). The 'agent' version produces an
expression useful for data collection, such as by tracepoints,
while 'maint agent-eval' produces an expression that evaluates
directly to a result. For instance, a collection expression for
'globa + globb' will include bytecodes to record four bytes of
memory at each of the addresses of 'globa' and 'globb', while
discarding the result of the addition, while an evaluation
expression will do the addition and return the sum. If '-at' is
given, generate remote agent bytecode for LOCATION. If not,
generate remote agent bytecode for current frame PC address.
'maint agent-printf FORMAT,EXPR,...'
Translate the given format string and list of argument expressions
into remote agent bytecodes and display them as a disassembled
list. This command is useful for debugging the agent version of
dynamic printf (Dynamic Printf).
'maint info breakpoints'
Using the same format as 'info breakpoints', display both the
breakpoints you've set explicitly, and those GDB is using for
internal purposes. Internal breakpoints are shown with negative
breakpoint numbers. The type column identifies what kind of
breakpoint is shown:
'breakpoint'
Normal, explicitly set breakpoint.
'watchpoint'
Normal, explicitly set watchpoint.
'longjmp'
Internal breakpoint, used to handle correctly stepping through
'longjmp' calls.
'longjmp resume'
Internal breakpoint at the target of a 'longjmp'.
'until'
Temporary internal breakpoint used by the GDB 'until' command.
'finish'
Temporary internal breakpoint used by the GDB 'finish'
command.
'shlib events'
Shared library events.
'maint info btrace'
Pint information about raw branch tracing data.
'maint btrace packet-history'
Print the raw branch trace packets that are used to compute the
execution history for the 'record btrace' command. Both the
information and the format in which it is printed depend on the
btrace recording format.
'bts'
For the BTS recording format, print a list of blocks of
sequential code. For each block, the following information is
printed:
Block number
Newer blocks have higher numbers. The oldest block has
number zero.
Lowest 'PC'
Highest 'PC'
'pt'
For the Intel Processor Trace recording format, print a list
of Intel Processor Trace packets. For each packet, the
following information is printed:
Packet number
Newer packets have higher numbers. The oldest packet has
number zero.
Trace offset
The packet's offset in the trace stream.
Packet opcode and payload
'maint btrace clear-packet-history'
Discards the cached packet history printed by the 'maint btrace
packet-history' command. The history will be computed again when
needed.
'maint btrace clear'
Discard the branch trace data. The data will be fetched anew and
the branch trace will be recomputed when needed.
This implicitly truncates the branch trace to a single branch trace
buffer. When updating branch trace incrementally, the branch trace
available to GDB may be bigger than a single branch trace buffer.
'maint set btrace pt skip-pad'
'maint show btrace pt skip-pad'
Control whether GDB will skip PAD packets when computing the packet
history.
'set displaced-stepping'
'show displaced-stepping'
Control whether or not GDB will do "displaced stepping" if the
target supports it. Displaced stepping is a way to single-step
over breakpoints without removing them from the inferior, by
executing an out-of-line copy of the instruction that was
originally at the breakpoint location. It is also known as
out-of-line single-stepping.
'set displaced-stepping on'
If the target architecture supports it, GDB will use displaced
stepping to step over breakpoints.
'set displaced-stepping off'
GDB will not use displaced stepping to step over breakpoints,
even if such is supported by the target architecture.
'set displaced-stepping auto'
This is the default mode. GDB will use displaced stepping
only if non-stop mode is active (Non-Stop Mode) and
the target architecture supports displaced stepping.
'maint check-psymtabs'
Check the consistency of currently expanded psymtabs versus
symtabs. Use this to check, for example, whether a symbol is in
one but not the other.
'maint check-symtabs'
Check the consistency of currently expanded symtabs.
'maint expand-symtabs [REGEXP]'
Expand symbol tables. If REGEXP is specified, only expand symbol
tables for file names matching REGEXP.
'maint set catch-demangler-crashes [on|off]'
'maint show catch-demangler-crashes'
Control whether GDB should attempt to catch crashes in the symbol
name demangler. The default is to attempt to catch crashes. If
enabled, the first time a crash is caught, a core file is created,
the offending symbol is displayed and the user is presented with
the option to terminate the current session.
'maint cplus first_component NAME'
Print the first C++ class/namespace component of NAME.
'maint cplus namespace'
Print the list of possible C++ namespaces.
'maint deprecate COMMAND [REPLACEMENT]'
'maint undeprecate COMMAND'
Deprecate or undeprecate the named COMMAND. Deprecated commands
cause GDB to issue a warning when you use them. The optional
argument REPLACEMENT says which newer command should be used in
favor of the deprecated one; if it is given, GDB will mention the
replacement as part of the warning.
'maint dump-me'
Cause a fatal signal in the debugger and force it to dump its core.
This is supported only on systems which support aborting a program
with the 'SIGQUIT' signal.
'maint internal-error [MESSAGE-TEXT]'
'maint internal-warning [MESSAGE-TEXT]'
'maint demangler-warning [MESSAGE-TEXT]'
Cause GDB to call the internal function 'internal_error',
'internal_warning' or 'demangler_warning' and hence behave as
though an internal problem has been detected. In addition to
reporting the internal problem, these functions give the user the
opportunity to either quit GDB or (for 'internal_error' and
'internal_warning') create a core file of the current GDB session.
These commands take an optional parameter MESSAGE-TEXT that is used
as the text of the error or warning message.
Here's an example of using 'internal-error':
(gdb) maint internal-error testing, 1, 2
.../maint.c:121: internal-error: testing, 1, 2
A problem internal to GDB has been detected. Further
debugging may prove unreliable.
Quit this debugging session? (y or n) n
Create a core file? (y or n) n
(gdb)
'maint set internal-error ACTION [ask|yes|no]'
'maint show internal-error ACTION'
'maint set internal-warning ACTION [ask|yes|no]'
'maint show internal-warning ACTION'
'maint set demangler-warning ACTION [ask|yes|no]'
'maint show demangler-warning ACTION'
When GDB reports an internal problem (error or warning) it gives
the user the opportunity to both quit GDB and create a core file of
the current GDB session. These commands let you override the
default behaviour for each particular ACTION, described in the
table below.
'quit'
You can specify that GDB should always (yes) or never (no)
quit. The default is to ask the user what to do.
'corefile'
You can specify that GDB should always (yes) or never (no)
create a core file. The default is to ask the user what to
do. Note that there is no 'corefile' option for
'demangler-warning': demangler warnings always create a core
file and this cannot be disabled.
'maint packet TEXT'
If GDB is talking to an inferior via the serial protocol, then this
command sends the string TEXT to the inferior, and displays the
response packet. GDB supplies the initial '$' character, the
terminating '#' character, and the checksum.
'maint print architecture [FILE]'
Print the entire architecture configuration. The optional argument
FILE names the file where the output goes.
'maint print c-tdesc'
Print the target description (Target Descriptions) as a C
source file. By default, the target description is for the current
target, but if the optional argument FILE is provided, that file is
used to produce the description. The FILE should be an XML
document, of the form described in Target Description
Format. The created source file is built into GDB when GDB is
built again. This command is used by developers after they add or
modify XML target descriptions.
'maint check xml-descriptions DIR'
Check that the target descriptions dynamically created by GDB equal
the descriptions created from XML files found in DIR.
'maint check libthread-db'
Run integrity checks on the current inferior's thread debugging
library. This exercises all 'libthread_db' functionality used by
GDB on GNU/Linux systems, and by extension also exercises the
'proc_service' functions provided by GDB that 'libthread_db' uses.
Note that parts of the test may be skipped on some platforms when
debugging core files.
'maint print dummy-frames'
Prints the contents of GDB's internal dummy-frame stack.
(gdb) b add
...
(gdb) print add(2,3)
Breakpoint 2, add (a=2, b=3) at ...
58 return (a + b);
The program being debugged stopped while in a function called from GDB.
...
(gdb) maint print dummy-frames
0xa8206d8: id={stack=0xbfffe734,code=0xbfffe73f,!special}, ptid=process 9353
(gdb)
Takes an optional file parameter.
'maint print registers [FILE]'
'maint print raw-registers [FILE]'
'maint print cooked-registers [FILE]'
'maint print register-groups [FILE]'
'maint print remote-registers [FILE]'
Print GDB's internal register data structures.
The command 'maint print raw-registers' includes the contents of
the raw register cache; the command 'maint print cooked-registers'
includes the (cooked) value of all registers, including registers
which aren't available on the target nor visible to user; the
command 'maint print register-groups' includes the groups that each
register is a member of; and the command 'maint print
remote-registers' includes the remote target's register numbers and
offsets in the 'G' packets.
These commands take an optional parameter, a file name to which to
write the information.
'maint print reggroups [FILE]'
Print GDB's internal register group data structures. The optional
argument FILE tells to what file to write the information.
The register groups info looks like this:
(gdb) maint print reggroups
Group Type
general user
float user
all user
vector user
system user
save internal
restore internal
'flushregs'
This command forces GDB to flush its internal register cache.
'maint print objfiles [REGEXP]'
Print a dump of all known object files. If REGEXP is specified,
only print object files whose names match REGEXP. For each object
file, this command prints its name, address in memory, and all of
its psymtabs and symtabs.
'maint print user-registers'
List all currently available "user registers". User registers
typically provide alternate names for actual hardware registers.
They include the four "standard" registers '$fp', '$pc', '$sp', and
'$ps'. standard registers. User registers can be used in
expressions in the same way as the canonical register names, but
only the latter are listed by the 'info registers' and 'maint print
registers' commands.
'maint print section-scripts [REGEXP]'
Print a dump of scripts specified in the '.debug_gdb_section'
section. If REGEXP is specified, only print scripts loaded by
object files matching REGEXP. For each script, this command prints
its name as specified in the objfile, and the full path if known.
dotdebug_gdb_scripts section.
'maint print statistics'
This command prints, for each object file in the program, various
data about that object file followed by the byte cache ("bcache")
statistics for the object file. The objfile data includes the
number of minimal, partial, full, and stabs symbols, the number of
types defined by the objfile, the number of as yet unexpanded psym
tables, the number of line tables and string tables, and the amount
of memory used by the various tables. The bcache statistics
include the counts, sizes, and counts of duplicates of all and
unique objects, max, average, and median entry size, total memory
used and its overhead and savings, and various measures of the hash
table size and chain lengths.
'maint print target-stack'
A "target" is an interface between the debugger and a particular
kind of file or process. Targets can be stacked in "strata", so
that more than one target can potentially respond to a request. In
particular, memory accesses will walk down the stack of targets
until they find a target that is interested in handling that
particular address.
This command prints a short description of each layer that was
pushed on the "target stack", starting from the top layer down to
the bottom one.
'maint print type EXPR'
Print the type chain for a type specified by EXPR. The argument
can be either a type name or a symbol. If it is a symbol, the type
of that symbol is described. The type chain produced by this
command is a recursive definition of the data type as stored in
GDB's data structures, including its flags and contained types.
'maint selftest [FILTER]'
Run any self tests that were compiled in to GDB. This will print a
message showing how many tests were run, and how many failed. If a
FILTER is passed, only the tests with FILTER in their name will by
ran.
'maint info selftests'
List the selftests compiled in to GDB.
'maint set dwarf always-disassemble'
'maint show dwarf always-disassemble'
Control the behavior of 'info address' when using DWARF debugging
information.
The default is 'off', which means that GDB should try to describe a
variable's location in an easily readable format. When 'on', GDB
will instead display the DWARF location expression in an
assembly-like format. Note that some locations are too complex for
GDB to describe simply; in this case you will always see the
disassembly form.
Here is an example of the resulting disassembly:
(gdb) info addr argc
Symbol "argc" is a complex DWARF expression:
1: DW_OP_fbreg 0
For more information on these expressions, see the DWARF standard
(http://www.dwarfstd.org/).
'maint set dwarf max-cache-age'
'maint show dwarf max-cache-age'
Control the DWARF compilation unit cache.
In object files with inter-compilation-unit references, such as
those produced by the GCC option '-feliminate-dwarf2-dups', the
DWARF reader needs to frequently refer to previously read
compilation units. This setting controls how long a compilation
unit will remain in the cache if it is not referenced. A higher
limit means that cached compilation units will be stored in memory
longer, and more total memory will be used. Setting it to zero
disables caching, which will slow down GDB startup, but reduce
memory consumption.
'maint set dwarf unwinders'
'maint show dwarf unwinders'
Control use of the DWARF frame unwinders.
Many targets that support DWARF debugging use GDB's DWARF frame
unwinders to build the backtrace. Many of these targets will also
have a second mechanism for building the backtrace for use in cases
where DWARF information is not available, this second mechanism is
often an analysis of a function's prologue.
In order to extend testing coverage of the second level stack
unwinding mechanisms it is helpful to be able to disable the DWARF
stack unwinders, this can be done with this switch.
In normal use of GDB disabling the DWARF unwinders is not
advisable, there are cases that are better handled through DWARF
than prologue analysis, and the debug experience is likely to be
better with the DWARF frame unwinders enabled.
If DWARF frame unwinders are not supported for a particular target
architecture, then enabling this flag does not cause them to be
used.
'maint set profile'
'maint show profile'
Control profiling of GDB.
Profiling will be disabled until you use the 'maint set profile'
command to enable it. When you enable profiling, the system will
begin collecting timing and execution count data; when you disable
profiling or exit GDB, the results will be written to a log file.
Remember that if you use profiling, GDB will overwrite the
profiling log file (often called 'gmon.out'). If you have a record
of important profiling data in a 'gmon.out' file, be sure to move
it to a safe location.
Configuring with '--enable-profiling' arranges for GDB to be
compiled with the '-pg' compiler option.
'maint set show-debug-regs'
'maint show show-debug-regs'
Control whether to show variables that mirror the hardware debug
registers. Use 'on' to enable, 'off' to disable. If enabled, the
debug registers values are shown when GDB inserts or removes a
hardware breakpoint or watchpoint, and when the inferior triggers a
hardware-assisted breakpoint or watchpoint.
'maint set show-all-tib'
'maint show show-all-tib'
Control whether to show all non zero areas within a 1k block
starting at thread local base, when using the 'info w32
thread-information-block' command.
'maint set target-async'
'maint show target-async'
This controls whether GDB targets operate in synchronous or
asynchronous mode (Background Execution). Normally the
default is asynchronous, if it is available; but this can be
changed to more easily debug problems occurring only in synchronous
mode.
'maint set target-non-stop'
'maint show target-non-stop'
This controls whether GDB targets always operate in non-stop mode
even if 'set non-stop' is 'off' (Non-Stop Mode). The
default is 'auto', meaning non-stop mode is enabled if supported by
the target.
'maint set target-non-stop auto'
This is the default mode. GDB controls the target in non-stop
mode if the target supports it.
'maint set target-non-stop on'
GDB controls the target in non-stop mode even if the target
does not indicate support.
'maint set target-non-stop off'
GDB does not control the target in non-stop mode even if the
target supports it.
'maint set per-command'
'maint show per-command'
GDB can display the resources used by each command. This is useful
in debugging performance problems.
'maint set per-command space [on|off]'
'maint show per-command space'
Enable or disable the printing of the memory used by GDB for
each command. If enabled, GDB will display how much memory
each command took, following the command's own output. This
can also be requested by invoking GDB with the '--statistics'
command-line switch (Mode Options).
'maint set per-command time [on|off]'
'maint show per-command time'
Enable or disable the printing of the execution time of GDB
for each command. If enabled, GDB will display how much time
it took to execute each command, following the command's own
output. Both CPU time and wallclock time are printed.
Printing both is useful when trying to determine whether the
cost is CPU or, e.g., disk/network latency. Note that the CPU
time printed is for GDB only, it does not include the
execution time of the inferior because there's no mechanism
currently to compute how much time was spent by GDB and how
much time was spent by the program been debugged. This can
also be requested by invoking GDB with the '--statistics'
command-line switch (Mode Options).
'maint set per-command symtab [on|off]'
'maint show per-command symtab'
Enable or disable the printing of basic symbol table
statistics for each command. If enabled, GDB will display the
following information:
a. number of symbol tables
b. number of primary symbol tables
c. number of blocks in the blockvector
'maint set check-libthread-db [on|off]'
'maint show check-libthread-db'
Control whether GDB should run integrity checks on inferior
specific thread debugging libraries as they are loaded. The
default is not to perform such checks. If any check fails GDB will
unload the library and continue searching for a suitable candidate
as described in set libthread-db-search-path. For more
information about the tests, see maint check libthread-db.
'maint space VALUE'
An alias for 'maint set per-command space'. A non-zero value
enables it, zero disables it.
'maint time VALUE'
An alias for 'maint set per-command time'. A non-zero value
enables it, zero disables it.
'maint translate-address [SECTION] ADDR'
Find the symbol stored at the location specified by the address
ADDR and an optional section name SECTION. If found, GDB prints
the name of the closest symbol and an offset from the symbol's
location to the specified address. This is similar to the 'info
address' command (Symbols), except that this command also
allows to find symbols in other sections.
If section was not specified, the section in which the symbol was
found is also printed. For dynamically linked executables, the
name of executable or shared library containing the symbol is
printed as well.
The following command is useful for non-interactive invocations of
GDB, such as in the test suite.
'set watchdog NSEC'
Set the maximum number of seconds GDB will wait for the target
operation to finish. If this time expires, GDB reports and error
and the command is aborted.
'show watchdog'
Show the current setting of the target wait timeout.
Info Catalog
gdb: Installing GDB
gdb: Top
gdb: Remote Protocol