| Debugging with GDB: Maintenance Commands |
|---|
Next: Remote Protocol, Previous: Installing GDB, Up: Top [Contents][Index]
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
(see 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 (see 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:
Newer blocks have higher numbers. The oldest block has number zero.
pt
For the Intel Processor Trace recording format, print a list of Intel Processor Trace packets. For each packet, the following information is printed:
Newer packets have higher numbers. The oldest packet has number zero.
The packet’s offset in the trace stream.
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 (see 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.
You can specify that GDB should always (yes) or never (no) quit. The default is to ask the user what to do.
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 (see 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 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. See 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.
See 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.
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 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 (see 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 (see 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 (see 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 (see 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:
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 (see 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.
Next: Remote Protocol, Previous: Installing GDB, Up: Top [Contents][Index]