7527 lines
304 KiB
Plaintext
7527 lines
304 KiB
Plaintext
This is gdb.info, produced by makeinfo version 6.5 from gdb.texinfo.
|
||
|
||
Copyright (C) 1988-2020 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
any later version published by the Free Software Foundation; with the
|
||
Invariant Sections being "Free Software" and "Free Software Needs Free
|
||
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
||
with the Back-Cover Texts as in (a) below.
|
||
|
||
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
||
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
||
developing GNU and promoting software freedom."
|
||
INFO-DIR-SECTION Software development
|
||
START-INFO-DIR-ENTRY
|
||
* Gdb: (gdb). The GNU debugger.
|
||
* gdbserver: (gdb) Server. The GNU debugging server.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
This file documents the GNU debugger GDB.
|
||
|
||
This is the Tenth Edition, of 'Debugging with GDB: the GNU
|
||
Source-Level Debugger' for GDB (GDB) Version 9.2.
|
||
|
||
Copyright (C) 1988-2020 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
any later version published by the Free Software Foundation; with the
|
||
Invariant Sections being "Free Software" and "Free Software Needs Free
|
||
Documentation", with the Front-Cover Texts being "A GNU Manual," and
|
||
with the Back-Cover Texts as in (a) below.
|
||
|
||
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
|
||
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
||
developing GNU and promoting software freedom."
|
||
|
||
|
||
File: gdb.info, Node: Screen Size, Next: Output Styling, Prev: Command History, Up: Controlling GDB
|
||
|
||
22.4 Screen Size
|
||
================
|
||
|
||
Certain commands to GDB may produce large amounts of information output
|
||
to the screen. To help you read all of it, GDB pauses and asks you for
|
||
input at the end of each page of output. Type <RET> when you want to
|
||
see one more page of output, 'q' to discard the remaining output, or 'c'
|
||
to continue without paging for the rest of the current command. Also,
|
||
the screen width setting determines when to wrap lines of output.
|
||
Depending on what is being printed, GDB tries to break the line at a
|
||
readable place, rather than simply letting it overflow onto the
|
||
following line.
|
||
|
||
Normally GDB knows the size of the screen from the terminal driver
|
||
software. For example, on Unix GDB uses the termcap data base together
|
||
with the value of the 'TERM' environment variable and the 'stty rows'
|
||
and 'stty cols' settings. If this is not correct, you can override it
|
||
with the 'set height' and 'set width' commands:
|
||
|
||
'set height LPP'
|
||
'set height unlimited'
|
||
'show height'
|
||
'set width CPL'
|
||
'set width unlimited'
|
||
'show width'
|
||
These 'set' commands specify a screen height of LPP lines and a
|
||
screen width of CPL characters. The associated 'show' commands
|
||
display the current settings.
|
||
|
||
If you specify a height of either 'unlimited' or zero lines, GDB
|
||
does not pause during output no matter how long the output is.
|
||
This is useful if output is to a file or to an editor buffer.
|
||
|
||
Likewise, you can specify 'set width unlimited' or 'set width 0' to
|
||
prevent GDB from wrapping its output.
|
||
|
||
'set pagination on'
|
||
'set pagination off'
|
||
Turn the output pagination on or off; the default is on. Turning
|
||
pagination off is the alternative to 'set height unlimited'. Note
|
||
that running GDB with the '--batch' option (*note -batch: Mode
|
||
Options.) also automatically disables pagination.
|
||
|
||
'show pagination'
|
||
Show the current pagination mode.
|
||
|
||
|
||
File: gdb.info, Node: Output Styling, Next: Numbers, Prev: Screen Size, Up: Controlling GDB
|
||
|
||
22.5 Output Styling
|
||
===================
|
||
|
||
GDB can style its output on a capable terminal. This is enabled by
|
||
default on most systems, but disabled by default when in batch mode
|
||
(*note Mode Options::). Various style settings are available; and
|
||
styles can also be disabled entirely.
|
||
|
||
'set style enabled 'on|off''
|
||
Enable or disable all styling. The default is host-dependent, with
|
||
most hosts defaulting to 'on'.
|
||
|
||
'show style enabled'
|
||
Show the current state of styling.
|
||
|
||
'set style sources 'on|off''
|
||
Enable or disable source code styling. This affects whether source
|
||
code, such as the output of the 'list' command, is styled. Note
|
||
that source styling only works if styling in general is enabled,
|
||
and if GDB was linked with the GNU Source Highlight library. The
|
||
default is 'on'.
|
||
|
||
'show style sources'
|
||
Show the current state of source code styling.
|
||
|
||
Subcommands of 'set style' control specific forms of styling. These
|
||
subcommands all follow the same pattern: each style-able object can be
|
||
styled with a foreground color, a background color, and an intensity.
|
||
|
||
For example, the style of file names can be controlled using the 'set
|
||
style filename' group of commands:
|
||
|
||
'set style filename background COLOR'
|
||
Set the background to COLOR. Valid colors are 'none' (meaning the
|
||
terminal's default color), 'black', 'red', 'green', 'yellow',
|
||
'blue', 'magenta', 'cyan', and'white'.
|
||
|
||
'set style filename foreground COLOR'
|
||
Set the foreground to COLOR. Valid colors are 'none' (meaning the
|
||
terminal's default color), 'black', 'red', 'green', 'yellow',
|
||
'blue', 'magenta', 'cyan', and'white'.
|
||
|
||
'set style filename intensity VALUE'
|
||
Set the intensity to VALUE. Valid intensities are 'normal' (the
|
||
default), 'bold', and 'dim'.
|
||
|
||
The 'show style' command and its subcommands are styling a style name
|
||
in their output using its own style. So, use 'show style' to see the
|
||
complete list of styles, their characteristics and the visual aspect of
|
||
each style.
|
||
|
||
The style-able objects are:
|
||
'filename'
|
||
Control the styling of file names. By default, this style's
|
||
foreground color is green.
|
||
|
||
'function'
|
||
Control the styling of function names. These are managed with the
|
||
'set style function' family of commands. By default, this style's
|
||
foreground color is yellow.
|
||
|
||
'variable'
|
||
Control the styling of variable names. These are managed with the
|
||
'set style variable' family of commands. By default, this style's
|
||
foreground color is cyan.
|
||
|
||
'address'
|
||
Control the styling of addresses. These are managed with the 'set
|
||
style address' family of commands. By default, this style's
|
||
foreground color is blue.
|
||
|
||
'title'
|
||
Control the styling of titles. These are managed with the 'set
|
||
style title' family of commands. By default, this style's
|
||
intensity is bold. Commands are using the title style to improve
|
||
the readability of large output. For example, the commands
|
||
'apropos' and 'help' are using the title style for the command
|
||
names.
|
||
|
||
'highlight'
|
||
Control the styling of highlightings. These are managed with the
|
||
'set style highlight' family of commands. By default, this style's
|
||
foreground color is red. Commands are using the highlight style to
|
||
draw the user attention to some specific parts of their output.
|
||
For example, the command 'apropos -v REGEXP' uses the highlight
|
||
style to mark the documentation parts matching REGEXP.
|
||
|
||
'tui-border'
|
||
Control the styling of the TUI border. Note that, unlike other
|
||
styling options, only the color of the border can be controlled via
|
||
'set style'. This was done for compatibility reasons, as TUI
|
||
controls to set the border's intensity predated the addition of
|
||
general styling to GDB. *Note TUI Configuration::.
|
||
|
||
'tui-active-border'
|
||
Control the styling of the active TUI border; that is, the TUI
|
||
window that has the focus.
|
||
|
||
|
||
File: gdb.info, Node: Numbers, Next: ABI, Prev: Output Styling, Up: Controlling GDB
|
||
|
||
22.6 Numbers
|
||
============
|
||
|
||
You can always enter numbers in octal, decimal, or hexadecimal in GDB by
|
||
the usual conventions: octal numbers begin with '0', decimal numbers end
|
||
with '.', and hexadecimal numbers begin with '0x'. Numbers that neither
|
||
begin with '0' or '0x', nor end with a '.' are, by default, entered in
|
||
base 10; likewise, the default display for numbers--when no particular
|
||
format is specified--is base 10. You can change the default base for
|
||
both input and output with the commands described below.
|
||
|
||
'set input-radix BASE'
|
||
Set the default base for numeric input. Supported choices for BASE
|
||
are decimal 8, 10, or 16. The base must itself be specified either
|
||
unambiguously or using the current input radix; for example, any of
|
||
|
||
set input-radix 012
|
||
set input-radix 10.
|
||
set input-radix 0xa
|
||
|
||
sets the input base to decimal. On the other hand, 'set
|
||
input-radix 10' leaves the input radix unchanged, no matter what it
|
||
was, since '10', being without any leading or trailing signs of its
|
||
base, is interpreted in the current radix. Thus, if the current
|
||
radix is 16, '10' is interpreted in hex, i.e. as 16 decimal, which
|
||
doesn't change the radix.
|
||
|
||
'set output-radix BASE'
|
||
Set the default base for numeric display. Supported choices for
|
||
BASE are decimal 8, 10, or 16. The base must itself be specified
|
||
either unambiguously or using the current input radix.
|
||
|
||
'show input-radix'
|
||
Display the current default base for numeric input.
|
||
|
||
'show output-radix'
|
||
Display the current default base for numeric display.
|
||
|
||
'set radix [BASE]'
|
||
'show radix'
|
||
These commands set and show the default base for both input and
|
||
output of numbers. 'set radix' sets the radix of input and output
|
||
to the same base; without an argument, it resets the radix back to
|
||
its default value of 10.
|
||
|
||
|
||
File: gdb.info, Node: ABI, Next: Auto-loading, Prev: Numbers, Up: Controlling GDB
|
||
|
||
22.7 Configuring the Current ABI
|
||
================================
|
||
|
||
GDB can determine the "ABI" (Application Binary Interface) of your
|
||
application automatically. However, sometimes you need to override its
|
||
conclusions. Use these commands to manage GDB's view of the current
|
||
ABI.
|
||
|
||
One GDB configuration can debug binaries for multiple operating
|
||
system targets, either via remote debugging or native emulation. GDB
|
||
will autodetect the "OS ABI" (Operating System ABI) in use, but you can
|
||
override its conclusion using the 'set osabi' command. One example
|
||
where this is useful is in debugging of binaries which use an alternate
|
||
C library (e.g. UCLIBC for GNU/Linux) which does not have the same
|
||
identifying marks that the standard C library for your platform
|
||
provides.
|
||
|
||
When GDB is debugging the AArch64 architecture, it provides a
|
||
"Newlib" OS ABI. This is useful for handling 'setjmp' and 'longjmp' when
|
||
debugging binaries that use the NEWLIB C library. The "Newlib" OS ABI
|
||
can be selected by 'set osabi Newlib'.
|
||
|
||
'show osabi'
|
||
Show the OS ABI currently in use.
|
||
|
||
'set osabi'
|
||
With no argument, show the list of registered available OS ABI's.
|
||
|
||
'set osabi ABI'
|
||
Set the current OS ABI to ABI.
|
||
|
||
Generally, the way that an argument of type 'float' is passed to a
|
||
function depends on whether the function is prototyped. For a
|
||
prototyped (i.e. ANSI/ISO style) function, 'float' arguments are passed
|
||
unchanged, according to the architecture's convention for 'float'. For
|
||
unprototyped (i.e. K&R style) functions, 'float' arguments are first
|
||
promoted to type 'double' and then passed.
|
||
|
||
Unfortunately, some forms of debug information do not reliably
|
||
indicate whether a function is prototyped. If GDB calls a function that
|
||
is not marked as prototyped, it consults 'set coerce-float-to-double'.
|
||
|
||
'set coerce-float-to-double'
|
||
'set coerce-float-to-double on'
|
||
Arguments of type 'float' will be promoted to 'double' when passed
|
||
to an unprototyped function. This is the default setting.
|
||
|
||
'set coerce-float-to-double off'
|
||
Arguments of type 'float' will be passed directly to unprototyped
|
||
functions.
|
||
|
||
'show coerce-float-to-double'
|
||
Show the current setting of promoting 'float' to 'double'.
|
||
|
||
GDB needs to know the ABI used for your program's C++ objects. The
|
||
correct C++ ABI depends on which C++ compiler was used to build your
|
||
application. GDB only fully supports programs with a single C++ ABI; if
|
||
your program contains code using multiple C++ ABI's or if GDB can not
|
||
identify your program's ABI correctly, you can tell GDB which ABI to
|
||
use. Currently supported ABI's include "gnu-v2", for 'g++' versions
|
||
before 3.0, "gnu-v3", for 'g++' versions 3.0 and later, and "hpaCC" for
|
||
the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or
|
||
"gnu-v3" ABI's as well. The default setting is "auto".
|
||
|
||
'show cp-abi'
|
||
Show the C++ ABI currently in use.
|
||
|
||
'set cp-abi'
|
||
With no argument, show the list of supported C++ ABI's.
|
||
|
||
'set cp-abi ABI'
|
||
'set cp-abi auto'
|
||
Set the current C++ ABI to ABI, or return to automatic detection.
|
||
|
||
|
||
File: gdb.info, Node: Auto-loading, Next: Messages/Warnings, Prev: ABI, Up: Controlling GDB
|
||
|
||
22.8 Automatically loading associated files
|
||
===========================================
|
||
|
||
GDB sometimes reads files with commands and settings automatically,
|
||
without being explicitly told so by the user. We call this feature
|
||
"auto-loading". While auto-loading is useful for automatically adapting
|
||
GDB to the needs of your project, it can sometimes produce unexpected
|
||
results or introduce security risks (e.g., if the file comes from
|
||
untrusted sources).
|
||
|
||
* Menu:
|
||
|
||
* Init File in the Current Directory:: 'set/show/info auto-load local-gdbinit'
|
||
* libthread_db.so.1 file:: 'set/show/info auto-load libthread-db'
|
||
|
||
* Auto-loading safe path:: 'set/show/info auto-load safe-path'
|
||
* Auto-loading verbose mode:: 'set/show debug auto-load'
|
||
|
||
There are various kinds of files GDB can automatically load. In
|
||
addition to these files, GDB supports auto-loading code written in
|
||
various extension languages. *Note Auto-loading extensions::.
|
||
|
||
Note that loading of these associated files (including the local
|
||
'.gdbinit' file) requires accordingly configured 'auto-load safe-path'
|
||
(*note Auto-loading safe path::).
|
||
|
||
For these reasons, GDB includes commands and options to let you
|
||
control when to auto-load files and which files should be auto-loaded.
|
||
|
||
'set auto-load off'
|
||
Globally disable loading of all auto-loaded files. You may want to
|
||
use this command with the '-iex' option (*note Option
|
||
-init-eval-command::) such as:
|
||
$ gdb -iex "set auto-load off" untrusted-executable corefile
|
||
|
||
Be aware that system init file (*note System-wide configuration::)
|
||
and init files from your home directory (*note Home Directory Init
|
||
File::) still get read (as they come from generally trusted
|
||
directories). To prevent GDB from auto-loading even those init
|
||
files, use the '-nx' option (*note Mode Options::), in addition to
|
||
'set auto-load no'.
|
||
|
||
'show auto-load'
|
||
Show whether auto-loading of each specific 'auto-load' file(s) is
|
||
enabled or disabled.
|
||
|
||
(gdb) show auto-load
|
||
gdb-scripts: Auto-loading of canned sequences of commands scripts is on.
|
||
libthread-db: Auto-loading of inferior specific libthread_db is on.
|
||
local-gdbinit: Auto-loading of .gdbinit script from current directory
|
||
is on.
|
||
python-scripts: Auto-loading of Python scripts is on.
|
||
safe-path: List of directories from which it is safe to auto-load files
|
||
is $debugdir:$datadir/auto-load.
|
||
scripts-directory: List of directories from which to load auto-loaded scripts
|
||
is $debugdir:$datadir/auto-load.
|
||
|
||
'info auto-load'
|
||
Print whether each specific 'auto-load' file(s) have been
|
||
auto-loaded or not.
|
||
|
||
(gdb) info auto-load
|
||
gdb-scripts:
|
||
Loaded Script
|
||
Yes /home/user/gdb/gdb-gdb.gdb
|
||
libthread-db: No auto-loaded libthread-db.
|
||
local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been
|
||
loaded.
|
||
python-scripts:
|
||
Loaded Script
|
||
Yes /home/user/gdb/gdb-gdb.py
|
||
|
||
These are GDB control commands for the auto-loading:
|
||
|
||
*Note set auto-load off::. Disable auto-loading globally.
|
||
*Note show auto-load::. Show setting of all kinds of
|
||
files.
|
||
*Note info auto-load::. Show state of all kinds of files.
|
||
*Note set auto-load gdb-scripts::. Control for GDB command scripts.
|
||
*Note show auto-load gdb-scripts::. Show setting of GDB command
|
||
scripts.
|
||
*Note info auto-load gdb-scripts::. Show state of GDB command scripts.
|
||
*Note set auto-load python-scripts::.Control for GDB Python scripts.
|
||
*Note show auto-load python-scripts::.Show setting of GDB Python
|
||
scripts.
|
||
*Note info auto-load python-scripts::.Show state of GDB Python scripts.
|
||
*Note set auto-load guile-scripts::. Control for GDB Guile scripts.
|
||
*Note show auto-load guile-scripts::.Show setting of GDB Guile scripts.
|
||
*Note info auto-load guile-scripts::.Show state of GDB Guile scripts.
|
||
*Note set auto-load scripts-directory::.Control for GDB auto-loaded
|
||
scripts location.
|
||
*Note show auto-load scripts-directory::.Show GDB auto-loaded scripts
|
||
location.
|
||
*Note add-auto-load-scripts-directory::.Add directory for auto-loaded
|
||
scripts location list.
|
||
*Note set auto-load local-gdbinit::. Control for init file in the
|
||
current directory.
|
||
*Note show auto-load local-gdbinit::.Show setting of init file in the
|
||
current directory.
|
||
*Note info auto-load local-gdbinit::.Show state of init file in the
|
||
current directory.
|
||
*Note set auto-load libthread-db::. Control for thread debugging
|
||
library.
|
||
*Note show auto-load libthread-db::. Show setting of thread debugging
|
||
library.
|
||
*Note info auto-load libthread-db::. Show state of thread debugging
|
||
library.
|
||
*Note set auto-load safe-path::. Control directories trusted for
|
||
automatic loading.
|
||
*Note show auto-load safe-path::. Show directories trusted for
|
||
automatic loading.
|
||
*Note add-auto-load-safe-path::. Add directory trusted for
|
||
automatic loading.
|
||
|
||
|
||
File: gdb.info, Node: Init File in the Current Directory, Next: libthread_db.so.1 file, Up: Auto-loading
|
||
|
||
22.8.1 Automatically loading init file in the current directory
|
||
---------------------------------------------------------------
|
||
|
||
By default, GDB reads and executes the canned sequences of commands from
|
||
init file (if any) in the current working directory, see *note Init File
|
||
in the Current Directory during Startup::.
|
||
|
||
Note that loading of this local '.gdbinit' file also requires
|
||
accordingly configured 'auto-load safe-path' (*note Auto-loading safe
|
||
path::).
|
||
|
||
'set auto-load local-gdbinit [on|off]'
|
||
Enable or disable the auto-loading of canned sequences of commands
|
||
(*note Sequences::) found in init file in the current directory.
|
||
|
||
'show auto-load local-gdbinit'
|
||
Show whether auto-loading of canned sequences of commands from init
|
||
file in the current directory is enabled or disabled.
|
||
|
||
'info auto-load local-gdbinit'
|
||
Print whether canned sequences of commands from init file in the
|
||
current directory have been auto-loaded.
|
||
|
||
|
||
File: gdb.info, Node: libthread_db.so.1 file, Next: Auto-loading safe path, Prev: Init File in the Current Directory, Up: Auto-loading
|
||
|
||
22.8.2 Automatically loading thread debugging library
|
||
-----------------------------------------------------
|
||
|
||
This feature is currently present only on GNU/Linux native hosts.
|
||
|
||
GDB reads in some cases thread debugging library from places specific
|
||
to the inferior (*note set libthread-db-search-path::).
|
||
|
||
The special 'libthread-db-search-path' entry '$sdir' is processed
|
||
without checking this 'set auto-load libthread-db' switch as system
|
||
libraries have to be trusted in general. In all other cases of
|
||
'libthread-db-search-path' entries GDB checks first if 'set auto-load
|
||
libthread-db' is enabled before trying to open such thread debugging
|
||
library.
|
||
|
||
Note that loading of this debugging library also requires accordingly
|
||
configured 'auto-load safe-path' (*note Auto-loading safe path::).
|
||
|
||
'set auto-load libthread-db [on|off]'
|
||
Enable or disable the auto-loading of inferior specific thread
|
||
debugging library.
|
||
|
||
'show auto-load libthread-db'
|
||
Show whether auto-loading of inferior specific thread debugging
|
||
library is enabled or disabled.
|
||
|
||
'info auto-load libthread-db'
|
||
Print the list of all loaded inferior specific thread debugging
|
||
libraries and for each such library print list of inferior PIDs
|
||
using it.
|
||
|
||
|
||
File: gdb.info, Node: Auto-loading safe path, Next: Auto-loading verbose mode, Prev: libthread_db.so.1 file, Up: Auto-loading
|
||
|
||
22.8.3 Security restriction for auto-loading
|
||
--------------------------------------------
|
||
|
||
As the files of inferior can come from untrusted source (such as
|
||
submitted by an application user) GDB does not always load any files
|
||
automatically. GDB provides the 'set auto-load safe-path' setting to
|
||
list directories trusted for loading files not explicitly requested by
|
||
user. Each directory can also be a shell wildcard pattern.
|
||
|
||
If the path is not set properly you will see a warning and the file
|
||
will not get loaded:
|
||
|
||
$ ./gdb -q ./gdb
|
||
Reading symbols from /home/user/gdb/gdb...done.
|
||
warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been
|
||
declined by your `auto-load safe-path' set
|
||
to "$debugdir:$datadir/auto-load".
|
||
warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been
|
||
declined by your `auto-load safe-path' set
|
||
to "$debugdir:$datadir/auto-load".
|
||
|
||
To instruct GDB to go ahead and use the init files anyway, invoke GDB
|
||
like this:
|
||
|
||
$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb
|
||
|
||
The list of trusted directories is controlled by the following
|
||
commands:
|
||
|
||
'set auto-load safe-path [DIRECTORIES]'
|
||
Set the list of directories (and their subdirectories) trusted for
|
||
automatic loading and execution of scripts. You can also enter a
|
||
specific trusted file. Each directory can also be a shell wildcard
|
||
pattern; wildcards do not match directory separator - see
|
||
'FNM_PATHNAME' for system function 'fnmatch' (*note fnmatch:
|
||
(libc)Wildcard Matching.). If you omit DIRECTORIES, 'auto-load
|
||
safe-path' will be reset to its default value as specified during
|
||
GDB compilation.
|
||
|
||
The list of directories uses path separator (':' on GNU and Unix
|
||
systems, ';' on MS-Windows and MS-DOS) to separate directories,
|
||
similarly to the 'PATH' environment variable.
|
||
|
||
'show auto-load safe-path'
|
||
Show the list of directories trusted for automatic loading and
|
||
execution of scripts.
|
||
|
||
'add-auto-load-safe-path'
|
||
Add an entry (or list of entries) to the list of directories
|
||
trusted for automatic loading and execution of scripts. Multiple
|
||
entries may be delimited by the host platform path separator in
|
||
use.
|
||
|
||
This variable defaults to what '--with-auto-load-dir' has been
|
||
configured to (*note with-auto-load-dir::). '$debugdir' and '$datadir'
|
||
substitution applies the same as for *note set auto-load
|
||
scripts-directory::. The default 'set auto-load safe-path' value can be
|
||
also overriden by GDB configuration option '--with-auto-load-safe-path'.
|
||
|
||
Setting this variable to '/' disables this security protection,
|
||
corresponding GDB configuration option is
|
||
'--without-auto-load-safe-path'. This variable is supposed to be set to
|
||
the system directories writable by the system superuser only. Users can
|
||
add their source directories in init files in their home directories
|
||
(*note Home Directory Init File::). See also deprecated init file in
|
||
the current directory (*note Init File in the Current Directory during
|
||
Startup::).
|
||
|
||
To force GDB to load the files it declined to load in the previous
|
||
example, you could use one of the following ways:
|
||
|
||
'~/.gdbinit': 'add-auto-load-safe-path ~/src/gdb'
|
||
Specify this trusted directory (or a file) as additional component
|
||
of the list. You have to specify also any existing directories
|
||
displayed by by 'show auto-load safe-path' (such as '/usr:/bin' in
|
||
this example).
|
||
|
||
'gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...'
|
||
Specify this directory as in the previous case but just for a
|
||
single GDB session.
|
||
|
||
'gdb -iex "set auto-load safe-path /" ...'
|
||
Disable auto-loading safety for a single GDB session. This assumes
|
||
all the files you debug during this GDB session will come from
|
||
trusted sources.
|
||
|
||
'./configure --without-auto-load-safe-path'
|
||
During compilation of GDB you may disable any auto-loading safety.
|
||
This assumes all the files you will ever debug with this GDB come
|
||
from trusted sources.
|
||
|
||
On the other hand you can also explicitly forbid automatic files
|
||
loading which also suppresses any such warning messages:
|
||
|
||
'gdb -iex "set auto-load no" ...'
|
||
You can use GDB command-line option for a single GDB session.
|
||
|
||
'~/.gdbinit': 'set auto-load no'
|
||
Disable auto-loading globally for the user (*note Home Directory
|
||
Init File::). While it is improbable, you could also use system
|
||
init file instead (*note System-wide configuration::).
|
||
|
||
This setting applies to the file names as entered by user. If no
|
||
entry matches GDB tries as a last resort to also resolve all the file
|
||
names into their canonical form (typically resolving symbolic links) and
|
||
compare the entries again. GDB already canonicalizes most of the
|
||
filenames on its own before starting the comparison so a canonical form
|
||
of directories is recommended to be entered.
|
||
|
||
|
||
File: gdb.info, Node: Auto-loading verbose mode, Prev: Auto-loading safe path, Up: Auto-loading
|
||
|
||
22.8.4 Displaying files tried for auto-load
|
||
-------------------------------------------
|
||
|
||
For better visibility of all the file locations where you can place
|
||
scripts to be auto-loaded with inferior -- or to protect yourself
|
||
against accidental execution of untrusted scripts -- GDB provides a
|
||
feature for printing all the files attempted to be loaded. Both
|
||
existing and non-existing files may be printed.
|
||
|
||
For example the list of directories from which it is safe to
|
||
auto-load files (*note Auto-loading safe path::) applies also to
|
||
canonicalized filenames which may not be too obvious while setting it
|
||
up.
|
||
|
||
(gdb) set debug auto-load on
|
||
(gdb) file ~/src/t/true
|
||
auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb"
|
||
for objfile "/tmp/true".
|
||
auto-load: Updating directories of "/usr:/opt".
|
||
auto-load: Using directory "/usr".
|
||
auto-load: Using directory "/opt".
|
||
warning: File "/tmp/true-gdb.gdb" auto-loading has been declined
|
||
by your `auto-load safe-path' set to "/usr:/opt".
|
||
|
||
'set debug auto-load [on|off]'
|
||
Set whether to print the filenames attempted to be auto-loaded.
|
||
|
||
'show debug auto-load'
|
||
Show whether printing of the filenames attempted to be auto-loaded
|
||
is turned on or off.
|
||
|
||
|
||
File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: Auto-loading, Up: Controlling GDB
|
||
|
||
22.9 Optional Warnings and Messages
|
||
===================================
|
||
|
||
By default, GDB is silent about its inner workings. If you are running
|
||
on a slow machine, you may want to use the 'set verbose' command. This
|
||
makes GDB tell you when it does a lengthy internal operation, so you
|
||
will not think it has crashed.
|
||
|
||
Currently, the messages controlled by 'set verbose' are those which
|
||
announce that the symbol table for a source file is being read; see
|
||
'symbol-file' in *note Commands to Specify Files: Files.
|
||
|
||
'set verbose on'
|
||
Enables GDB output of certain informational messages.
|
||
|
||
'set verbose off'
|
||
Disables GDB output of certain informational messages.
|
||
|
||
'show verbose'
|
||
Displays whether 'set verbose' is on or off.
|
||
|
||
By default, if GDB encounters bugs in the symbol table of an object
|
||
file, it is silent; but if you are debugging a compiler, you may find
|
||
this information useful (*note Errors Reading Symbol Files: Symbol
|
||
Errors.).
|
||
|
||
'set complaints LIMIT'
|
||
Permits GDB to output LIMIT complaints about each type of unusual
|
||
symbols before becoming silent about the problem. Set LIMIT to
|
||
zero to suppress all complaints; set it to a large number to
|
||
prevent complaints from being suppressed.
|
||
|
||
'show complaints'
|
||
Displays how many symbol complaints GDB is permitted to produce.
|
||
|
||
By default, GDB is cautious, and asks what sometimes seems to be a
|
||
lot of stupid questions to confirm certain commands. For example, if
|
||
you try to run a program which is already running:
|
||
|
||
(gdb) run
|
||
The program being debugged has been started already.
|
||
Start it from the beginning? (y or n)
|
||
|
||
If you are willing to unflinchingly face the consequences of your own
|
||
commands, you can disable this "feature":
|
||
|
||
'set confirm off'
|
||
Disables confirmation requests. Note that running GDB with the
|
||
'--batch' option (*note -batch: Mode Options.) also automatically
|
||
disables confirmation requests.
|
||
|
||
'set confirm on'
|
||
Enables confirmation requests (the default).
|
||
|
||
'show confirm'
|
||
Displays state of confirmation requests.
|
||
|
||
If you need to debug user-defined commands or sourced files you may
|
||
find it useful to enable "command tracing". In this mode each command
|
||
will be printed as it is executed, prefixed with one or more '+'
|
||
symbols, the quantity denoting the call depth of each command.
|
||
|
||
'set trace-commands on'
|
||
Enable command tracing.
|
||
'set trace-commands off'
|
||
Disable command tracing.
|
||
'show trace-commands'
|
||
Display the current state of command tracing.
|
||
|
||
|
||
File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB
|
||
|
||
22.10 Optional Messages about Internal Happenings
|
||
=================================================
|
||
|
||
GDB has commands that enable optional debugging messages from various
|
||
GDB subsystems; normally these commands are of interest to GDB
|
||
maintainers, or when reporting a bug. This section documents those
|
||
commands.
|
||
|
||
'set exec-done-display'
|
||
Turns on or off the notification of asynchronous commands'
|
||
completion. When on, GDB will print a message when an asynchronous
|
||
command finishes its execution. The default is off.
|
||
'show exec-done-display'
|
||
Displays the current setting of asynchronous command completion
|
||
notification.
|
||
'set debug aarch64'
|
||
Turns on or off display of debugging messages related to ARM
|
||
AArch64. The default is off.
|
||
'show debug aarch64'
|
||
Displays the current state of displaying debugging messages related
|
||
to ARM AArch64.
|
||
'set debug arch'
|
||
Turns on or off display of gdbarch debugging info. The default is
|
||
off
|
||
'show debug arch'
|
||
Displays the current state of displaying gdbarch debugging info.
|
||
'set debug aix-solib'
|
||
Control display of debugging messages from the AIX shared library
|
||
support module. The default is off.
|
||
'show debug aix-thread'
|
||
Show the current state of displaying AIX shared library debugging
|
||
messages.
|
||
'set debug aix-thread'
|
||
Display debugging messages about inner workings of the AIX thread
|
||
module.
|
||
'show debug aix-thread'
|
||
Show the current state of AIX thread debugging info display.
|
||
'set debug check-physname'
|
||
Check the results of the "physname" computation. When reading
|
||
DWARF debugging information for C++, GDB attempts to compute each
|
||
entity's name. GDB can do this computation in two different ways,
|
||
depending on exactly what information is present. When enabled,
|
||
this setting causes GDB to compute the names both ways and display
|
||
any discrepancies.
|
||
'show debug check-physname'
|
||
Show the current state of "physname" checking.
|
||
'set debug coff-pe-read'
|
||
Control display of debugging messages related to reading of COFF/PE
|
||
exported symbols. The default is off.
|
||
'show debug coff-pe-read'
|
||
Displays the current state of displaying debugging messages related
|
||
to reading of COFF/PE exported symbols.
|
||
'set debug dwarf-die'
|
||
Dump DWARF DIEs after they are read in. The value is the number of
|
||
nesting levels to print. A value of zero turns off the display.
|
||
'show debug dwarf-die'
|
||
Show the current state of DWARF DIE debugging.
|
||
'set debug dwarf-line'
|
||
Turns on or off display of debugging messages related to reading
|
||
DWARF line tables. The default is 0 (off). A value of 1 provides
|
||
basic information. A value greater than 1 provides more verbose
|
||
information.
|
||
'show debug dwarf-line'
|
||
Show the current state of DWARF line table debugging.
|
||
'set debug dwarf-read'
|
||
Turns on or off display of debugging messages related to reading
|
||
DWARF debug info. The default is 0 (off). A value of 1 provides
|
||
basic information. A value greater than 1 provides more verbose
|
||
information.
|
||
'show debug dwarf-read'
|
||
Show the current state of DWARF reader debugging.
|
||
'set debug displaced'
|
||
Turns on or off display of GDB debugging info for the displaced
|
||
stepping support. The default is off.
|
||
'show debug displaced'
|
||
Displays the current state of displaying GDB debugging info related
|
||
to displaced stepping.
|
||
'set debug event'
|
||
Turns on or off display of GDB event debugging info. The default
|
||
is off.
|
||
'show debug event'
|
||
Displays the current state of displaying GDB event debugging info.
|
||
'set debug expression'
|
||
Turns on or off display of debugging info about GDB expression
|
||
parsing. The default is off.
|
||
'show debug expression'
|
||
Displays the current state of displaying debugging info about GDB
|
||
expression parsing.
|
||
'set debug fbsd-lwp'
|
||
Turns on or off debugging messages from the FreeBSD LWP debug
|
||
support.
|
||
'show debug fbsd-lwp'
|
||
Show the current state of FreeBSD LWP debugging messages.
|
||
'set debug fbsd-nat'
|
||
Turns on or off debugging messages from the FreeBSD native target.
|
||
'show debug fbsd-nat'
|
||
Show the current state of FreeBSD native target debugging messages.
|
||
'set debug frame'
|
||
Turns on or off display of GDB frame debugging info. The default
|
||
is off.
|
||
'show debug frame'
|
||
Displays the current state of displaying GDB frame debugging info.
|
||
'set debug gnu-nat'
|
||
Turn on or off debugging messages from the GNU/Hurd debug support.
|
||
'show debug gnu-nat'
|
||
Show the current state of GNU/Hurd debugging messages.
|
||
'set debug infrun'
|
||
Turns on or off display of GDB debugging info for running the
|
||
inferior. The default is off. 'infrun.c' contains GDB's runtime
|
||
state machine used for implementing operations such as
|
||
single-stepping the inferior.
|
||
'show debug infrun'
|
||
Displays the current state of GDB inferior debugging.
|
||
'set debug jit'
|
||
Turn on or off debugging messages from JIT debug support.
|
||
'show debug jit'
|
||
Displays the current state of GDB JIT debugging.
|
||
'set debug lin-lwp'
|
||
Turn on or off debugging messages from the Linux LWP debug support.
|
||
'show debug lin-lwp'
|
||
Show the current state of Linux LWP debugging messages.
|
||
'set debug linux-namespaces'
|
||
Turn on or off debugging messages from the Linux namespaces debug
|
||
support.
|
||
'show debug linux-namespaces'
|
||
Show the current state of Linux namespaces debugging messages.
|
||
'set debug mach-o'
|
||
Control display of debugging messages related to Mach-O symbols
|
||
processing. The default is off.
|
||
'show debug mach-o'
|
||
Displays the current state of displaying debugging messages related
|
||
to reading of COFF/PE exported symbols.
|
||
'set debug notification'
|
||
Turn on or off debugging messages about remote async notification.
|
||
The default is off.
|
||
'show debug notification'
|
||
Displays the current state of remote async notification debugging
|
||
messages.
|
||
'set debug observer'
|
||
Turns on or off display of GDB observer debugging. This includes
|
||
info such as the notification of observable events.
|
||
'show debug observer'
|
||
Displays the current state of observer debugging.
|
||
'set debug overload'
|
||
Turns on or off display of GDB C++ overload debugging info. This
|
||
includes info such as ranking of functions, etc. The default is
|
||
off.
|
||
'show debug overload'
|
||
Displays the current state of displaying GDB C++ overload debugging
|
||
info.
|
||
'set debug parser'
|
||
Turns on or off the display of expression parser debugging output.
|
||
Internally, this sets the 'yydebug' variable in the expression
|
||
parser. *Note Tracing Your Parser: (bison)Tracing, for details.
|
||
The default is off.
|
||
'show debug parser'
|
||
Show the current state of expression parser debugging.
|
||
'set debug remote'
|
||
Turns on or off display of reports on all packets sent back and
|
||
forth across the serial line to the remote machine. The info is
|
||
printed on the GDB standard output stream. The default is off.
|
||
'show debug remote'
|
||
Displays the state of display of remote packets.
|
||
|
||
'set debug remote-packet-max-chars'
|
||
Sets the maximum number of characters to display for each remote
|
||
packet when 'set debug remote' is on. This is useful to prevent
|
||
GDB from displaying lengthy remote packets and polluting the
|
||
console.
|
||
|
||
The default value is '512', which means GDB will truncate each
|
||
remote packet after 512 bytes.
|
||
|
||
Setting this option to 'unlimited' will disable truncation and will
|
||
output the full length of the remote packets.
|
||
'show debug remote-packet-max-chars'
|
||
Displays the number of bytes to output for remote packet debugging.
|
||
|
||
'set debug separate-debug-file'
|
||
Turns on or off display of debug output about separate debug file
|
||
search.
|
||
'show debug separate-debug-file'
|
||
Displays the state of separate debug file search debug output.
|
||
|
||
'set debug serial'
|
||
Turns on or off display of GDB serial debugging info. The default
|
||
is off.
|
||
'show debug serial'
|
||
Displays the current state of displaying GDB serial debugging info.
|
||
'set debug solib-frv'
|
||
Turn on or off debugging messages for FR-V shared-library code.
|
||
'show debug solib-frv'
|
||
Display the current state of FR-V shared-library code debugging
|
||
messages.
|
||
'set debug symbol-lookup'
|
||
Turns on or off display of debugging messages related to symbol
|
||
lookup. The default is 0 (off). A value of 1 provides basic
|
||
information. A value greater than 1 provides more verbose
|
||
information.
|
||
'show debug symbol-lookup'
|
||
Show the current state of symbol lookup debugging messages.
|
||
'set debug symfile'
|
||
Turns on or off display of debugging messages related to symbol
|
||
file functions. The default is off. *Note Files::.
|
||
'show debug symfile'
|
||
Show the current state of symbol file debugging messages.
|
||
'set debug symtab-create'
|
||
Turns on or off display of debugging messages related to symbol
|
||
table creation. The default is 0 (off). A value of 1 provides
|
||
basic information. A value greater than 1 provides more verbose
|
||
information.
|
||
'show debug symtab-create'
|
||
Show the current state of symbol table creation debugging.
|
||
'set debug target'
|
||
Turns on or off display of GDB target debugging info. This info
|
||
includes what is going on at the target level of GDB, as it
|
||
happens. The default is 0. Set it to 1 to track events, and to 2
|
||
to also track the value of large memory transfers.
|
||
'show debug target'
|
||
Displays the current state of displaying GDB target debugging info.
|
||
'set debug timestamp'
|
||
Turns on or off display of timestamps with GDB debugging info.
|
||
When enabled, seconds and microseconds are displayed before each
|
||
debugging message.
|
||
'show debug timestamp'
|
||
Displays the current state of displaying timestamps with GDB
|
||
debugging info.
|
||
'set debug varobj'
|
||
Turns on or off display of GDB variable object debugging info. The
|
||
default is off.
|
||
'show debug varobj'
|
||
Displays the current state of displaying GDB variable object
|
||
debugging info.
|
||
'set debug xml'
|
||
Turn on or off debugging messages for built-in XML parsers.
|
||
'show debug xml'
|
||
Displays the current state of XML debugging messages.
|
||
|
||
|
||
File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB
|
||
|
||
22.11 Other Miscellaneous Settings
|
||
==================================
|
||
|
||
'set interactive-mode'
|
||
If 'on', forces GDB to assume that GDB was started in a terminal.
|
||
In practice, this means that GDB should wait for the user to answer
|
||
queries generated by commands entered at the command prompt. If
|
||
'off', forces GDB to operate in the opposite mode, and it uses the
|
||
default answers to all queries. If 'auto' (the default), GDB tries
|
||
to determine whether its standard input is a terminal, and works in
|
||
interactive-mode if it is, non-interactively otherwise.
|
||
|
||
In the vast majority of cases, the debugger should be able to guess
|
||
correctly which mode should be used. But this setting can be
|
||
useful in certain specific cases, such as running a MinGW GDB
|
||
inside a cygwin window.
|
||
|
||
'show interactive-mode'
|
||
Displays whether the debugger is operating in interactive mode or
|
||
not.
|
||
|
||
|
||
File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top
|
||
|
||
23 Extending GDB
|
||
****************
|
||
|
||
GDB provides several mechanisms for extension. GDB also provides the
|
||
ability to automatically load extensions when it reads a file for
|
||
debugging. This allows the user to automatically customize GDB for the
|
||
program being debugged.
|
||
|
||
* Menu:
|
||
|
||
* Sequences:: Canned Sequences of GDB Commands
|
||
* Python:: Extending GDB using Python
|
||
* Guile:: Extending GDB using Guile
|
||
* Auto-loading extensions:: Automatically loading extensions
|
||
* Multiple Extension Languages:: Working with multiple extension languages
|
||
* Aliases:: Creating new spellings of existing commands
|
||
|
||
To facilitate the use of extension languages, GDB is capable of
|
||
evaluating the contents of a file. When doing so, GDB can recognize
|
||
which extension language is being used by looking at the filename
|
||
extension. Files with an unrecognized filename extension are always
|
||
treated as a GDB Command Files. *Note Command files: Command Files.
|
||
|
||
You can control how GDB evaluates these files with the following
|
||
setting:
|
||
|
||
'set script-extension off'
|
||
All scripts are always evaluated as GDB Command Files.
|
||
|
||
'set script-extension soft'
|
||
The debugger determines the scripting language based on filename
|
||
extension. If this scripting language is supported, GDB evaluates
|
||
the script using that language. Otherwise, it evaluates the file
|
||
as a GDB Command File.
|
||
|
||
'set script-extension strict'
|
||
The debugger determines the scripting language based on filename
|
||
extension, and evaluates the script using that language. If the
|
||
language is not supported, then the evaluation fails.
|
||
|
||
'show script-extension'
|
||
Display the current value of the 'script-extension' option.
|
||
|
||
|
||
File: gdb.info, Node: Sequences, Next: Python, Up: Extending GDB
|
||
|
||
23.1 Canned Sequences of Commands
|
||
=================================
|
||
|
||
Aside from breakpoint commands (*note Breakpoint Command Lists: Break
|
||
Commands.), GDB provides two ways to store sequences of commands for
|
||
execution as a unit: user-defined commands and command files.
|
||
|
||
* Menu:
|
||
|
||
* Define:: How to define your own commands
|
||
* Hooks:: Hooks for user-defined commands
|
||
* Command Files:: How to write scripts of commands to be stored in a file
|
||
* Output:: Commands for controlled output
|
||
* Auto-loading sequences:: Controlling auto-loaded command files
|
||
|
||
|
||
File: gdb.info, Node: Define, Next: Hooks, Up: Sequences
|
||
|
||
23.1.1 User-defined Commands
|
||
----------------------------
|
||
|
||
A "user-defined command" is a sequence of GDB commands to which you
|
||
assign a new name as a command. This is done with the 'define' command.
|
||
User commands may accept an unlimited number of arguments separated by
|
||
whitespace. Arguments are accessed within the user command via
|
||
'$arg0...$argN'. A trivial example:
|
||
|
||
define adder
|
||
print $arg0 + $arg1 + $arg2
|
||
end
|
||
|
||
To execute the command use:
|
||
|
||
adder 1 2 3
|
||
|
||
This defines the command 'adder', which prints the sum of its three
|
||
arguments. Note the arguments are text substitutions, so they may
|
||
reference variables, use complex expressions, or even perform inferior
|
||
functions calls.
|
||
|
||
In addition, '$argc' may be used to find out how many arguments have
|
||
been passed.
|
||
|
||
define adder
|
||
if $argc == 2
|
||
print $arg0 + $arg1
|
||
end
|
||
if $argc == 3
|
||
print $arg0 + $arg1 + $arg2
|
||
end
|
||
end
|
||
|
||
Combining with the 'eval' command (*note eval::) makes it easier to
|
||
process a variable number of arguments:
|
||
|
||
define adder
|
||
set $i = 0
|
||
set $sum = 0
|
||
while $i < $argc
|
||
eval "set $sum = $sum + $arg%d", $i
|
||
set $i = $i + 1
|
||
end
|
||
print $sum
|
||
end
|
||
|
||
'define COMMANDNAME'
|
||
Define a command named COMMANDNAME. If there is already a command
|
||
by that name, you are asked to confirm that you want to redefine
|
||
it. The argument COMMANDNAME may be a bare command name consisting
|
||
of letters, numbers, dashes, dots, and underscores. It may also
|
||
start with any predefined or user-defined prefix command. For
|
||
example, 'define target my-target' creates a user-defined 'target
|
||
my-target' command.
|
||
|
||
The definition of the command is made up of other GDB command
|
||
lines, which are given following the 'define' command. The end of
|
||
these commands is marked by a line containing 'end'.
|
||
|
||
'document COMMANDNAME'
|
||
Document the user-defined command COMMANDNAME, so that it can be
|
||
accessed by 'help'. The command COMMANDNAME must already be
|
||
defined. This command reads lines of documentation just as
|
||
'define' reads the lines of the command definition, ending with
|
||
'end'. After the 'document' command is finished, 'help' on command
|
||
COMMANDNAME displays the documentation you have written.
|
||
|
||
You may use the 'document' command again to change the
|
||
documentation of a command. Redefining the command with 'define'
|
||
does not change the documentation.
|
||
|
||
'define-prefix COMMANDNAME'
|
||
Define or mark the command COMMANDNAME as a user-defined prefix
|
||
command. Once marked, COMMANDNAME can be used as prefix command by
|
||
the 'define' command. Note that 'define-prefix' can be used with a
|
||
not yet defined COMMANDNAME. In such a case, COMMANDNAME is
|
||
defined as an empty user-defined command. In case you redefine a
|
||
command that was marked as a user-defined prefix command, the
|
||
subcommands of the redefined command are kept (and GDB indicates so
|
||
to the user).
|
||
|
||
Example:
|
||
(gdb) define-prefix abc
|
||
(gdb) define-prefix abc def
|
||
(gdb) define abc def
|
||
Type commands for definition of "abc def".
|
||
End with a line saying just "end".
|
||
>echo command initial def\n
|
||
>end
|
||
(gdb) define abc def ghi
|
||
Type commands for definition of "abc def ghi".
|
||
End with a line saying just "end".
|
||
>echo command ghi\n
|
||
>end
|
||
(gdb) define abc def
|
||
Keeping subcommands of prefix command "def".
|
||
Redefine command "def"? (y or n) y
|
||
Type commands for definition of "abc def".
|
||
End with a line saying just "end".
|
||
>echo command def\n
|
||
>end
|
||
(gdb) abc def ghi
|
||
command ghi
|
||
(gdb) abc def
|
||
command def
|
||
(gdb)
|
||
|
||
'dont-repeat'
|
||
Used inside a user-defined command, this tells GDB that this
|
||
command should not be repeated when the user hits <RET> (*note
|
||
repeat last command: Command Syntax.).
|
||
|
||
'help user-defined'
|
||
List all user-defined commands and all python commands defined in
|
||
class COMMAND_USER. The first line of the documentation or
|
||
docstring is included (if any).
|
||
|
||
'show user'
|
||
'show user COMMANDNAME'
|
||
Display the GDB commands used to define COMMANDNAME (but not its
|
||
documentation). If no COMMANDNAME is given, display the
|
||
definitions for all user-defined commands. This does not work for
|
||
user-defined python commands.
|
||
|
||
'show max-user-call-depth'
|
||
'set max-user-call-depth'
|
||
The value of 'max-user-call-depth' controls how many recursion
|
||
levels are allowed in user-defined commands before GDB suspects an
|
||
infinite recursion and aborts the command. This does not apply to
|
||
user-defined python commands.
|
||
|
||
In addition to the above commands, user-defined commands frequently
|
||
use control flow commands, described in *note Command Files::.
|
||
|
||
When user-defined commands are executed, the commands of the
|
||
definition are not printed. An error in any command stops execution of
|
||
the user-defined command.
|
||
|
||
If used interactively, commands that would ask for confirmation
|
||
proceed without asking when used inside a user-defined command. Many
|
||
GDB commands that normally print messages to say what they are doing
|
||
omit the messages when used in a user-defined command.
|
||
|
||
|
||
File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences
|
||
|
||
23.1.2 User-defined Command Hooks
|
||
---------------------------------
|
||
|
||
You may define "hooks", which are a special kind of user-defined
|
||
command. Whenever you run the command 'foo', if the user-defined
|
||
command 'hook-foo' exists, it is executed (with no arguments) before
|
||
that command.
|
||
|
||
A hook may also be defined which is run after the command you
|
||
executed. Whenever you run the command 'foo', if the user-defined
|
||
command 'hookpost-foo' exists, it is executed (with no arguments) after
|
||
that command. Post-execution hooks may exist simultaneously with
|
||
pre-execution hooks, for the same command.
|
||
|
||
It is valid for a hook to call the command which it hooks. If this
|
||
occurs, the hook is not re-executed, thereby avoiding infinite
|
||
recursion.
|
||
|
||
In addition, a pseudo-command, 'stop' exists. Defining ('hook-stop')
|
||
makes the associated commands execute every time execution stops in your
|
||
program: before breakpoint commands are run, displays are printed, or
|
||
the stack frame is printed.
|
||
|
||
For example, to ignore 'SIGALRM' signals while single-stepping, but
|
||
treat them normally during normal execution, you could define:
|
||
|
||
define hook-stop
|
||
handle SIGALRM nopass
|
||
end
|
||
|
||
define hook-run
|
||
handle SIGALRM pass
|
||
end
|
||
|
||
define hook-continue
|
||
handle SIGALRM pass
|
||
end
|
||
|
||
As a further example, to hook at the beginning and end of the 'echo'
|
||
command, and to add extra text to the beginning and end of the message,
|
||
you could define:
|
||
|
||
define hook-echo
|
||
echo <<<---
|
||
end
|
||
|
||
define hookpost-echo
|
||
echo --->>>\n
|
||
end
|
||
|
||
(gdb) echo Hello World
|
||
<<<---Hello World--->>>
|
||
(gdb)
|
||
|
||
|
||
You can define a hook for any single-word command in GDB, but not for
|
||
command aliases; you should define a hook for the basic command name,
|
||
e.g. 'backtrace' rather than 'bt'. You can hook a multi-word command by
|
||
adding 'hook-' or 'hookpost-' to the last word of the command, e.g.
|
||
'define target hook-remote' to add a hook to 'target remote'.
|
||
|
||
If an error occurs during the execution of your hook, execution of
|
||
GDB commands stops and GDB issues a prompt (before the command that you
|
||
actually typed had a chance to run).
|
||
|
||
If you try to define a hook which does not match any known command,
|
||
you get a warning from the 'define' command.
|
||
|
||
|
||
File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences
|
||
|
||
23.1.3 Command Files
|
||
--------------------
|
||
|
||
A command file for GDB is a text file made of lines that are GDB
|
||
commands. Comments (lines starting with '#') may also be included. An
|
||
empty line in a command file does nothing; it does not mean to repeat
|
||
the last command, as it would from the terminal.
|
||
|
||
You can request the execution of a command file with the 'source'
|
||
command. Note that the 'source' command is also used to evaluate
|
||
scripts that are not Command Files. The exact behavior can be
|
||
configured using the 'script-extension' setting. *Note Extending GDB:
|
||
Extending GDB.
|
||
|
||
'source [-s] [-v] FILENAME'
|
||
Execute the command file FILENAME.
|
||
|
||
The lines in a command file are generally executed sequentially,
|
||
unless the order of execution is changed by one of the _flow-control
|
||
commands_ described below. The commands are not printed as they are
|
||
executed. An error in any command terminates execution of the command
|
||
file and control is returned to the console.
|
||
|
||
GDB first searches for FILENAME in the current directory. If the
|
||
file is not found there, and FILENAME does not specify a directory, then
|
||
GDB also looks for the file on the source search path (specified with
|
||
the 'directory' command); except that '$cdir' is not searched because
|
||
the compilation directory is not relevant to scripts.
|
||
|
||
If '-s' is specified, then GDB searches for FILENAME on the search
|
||
path even if FILENAME specifies a directory. The search is done by
|
||
appending FILENAME to each element of the search path. So, for example,
|
||
if FILENAME is 'mylib/myscript' and the search path contains
|
||
'/home/user' then GDB will look for the script
|
||
'/home/user/mylib/myscript'. The search is also done if FILENAME is an
|
||
absolute path. For example, if FILENAME is '/tmp/myscript' and the
|
||
search path contains '/home/user' then GDB will look for the script
|
||
'/home/user/tmp/myscript'. For DOS-like systems, if FILENAME contains a
|
||
drive specification, it is stripped before concatenation. For example,
|
||
if FILENAME is 'd:myscript' and the search path contains 'c:/tmp' then
|
||
GDB will look for the script 'c:/tmp/myscript'.
|
||
|
||
If '-v', for verbose mode, is given then GDB displays each command as
|
||
it is executed. The option must be given before FILENAME, and is
|
||
interpreted as part of the filename anywhere else.
|
||
|
||
Commands that would ask for confirmation if used interactively
|
||
proceed without asking when used in a command file. Many GDB commands
|
||
that normally print messages to say what they are doing omit the
|
||
messages when called from command files.
|
||
|
||
GDB also accepts command input from standard input. In this mode,
|
||
normal output goes to standard output and error output goes to standard
|
||
error. Errors in a command file supplied on standard input do not
|
||
terminate execution of the command file--execution continues with the
|
||
next command.
|
||
|
||
gdb < cmds > log 2>&1
|
||
|
||
(The syntax above will vary depending on the shell used.) This
|
||
example will execute commands from the file 'cmds'. All output and
|
||
errors would be directed to 'log'.
|
||
|
||
Since commands stored on command files tend to be more general than
|
||
commands typed interactively, they frequently need to deal with
|
||
complicated situations, such as different or unexpected values of
|
||
variables and symbols, changes in how the program being debugged is
|
||
built, etc. GDB provides a set of flow-control commands to deal with
|
||
these complexities. Using these commands, you can write complex scripts
|
||
that loop over data structures, execute commands conditionally, etc.
|
||
|
||
'if'
|
||
'else'
|
||
This command allows to include in your script conditionally
|
||
executed commands. The 'if' command takes a single argument, which
|
||
is an expression to evaluate. It is followed by a series of
|
||
commands that are executed only if the expression is true (its
|
||
value is nonzero). There can then optionally be an 'else' line,
|
||
followed by a series of commands that are only executed if the
|
||
expression was false. The end of the list is marked by a line
|
||
containing 'end'.
|
||
|
||
'while'
|
||
This command allows to write loops. Its syntax is similar to 'if':
|
||
the command takes a single argument, which is an expression to
|
||
evaluate, and must be followed by the commands to execute, one per
|
||
line, terminated by an 'end'. These commands are called the "body"
|
||
of the loop. The commands in the body of 'while' are executed
|
||
repeatedly as long as the expression evaluates to true.
|
||
|
||
'loop_break'
|
||
This command exits the 'while' loop in whose body it is included.
|
||
Execution of the script continues after that 'while's 'end' line.
|
||
|
||
'loop_continue'
|
||
This command skips the execution of the rest of the body of
|
||
commands in the 'while' loop in whose body it is included.
|
||
Execution branches to the beginning of the 'while' loop, where it
|
||
evaluates the controlling expression.
|
||
|
||
'end'
|
||
Terminate the block of commands that are the body of 'if', 'else',
|
||
or 'while' flow-control commands.
|
||
|
||
|
||
File: gdb.info, Node: Output, Next: Auto-loading sequences, Prev: Command Files, Up: Sequences
|
||
|
||
23.1.4 Commands for Controlled Output
|
||
-------------------------------------
|
||
|
||
During the execution of a command file or a user-defined command, normal
|
||
GDB output is suppressed; the only output that appears is what is
|
||
explicitly printed by the commands in the definition. This section
|
||
describes three commands useful for generating exactly the output you
|
||
want.
|
||
|
||
'echo TEXT'
|
||
Print TEXT. Nonprinting characters can be included in TEXT using C
|
||
escape sequences, such as '\n' to print a newline. *No newline is
|
||
printed unless you specify one.* In addition to the standard C
|
||
escape sequences, a backslash followed by a space stands for a
|
||
space. This is useful for displaying a string with spaces at the
|
||
beginning or the end, since leading and trailing spaces are
|
||
otherwise trimmed from all arguments. To print ' and foo = ', use
|
||
the command 'echo \ and foo = \ '.
|
||
|
||
A backslash at the end of TEXT can be used, as in C, to continue
|
||
the command onto subsequent lines. For example,
|
||
|
||
echo This is some text\n\
|
||
which is continued\n\
|
||
onto several lines.\n
|
||
|
||
produces the same output as
|
||
|
||
echo This is some text\n
|
||
echo which is continued\n
|
||
echo onto several lines.\n
|
||
|
||
'output EXPRESSION'
|
||
Print the value of EXPRESSION and nothing but that value: no
|
||
newlines, no '$NN = '. The value is not entered in the value
|
||
history either. *Note Expressions: Expressions, for more
|
||
information on expressions.
|
||
|
||
'output/FMT EXPRESSION'
|
||
Print the value of EXPRESSION in format FMT. You can use the same
|
||
formats as for 'print'. *Note Output Formats: Output Formats, for
|
||
more information.
|
||
|
||
'printf TEMPLATE, EXPRESSIONS...'
|
||
Print the values of one or more EXPRESSIONS under the control of
|
||
the string TEMPLATE. To print several values, make EXPRESSIONS be
|
||
a comma-separated list of individual expressions, which may be
|
||
either numbers or pointers. Their values are printed as specified
|
||
by TEMPLATE, exactly as a C program would do by executing the code
|
||
below:
|
||
|
||
printf (TEMPLATE, EXPRESSIONS...);
|
||
|
||
As in 'C' 'printf', ordinary characters in TEMPLATE are printed
|
||
verbatim, while "conversion specification" introduced by the '%'
|
||
character cause subsequent EXPRESSIONS to be evaluated, their
|
||
values converted and formatted according to type and style
|
||
information encoded in the conversion specifications, and then
|
||
printed.
|
||
|
||
For example, you can print two values in hex like this:
|
||
|
||
printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo
|
||
|
||
'printf' supports all the standard 'C' conversion specifications,
|
||
including the flags and modifiers between the '%' character and the
|
||
conversion letter, with the following exceptions:
|
||
|
||
* The argument-ordering modifiers, such as '2$', are not
|
||
supported.
|
||
|
||
* The modifier '*' is not supported for specifying precision or
|
||
width.
|
||
|
||
* The ''' flag (for separation of digits into groups according
|
||
to 'LC_NUMERIC'') is not supported.
|
||
|
||
* The type modifiers 'hh', 'j', 't', and 'z' are not supported.
|
||
|
||
* The conversion letter 'n' (as in '%n') is not supported.
|
||
|
||
* The conversion letters 'a' and 'A' are not supported.
|
||
|
||
Note that the 'll' type modifier is supported only if the
|
||
underlying 'C' implementation used to build GDB supports the 'long
|
||
long int' type, and the 'L' type modifier is supported only if
|
||
'long double' type is available.
|
||
|
||
As in 'C', 'printf' supports simple backslash-escape sequences,
|
||
such as '\n', '\t', '\\', '\"', '\a', and '\f', that consist of
|
||
backslash followed by a single character. Octal and hexadecimal
|
||
escape sequences are not supported.
|
||
|
||
Additionally, 'printf' supports conversion specifications for DFP
|
||
("Decimal Floating Point") types using the following length
|
||
modifiers together with a floating point specifier. letters:
|
||
|
||
* 'H' for printing 'Decimal32' types.
|
||
|
||
* 'D' for printing 'Decimal64' types.
|
||
|
||
* 'DD' for printing 'Decimal128' types.
|
||
|
||
If the underlying 'C' implementation used to build GDB has support
|
||
for the three length modifiers for DFP types, other modifiers such
|
||
as width and precision will also be available for GDB to use.
|
||
|
||
In case there is no such 'C' support, no additional modifiers will
|
||
be available and the value will be printed in the standard way.
|
||
|
||
Here's an example of printing DFP types using the above conversion
|
||
letters:
|
||
printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl
|
||
|
||
'eval TEMPLATE, EXPRESSIONS...'
|
||
Convert the values of one or more EXPRESSIONS under the control of
|
||
the string TEMPLATE to a command line, and call it.
|
||
|
||
|
||
File: gdb.info, Node: Auto-loading sequences, Prev: Output, Up: Sequences
|
||
|
||
23.1.5 Controlling auto-loading native GDB scripts
|
||
--------------------------------------------------
|
||
|
||
When a new object file is read (for example, due to the 'file' command,
|
||
or because the inferior has loaded a shared library), GDB will look for
|
||
the command file 'OBJFILE-gdb.gdb'. *Note Auto-loading extensions::.
|
||
|
||
Auto-loading can be enabled or disabled, and the list of auto-loaded
|
||
scripts can be printed.
|
||
|
||
'set auto-load gdb-scripts [on|off]'
|
||
Enable or disable the auto-loading of canned sequences of commands
|
||
scripts.
|
||
|
||
'show auto-load gdb-scripts'
|
||
Show whether auto-loading of canned sequences of commands scripts
|
||
is enabled or disabled.
|
||
|
||
'info auto-load gdb-scripts [REGEXP]'
|
||
Print the list of all canned sequences of commands scripts that GDB
|
||
auto-loaded.
|
||
|
||
If REGEXP is supplied only canned sequences of commands scripts with
|
||
matching names are printed.
|
||
|
||
|
||
File: gdb.info, Node: Python, Next: Guile, Prev: Sequences, Up: Extending GDB
|
||
|
||
23.2 Extending GDB using Python
|
||
===============================
|
||
|
||
You can extend GDB using the Python programming language
|
||
(http://www.python.org/). This feature is available only if GDB was
|
||
configured using '--with-python'. GDB can be built against either
|
||
Python 2 or Python 3; which one you have depends on this configure-time
|
||
option.
|
||
|
||
Python scripts used by GDB should be installed in
|
||
'DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as
|
||
determined at GDB startup (*note Data Files::). This directory, known
|
||
as the "python directory", is automatically added to the Python Search
|
||
Path in order to allow the Python interpreter to locate all scripts
|
||
installed at this location.
|
||
|
||
Additionally, GDB commands and convenience functions which are
|
||
written in Python and are located in the
|
||
'DATA-DIRECTORY/python/gdb/command' or
|
||
'DATA-DIRECTORY/python/gdb/function' directories are automatically
|
||
imported when GDB starts.
|
||
|
||
* Menu:
|
||
|
||
* Python Commands:: Accessing Python from GDB.
|
||
* Python API:: Accessing GDB from Python.
|
||
* Python Auto-loading:: Automatically loading Python code.
|
||
* Python modules:: Python modules provided by GDB.
|
||
|
||
|
||
File: gdb.info, Node: Python Commands, Next: Python API, Up: Python
|
||
|
||
23.2.1 Python Commands
|
||
----------------------
|
||
|
||
GDB provides two commands for accessing the Python interpreter, and one
|
||
related setting:
|
||
|
||
'python-interactive [COMMAND]'
|
||
'pi [COMMAND]'
|
||
Without an argument, the 'python-interactive' command can be used
|
||
to start an interactive Python prompt. To return to GDB, type the
|
||
'EOF' character (e.g., 'Ctrl-D' on an empty prompt).
|
||
|
||
Alternatively, a single-line Python command can be given as an
|
||
argument and evaluated. If the command is an expression, the
|
||
result will be printed; otherwise, nothing will be printed. For
|
||
example:
|
||
|
||
(gdb) python-interactive 2 + 3
|
||
5
|
||
|
||
'python [COMMAND]'
|
||
'py [COMMAND]'
|
||
The 'python' command can be used to evaluate Python code.
|
||
|
||
If given an argument, the 'python' command will evaluate the
|
||
argument as a Python command. For example:
|
||
|
||
(gdb) python print 23
|
||
23
|
||
|
||
If you do not provide an argument to 'python', it will act as a
|
||
multi-line command, like 'define'. In this case, the Python script
|
||
is made up of subsequent command lines, given after the 'python'
|
||
command. This command list is terminated using a line containing
|
||
'end'. For example:
|
||
|
||
(gdb) python
|
||
>print 23
|
||
>end
|
||
23
|
||
|
||
'set python print-stack'
|
||
By default, GDB will print only the message component of a Python
|
||
exception when an error occurs in a Python script. This can be
|
||
controlled using 'set python print-stack': if 'full', then full
|
||
Python stack printing is enabled; if 'none', then Python stack and
|
||
message printing is disabled; if 'message', the default, only the
|
||
message component of the error is printed.
|
||
|
||
It is also possible to execute a Python script from the GDB
|
||
interpreter:
|
||
|
||
'source script-name'
|
||
The script name must end with '.py' and GDB must be configured to
|
||
recognize the script language based on filename extension using the
|
||
'script-extension' setting. *Note Extending GDB: Extending GDB.
|
||
|
||
|
||
File: gdb.info, Node: Python API, Next: Python Auto-loading, Prev: Python Commands, Up: Python
|
||
|
||
23.2.2 Python API
|
||
-----------------
|
||
|
||
You can get quick online help for GDB's Python API by issuing the
|
||
command 'python help (gdb)'.
|
||
|
||
Functions and methods which have two or more optional arguments allow
|
||
them to be specified using keyword syntax. This allows passing some
|
||
optional arguments while skipping others. Example:
|
||
'gdb.some_function ('foo', bar = 1, baz = 2)'.
|
||
|
||
* Menu:
|
||
|
||
* Basic Python:: Basic Python Functions.
|
||
* Exception Handling:: How Python exceptions are translated.
|
||
* Values From Inferior:: Python representation of values.
|
||
* Types In Python:: Python representation of types.
|
||
* Pretty Printing API:: Pretty-printing values.
|
||
* Selecting Pretty-Printers:: How GDB chooses a pretty-printer.
|
||
* Writing a Pretty-Printer:: Writing a Pretty-Printer.
|
||
* Type Printing API:: Pretty-printing types.
|
||
* Frame Filter API:: Filtering Frames.
|
||
* Frame Decorator API:: Decorating Frames.
|
||
* Writing a Frame Filter:: Writing a Frame Filter.
|
||
* Unwinding Frames in Python:: Writing frame unwinder.
|
||
* Xmethods In Python:: Adding and replacing methods of C++ classes.
|
||
* Xmethod API:: Xmethod types.
|
||
* Writing an Xmethod:: Writing an xmethod.
|
||
* Inferiors In Python:: Python representation of inferiors (processes)
|
||
* Events In Python:: Listening for events from GDB.
|
||
* Threads In Python:: Accessing inferior threads from Python.
|
||
* Recordings In Python:: Accessing recordings from Python.
|
||
* Commands In Python:: Implementing new commands in Python.
|
||
* Parameters In Python:: Adding new GDB parameters.
|
||
* Functions In Python:: Writing new convenience functions.
|
||
* Progspaces In Python:: Program spaces.
|
||
* Objfiles In Python:: Object files.
|
||
* Frames In Python:: Accessing inferior stack frames from Python.
|
||
* Blocks In Python:: Accessing blocks from Python.
|
||
* Symbols In Python:: Python representation of symbols.
|
||
* Symbol Tables In Python:: Python representation of symbol tables.
|
||
* Line Tables In Python:: Python representation of line tables.
|
||
* Breakpoints In Python:: Manipulating breakpoints using Python.
|
||
* Finish Breakpoints in Python:: Setting Breakpoints on function return
|
||
using Python.
|
||
* Lazy Strings In Python:: Python representation of lazy strings.
|
||
* Architectures In Python:: Python representation of architectures.
|
||
|
||
|
||
File: gdb.info, Node: Basic Python, Next: Exception Handling, Up: Python API
|
||
|
||
23.2.2.1 Basic Python
|
||
.....................
|
||
|
||
At startup, GDB overrides Python's 'sys.stdout' and 'sys.stderr' to
|
||
print using GDB's output-paging streams. A Python program which outputs
|
||
to one of these streams may have its output interrupted by the user
|
||
(*note Screen Size::). In this situation, a Python 'KeyboardInterrupt'
|
||
exception is thrown.
|
||
|
||
Some care must be taken when writing Python code to run in GDB. Two
|
||
things worth noting in particular:
|
||
|
||
* GDB install handlers for 'SIGCHLD' and 'SIGINT'. Python code must
|
||
not override these, or even change the options using 'sigaction'.
|
||
If your program changes the handling of these signals, GDB will
|
||
most likely stop working correctly. Note that it is unfortunately
|
||
common for GUI toolkits to install a 'SIGCHLD' handler.
|
||
|
||
* GDB takes care to mark its internal file descriptors as
|
||
close-on-exec. However, this cannot be done in a thread-safe way
|
||
on all platforms. Your Python programs should be aware of this and
|
||
should both create new file descriptors with the close-on-exec flag
|
||
set and arrange to close unneeded file descriptors before starting
|
||
a child process.
|
||
|
||
GDB introduces a new Python module, named 'gdb'. All methods and
|
||
classes added by GDB are placed in this module. GDB automatically
|
||
'import's the 'gdb' module for use in all scripts evaluated by the
|
||
'python' command.
|
||
|
||
Some types of the 'gdb' module come with a textual representation
|
||
(accessible through the 'repr' or 'str' functions). These are offered
|
||
for debugging purposes only, expect them to change over time.
|
||
|
||
-- Variable: gdb.PYTHONDIR
|
||
A string containing the python directory (*note Python::).
|
||
|
||
-- Function: gdb.execute (command [, from_tty [, to_string]])
|
||
Evaluate COMMAND, a string, as a GDB CLI command. If a GDB
|
||
exception happens while COMMAND runs, it is translated as described
|
||
in *note Exception Handling: Exception Handling.
|
||
|
||
The FROM_TTY flag specifies whether GDB ought to consider this
|
||
command as having originated from the user invoking it
|
||
interactively. It must be a boolean value. If omitted, it
|
||
defaults to 'False'.
|
||
|
||
By default, any output produced by COMMAND is sent to GDB's
|
||
standard output (and to the log output if logging is turned on).
|
||
If the TO_STRING parameter is 'True', then output will be collected
|
||
by 'gdb.execute' and returned as a string. The default is 'False',
|
||
in which case the return value is 'None'. If TO_STRING is 'True',
|
||
the GDB virtual terminal will be temporarily set to unlimited width
|
||
and height, and its pagination will be disabled; *note Screen
|
||
Size::.
|
||
|
||
-- Function: gdb.breakpoints ()
|
||
Return a sequence holding all of GDB's breakpoints. *Note
|
||
Breakpoints In Python::, for more information. In GDB version 7.11
|
||
and earlier, this function returned 'None' if there were no
|
||
breakpoints. This peculiarity was subsequently fixed, and now
|
||
'gdb.breakpoints' returns an empty sequence in this case.
|
||
|
||
-- Function: gdb.rbreak (regex [, minsyms [, throttle, [, symtabs ]]])
|
||
Return a Python list holding a collection of newly set
|
||
'gdb.Breakpoint' objects matching function names defined by the
|
||
REGEX pattern. If the MINSYMS keyword is 'True', all system
|
||
functions (those not explicitly defined in the inferior) will also
|
||
be included in the match. The THROTTLE keyword takes an integer
|
||
that defines the maximum number of pattern matches for functions
|
||
matched by the REGEX pattern. If the number of matches exceeds the
|
||
integer value of THROTTLE, a 'RuntimeError' will be raised and no
|
||
breakpoints will be created. If THROTTLE is not defined then there
|
||
is no imposed limit on the maximum number of matches and
|
||
breakpoints to be created. The SYMTABS keyword takes a Python
|
||
iterable that yields a collection of 'gdb.Symtab' objects and will
|
||
restrict the search to those functions only contained within the
|
||
'gdb.Symtab' objects.
|
||
|
||
-- Function: gdb.parameter (parameter)
|
||
Return the value of a GDB PARAMETER given by its name, a string;
|
||
the parameter name string may contain spaces if the parameter has a
|
||
multi-part name. For example, 'print object' is a valid parameter
|
||
name.
|
||
|
||
If the named parameter does not exist, this function throws a
|
||
'gdb.error' (*note Exception Handling::). Otherwise, the
|
||
parameter's value is converted to a Python value of the appropriate
|
||
type, and returned.
|
||
|
||
-- Function: gdb.history (number)
|
||
Return a value from GDB's value history (*note Value History::).
|
||
The NUMBER argument indicates which history element to return. If
|
||
NUMBER is negative, then GDB will take its absolute value and count
|
||
backward from the last element (i.e., the most recent element) to
|
||
find the value to return. If NUMBER is zero, then GDB will return
|
||
the most recent element. If the element specified by NUMBER
|
||
doesn't exist in the value history, a 'gdb.error' exception will be
|
||
raised.
|
||
|
||
If no exception is raised, the return value is always an instance
|
||
of 'gdb.Value' (*note Values From Inferior::).
|
||
|
||
-- Function: gdb.convenience_variable (name)
|
||
Return the value of the convenience variable (*note Convenience
|
||
Vars::) named NAME. NAME must be a string. The name should not
|
||
include the '$' that is used to mark a convenience variable in an
|
||
expression. If the convenience variable does not exist, then
|
||
'None' is returned.
|
||
|
||
-- Function: gdb.set_convenience_variable (name, value)
|
||
Set the value of the convenience variable (*note Convenience
|
||
Vars::) named NAME. NAME must be a string. The name should not
|
||
include the '$' that is used to mark a convenience variable in an
|
||
expression. If VALUE is 'None', then the convenience variable is
|
||
removed. Otherwise, if VALUE is not a 'gdb.Value' (*note Values
|
||
From Inferior::), it is is converted using the 'gdb.Value'
|
||
constructor.
|
||
|
||
-- Function: gdb.parse_and_eval (expression)
|
||
Parse EXPRESSION, which must be a string, as an expression in the
|
||
current language, evaluate it, and return the result as a
|
||
'gdb.Value'.
|
||
|
||
This function can be useful when implementing a new command (*note
|
||
Commands In Python::), as it provides a way to parse the command's
|
||
argument as an expression. It is also useful simply to compute
|
||
values.
|
||
|
||
-- Function: gdb.find_pc_line (pc)
|
||
Return the 'gdb.Symtab_and_line' object corresponding to the PC
|
||
value. *Note Symbol Tables In Python::. If an invalid value of PC
|
||
is passed as an argument, then the 'symtab' and 'line' attributes
|
||
of the returned 'gdb.Symtab_and_line' object will be 'None' and 0
|
||
respectively. This is identical to
|
||
'gdb.current_progspace().find_pc_line(pc)' and is included for
|
||
historical compatibility.
|
||
|
||
-- Function: gdb.post_event (event)
|
||
Put EVENT, a callable object taking no arguments, into GDB's
|
||
internal event queue. This callable will be invoked at some later
|
||
point, during GDB's event processing. Events posted using
|
||
'post_event' will be run in the order in which they were posted;
|
||
however, there is no way to know when they will be processed
|
||
relative to other events inside GDB.
|
||
|
||
GDB is not thread-safe. If your Python program uses multiple
|
||
threads, you must be careful to only call GDB-specific functions in
|
||
the GDB thread. 'post_event' ensures this. For example:
|
||
|
||
(gdb) python
|
||
>import threading
|
||
>
|
||
>class Writer():
|
||
> def __init__(self, message):
|
||
> self.message = message;
|
||
> def __call__(self):
|
||
> gdb.write(self.message)
|
||
>
|
||
>class MyThread1 (threading.Thread):
|
||
> def run (self):
|
||
> gdb.post_event(Writer("Hello "))
|
||
>
|
||
>class MyThread2 (threading.Thread):
|
||
> def run (self):
|
||
> gdb.post_event(Writer("World\n"))
|
||
>
|
||
>MyThread1().start()
|
||
>MyThread2().start()
|
||
>end
|
||
(gdb) Hello World
|
||
|
||
-- Function: gdb.write (string [, stream])
|
||
Print a string to GDB's paginated output stream. The optional
|
||
STREAM determines the stream to print to. The default stream is
|
||
GDB's standard output stream. Possible stream values are:
|
||
|
||
'gdb.STDOUT'
|
||
GDB's standard output stream.
|
||
|
||
'gdb.STDERR'
|
||
GDB's standard error stream.
|
||
|
||
'gdb.STDLOG'
|
||
GDB's log stream (*note Logging Output::).
|
||
|
||
Writing to 'sys.stdout' or 'sys.stderr' will automatically call
|
||
this function and will automatically direct the output to the
|
||
relevant stream.
|
||
|
||
-- Function: gdb.flush ()
|
||
Flush the buffer of a GDB paginated stream so that the contents are
|
||
displayed immediately. GDB will flush the contents of a stream
|
||
automatically when it encounters a newline in the buffer. The
|
||
optional STREAM determines the stream to flush. The default stream
|
||
is GDB's standard output stream. Possible stream values are:
|
||
|
||
'gdb.STDOUT'
|
||
GDB's standard output stream.
|
||
|
||
'gdb.STDERR'
|
||
GDB's standard error stream.
|
||
|
||
'gdb.STDLOG'
|
||
GDB's log stream (*note Logging Output::).
|
||
|
||
Flushing 'sys.stdout' or 'sys.stderr' will automatically call this
|
||
function for the relevant stream.
|
||
|
||
-- Function: gdb.target_charset ()
|
||
Return the name of the current target character set (*note
|
||
Character Sets::). This differs from
|
||
'gdb.parameter('target-charset')' in that 'auto' is never returned.
|
||
|
||
-- Function: gdb.target_wide_charset ()
|
||
Return the name of the current target wide character set (*note
|
||
Character Sets::). This differs from
|
||
'gdb.parameter('target-wide-charset')' in that 'auto' is never
|
||
returned.
|
||
|
||
-- Function: gdb.solib_name (address)
|
||
Return the name of the shared library holding the given ADDRESS as
|
||
a string, or 'None'. This is identical to
|
||
'gdb.current_progspace().solib_name(address)' and is included for
|
||
historical compatibility.
|
||
|
||
-- Function: gdb.decode_line ([expression])
|
||
Return locations of the line specified by EXPRESSION, or of the
|
||
current line if no argument was given. This function returns a
|
||
Python tuple containing two elements. The first element contains a
|
||
string holding any unparsed section of EXPRESSION (or 'None' if the
|
||
expression has been fully parsed). The second element contains
|
||
either 'None' or another tuple that contains all the locations that
|
||
match the expression represented as 'gdb.Symtab_and_line' objects
|
||
(*note Symbol Tables In Python::). If EXPRESSION is provided, it
|
||
is decoded the way that GDB's inbuilt 'break' or 'edit' commands do
|
||
(*note Specify Location::).
|
||
|
||
-- Function: gdb.prompt_hook (current_prompt)
|
||
|
||
If PROMPT_HOOK is callable, GDB will call the method assigned to
|
||
this operation before a prompt is displayed by GDB.
|
||
|
||
The parameter 'current_prompt' contains the current GDB prompt.
|
||
This method must return a Python string, or 'None'. If a string is
|
||
returned, the GDB prompt will be set to that string. If 'None' is
|
||
returned, GDB will continue to use the current prompt.
|
||
|
||
Some prompts cannot be substituted in GDB. Secondary prompts such
|
||
as those used by readline for command input, and annotation related
|
||
prompts are prohibited from being changed.
|
||
|
||
|
||
File: gdb.info, Node: Exception Handling, Next: Values From Inferior, Prev: Basic Python, Up: Python API
|
||
|
||
23.2.2.2 Exception Handling
|
||
...........................
|
||
|
||
When executing the 'python' command, Python exceptions uncaught within
|
||
the Python code are translated to calls to GDB error-reporting
|
||
mechanism. If the command that called 'python' does not handle the
|
||
error, GDB will terminate it and print an error message containing the
|
||
Python exception name, the associated value, and the Python call stack
|
||
backtrace at the point where the exception was raised. Example:
|
||
|
||
(gdb) python print foo
|
||
Traceback (most recent call last):
|
||
File "<string>", line 1, in <module>
|
||
NameError: name 'foo' is not defined
|
||
|
||
GDB errors that happen in GDB commands invoked by Python code are
|
||
converted to Python exceptions. The type of the Python exception
|
||
depends on the error.
|
||
|
||
'gdb.error'
|
||
This is the base class for most exceptions generated by GDB. It is
|
||
derived from 'RuntimeError', for compatibility with earlier
|
||
versions of GDB.
|
||
|
||
If an error occurring in GDB does not fit into some more specific
|
||
category, then the generated exception will have this type.
|
||
|
||
'gdb.MemoryError'
|
||
This is a subclass of 'gdb.error' which is thrown when an operation
|
||
tried to access invalid memory in the inferior.
|
||
|
||
'KeyboardInterrupt'
|
||
User interrupt (via 'C-c' or by typing 'q' at a pagination prompt)
|
||
is translated to a Python 'KeyboardInterrupt' exception.
|
||
|
||
In all cases, your exception handler will see the GDB error message
|
||
as its value and the Python call stack backtrace at the Python statement
|
||
closest to where the GDB error occured as the traceback.
|
||
|
||
When implementing GDB commands in Python via 'gdb.Command', or
|
||
functions via 'gdb.Function', it is useful to be able to throw an
|
||
exception that doesn't cause a traceback to be printed. For example,
|
||
the user may have invoked the command incorrectly. GDB provides a
|
||
special exception class that can be used for this purpose.
|
||
|
||
'gdb.GdbError'
|
||
When thrown from a command or function, this exception will cause
|
||
the command or function to fail, but the Python stack will not be
|
||
displayed. GDB does not throw this exception itself, but rather
|
||
recognizes it when thrown from user Python code. Example:
|
||
|
||
(gdb) python
|
||
>class HelloWorld (gdb.Command):
|
||
> """Greet the whole world."""
|
||
> def __init__ (self):
|
||
> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
|
||
> def invoke (self, args, from_tty):
|
||
> argv = gdb.string_to_argv (args)
|
||
> if len (argv) != 0:
|
||
> raise gdb.GdbError ("hello-world takes no arguments")
|
||
> print "Hello, World!"
|
||
>HelloWorld ()
|
||
>end
|
||
(gdb) hello-world 42
|
||
hello-world takes no arguments
|
||
|
||
|
||
File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Exception Handling, Up: Python API
|
||
|
||
23.2.2.3 Values From Inferior
|
||
.............................
|
||
|
||
GDB provides values it obtains from the inferior program in an object of
|
||
type 'gdb.Value'. GDB uses this object for its internal bookkeeping of
|
||
the inferior's values, and for fetching values when necessary.
|
||
|
||
Inferior values that are simple scalars can be used directly in
|
||
Python expressions that are valid for the value's data type. Here's an
|
||
example for an integer or floating-point value 'some_val':
|
||
|
||
bar = some_val + 2
|
||
|
||
As result of this, 'bar' will also be a 'gdb.Value' object whose values
|
||
are of the same type as those of 'some_val'. Valid Python operations
|
||
can also be performed on 'gdb.Value' objects representing a 'struct' or
|
||
'class' object. For such cases, the overloaded operator (if present),
|
||
is used to perform the operation. For example, if 'val1' and 'val2' are
|
||
'gdb.Value' objects representing instances of a 'class' which overloads
|
||
the '+' operator, then one can use the '+' operator in their Python
|
||
script as follows:
|
||
|
||
val3 = val1 + val2
|
||
|
||
The result of the operation 'val3' is also a 'gdb.Value' object
|
||
corresponding to the value returned by the overloaded '+' operator. In
|
||
general, overloaded operators are invoked for the following operations:
|
||
'+' (binary addition), '-' (binary subtraction), '*' (multiplication),
|
||
'/', '%', '<<', '>>', '|', '&', '^'.
|
||
|
||
Inferior values that are structures or instances of some class can be
|
||
accessed using the Python "dictionary syntax". For example, if
|
||
'some_val' is a 'gdb.Value' instance holding a structure, you can access
|
||
its 'foo' element with:
|
||
|
||
bar = some_val['foo']
|
||
|
||
Again, 'bar' will also be a 'gdb.Value' object. Structure elements
|
||
can also be accessed by using 'gdb.Field' objects as subscripts (*note
|
||
Types In Python::, for more information on 'gdb.Field' objects). For
|
||
example, if 'foo_field' is a 'gdb.Field' object corresponding to element
|
||
'foo' of the above structure, then 'bar' can also be accessed as
|
||
follows:
|
||
|
||
bar = some_val[foo_field]
|
||
|
||
A 'gdb.Value' that represents a function can be executed via inferior
|
||
function call. Any arguments provided to the call must match the
|
||
function's prototype, and must be provided in the order specified by
|
||
that prototype.
|
||
|
||
For example, 'some_val' is a 'gdb.Value' instance representing a
|
||
function that takes two integers as arguments. To execute this
|
||
function, call it like so:
|
||
|
||
result = some_val (10,20)
|
||
|
||
Any values returned from a function call will be stored as a
|
||
'gdb.Value'.
|
||
|
||
The following attributes are provided:
|
||
|
||
-- Variable: Value.address
|
||
If this object is addressable, this read-only attribute holds a
|
||
'gdb.Value' object representing the address. Otherwise, this
|
||
attribute holds 'None'.
|
||
|
||
-- Variable: Value.is_optimized_out
|
||
This read-only boolean attribute is true if the compiler optimized
|
||
out this value, thus it is not available for fetching from the
|
||
inferior.
|
||
|
||
-- Variable: Value.type
|
||
The type of this 'gdb.Value'. The value of this attribute is a
|
||
'gdb.Type' object (*note Types In Python::).
|
||
|
||
-- Variable: Value.dynamic_type
|
||
The dynamic type of this 'gdb.Value'. This uses the object's
|
||
virtual table and the C++ run-time type information (RTTI) to
|
||
determine the dynamic type of the value. If this value is of class
|
||
type, it will return the class in which the value is embedded, if
|
||
any. If this value is of pointer or reference to a class type, it
|
||
will compute the dynamic type of the referenced object, and return
|
||
a pointer or reference to that type, respectively. In all other
|
||
cases, it will return the value's static type.
|
||
|
||
Note that this feature will only work when debugging a C++ program
|
||
that includes RTTI for the object in question. Otherwise, it will
|
||
just return the static type of the value as in 'ptype foo' (*note
|
||
ptype: Symbols.).
|
||
|
||
-- Variable: Value.is_lazy
|
||
The value of this read-only boolean attribute is 'True' if this
|
||
'gdb.Value' has not yet been fetched from the inferior. GDB does
|
||
not fetch values until necessary, for efficiency. For example:
|
||
|
||
myval = gdb.parse_and_eval ('somevar')
|
||
|
||
The value of 'somevar' is not fetched at this time. It will be
|
||
fetched when the value is needed, or when the 'fetch_lazy' method
|
||
is invoked.
|
||
|
||
The following methods are provided:
|
||
|
||
-- Function: Value.__init__ (VAL)
|
||
Many Python values can be converted directly to a 'gdb.Value' via
|
||
this object initializer. Specifically:
|
||
|
||
Python boolean
|
||
A Python boolean is converted to the boolean type from the
|
||
current language.
|
||
|
||
Python integer
|
||
A Python integer is converted to the C 'long' type for the
|
||
current architecture.
|
||
|
||
Python long
|
||
A Python long is converted to the C 'long long' type for the
|
||
current architecture.
|
||
|
||
Python float
|
||
A Python float is converted to the C 'double' type for the
|
||
current architecture.
|
||
|
||
Python string
|
||
A Python string is converted to a target string in the current
|
||
target language using the current target encoding. If a
|
||
character cannot be represented in the current target
|
||
encoding, then an exception is thrown.
|
||
|
||
'gdb.Value'
|
||
If 'val' is a 'gdb.Value', then a copy of the value is made.
|
||
|
||
'gdb.LazyString'
|
||
If 'val' is a 'gdb.LazyString' (*note Lazy Strings In
|
||
Python::), then the lazy string's 'value' method is called,
|
||
and its result is used.
|
||
|
||
-- Function: Value.__init__ (VAL, TYPE)
|
||
This second form of the 'gdb.Value' constructor returns a
|
||
'gdb.Value' of type TYPE where the value contents are taken from
|
||
the Python buffer object specified by VAL. The number of bytes in
|
||
the Python buffer object must be greater than or equal to the size
|
||
of TYPE.
|
||
|
||
-- Function: Value.cast (type)
|
||
Return a new instance of 'gdb.Value' that is the result of casting
|
||
this instance to the type described by TYPE, which must be a
|
||
'gdb.Type' object. If the cast cannot be performed for some
|
||
reason, this method throws an exception.
|
||
|
||
-- Function: Value.dereference ()
|
||
For pointer data types, this method returns a new 'gdb.Value'
|
||
object whose contents is the object pointed to by the pointer. For
|
||
example, if 'foo' is a C pointer to an 'int', declared in your C
|
||
program as
|
||
|
||
int *foo;
|
||
|
||
then you can use the corresponding 'gdb.Value' to access what 'foo'
|
||
points to like this:
|
||
|
||
bar = foo.dereference ()
|
||
|
||
The result 'bar' will be a 'gdb.Value' object holding the value
|
||
pointed to by 'foo'.
|
||
|
||
A similar function 'Value.referenced_value' exists which also
|
||
returns 'gdb.Value' objects corresponding to the values pointed to
|
||
by pointer values (and additionally, values referenced by reference
|
||
values). However, the behavior of 'Value.dereference' differs from
|
||
'Value.referenced_value' by the fact that the behavior of
|
||
'Value.dereference' is identical to applying the C unary operator
|
||
'*' on a given value. For example, consider a reference to a
|
||
pointer 'ptrref', declared in your C++ program as
|
||
|
||
typedef int *intptr;
|
||
...
|
||
int val = 10;
|
||
intptr ptr = &val;
|
||
intptr &ptrref = ptr;
|
||
|
||
Though 'ptrref' is a reference value, one can apply the method
|
||
'Value.dereference' to the 'gdb.Value' object corresponding to it
|
||
and obtain a 'gdb.Value' which is identical to that corresponding
|
||
to 'val'. However, if you apply the method
|
||
'Value.referenced_value', the result would be a 'gdb.Value' object
|
||
identical to that corresponding to 'ptr'.
|
||
|
||
py_ptrref = gdb.parse_and_eval ("ptrref")
|
||
py_val = py_ptrref.dereference ()
|
||
py_ptr = py_ptrref.referenced_value ()
|
||
|
||
The 'gdb.Value' object 'py_val' is identical to that corresponding
|
||
to 'val', and 'py_ptr' is identical to that corresponding to 'ptr'.
|
||
In general, 'Value.dereference' can be applied whenever the C unary
|
||
operator '*' can be applied to the corresponding C value. For
|
||
those cases where applying both 'Value.dereference' and
|
||
'Value.referenced_value' is allowed, the results obtained need not
|
||
be identical (as we have seen in the above example). The results
|
||
are however identical when applied on 'gdb.Value' objects
|
||
corresponding to pointers ('gdb.Value' objects with type code
|
||
'TYPE_CODE_PTR') in a C/C++ program.
|
||
|
||
-- Function: Value.referenced_value ()
|
||
For pointer or reference data types, this method returns a new
|
||
'gdb.Value' object corresponding to the value referenced by the
|
||
pointer/reference value. For pointer data types,
|
||
'Value.dereference' and 'Value.referenced_value' produce identical
|
||
results. The difference between these methods is that
|
||
'Value.dereference' cannot get the values referenced by reference
|
||
values. For example, consider a reference to an 'int', declared in
|
||
your C++ program as
|
||
|
||
int val = 10;
|
||
int &ref = val;
|
||
|
||
then applying 'Value.dereference' to the 'gdb.Value' object
|
||
corresponding to 'ref' will result in an error, while applying
|
||
'Value.referenced_value' will result in a 'gdb.Value' object
|
||
identical to that corresponding to 'val'.
|
||
|
||
py_ref = gdb.parse_and_eval ("ref")
|
||
er_ref = py_ref.dereference () # Results in error
|
||
py_val = py_ref.referenced_value () # Returns the referenced value
|
||
|
||
The 'gdb.Value' object 'py_val' is identical to that corresponding
|
||
to 'val'.
|
||
|
||
-- Function: Value.reference_value ()
|
||
Return a 'gdb.Value' object which is a reference to the value
|
||
encapsulated by this instance.
|
||
|
||
-- Function: Value.const_value ()
|
||
Return a 'gdb.Value' object which is a 'const' version of the value
|
||
encapsulated by this instance.
|
||
|
||
-- Function: Value.dynamic_cast (type)
|
||
Like 'Value.cast', but works as if the C++ 'dynamic_cast' operator
|
||
were used. Consult a C++ reference for details.
|
||
|
||
-- Function: Value.reinterpret_cast (type)
|
||
Like 'Value.cast', but works as if the C++ 'reinterpret_cast'
|
||
operator were used. Consult a C++ reference for details.
|
||
|
||
-- Function: Value.format_string (...)
|
||
Convert a 'gdb.Value' to a string, similarly to what the 'print'
|
||
command does. Invoked with no arguments, this is equivalent to
|
||
calling the 'str' function on the 'gdb.Value'. The representation
|
||
of the same value may change across different versions of GDB, so
|
||
you shouldn't, for instance, parse the strings returned by this
|
||
method.
|
||
|
||
All the arguments are keyword only. If an argument is not
|
||
specified, the current global default setting is used.
|
||
|
||
'raw'
|
||
'True' if pretty-printers (*note Pretty Printing::) should not
|
||
be used to format the value. 'False' if enabled
|
||
pretty-printers matching the type represented by the
|
||
'gdb.Value' should be used to format it.
|
||
|
||
'pretty_arrays'
|
||
'True' if arrays should be pretty printed to be more
|
||
convenient to read, 'False' if they shouldn't (see 'set print
|
||
array' in *note Print Settings::).
|
||
|
||
'pretty_structs'
|
||
'True' if structs should be pretty printed to be more
|
||
convenient to read, 'False' if they shouldn't (see 'set print
|
||
pretty' in *note Print Settings::).
|
||
|
||
'array_indexes'
|
||
'True' if array indexes should be included in the string
|
||
representation of arrays, 'False' if they shouldn't (see 'set
|
||
print array-indexes' in *note Print Settings::).
|
||
|
||
'symbols'
|
||
'True' if the string representation of a pointer should
|
||
include the corresponding symbol name (if one exists), 'False'
|
||
if it shouldn't (see 'set print symbol' in *note Print
|
||
Settings::).
|
||
|
||
'unions'
|
||
'True' if unions which are contained in other structures or
|
||
unions should be expanded, 'False' if they shouldn't (see 'set
|
||
print union' in *note Print Settings::).
|
||
|
||
'deref_refs'
|
||
'True' if C++ references should be resolved to the value they
|
||
refer to, 'False' (the default) if they shouldn't. Note that,
|
||
unlike for the 'print' command, references are not
|
||
automatically expanded when using the 'format_string' method
|
||
or the 'str' function. There is no global 'print' setting to
|
||
change the default behaviour.
|
||
|
||
'actual_objects'
|
||
'True' if the representation of a pointer to an object should
|
||
identify the _actual_ (derived) type of the object rather than
|
||
the _declared_ type, using the virtual function table.
|
||
'False' if the _declared_ type should be used. (See 'set
|
||
print object' in *note Print Settings::).
|
||
|
||
'static_fields'
|
||
'True' if static members should be included in the string
|
||
representation of a C++ object, 'False' if they shouldn't (see
|
||
'set print static-members' in *note Print Settings::).
|
||
|
||
'max_elements'
|
||
Number of array elements to print, or '0' to print an
|
||
unlimited number of elements (see 'set print elements' in
|
||
*note Print Settings::).
|
||
|
||
'max_depth'
|
||
The maximum depth to print for nested structs and unions, or
|
||
'-1' to print an unlimited number of elements (see 'set print
|
||
max-depth' in *note Print Settings::).
|
||
|
||
'repeat_threshold'
|
||
Set the threshold for suppressing display of repeated array
|
||
elements, or '0' to represent all elements, even if repeated.
|
||
(See 'set print repeats' in *note Print Settings::).
|
||
|
||
'format'
|
||
A string containing a single character representing the format
|
||
to use for the returned string. For instance, ''x'' is
|
||
equivalent to using the GDB command 'print' with the '/x'
|
||
option and formats the value as a hexadecimal number.
|
||
|
||
-- Function: Value.string ([encoding[, errors[, length]]])
|
||
If this 'gdb.Value' represents a string, then this method converts
|
||
the contents to a Python string. Otherwise, this method will throw
|
||
an exception.
|
||
|
||
Values are interpreted as strings according to the rules of the
|
||
current language. If the optional length argument is given, the
|
||
string will be converted to that length, and will include any
|
||
embedded zeroes that the string may contain. Otherwise, for
|
||
languages where the string is zero-terminated, the entire string
|
||
will be converted.
|
||
|
||
For example, in C-like languages, a value is a string if it is a
|
||
pointer to or an array of characters or ints of type 'wchar_t',
|
||
'char16_t', or 'char32_t'.
|
||
|
||
If the optional ENCODING argument is given, it must be a string
|
||
naming the encoding of the string in the 'gdb.Value', such as
|
||
'"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same
|
||
encodings as the corresponding argument to Python's 'string.decode'
|
||
method, and the Python codec machinery will be used to convert the
|
||
string. If ENCODING is not given, or if ENCODING is the empty
|
||
string, then either the 'target-charset' (*note Character Sets::)
|
||
will be used, or a language-specific encoding will be used, if the
|
||
current language is able to supply one.
|
||
|
||
The optional ERRORS argument is the same as the corresponding
|
||
argument to Python's 'string.decode' method.
|
||
|
||
If the optional LENGTH argument is given, the string will be
|
||
fetched and converted to the given length.
|
||
|
||
-- Function: Value.lazy_string ([encoding [, length]])
|
||
If this 'gdb.Value' represents a string, then this method converts
|
||
the contents to a 'gdb.LazyString' (*note Lazy Strings In
|
||
Python::). Otherwise, this method will throw an exception.
|
||
|
||
If the optional ENCODING argument is given, it must be a string
|
||
naming the encoding of the 'gdb.LazyString'. Some examples are:
|
||
'ascii', 'iso-8859-6' or 'utf-8'. If the ENCODING argument is an
|
||
encoding that GDB does recognize, GDB will raise an error.
|
||
|
||
When a lazy string is printed, the GDB encoding machinery is used
|
||
to convert the string during printing. If the optional ENCODING
|
||
argument is not provided, or is an empty string, GDB will
|
||
automatically select the encoding most suitable for the string
|
||
type. For further information on encoding in GDB please see *note
|
||
Character Sets::.
|
||
|
||
If the optional LENGTH argument is given, the string will be
|
||
fetched and encoded to the length of characters specified. If the
|
||
LENGTH argument is not provided, the string will be fetched and
|
||
encoded until a null of appropriate width is found.
|
||
|
||
-- Function: Value.fetch_lazy ()
|
||
If the 'gdb.Value' object is currently a lazy value
|
||
('gdb.Value.is_lazy' is 'True'), then the value is fetched from the
|
||
inferior. Any errors that occur in the process will produce a
|
||
Python exception.
|
||
|
||
If the 'gdb.Value' object is not a lazy value, this method has no
|
||
effect.
|
||
|
||
This method does not return a value.
|
||
|
||
|
||
File: gdb.info, Node: Types In Python, Next: Pretty Printing API, Prev: Values From Inferior, Up: Python API
|
||
|
||
23.2.2.4 Types In Python
|
||
........................
|
||
|
||
GDB represents types from the inferior using the class 'gdb.Type'.
|
||
|
||
The following type-related functions are available in the 'gdb'
|
||
module:
|
||
|
||
-- Function: gdb.lookup_type (name [, block])
|
||
This function looks up a type by its NAME, which must be a string.
|
||
|
||
If BLOCK is given, then NAME is looked up in that scope.
|
||
Otherwise, it is searched for globally.
|
||
|
||
Ordinarily, this function will return an instance of 'gdb.Type'.
|
||
If the named type cannot be found, it will throw an exception.
|
||
|
||
If the type is a structure or class type, or an enum type, the fields
|
||
of that type can be accessed using the Python "dictionary syntax". For
|
||
example, if 'some_type' is a 'gdb.Type' instance holding a structure
|
||
type, you can access its 'foo' field with:
|
||
|
||
bar = some_type['foo']
|
||
|
||
'bar' will be a 'gdb.Field' object; see below under the description
|
||
of the 'Type.fields' method for a description of the 'gdb.Field' class.
|
||
|
||
An instance of 'Type' has the following attributes:
|
||
|
||
-- Variable: Type.alignof
|
||
The alignment of this type, in bytes. Type alignment comes from
|
||
the debugging information; if it was not specified, then GDB will
|
||
use the relevant ABI to try to determine the alignment. In some
|
||
cases, even this is not possible, and zero will be returned.
|
||
|
||
-- Variable: Type.code
|
||
The type code for this type. The type code will be one of the
|
||
'TYPE_CODE_' constants defined below.
|
||
|
||
-- Variable: Type.name
|
||
The name of this type. If this type has no name, then 'None' is
|
||
returned.
|
||
|
||
-- Variable: Type.sizeof
|
||
The size of this type, in target 'char' units. Usually, a target's
|
||
'char' type will be an 8-bit byte. However, on some unusual
|
||
platforms, this type may have a different size.
|
||
|
||
-- Variable: Type.tag
|
||
The tag name for this type. The tag name is the name after
|
||
'struct', 'union', or 'enum' in C and C++; not all languages have
|
||
this concept. If this type has no tag name, then 'None' is
|
||
returned.
|
||
|
||
-- Variable: Type.objfile
|
||
The 'gdb.Objfile' that this type was defined in, or 'None' if there
|
||
is no associated objfile.
|
||
|
||
The following methods are provided:
|
||
|
||
-- Function: Type.fields ()
|
||
For structure and union types, this method returns the fields.
|
||
Range types have two fields, the minimum and maximum values. Enum
|
||
types have one field per enum constant. Function and method types
|
||
have one field per parameter. The base types of C++ classes are
|
||
also represented as fields. If the type has no fields, or does not
|
||
fit into one of these categories, an empty sequence will be
|
||
returned.
|
||
|
||
Each field is a 'gdb.Field' object, with some pre-defined
|
||
attributes:
|
||
'bitpos'
|
||
This attribute is not available for 'enum' or 'static' (as in
|
||
C++) fields. The value is the position, counting in bits,
|
||
from the start of the containing type.
|
||
|
||
'enumval'
|
||
This attribute is only available for 'enum' fields, and its
|
||
value is the enumeration member's integer representation.
|
||
|
||
'name'
|
||
The name of the field, or 'None' for anonymous fields.
|
||
|
||
'artificial'
|
||
This is 'True' if the field is artificial, usually meaning
|
||
that it was provided by the compiler and not the user. This
|
||
attribute is always provided, and is 'False' if the field is
|
||
not artificial.
|
||
|
||
'is_base_class'
|
||
This is 'True' if the field represents a base class of a C++
|
||
structure. This attribute is always provided, and is 'False'
|
||
if the field is not a base class of the type that is the
|
||
argument of 'fields', or if that type was not a C++ class.
|
||
|
||
'bitsize'
|
||
If the field is packed, or is a bitfield, then this will have
|
||
a non-zero value, which is the size of the field in bits.
|
||
Otherwise, this will be zero; in this case the field's size is
|
||
given by its type.
|
||
|
||
'type'
|
||
The type of the field. This is usually an instance of 'Type',
|
||
but it can be 'None' in some situations.
|
||
|
||
'parent_type'
|
||
The type which contains this field. This is an instance of
|
||
'gdb.Type'.
|
||
|
||
-- Function: Type.array (N1 [, N2])
|
||
Return a new 'gdb.Type' object which represents an array of this
|
||
type. If one argument is given, it is the inclusive upper bound of
|
||
the array; in this case the lower bound is zero. If two arguments
|
||
are given, the first argument is the lower bound of the array, and
|
||
the second argument is the upper bound of the array. An array's
|
||
length must not be negative, but the bounds can be.
|
||
|
||
-- Function: Type.vector (N1 [, N2])
|
||
Return a new 'gdb.Type' object which represents a vector of this
|
||
type. If one argument is given, it is the inclusive upper bound of
|
||
the vector; in this case the lower bound is zero. If two arguments
|
||
are given, the first argument is the lower bound of the vector, and
|
||
the second argument is the upper bound of the vector. A vector's
|
||
length must not be negative, but the bounds can be.
|
||
|
||
The difference between an 'array' and a 'vector' is that arrays
|
||
behave like in C: when used in expressions they decay to a pointer
|
||
to the first element whereas vectors are treated as first class
|
||
values.
|
||
|
||
-- Function: Type.const ()
|
||
Return a new 'gdb.Type' object which represents a 'const'-qualified
|
||
variant of this type.
|
||
|
||
-- Function: Type.volatile ()
|
||
Return a new 'gdb.Type' object which represents a
|
||
'volatile'-qualified variant of this type.
|
||
|
||
-- Function: Type.unqualified ()
|
||
Return a new 'gdb.Type' object which represents an unqualified
|
||
variant of this type. That is, the result is neither 'const' nor
|
||
'volatile'.
|
||
|
||
-- Function: Type.range ()
|
||
Return a Python 'Tuple' object that contains two elements: the low
|
||
bound of the argument type and the high bound of that type. If the
|
||
type does not have a range, GDB will raise a 'gdb.error' exception
|
||
(*note Exception Handling::).
|
||
|
||
-- Function: Type.reference ()
|
||
Return a new 'gdb.Type' object which represents a reference to this
|
||
type.
|
||
|
||
-- Function: Type.pointer ()
|
||
Return a new 'gdb.Type' object which represents a pointer to this
|
||
type.
|
||
|
||
-- Function: Type.strip_typedefs ()
|
||
Return a new 'gdb.Type' that represents the real type, after
|
||
removing all layers of typedefs.
|
||
|
||
-- Function: Type.target ()
|
||
Return a new 'gdb.Type' object which represents the target type of
|
||
this type.
|
||
|
||
For a pointer type, the target type is the type of the pointed-to
|
||
object. For an array type (meaning C-like arrays), the target type
|
||
is the type of the elements of the array. For a function or method
|
||
type, the target type is the type of the return value. For a
|
||
complex type, the target type is the type of the elements. For a
|
||
typedef, the target type is the aliased type.
|
||
|
||
If the type does not have a target, this method will throw an
|
||
exception.
|
||
|
||
-- Function: Type.template_argument (n [, block])
|
||
If this 'gdb.Type' is an instantiation of a template, this will
|
||
return a new 'gdb.Value' or 'gdb.Type' which represents the value
|
||
of the Nth template argument (indexed starting at 0).
|
||
|
||
If this 'gdb.Type' is not a template type, or if the type has fewer
|
||
than N template arguments, this will throw an exception.
|
||
Ordinarily, only C++ code will have template types.
|
||
|
||
If BLOCK is given, then NAME is looked up in that scope.
|
||
Otherwise, it is searched for globally.
|
||
|
||
-- Function: Type.optimized_out ()
|
||
Return 'gdb.Value' instance of this type whose value is optimized
|
||
out. This allows a frame decorator to indicate that the value of
|
||
an argument or a local variable is not known.
|
||
|
||
Each type has a code, which indicates what category this type falls
|
||
into. The available type categories are represented by constants
|
||
defined in the 'gdb' module:
|
||
|
||
'gdb.TYPE_CODE_PTR'
|
||
The type is a pointer.
|
||
|
||
'gdb.TYPE_CODE_ARRAY'
|
||
The type is an array.
|
||
|
||
'gdb.TYPE_CODE_STRUCT'
|
||
The type is a structure.
|
||
|
||
'gdb.TYPE_CODE_UNION'
|
||
The type is a union.
|
||
|
||
'gdb.TYPE_CODE_ENUM'
|
||
The type is an enum.
|
||
|
||
'gdb.TYPE_CODE_FLAGS'
|
||
A bit flags type, used for things such as status registers.
|
||
|
||
'gdb.TYPE_CODE_FUNC'
|
||
The type is a function.
|
||
|
||
'gdb.TYPE_CODE_INT'
|
||
The type is an integer type.
|
||
|
||
'gdb.TYPE_CODE_FLT'
|
||
A floating point type.
|
||
|
||
'gdb.TYPE_CODE_VOID'
|
||
The special type 'void'.
|
||
|
||
'gdb.TYPE_CODE_SET'
|
||
A Pascal set type.
|
||
|
||
'gdb.TYPE_CODE_RANGE'
|
||
A range type, that is, an integer type with bounds.
|
||
|
||
'gdb.TYPE_CODE_STRING'
|
||
A string type. Note that this is only used for certain languages
|
||
with language-defined string types; C strings are not represented
|
||
this way.
|
||
|
||
'gdb.TYPE_CODE_BITSTRING'
|
||
A string of bits. It is deprecated.
|
||
|
||
'gdb.TYPE_CODE_ERROR'
|
||
An unknown or erroneous type.
|
||
|
||
'gdb.TYPE_CODE_METHOD'
|
||
A method type, as found in C++.
|
||
|
||
'gdb.TYPE_CODE_METHODPTR'
|
||
A pointer-to-member-function.
|
||
|
||
'gdb.TYPE_CODE_MEMBERPTR'
|
||
A pointer-to-member.
|
||
|
||
'gdb.TYPE_CODE_REF'
|
||
A reference type.
|
||
|
||
'gdb.TYPE_CODE_RVALUE_REF'
|
||
A C++11 rvalue reference type.
|
||
|
||
'gdb.TYPE_CODE_CHAR'
|
||
A character type.
|
||
|
||
'gdb.TYPE_CODE_BOOL'
|
||
A boolean type.
|
||
|
||
'gdb.TYPE_CODE_COMPLEX'
|
||
A complex float type.
|
||
|
||
'gdb.TYPE_CODE_TYPEDEF'
|
||
A typedef to some other type.
|
||
|
||
'gdb.TYPE_CODE_NAMESPACE'
|
||
A C++ namespace.
|
||
|
||
'gdb.TYPE_CODE_DECFLOAT'
|
||
A decimal floating point type.
|
||
|
||
'gdb.TYPE_CODE_INTERNAL_FUNCTION'
|
||
A function internal to GDB. This is the type used to represent
|
||
convenience functions.
|
||
|
||
Further support for types is provided in the 'gdb.types' Python
|
||
module (*note gdb.types::).
|
||
|
||
|
||
File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API
|
||
|
||
23.2.2.5 Pretty Printing API
|
||
............................
|
||
|
||
A pretty-printer is just an object that holds a value and implements a
|
||
specific interface, defined here. An example output is provided (*note
|
||
Pretty Printing::).
|
||
|
||
-- Function: pretty_printer.children (self)
|
||
GDB will call this method on a pretty-printer to compute the
|
||
children of the pretty-printer's value.
|
||
|
||
This method must return an object conforming to the Python iterator
|
||
protocol. Each item returned by the iterator must be a tuple
|
||
holding two elements. The first element is the "name" of the
|
||
child; the second element is the child's value. The value can be
|
||
any Python object which is convertible to a GDB value.
|
||
|
||
This method is optional. If it does not exist, GDB will act as
|
||
though the value has no children.
|
||
|
||
For efficiency, the 'children' method should lazily compute its
|
||
results. This will let GDB read as few elements as necessary, for
|
||
example when various print settings (*note Print Settings::) or
|
||
'-var-list-children' (*note GDB/MI Variable Objects::) limit the
|
||
number of elements to be displayed.
|
||
|
||
Children may be hidden from display based on the value of 'set
|
||
print max-depth' (*note Print Settings::).
|
||
|
||
-- Function: pretty_printer.display_hint (self)
|
||
The CLI may call this method and use its result to change the
|
||
formatting of a value. The result will also be supplied to an MI
|
||
consumer as a 'displayhint' attribute of the variable being
|
||
printed.
|
||
|
||
This method is optional. If it does exist, this method must return
|
||
a string or the special value 'None'.
|
||
|
||
Some display hints are predefined by GDB:
|
||
|
||
'array'
|
||
Indicate that the object being printed is "array-like". The
|
||
CLI uses this to respect parameters such as 'set print
|
||
elements' and 'set print array'.
|
||
|
||
'map'
|
||
Indicate that the object being printed is "map-like", and that
|
||
the children of this value can be assumed to alternate between
|
||
keys and values.
|
||
|
||
'string'
|
||
Indicate that the object being printed is "string-like". If
|
||
the printer's 'to_string' method returns a Python string of
|
||
some kind, then GDB will call its internal language-specific
|
||
string-printing function to format the string. For the CLI
|
||
this means adding quotation marks, possibly escaping some
|
||
characters, respecting 'set print elements', and the like.
|
||
|
||
The special value 'None' causes GDB to apply the default display
|
||
rules.
|
||
|
||
-- Function: pretty_printer.to_string (self)
|
||
GDB will call this method to display the string representation of
|
||
the value passed to the object's constructor.
|
||
|
||
When printing from the CLI, if the 'to_string' method exists, then
|
||
GDB will prepend its result to the values returned by 'children'.
|
||
Exactly how this formatting is done is dependent on the display
|
||
hint, and may change as more hints are added. Also, depending on
|
||
the print settings (*note Print Settings::), the CLI may print just
|
||
the result of 'to_string' in a stack trace, omitting the result of
|
||
'children'.
|
||
|
||
If this method returns a string, it is printed verbatim.
|
||
|
||
Otherwise, if this method returns an instance of 'gdb.Value', then
|
||
GDB prints this value. This may result in a call to another
|
||
pretty-printer.
|
||
|
||
If instead the method returns a Python value which is convertible
|
||
to a 'gdb.Value', then GDB performs the conversion and prints the
|
||
resulting value. Again, this may result in a call to another
|
||
pretty-printer. Python scalars (integers, floats, and booleans)
|
||
and strings are convertible to 'gdb.Value'; other types are not.
|
||
|
||
Finally, if this method returns 'None' then no further operations
|
||
are peformed in this method and nothing is printed.
|
||
|
||
If the result is not one of these types, an exception is raised.
|
||
|
||
GDB provides a function which can be used to look up the default
|
||
pretty-printer for a 'gdb.Value':
|
||
|
||
-- Function: gdb.default_visualizer (value)
|
||
This function takes a 'gdb.Value' object as an argument. If a
|
||
pretty-printer for this value exists, then it is returned. If no
|
||
such printer exists, then this returns 'None'.
|
||
|
||
|
||
File: gdb.info, Node: Selecting Pretty-Printers, Next: Writing a Pretty-Printer, Prev: Pretty Printing API, Up: Python API
|
||
|
||
23.2.2.6 Selecting Pretty-Printers
|
||
..................................
|
||
|
||
GDB provides several ways to register a pretty-printer: globally, per
|
||
program space, and per objfile. When choosing how to register your
|
||
pretty-printer, a good rule is to register it with the smallest scope
|
||
possible: that is prefer a specific objfile first, then a program space,
|
||
and only register a printer globally as a last resort.
|
||
|
||
-- Variable: gdb.pretty_printers
|
||
The Python list 'gdb.pretty_printers' contains an array of
|
||
functions or callable objects that have been registered via
|
||
addition as a pretty-printer. Printers in this list are called
|
||
'global' printers, they're available when debugging all inferiors.
|
||
|
||
Each 'gdb.Progspace' contains a 'pretty_printers' attribute. Each
|
||
'gdb.Objfile' also contains a 'pretty_printers' attribute.
|
||
|
||
Each function on these lists is passed a single 'gdb.Value' argument
|
||
and should return a pretty-printer object conforming to the interface
|
||
definition above (*note Pretty Printing API::). If a function cannot
|
||
create a pretty-printer for the value, it should return 'None'.
|
||
|
||
GDB first checks the 'pretty_printers' attribute of each
|
||
'gdb.Objfile' in the current program space and iteratively calls each
|
||
enabled lookup routine in the list for that 'gdb.Objfile' until it
|
||
receives a pretty-printer object. If no pretty-printer is found in the
|
||
objfile lists, GDB then searches the pretty-printer list of the current
|
||
program space, calling each enabled function until an object is
|
||
returned. After these lists have been exhausted, it tries the global
|
||
'gdb.pretty_printers' list, again calling each enabled function until an
|
||
object is returned.
|
||
|
||
The order in which the objfiles are searched is not specified. For a
|
||
given list, functions are always invoked from the head of the list, and
|
||
iterated over sequentially until the end of the list, or a printer
|
||
object is returned.
|
||
|
||
For various reasons a pretty-printer may not work. For example, the
|
||
underlying data structure may have changed and the pretty-printer is out
|
||
of date.
|
||
|
||
The consequences of a broken pretty-printer are severe enough that
|
||
GDB provides support for enabling and disabling individual printers.
|
||
For example, if 'print frame-arguments' is on, a backtrace can become
|
||
highly illegible if any argument is printed with a broken printer.
|
||
|
||
Pretty-printers are enabled and disabled by attaching an 'enabled'
|
||
attribute to the registered function or callable object. If this
|
||
attribute is present and its value is 'False', the printer is disabled,
|
||
otherwise the printer is enabled.
|
||
|
||
|
||
File: gdb.info, Node: Writing a Pretty-Printer, Next: Type Printing API, Prev: Selecting Pretty-Printers, Up: Python API
|
||
|
||
23.2.2.7 Writing a Pretty-Printer
|
||
.................................
|
||
|
||
A pretty-printer consists of two parts: a lookup function to detect if
|
||
the type is supported, and the printer itself.
|
||
|
||
Here is an example showing how a 'std::string' printer might be
|
||
written. *Note Pretty Printing API::, for details on the API this class
|
||
must provide.
|
||
|
||
class StdStringPrinter(object):
|
||
"Print a std::string"
|
||
|
||
def __init__(self, val):
|
||
self.val = val
|
||
|
||
def to_string(self):
|
||
return self.val['_M_dataplus']['_M_p']
|
||
|
||
def display_hint(self):
|
||
return 'string'
|
||
|
||
And here is an example showing how a lookup function for the printer
|
||
example above might be written.
|
||
|
||
def str_lookup_function(val):
|
||
lookup_tag = val.type.tag
|
||
if lookup_tag == None:
|
||
return None
|
||
regex = re.compile("^std::basic_string<char,.*>$")
|
||
if regex.match(lookup_tag):
|
||
return StdStringPrinter(val)
|
||
return None
|
||
|
||
The example lookup function extracts the value's type, and attempts
|
||
to match it to a type that it can pretty-print. If it is a type the
|
||
printer can pretty-print, it will return a printer object. If not, it
|
||
returns 'None'.
|
||
|
||
We recommend that you put your core pretty-printers into a Python
|
||
package. If your pretty-printers are for use with a library, we further
|
||
recommend embedding a version number into the package name. This
|
||
practice will enable GDB to load multiple versions of your
|
||
pretty-printers at the same time, because they will have different
|
||
names.
|
||
|
||
You should write auto-loaded code (*note Python Auto-loading::) such
|
||
that it can be evaluated multiple times without changing its meaning.
|
||
An ideal auto-load file will consist solely of 'import's of your printer
|
||
modules, followed by a call to a register pretty-printers with the
|
||
current objfile.
|
||
|
||
Taken as a whole, this approach will scale nicely to multiple
|
||
inferiors, each potentially using a different library version.
|
||
Embedding a version number in the Python package name will ensure that
|
||
GDB is able to load both sets of printers simultaneously. Then, because
|
||
the search for pretty-printers is done by objfile, and because your
|
||
auto-loaded code took care to register your library's printers with a
|
||
specific objfile, GDB will find the correct printers for the specific
|
||
version of the library used by each inferior.
|
||
|
||
To continue the 'std::string' example (*note Pretty Printing API::),
|
||
this code might appear in 'gdb.libstdcxx.v6':
|
||
|
||
def register_printers(objfile):
|
||
objfile.pretty_printers.append(str_lookup_function)
|
||
|
||
And then the corresponding contents of the auto-load file would be:
|
||
|
||
import gdb.libstdcxx.v6
|
||
gdb.libstdcxx.v6.register_printers(gdb.current_objfile())
|
||
|
||
The previous example illustrates a basic pretty-printer. There are a
|
||
few things that can be improved on. The printer doesn't have a name,
|
||
making it hard to identify in a list of installed printers. The lookup
|
||
function has a name, but lookup functions can have arbitrary, even
|
||
identical, names.
|
||
|
||
Second, the printer only handles one type, whereas a library
|
||
typically has several types. One could install a lookup function for
|
||
each desired type in the library, but one could also have a single
|
||
lookup function recognize several types. The latter is the conventional
|
||
way this is handled. If a pretty-printer can handle multiple data
|
||
types, then its "subprinters" are the printers for the individual data
|
||
types.
|
||
|
||
The 'gdb.printing' module provides a formal way of solving these
|
||
problems (*note gdb.printing::). Here is another example that handles
|
||
multiple types.
|
||
|
||
These are the types we are going to pretty-print:
|
||
|
||
struct foo { int a, b; };
|
||
struct bar { struct foo x, y; };
|
||
|
||
Here are the printers:
|
||
|
||
class fooPrinter:
|
||
"""Print a foo object."""
|
||
|
||
def __init__(self, val):
|
||
self.val = val
|
||
|
||
def to_string(self):
|
||
return ("a=<" + str(self.val["a"]) +
|
||
"> b=<" + str(self.val["b"]) + ">")
|
||
|
||
class barPrinter:
|
||
"""Print a bar object."""
|
||
|
||
def __init__(self, val):
|
||
self.val = val
|
||
|
||
def to_string(self):
|
||
return ("x=<" + str(self.val["x"]) +
|
||
"> y=<" + str(self.val["y"]) + ">")
|
||
|
||
This example doesn't need a lookup function, that is handled by the
|
||
'gdb.printing' module. Instead a function is provided to build up the
|
||
object that handles the lookup.
|
||
|
||
import gdb.printing
|
||
|
||
def build_pretty_printer():
|
||
pp = gdb.printing.RegexpCollectionPrettyPrinter(
|
||
"my_library")
|
||
pp.add_printer('foo', '^foo$', fooPrinter)
|
||
pp.add_printer('bar', '^bar$', barPrinter)
|
||
return pp
|
||
|
||
And here is the autoload support:
|
||
|
||
import gdb.printing
|
||
import my_library
|
||
gdb.printing.register_pretty_printer(
|
||
gdb.current_objfile(),
|
||
my_library.build_pretty_printer())
|
||
|
||
Finally, when this printer is loaded into GDB, here is the
|
||
corresponding output of 'info pretty-printer':
|
||
|
||
(gdb) info pretty-printer
|
||
my_library.so:
|
||
my_library
|
||
foo
|
||
bar
|
||
|
||
|
||
File: gdb.info, Node: Type Printing API, Next: Frame Filter API, Prev: Writing a Pretty-Printer, Up: Python API
|
||
|
||
23.2.2.8 Type Printing API
|
||
..........................
|
||
|
||
GDB provides a way for Python code to customize type display. This is
|
||
mainly useful for substituting canonical typedef names for types.
|
||
|
||
A "type printer" is just a Python object conforming to a certain
|
||
protocol. A simple base class implementing the protocol is provided;
|
||
see *note gdb.types::. A type printer must supply at least:
|
||
|
||
-- Instance Variable of type_printer: enabled
|
||
A boolean which is True if the printer is enabled, and False
|
||
otherwise. This is manipulated by the 'enable type-printer' and
|
||
'disable type-printer' commands.
|
||
|
||
-- Instance Variable of type_printer: name
|
||
The name of the type printer. This must be a string. This is used
|
||
by the 'enable type-printer' and 'disable type-printer' commands.
|
||
|
||
-- Method on type_printer: instantiate (self)
|
||
This is called by GDB at the start of type-printing. It is only
|
||
called if the type printer is enabled. This method must return a
|
||
new object that supplies a 'recognize' method, as described below.
|
||
|
||
When displaying a type, say via the 'ptype' command, GDB will compute
|
||
a list of type recognizers. This is done by iterating first over the
|
||
per-objfile type printers (*note Objfiles In Python::), followed by the
|
||
per-progspace type printers (*note Progspaces In Python::), and finally
|
||
the global type printers.
|
||
|
||
GDB will call the 'instantiate' method of each enabled type printer.
|
||
If this method returns 'None', then the result is ignored; otherwise, it
|
||
is appended to the list of recognizers.
|
||
|
||
Then, when GDB is going to display a type name, it iterates over the
|
||
list of recognizers. For each one, it calls the recognition function,
|
||
stopping if the function returns a non-'None' value. The recognition
|
||
function is defined as:
|
||
|
||
-- Method on type_recognizer: recognize (self, type)
|
||
If TYPE is not recognized, return 'None'. Otherwise, return a
|
||
string which is to be printed as the name of TYPE. The TYPE
|
||
argument will be an instance of 'gdb.Type' (*note Types In
|
||
Python::).
|
||
|
||
GDB uses this two-pass approach so that type printers can efficiently
|
||
cache information without holding on to it too long. For example, it
|
||
can be convenient to look up type information in a type printer and hold
|
||
it for a recognizer's lifetime; if a single pass were done then type
|
||
printers would have to make use of the event system in order to avoid
|
||
holding information that could become stale as the inferior changed.
|
||
|
||
|
||
File: gdb.info, Node: Frame Filter API, Next: Frame Decorator API, Prev: Type Printing API, Up: Python API
|
||
|
||
23.2.2.9 Filtering Frames
|
||
.........................
|
||
|
||
Frame filters are Python objects that manipulate the visibility of a
|
||
frame or frames when a backtrace (*note Backtrace::) is printed by GDB.
|
||
|
||
Only commands that print a backtrace, or, in the case of GDB/MI
|
||
commands (*note GDB/MI::), those that return a collection of frames are
|
||
affected. The commands that work with frame filters are:
|
||
|
||
'backtrace' (*note The backtrace command: backtrace-command.),
|
||
'-stack-list-frames' (*note The -stack-list-frames command:
|
||
-stack-list-frames.), '-stack-list-variables' (*note The
|
||
-stack-list-variables command: -stack-list-variables.),
|
||
'-stack-list-arguments' *note The -stack-list-arguments command:
|
||
-stack-list-arguments.) and '-stack-list-locals' (*note The
|
||
-stack-list-locals command: -stack-list-locals.).
|
||
|
||
A frame filter works by taking an iterator as an argument, applying
|
||
actions to the contents of that iterator, and returning another iterator
|
||
(or, possibly, the same iterator it was provided in the case where the
|
||
filter does not perform any operations). Typically, frame filters
|
||
utilize tools such as the Python's 'itertools' module to work with and
|
||
create new iterators from the source iterator. Regardless of how a
|
||
filter chooses to apply actions, it must not alter the underlying GDB
|
||
frame or frames, or attempt to alter the call-stack within GDB. This
|
||
preserves data integrity within GDB. Frame filters are executed on a
|
||
priority basis and care should be taken that some frame filters may have
|
||
been executed before, and that some frame filters will be executed
|
||
after.
|
||
|
||
An important consideration when designing frame filters, and well
|
||
worth reflecting upon, is that frame filters should avoid unwinding the
|
||
call stack if possible. Some stacks can run very deep, into the tens of
|
||
thousands in some cases. To search every frame when a frame filter
|
||
executes may be too expensive at that step. The frame filter cannot
|
||
know how many frames it has to iterate over, and it may have to iterate
|
||
through them all. This ends up duplicating effort as GDB performs this
|
||
iteration when it prints the frames. If the filter can defer unwinding
|
||
frames until frame decorators are executed, after the last filter has
|
||
executed, it should. *Note Frame Decorator API::, for more information
|
||
on decorators. Also, there are examples for both frame decorators and
|
||
filters in later chapters. *Note Writing a Frame Filter::, for more
|
||
information.
|
||
|
||
The Python dictionary 'gdb.frame_filters' contains key/object
|
||
pairings that comprise a frame filter. Frame filters in this dictionary
|
||
are called 'global' frame filters, and they are available when debugging
|
||
all inferiors. These frame filters must register with the dictionary
|
||
directly. In addition to the 'global' dictionary, there are other
|
||
dictionaries that are loaded with different inferiors via auto-loading
|
||
(*note Python Auto-loading::). The two other areas where frame filter
|
||
dictionaries can be found are: 'gdb.Progspace' which contains a
|
||
'frame_filters' dictionary attribute, and each 'gdb.Objfile' object
|
||
which also contains a 'frame_filters' dictionary attribute.
|
||
|
||
When a command is executed from GDB that is compatible with frame
|
||
filters, GDB combines the 'global', 'gdb.Progspace' and all
|
||
'gdb.Objfile' dictionaries currently loaded. All of the 'gdb.Objfile'
|
||
dictionaries are combined, as several frames, and thus several object
|
||
files, might be in use. GDB then prunes any frame filter whose
|
||
'enabled' attribute is 'False'. This pruned list is then sorted
|
||
according to the 'priority' attribute in each filter.
|
||
|
||
Once the dictionaries are combined, pruned and sorted, GDB creates an
|
||
iterator which wraps each frame in the call stack in a 'FrameDecorator'
|
||
object, and calls each filter in order. The output from the previous
|
||
filter will always be the input to the next filter, and so on.
|
||
|
||
Frame filters have a mandatory interface which each frame filter must
|
||
implement, defined here:
|
||
|
||
-- Function: FrameFilter.filter (iterator)
|
||
GDB will call this method on a frame filter when it has reached the
|
||
order in the priority list for that filter.
|
||
|
||
For example, if there are four frame filters:
|
||
|
||
Name Priority
|
||
|
||
Filter1 5
|
||
Filter2 10
|
||
Filter3 100
|
||
Filter4 1
|
||
|
||
The order that the frame filters will be called is:
|
||
|
||
Filter3 -> Filter2 -> Filter1 -> Filter4
|
||
|
||
Note that the output from 'Filter3' is passed to the input of
|
||
'Filter2', and so on.
|
||
|
||
This 'filter' method is passed a Python iterator. This iterator
|
||
contains a sequence of frame decorators that wrap each 'gdb.Frame',
|
||
or a frame decorator that wraps another frame decorator. The first
|
||
filter that is executed in the sequence of frame filters will
|
||
receive an iterator entirely comprised of default 'FrameDecorator'
|
||
objects. However, after each frame filter is executed, the
|
||
previous frame filter may have wrapped some or all of the frame
|
||
decorators with their own frame decorator. As frame decorators
|
||
must also conform to a mandatory interface, these decorators can be
|
||
assumed to act in a uniform manner (*note Frame Decorator API::).
|
||
|
||
This method must return an object conforming to the Python iterator
|
||
protocol. Each item in the iterator must be an object conforming
|
||
to the frame decorator interface. If a frame filter does not wish
|
||
to perform any operations on this iterator, it should return that
|
||
iterator untouched.
|
||
|
||
This method is not optional. If it does not exist, GDB will raise
|
||
and print an error.
|
||
|
||
-- Variable: FrameFilter.name
|
||
The 'name' attribute must be Python string which contains the name
|
||
of the filter displayed by GDB (*note Frame Filter Management::).
|
||
This attribute may contain any combination of letters or numbers.
|
||
Care should be taken to ensure that it is unique. This attribute
|
||
is mandatory.
|
||
|
||
-- Variable: FrameFilter.enabled
|
||
The 'enabled' attribute must be Python boolean. This attribute
|
||
indicates to GDB whether the frame filter is enabled, and should be
|
||
considered when frame filters are executed. If 'enabled' is
|
||
'True', then the frame filter will be executed when any of the
|
||
backtrace commands detailed earlier in this chapter are executed.
|
||
If 'enabled' is 'False', then the frame filter will not be
|
||
executed. This attribute is mandatory.
|
||
|
||
-- Variable: FrameFilter.priority
|
||
The 'priority' attribute must be Python integer. This attribute
|
||
controls the order of execution in relation to other frame filters.
|
||
There are no imposed limits on the range of 'priority' other than
|
||
it must be a valid integer. The higher the 'priority' attribute,
|
||
the sooner the frame filter will be executed in relation to other
|
||
frame filters. Although 'priority' can be negative, it is
|
||
recommended practice to assume zero is the lowest priority that a
|
||
frame filter can be assigned. Frame filters that have the same
|
||
priority are executed in unsorted order in that priority slot.
|
||
This attribute is mandatory. 100 is a good default priority.
|
||
|
||
|
||
File: gdb.info, Node: Frame Decorator API, Next: Writing a Frame Filter, Prev: Frame Filter API, Up: Python API
|
||
|
||
23.2.2.10 Decorating Frames
|
||
...........................
|
||
|
||
Frame decorators are sister objects to frame filters (*note Frame Filter
|
||
API::). Frame decorators are applied by a frame filter and can only be
|
||
used in conjunction with frame filters.
|
||
|
||
The purpose of a frame decorator is to customize the printed content
|
||
of each 'gdb.Frame' in commands where frame filters are executed. This
|
||
concept is called decorating a frame. Frame decorators decorate a
|
||
'gdb.Frame' with Python code contained within each API call. This
|
||
separates the actual data contained in a 'gdb.Frame' from the decorated
|
||
data produced by a frame decorator. This abstraction is necessary to
|
||
maintain integrity of the data contained in each 'gdb.Frame'.
|
||
|
||
Frame decorators have a mandatory interface, defined below.
|
||
|
||
GDB already contains a frame decorator called 'FrameDecorator'. This
|
||
contains substantial amounts of boilerplate code to decorate the content
|
||
of a 'gdb.Frame'. It is recommended that other frame decorators inherit
|
||
and extend this object, and only to override the methods needed.
|
||
|
||
'FrameDecorator' is defined in the Python module
|
||
'gdb.FrameDecorator', so your code can import it like:
|
||
from gdb.FrameDecorator import FrameDecorator
|
||
|
||
-- Function: FrameDecorator.elided (self)
|
||
|
||
The 'elided' method groups frames together in a hierarchical
|
||
system. An example would be an interpreter, where multiple
|
||
low-level frames make up a single call in the interpreted language.
|
||
In this example, the frame filter would elide the low-level frames
|
||
and present a single high-level frame, representing the call in the
|
||
interpreted language, to the user.
|
||
|
||
The 'elided' function must return an iterable and this iterable
|
||
must contain the frames that are being elided wrapped in a suitable
|
||
frame decorator. If no frames are being elided this function may
|
||
return an empty iterable, or 'None'. Elided frames are indented
|
||
from normal frames in a 'CLI' backtrace, or in the case of
|
||
'GDB/MI', are placed in the 'children' field of the eliding frame.
|
||
|
||
It is the frame filter's task to also filter out the elided frames
|
||
from the source iterator. This will avoid printing the frame
|
||
twice.
|
||
|
||
-- Function: FrameDecorator.function (self)
|
||
|
||
This method returns the name of the function in the frame that is
|
||
to be printed.
|
||
|
||
This method must return a Python string describing the function, or
|
||
'None'.
|
||
|
||
If this function returns 'None', GDB will not print any data for
|
||
this field.
|
||
|
||
-- Function: FrameDecorator.address (self)
|
||
|
||
This method returns the address of the frame that is to be printed.
|
||
|
||
This method must return a Python numeric integer type of sufficient
|
||
size to describe the address of the frame, or 'None'.
|
||
|
||
If this function returns a 'None', GDB will not print any data for
|
||
this field.
|
||
|
||
-- Function: FrameDecorator.filename (self)
|
||
|
||
This method returns the filename and path associated with this
|
||
frame.
|
||
|
||
This method must return a Python string containing the filename and
|
||
the path to the object file backing the frame, or 'None'.
|
||
|
||
If this function returns a 'None', GDB will not print any data for
|
||
this field.
|
||
|
||
-- Function: FrameDecorator.line (self):
|
||
|
||
This method returns the line number associated with the current
|
||
position within the function addressed by this frame.
|
||
|
||
This method must return a Python integer type, or 'None'.
|
||
|
||
If this function returns a 'None', GDB will not print any data for
|
||
this field.
|
||
|
||
-- Function: FrameDecorator.frame_args (self)
|
||
|
||
This method must return an iterable, or 'None'. Returning an empty
|
||
iterable, or 'None' means frame arguments will not be printed for
|
||
this frame. This iterable must contain objects that implement two
|
||
methods, described here.
|
||
|
||
This object must implement a 'argument' method which takes a single
|
||
'self' parameter and must return a 'gdb.Symbol' (*note Symbols In
|
||
Python::), or a Python string. The object must also implement a
|
||
'value' method which takes a single 'self' parameter and must
|
||
return a 'gdb.Value' (*note Values From Inferior::), a Python
|
||
value, or 'None'. If the 'value' method returns 'None', and the
|
||
'argument' method returns a 'gdb.Symbol', GDB will look-up and
|
||
print the value of the 'gdb.Symbol' automatically.
|
||
|
||
A brief example:
|
||
|
||
class SymValueWrapper():
|
||
|
||
def __init__(self, symbol, value):
|
||
self.sym = symbol
|
||
self.val = value
|
||
|
||
def value(self):
|
||
return self.val
|
||
|
||
def symbol(self):
|
||
return self.sym
|
||
|
||
class SomeFrameDecorator()
|
||
...
|
||
...
|
||
def frame_args(self):
|
||
args = []
|
||
try:
|
||
block = self.inferior_frame.block()
|
||
except:
|
||
return None
|
||
|
||
# Iterate over all symbols in a block. Only add
|
||
# symbols that are arguments.
|
||
for sym in block:
|
||
if not sym.is_argument:
|
||
continue
|
||
args.append(SymValueWrapper(sym,None))
|
||
|
||
# Add example synthetic argument.
|
||
args.append(SymValueWrapper(``foo'', 42))
|
||
|
||
return args
|
||
|
||
-- Function: FrameDecorator.frame_locals (self)
|
||
|
||
This method must return an iterable or 'None'. Returning an empty
|
||
iterable, or 'None' means frame local arguments will not be printed
|
||
for this frame.
|
||
|
||
The object interface, the description of the various strategies for
|
||
reading frame locals, and the example are largely similar to those
|
||
described in the 'frame_args' function, (*note The frame filter
|
||
frame_args function: frame_args.). Below is a modified example:
|
||
|
||
class SomeFrameDecorator()
|
||
...
|
||
...
|
||
def frame_locals(self):
|
||
vars = []
|
||
try:
|
||
block = self.inferior_frame.block()
|
||
except:
|
||
return None
|
||
|
||
# Iterate over all symbols in a block. Add all
|
||
# symbols, except arguments.
|
||
for sym in block:
|
||
if sym.is_argument:
|
||
continue
|
||
vars.append(SymValueWrapper(sym,None))
|
||
|
||
# Add an example of a synthetic local variable.
|
||
vars.append(SymValueWrapper(``bar'', 99))
|
||
|
||
return vars
|
||
|
||
-- Function: FrameDecorator.inferior_frame (self):
|
||
|
||
This method must return the underlying 'gdb.Frame' that this frame
|
||
decorator is decorating. GDB requires the underlying frame for
|
||
internal frame information to determine how to print certain values
|
||
when printing a frame.
|
||
|
||
|
||
File: gdb.info, Node: Writing a Frame Filter, Next: Unwinding Frames in Python, Prev: Frame Decorator API, Up: Python API
|
||
|
||
23.2.2.11 Writing a Frame Filter
|
||
................................
|
||
|
||
There are three basic elements that a frame filter must implement: it
|
||
must correctly implement the documented interface (*note Frame Filter
|
||
API::), it must register itself with GDB, and finally, it must decide if
|
||
it is to work on the data provided by GDB. In all cases, whether it
|
||
works on the iterator or not, each frame filter must return an iterator.
|
||
A bare-bones frame filter follows the pattern in the following example.
|
||
|
||
import gdb
|
||
|
||
class FrameFilter():
|
||
|
||
def __init__(self):
|
||
# Frame filter attribute creation.
|
||
#
|
||
# 'name' is the name of the filter that GDB will display.
|
||
#
|
||
# 'priority' is the priority of the filter relative to other
|
||
# filters.
|
||
#
|
||
# 'enabled' is a boolean that indicates whether this filter is
|
||
# enabled and should be executed.
|
||
|
||
self.name = "Foo"
|
||
self.priority = 100
|
||
self.enabled = True
|
||
|
||
# Register this frame filter with the global frame_filters
|
||
# dictionary.
|
||
gdb.frame_filters[self.name] = self
|
||
|
||
def filter(self, frame_iter):
|
||
# Just return the iterator.
|
||
return frame_iter
|
||
|
||
The frame filter in the example above implements the three
|
||
requirements for all frame filters. It implements the API, self
|
||
registers, and makes a decision on the iterator (in this case, it just
|
||
returns the iterator untouched).
|
||
|
||
The first step is attribute creation and assignment, and as shown in
|
||
the comments the filter assigns the following attributes: 'name',
|
||
'priority' and whether the filter should be enabled with the 'enabled'
|
||
attribute.
|
||
|
||
The second step is registering the frame filter with the dictionary
|
||
or dictionaries that the frame filter has interest in. As shown in the
|
||
comments, this filter just registers itself with the global dictionary
|
||
'gdb.frame_filters'. As noted earlier, 'gdb.frame_filters' is a
|
||
dictionary that is initialized in the 'gdb' module when GDB starts.
|
||
What dictionary a filter registers with is an important consideration.
|
||
Generally, if a filter is specific to a set of code, it should be
|
||
registered either in the 'objfile' or 'progspace' dictionaries as they
|
||
are specific to the program currently loaded in GDB. The global
|
||
dictionary is always present in GDB and is never unloaded. Any filters
|
||
registered with the global dictionary will exist until GDB exits. To
|
||
avoid filters that may conflict, it is generally better to register
|
||
frame filters against the dictionaries that more closely align with the
|
||
usage of the filter currently in question. *Note Python Auto-loading::,
|
||
for further information on auto-loading Python scripts.
|
||
|
||
GDB takes a hands-off approach to frame filter registration,
|
||
therefore it is the frame filter's responsibility to ensure registration
|
||
has occurred, and that any exceptions are handled appropriately. In
|
||
particular, you may wish to handle exceptions relating to Python
|
||
dictionary key uniqueness. It is mandatory that the dictionary key is
|
||
the same as frame filter's 'name' attribute. When a user manages frame
|
||
filters (*note Frame Filter Management::), the names GDB will display
|
||
are those contained in the 'name' attribute.
|
||
|
||
The final step of this example is the implementation of the 'filter'
|
||
method. As shown in the example comments, we define the 'filter' method
|
||
and note that the method must take an iterator, and also must return an
|
||
iterator. In this bare-bones example, the frame filter is not very
|
||
useful as it just returns the iterator untouched. However this is a
|
||
valid operation for frame filters that have the 'enabled' attribute set,
|
||
but decide not to operate on any frames.
|
||
|
||
In the next example, the frame filter operates on all frames and
|
||
utilizes a frame decorator to perform some work on the frames. *Note
|
||
Frame Decorator API::, for further information on the frame decorator
|
||
interface.
|
||
|
||
This example works on inlined frames. It highlights frames which are
|
||
inlined by tagging them with an "[inlined]" tag. By applying a frame
|
||
decorator to all frames with the Python 'itertools imap' method, the
|
||
example defers actions to the frame decorator. Frame decorators are
|
||
only processed when GDB prints the backtrace.
|
||
|
||
This introduces a new decision making topic: whether to perform
|
||
decision making operations at the filtering step, or at the printing
|
||
step. In this example's approach, it does not perform any filtering
|
||
decisions at the filtering step beyond mapping a frame decorator to each
|
||
frame. This allows the actual decision making to be performed when each
|
||
frame is printed. This is an important consideration, and well worth
|
||
reflecting upon when designing a frame filter. An issue that frame
|
||
filters should avoid is unwinding the stack if possible. Some stacks
|
||
can run very deep, into the tens of thousands in some cases. To search
|
||
every frame to determine if it is inlined ahead of time may be too
|
||
expensive at the filtering step. The frame filter cannot know how many
|
||
frames it has to iterate over, and it would have to iterate through them
|
||
all. This ends up duplicating effort as GDB performs this iteration
|
||
when it prints the frames.
|
||
|
||
In this example decision making can be deferred to the printing step.
|
||
As each frame is printed, the frame decorator can examine each frame in
|
||
turn when GDB iterates. From a performance viewpoint, this is the most
|
||
appropriate decision to make as it avoids duplicating the effort that
|
||
the printing step would undertake anyway. Also, if there are many frame
|
||
filters unwinding the stack during filtering, it can substantially delay
|
||
the printing of the backtrace which will result in large memory usage,
|
||
and a poor user experience.
|
||
|
||
class InlineFilter():
|
||
|
||
def __init__(self):
|
||
self.name = "InlinedFrameFilter"
|
||
self.priority = 100
|
||
self.enabled = True
|
||
gdb.frame_filters[self.name] = self
|
||
|
||
def filter(self, frame_iter):
|
||
frame_iter = itertools.imap(InlinedFrameDecorator,
|
||
frame_iter)
|
||
return frame_iter
|
||
|
||
This frame filter is somewhat similar to the earlier example, except
|
||
that the 'filter' method applies a frame decorator object called
|
||
'InlinedFrameDecorator' to each element in the iterator. The 'imap'
|
||
Python method is light-weight. It does not proactively iterate over the
|
||
iterator, but rather creates a new iterator which wraps the existing
|
||
one.
|
||
|
||
Below is the frame decorator for this example.
|
||
|
||
class InlinedFrameDecorator(FrameDecorator):
|
||
|
||
def __init__(self, fobj):
|
||
super(InlinedFrameDecorator, self).__init__(fobj)
|
||
|
||
def function(self):
|
||
frame = fobj.inferior_frame()
|
||
name = str(frame.name())
|
||
|
||
if frame.type() == gdb.INLINE_FRAME:
|
||
name = name + " [inlined]"
|
||
|
||
return name
|
||
|
||
This frame decorator only defines and overrides the 'function'
|
||
method. It lets the supplied 'FrameDecorator', which is shipped with
|
||
GDB, perform the other work associated with printing this frame.
|
||
|
||
The combination of these two objects create this output from a
|
||
backtrace:
|
||
|
||
#0 0x004004e0 in bar () at inline.c:11
|
||
#1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21
|
||
#2 0x00400566 in main () at inline.c:31
|
||
|
||
So in the case of this example, a frame decorator is applied to all
|
||
frames, regardless of whether they may be inlined or not. As GDB
|
||
iterates over the iterator produced by the frame filters, GDB executes
|
||
each frame decorator which then makes a decision on what to print in the
|
||
'function' callback. Using a strategy like this is a way to defer
|
||
decisions on the frame content to printing time.
|
||
|
||
Eliding Frames
|
||
--------------
|
||
|
||
It might be that the above example is not desirable for representing
|
||
inlined frames, and a hierarchical approach may be preferred. If we
|
||
want to hierarchically represent frames, the 'elided' frame decorator
|
||
interface might be preferable.
|
||
|
||
This example approaches the issue with the 'elided' method. This
|
||
example is quite long, but very simplistic. It is out-of-scope for this
|
||
section to write a complete example that comprehensively covers all
|
||
approaches of finding and printing inlined frames. However, this
|
||
example illustrates the approach an author might use.
|
||
|
||
This example comprises of three sections.
|
||
|
||
class InlineFrameFilter():
|
||
|
||
def __init__(self):
|
||
self.name = "InlinedFrameFilter"
|
||
self.priority = 100
|
||
self.enabled = True
|
||
gdb.frame_filters[self.name] = self
|
||
|
||
def filter(self, frame_iter):
|
||
return ElidingInlineIterator(frame_iter)
|
||
|
||
This frame filter is very similar to the other examples. The only
|
||
difference is this frame filter is wrapping the iterator provided to it
|
||
('frame_iter') with a custom iterator called 'ElidingInlineIterator'.
|
||
This again defers actions to when GDB prints the backtrace, as the
|
||
iterator is not traversed until printing.
|
||
|
||
The iterator for this example is as follows. It is in this section
|
||
of the example where decisions are made on the content of the backtrace.
|
||
|
||
class ElidingInlineIterator:
|
||
def __init__(self, ii):
|
||
self.input_iterator = ii
|
||
|
||
def __iter__(self):
|
||
return self
|
||
|
||
def next(self):
|
||
frame = next(self.input_iterator)
|
||
|
||
if frame.inferior_frame().type() != gdb.INLINE_FRAME:
|
||
return frame
|
||
|
||
try:
|
||
eliding_frame = next(self.input_iterator)
|
||
except StopIteration:
|
||
return frame
|
||
return ElidingFrameDecorator(eliding_frame, [frame])
|
||
|
||
This iterator implements the Python iterator protocol. When the
|
||
'next' function is called (when GDB prints each frame), the iterator
|
||
checks if this frame decorator, 'frame', is wrapping an inlined frame.
|
||
If it is not, it returns the existing frame decorator untouched. If it
|
||
is wrapping an inlined frame, it assumes that the inlined frame was
|
||
contained within the next oldest frame, 'eliding_frame', which it
|
||
fetches. It then creates and returns a frame decorator,
|
||
'ElidingFrameDecorator', which contains both the elided frame, and the
|
||
eliding frame.
|
||
|
||
class ElidingInlineDecorator(FrameDecorator):
|
||
|
||
def __init__(self, frame, elided_frames):
|
||
super(ElidingInlineDecorator, self).__init__(frame)
|
||
self.frame = frame
|
||
self.elided_frames = elided_frames
|
||
|
||
def elided(self):
|
||
return iter(self.elided_frames)
|
||
|
||
This frame decorator overrides one function and returns the inlined
|
||
frame in the 'elided' method. As before it lets 'FrameDecorator' do the
|
||
rest of the work involved in printing this frame. This produces the
|
||
following output.
|
||
|
||
#0 0x004004e0 in bar () at inline.c:11
|
||
#2 0x00400529 in main () at inline.c:25
|
||
#1 0x00400529 in max (b=6, a=12) at inline.c:15
|
||
|
||
In that output, 'max' which has been inlined into 'main' is printed
|
||
hierarchically. Another approach would be to combine the 'function'
|
||
method, and the 'elided' method to both print a marker in the inlined
|
||
frame, and also show the hierarchical relationship.
|
||
|
||
|
||
File: gdb.info, Node: Unwinding Frames in Python, Next: Xmethods In Python, Prev: Writing a Frame Filter, Up: Python API
|
||
|
||
23.2.2.12 Unwinding Frames in Python
|
||
....................................
|
||
|
||
In GDB terminology "unwinding" is the process of finding the previous
|
||
frame (that is, caller's) from the current one. An unwinder has three
|
||
methods. The first one checks if it can handle given frame ("sniff"
|
||
it). For the frames it can sniff an unwinder provides two additional
|
||
methods: it can return frame's ID, and it can fetch registers from the
|
||
previous frame. A running GDB mantains a list of the unwinders and
|
||
calls each unwinder's sniffer in turn until it finds the one that
|
||
recognizes the current frame. There is an API to register an unwinder.
|
||
|
||
The unwinders that come with GDB handle standard frames. However,
|
||
mixed language applications (for example, an application running Java
|
||
Virtual Machine) sometimes use frame layouts that cannot be handled by
|
||
the GDB unwinders. You can write Python code that can handle such
|
||
custom frames.
|
||
|
||
You implement a frame unwinder in Python as a class with which has
|
||
two attributes, 'name' and 'enabled', with obvious meanings, and a
|
||
single method '__call__', which examines a given frame and returns an
|
||
object (an instance of 'gdb.UnwindInfo class)' describing it. If an
|
||
unwinder does not recognize a frame, it should return 'None'. The code
|
||
in GDB that enables writing unwinders in Python uses this object to
|
||
return frame's ID and previous frame registers when GDB core asks for
|
||
them.
|
||
|
||
An unwinder should do as little work as possible. Some otherwise
|
||
innocuous operations can cause problems (even crashes, as this code is
|
||
not not well-hardened yet). For example, making an inferior call from
|
||
an unwinder is unadvisable, as an inferior call will reset GDB's stack
|
||
unwinding process, potentially causing re-entrant unwinding.
|
||
|
||
Unwinder Input
|
||
--------------
|
||
|
||
An object passed to an unwinder (a 'gdb.PendingFrame' instance) provides
|
||
a method to read frame's registers:
|
||
|
||
-- Function: PendingFrame.read_register (reg)
|
||
This method returns the contents of the register REG in the frame
|
||
as a 'gdb.Value' object. REG can be either a register number or a
|
||
register name; the values are platform-specific. They are usually
|
||
found in the corresponding 'PLATFORM-tdep.h' file in the GDB source
|
||
tree. If REG does not name a register for the current
|
||
architecture, this method will throw an exception.
|
||
|
||
Note that this method will always return a 'gdb.Value' for a valid
|
||
register name. This does not mean that the value will be valid.
|
||
For example, you may request a register that an earlier unwinder
|
||
could not unwind--the value will be unavailable. Instead, the
|
||
'gdb.Value' returned from this method will be lazy; that is, its
|
||
underlying bits will not be fetched until it is first used. So,
|
||
attempting to use such a value will cause an exception at the point
|
||
of use.
|
||
|
||
The type of the returned 'gdb.Value' depends on the register and
|
||
the architecture. It is common for registers to have a scalar
|
||
type, like 'long long'; but many other types are possible, such as
|
||
pointer, pointer-to-function, floating point or vector types.
|
||
|
||
It also provides a factory method to create a 'gdb.UnwindInfo'
|
||
instance to be returned to GDB:
|
||
|
||
-- Function: PendingFrame.create_unwind_info (frame_id)
|
||
Returns a new 'gdb.UnwindInfo' instance identified by given
|
||
FRAME_ID. The argument is used to build GDB's frame ID using one
|
||
of functions provided by GDB. FRAME_ID's attributes determine
|
||
which function will be used, as follows:
|
||
|
||
'sp, pc'
|
||
The frame is identified by the given stack address and PC. The
|
||
stack address must be chosen so that it is constant throughout
|
||
the lifetime of the frame, so a typical choice is the value of
|
||
the stack pointer at the start of the function--in the DWARF
|
||
standard, this would be the "Call Frame Address".
|
||
|
||
This is the most common case by far. The other cases are
|
||
documented for completeness but are only useful in specialized
|
||
situations.
|
||
|
||
'sp, pc, special'
|
||
The frame is identified by the stack address, the PC, and a
|
||
"special" address. The special address is used on
|
||
architectures that can have frames that do not change the
|
||
stack, but which are still distinct, for example the IA-64,
|
||
which has a second stack for registers. Both SP and SPECIAL
|
||
must be constant throughout the lifetime of the frame.
|
||
|
||
'sp'
|
||
The frame is identified by the stack address only. Any other
|
||
stack frame with a matching SP will be considered to match
|
||
this frame. Inside gdb, this is called a "wild frame". You
|
||
will never need this.
|
||
|
||
Each attribute value should be an instance of 'gdb.Value'.
|
||
|
||
Unwinder Output: UnwindInfo
|
||
---------------------------
|
||
|
||
Use 'PendingFrame.create_unwind_info' method described above to create a
|
||
'gdb.UnwindInfo' instance. Use the following method to specify caller
|
||
registers that have been saved in this frame:
|
||
|
||
-- Function: gdb.UnwindInfo.add_saved_register (reg, value)
|
||
REG identifies the register. It can be a number or a name, just as
|
||
for the 'PendingFrame.read_register' method above. VALUE is a
|
||
register value (a 'gdb.Value' object).
|
||
|
||
Unwinder Skeleton Code
|
||
----------------------
|
||
|
||
GDB comes with the module containing the base 'Unwinder' class. Derive
|
||
your unwinder class from it and structure the code as follows:
|
||
|
||
from gdb.unwinders import Unwinder
|
||
|
||
class FrameId(object):
|
||
def __init__(self, sp, pc):
|
||
self.sp = sp
|
||
self.pc = pc
|
||
|
||
|
||
class MyUnwinder(Unwinder):
|
||
def __init__(....):
|
||
super(MyUnwinder, self).__init___(<expects unwinder name argument>)
|
||
|
||
def __call__(pending_frame):
|
||
if not <we recognize frame>:
|
||
return None
|
||
# Create UnwindInfo. Usually the frame is identified by the stack
|
||
# pointer and the program counter.
|
||
sp = pending_frame.read_register(<SP number>)
|
||
pc = pending_frame.read_register(<PC number>)
|
||
unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc))
|
||
|
||
# Find the values of the registers in the caller's frame and
|
||
# save them in the result:
|
||
unwind_info.add_saved_register(<register>, <value>)
|
||
....
|
||
|
||
# Return the result:
|
||
return unwind_info
|
||
|
||
|
||
Registering a Unwinder
|
||
----------------------
|
||
|
||
An object file, a program space, and the GDB proper can have unwinders
|
||
registered with it.
|
||
|
||
The 'gdb.unwinders' module provides the function to register a
|
||
unwinder:
|
||
|
||
-- Function: gdb.unwinder.register_unwinder (locus, unwinder,
|
||
replace=False)
|
||
LOCUS is specifies an object file or a program space to which
|
||
UNWINDER is added. Passing 'None' or 'gdb' adds UNWINDER to the
|
||
GDB's global unwinder list. The newly added UNWINDER will be
|
||
called before any other unwinder from the same locus. Two
|
||
unwinders in the same locus cannot have the same name. An attempt
|
||
to add a unwinder with already existing name raises an exception
|
||
unless REPLACE is 'True', in which case the old unwinder is
|
||
deleted.
|
||
|
||
Unwinder Precedence
|
||
-------------------
|
||
|
||
GDB first calls the unwinders from all the object files in no particular
|
||
order, then the unwinders from the current program space, and finally
|
||
the unwinders from GDB.
|
||
|
||
|
||
File: gdb.info, Node: Xmethods In Python, Next: Xmethod API, Prev: Unwinding Frames in Python, Up: Python API
|
||
|
||
23.2.2.13 Xmethods In Python
|
||
............................
|
||
|
||
"Xmethods" are additional methods or replacements for existing methods
|
||
of a C++ class. This feature is useful for those cases where a method
|
||
defined in C++ source code could be inlined or optimized out by the
|
||
compiler, making it unavailable to GDB. For such cases, one can define
|
||
an xmethod to serve as a replacement for the method defined in the C++
|
||
source code. GDB will then invoke the xmethod, instead of the C++
|
||
method, to evaluate expressions. One can also use xmethods when
|
||
debugging with core files. Moreover, when debugging live programs,
|
||
invoking an xmethod need not involve running the inferior (which can
|
||
potentially perturb its state). Hence, even if the C++ method is
|
||
available, it is better to use its replacement xmethod if one is
|
||
defined.
|
||
|
||
The xmethods feature in Python is available via the concepts of an
|
||
"xmethod matcher" and an "xmethod worker". To implement an xmethod, one
|
||
has to implement a matcher and a corresponding worker for it (more than
|
||
one worker can be implemented, each catering to a different overloaded
|
||
instance of the method). Internally, GDB invokes the 'match' method of
|
||
a matcher to match the class type and method name. On a match, the
|
||
'match' method returns a list of matching _worker_ objects. Each worker
|
||
object typically corresponds to an overloaded instance of the xmethod.
|
||
They implement a 'get_arg_types' method which returns a sequence of
|
||
types corresponding to the arguments the xmethod requires. GDB uses
|
||
this sequence of types to perform overload resolution and picks a
|
||
winning xmethod worker. A winner is also selected from among the
|
||
methods GDB finds in the C++ source code. Next, the winning xmethod
|
||
worker and the winning C++ method are compared to select an overall
|
||
winner. In case of a tie between a xmethod worker and a C++ method, the
|
||
xmethod worker is selected as the winner. That is, if a winning xmethod
|
||
worker is found to be equivalent to the winning C++ method, then the
|
||
xmethod worker is treated as a replacement for the C++ method. GDB uses
|
||
the overall winner to invoke the method. If the winning xmethod worker
|
||
is the overall winner, then the corresponding xmethod is invoked via the
|
||
'__call__' method of the worker object.
|
||
|
||
If one wants to implement an xmethod as a replacement for an existing
|
||
C++ method, then they have to implement an equivalent xmethod which has
|
||
exactly the same name and takes arguments of exactly the same type as
|
||
the C++ method. If the user wants to invoke the C++ method even though
|
||
a replacement xmethod is available for that method, then they can
|
||
disable the xmethod.
|
||
|
||
*Note Xmethod API::, for API to implement xmethods in Python. *Note
|
||
Writing an Xmethod::, for implementing xmethods in Python.
|
||
|
||
|
||
File: gdb.info, Node: Xmethod API, Next: Writing an Xmethod, Prev: Xmethods In Python, Up: Python API
|
||
|
||
23.2.2.14 Xmethod API
|
||
.....................
|
||
|
||
The GDB Python API provides classes, interfaces and functions to
|
||
implement, register and manipulate xmethods. *Note Xmethods In
|
||
Python::.
|
||
|
||
An xmethod matcher should be an instance of a class derived from
|
||
'XMethodMatcher' defined in the module 'gdb.xmethod', or an object with
|
||
similar interface and attributes. An instance of 'XMethodMatcher' has
|
||
the following attributes:
|
||
|
||
-- Variable: name
|
||
The name of the matcher.
|
||
|
||
-- Variable: enabled
|
||
A boolean value indicating whether the matcher is enabled or
|
||
disabled.
|
||
|
||
-- Variable: methods
|
||
A list of named methods managed by the matcher. Each object in the
|
||
list is an instance of the class 'XMethod' defined in the module
|
||
'gdb.xmethod', or any object with the following attributes:
|
||
|
||
'name'
|
||
Name of the xmethod which should be unique for each xmethod
|
||
managed by the matcher.
|
||
|
||
'enabled'
|
||
A boolean value indicating whether the xmethod is enabled or
|
||
disabled.
|
||
|
||
The class 'XMethod' is a convenience class with same attributes as
|
||
above along with the following constructor:
|
||
|
||
-- Function: XMethod.__init__ (self, name)
|
||
Constructs an enabled xmethod with name NAME.
|
||
|
||
The 'XMethodMatcher' class has the following methods:
|
||
|
||
-- Function: XMethodMatcher.__init__ (self, name)
|
||
Constructs an enabled xmethod matcher with name NAME. The
|
||
'methods' attribute is initialized to 'None'.
|
||
|
||
-- Function: XMethodMatcher.match (self, class_type, method_name)
|
||
Derived classes should override this method. It should return a
|
||
xmethod worker object (or a sequence of xmethod worker objects)
|
||
matching the CLASS_TYPE and METHOD_NAME. CLASS_TYPE is a
|
||
'gdb.Type' object, and METHOD_NAME is a string value. If the
|
||
matcher manages named methods as listed in its 'methods' attribute,
|
||
then only those worker objects whose corresponding entries in the
|
||
'methods' list are enabled should be returned.
|
||
|
||
An xmethod worker should be an instance of a class derived from
|
||
'XMethodWorker' defined in the module 'gdb.xmethod', or support the
|
||
following interface:
|
||
|
||
-- Function: XMethodWorker.get_arg_types (self)
|
||
This method returns a sequence of 'gdb.Type' objects corresponding
|
||
to the arguments that the xmethod takes. It can return an empty
|
||
sequence or 'None' if the xmethod does not take any arguments. If
|
||
the xmethod takes a single argument, then a single 'gdb.Type'
|
||
object corresponding to it can be returned.
|
||
|
||
-- Function: XMethodWorker.get_result_type (self, *args)
|
||
This method returns a 'gdb.Type' object representing the type of
|
||
the result of invoking this xmethod. The ARGS argument is the same
|
||
tuple of arguments that would be passed to the '__call__' method of
|
||
this worker.
|
||
|
||
-- Function: XMethodWorker.__call__ (self, *args)
|
||
This is the method which does the _work_ of the xmethod. The ARGS
|
||
arguments is the tuple of arguments to the xmethod. Each element
|
||
in this tuple is a gdb.Value object. The first element is always
|
||
the 'this' pointer value.
|
||
|
||
For GDB to lookup xmethods, the xmethod matchers should be registered
|
||
using the following function defined in the module 'gdb.xmethod':
|
||
|
||
-- Function: register_xmethod_matcher (locus, matcher, replace=False)
|
||
The 'matcher' is registered with 'locus', replacing an existing
|
||
matcher with the same name as 'matcher' if 'replace' is 'True'.
|
||
'locus' can be a 'gdb.Objfile' object (*note Objfiles In Python::),
|
||
or a 'gdb.Progspace' object (*note Progspaces In Python::), or
|
||
'None'. If it is 'None', then 'matcher' is registered globally.
|
||
|
||
|
||
File: gdb.info, Node: Writing an Xmethod, Next: Inferiors In Python, Prev: Xmethod API, Up: Python API
|
||
|
||
23.2.2.15 Writing an Xmethod
|
||
............................
|
||
|
||
Implementing xmethods in Python will require implementing xmethod
|
||
matchers and xmethod workers (*note Xmethods In Python::). Consider the
|
||
following C++ class:
|
||
|
||
class MyClass
|
||
{
|
||
public:
|
||
MyClass (int a) : a_(a) { }
|
||
|
||
int geta (void) { return a_; }
|
||
int operator+ (int b);
|
||
|
||
private:
|
||
int a_;
|
||
};
|
||
|
||
int
|
||
MyClass::operator+ (int b)
|
||
{
|
||
return a_ + b;
|
||
}
|
||
|
||
Let us define two xmethods for the class 'MyClass', one replacing the
|
||
method 'geta', and another adding an overloaded flavor of 'operator+'
|
||
which takes a 'MyClass' argument (the C++ code above already has an
|
||
overloaded 'operator+' which takes an 'int' argument). The xmethod
|
||
matcher can be defined as follows:
|
||
|
||
class MyClass_geta(gdb.xmethod.XMethod):
|
||
def __init__(self):
|
||
gdb.xmethod.XMethod.__init__(self, 'geta')
|
||
|
||
def get_worker(self, method_name):
|
||
if method_name == 'geta':
|
||
return MyClassWorker_geta()
|
||
|
||
|
||
class MyClass_sum(gdb.xmethod.XMethod):
|
||
def __init__(self):
|
||
gdb.xmethod.XMethod.__init__(self, 'sum')
|
||
|
||
def get_worker(self, method_name):
|
||
if method_name == 'operator+':
|
||
return MyClassWorker_plus()
|
||
|
||
|
||
class MyClassMatcher(gdb.xmethod.XMethodMatcher):
|
||
def __init__(self):
|
||
gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher')
|
||
# List of methods 'managed' by this matcher
|
||
self.methods = [MyClass_geta(), MyClass_sum()]
|
||
|
||
def match(self, class_type, method_name):
|
||
if class_type.tag != 'MyClass':
|
||
return None
|
||
workers = []
|
||
for method in self.methods:
|
||
if method.enabled:
|
||
worker = method.get_worker(method_name)
|
||
if worker:
|
||
workers.append(worker)
|
||
|
||
return workers
|
||
|
||
Notice that the 'match' method of 'MyClassMatcher' returns a worker
|
||
object of type 'MyClassWorker_geta' for the 'geta' method, and a worker
|
||
object of type 'MyClassWorker_plus' for the 'operator+' method. This is
|
||
done indirectly via helper classes derived from 'gdb.xmethod.XMethod'.
|
||
One does not need to use the 'methods' attribute in a matcher as it is
|
||
optional. However, if a matcher manages more than one xmethod, it is a
|
||
good practice to list the xmethods in the 'methods' attribute of the
|
||
matcher. This will then facilitate enabling and disabling individual
|
||
xmethods via the 'enable/disable' commands. Notice also that a worker
|
||
object is returned only if the corresponding entry in the 'methods'
|
||
attribute of the matcher is enabled.
|
||
|
||
The implementation of the worker classes returned by the matcher
|
||
setup above is as follows:
|
||
|
||
class MyClassWorker_geta(gdb.xmethod.XMethodWorker):
|
||
def get_arg_types(self):
|
||
return None
|
||
|
||
def get_result_type(self, obj):
|
||
return gdb.lookup_type('int')
|
||
|
||
def __call__(self, obj):
|
||
return obj['a_']
|
||
|
||
|
||
class MyClassWorker_plus(gdb.xmethod.XMethodWorker):
|
||
def get_arg_types(self):
|
||
return gdb.lookup_type('MyClass')
|
||
|
||
def get_result_type(self, obj):
|
||
return gdb.lookup_type('int')
|
||
|
||
def __call__(self, obj, other):
|
||
return obj['a_'] + other['a_']
|
||
|
||
For GDB to actually lookup a xmethod, it has to be registered with
|
||
it. The matcher defined above is registered with GDB globally as
|
||
follows:
|
||
|
||
gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher())
|
||
|
||
If an object 'obj' of type 'MyClass' is initialized in C++ code as
|
||
follows:
|
||
|
||
MyClass obj(5);
|
||
|
||
then, after loading the Python script defining the xmethod matchers and
|
||
workers into 'GDBN', invoking the method 'geta' or using the operator
|
||
'+' on 'obj' will invoke the xmethods defined above:
|
||
|
||
(gdb) p obj.geta()
|
||
$1 = 5
|
||
|
||
(gdb) p obj + obj
|
||
$2 = 10
|
||
|
||
Consider another example with a C++ template class:
|
||
|
||
template <class T>
|
||
class MyTemplate
|
||
{
|
||
public:
|
||
MyTemplate () : dsize_(10), data_ (new T [10]) { }
|
||
~MyTemplate () { delete [] data_; }
|
||
|
||
int footprint (void)
|
||
{
|
||
return sizeof (T) * dsize_ + sizeof (MyTemplate<T>);
|
||
}
|
||
|
||
private:
|
||
int dsize_;
|
||
T *data_;
|
||
};
|
||
|
||
Let us implement an xmethod for the above class which serves as a
|
||
replacement for the 'footprint' method. The full code listing of the
|
||
xmethod workers and xmethod matchers is as follows:
|
||
|
||
class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker):
|
||
def __init__(self, class_type):
|
||
self.class_type = class_type
|
||
|
||
def get_arg_types(self):
|
||
return None
|
||
|
||
def get_result_type(self):
|
||
return gdb.lookup_type('int')
|
||
|
||
def __call__(self, obj):
|
||
return (self.class_type.sizeof +
|
||
obj['dsize_'] *
|
||
self.class_type.template_argument(0).sizeof)
|
||
|
||
|
||
class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher):
|
||
def __init__(self):
|
||
gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher')
|
||
|
||
def match(self, class_type, method_name):
|
||
if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>',
|
||
class_type.tag) and
|
||
method_name == 'footprint'):
|
||
return MyTemplateWorker_footprint(class_type)
|
||
|
||
Notice that, in this example, we have not used the 'methods'
|
||
attribute of the matcher as the matcher manages only one xmethod. The
|
||
user can enable/disable this xmethod by enabling/disabling the matcher
|
||
itself.
|
||
|
||
|
||
File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing an Xmethod, Up: Python API
|
||
|
||
23.2.2.16 Inferiors In Python
|
||
.............................
|
||
|
||
Programs which are being run under GDB are called inferiors (*note
|
||
Inferiors and Programs::). Python scripts can access information about
|
||
and manipulate inferiors controlled by GDB via objects of the
|
||
'gdb.Inferior' class.
|
||
|
||
The following inferior-related functions are available in the 'gdb'
|
||
module:
|
||
|
||
-- Function: gdb.inferiors ()
|
||
Return a tuple containing all inferior objects.
|
||
|
||
-- Function: gdb.selected_inferior ()
|
||
Return an object representing the current inferior.
|
||
|
||
A 'gdb.Inferior' object has the following attributes:
|
||
|
||
-- Variable: Inferior.num
|
||
ID of inferior, as assigned by GDB.
|
||
|
||
-- Variable: Inferior.pid
|
||
Process ID of the inferior, as assigned by the underlying operating
|
||
system.
|
||
|
||
-- Variable: Inferior.was_attached
|
||
Boolean signaling whether the inferior was created using 'attach',
|
||
or started by GDB itself.
|
||
|
||
-- Variable: Inferior.progspace
|
||
The inferior's program space. *Note Progspaces In Python::.
|
||
|
||
A 'gdb.Inferior' object has the following methods:
|
||
|
||
-- Function: Inferior.is_valid ()
|
||
Returns 'True' if the 'gdb.Inferior' object is valid, 'False' if
|
||
not. A 'gdb.Inferior' object will become invalid if the inferior
|
||
no longer exists within GDB. All other 'gdb.Inferior' methods will
|
||
throw an exception if it is invalid at the time the method is
|
||
called.
|
||
|
||
-- Function: Inferior.threads ()
|
||
This method returns a tuple holding all the threads which are valid
|
||
when it is called. If there are no valid threads, the method will
|
||
return an empty tuple.
|
||
|
||
-- Function: Inferior.architecture ()
|
||
Return the 'gdb.Architecture' (*note Architectures In Python::) for
|
||
this inferior. This represents the architecture of the inferior as
|
||
a whole. Some platforms can have multiple architectures in a
|
||
single address space, so this may not match the architecture of a
|
||
particular frame (*note Frames In Python::).
|
||
|
||
-- Function: Inferior.read_memory (address, length)
|
||
Read LENGTH addressable memory units from the inferior, starting at
|
||
ADDRESS. Returns a buffer object, which behaves much like an array
|
||
or a string. It can be modified and given to the
|
||
'Inferior.write_memory' function. In Python 3, the return value is
|
||
a 'memoryview' object.
|
||
|
||
-- Function: Inferior.write_memory (address, buffer [, length])
|
||
Write the contents of BUFFER to the inferior, starting at ADDRESS.
|
||
The BUFFER parameter must be a Python object which supports the
|
||
buffer protocol, i.e., a string, an array or the object returned
|
||
from 'Inferior.read_memory'. If given, LENGTH determines the
|
||
number of addressable memory units from BUFFER to be written.
|
||
|
||
-- Function: Inferior.search_memory (address, length, pattern)
|
||
Search a region of the inferior memory starting at ADDRESS with the
|
||
given LENGTH using the search pattern supplied in PATTERN. The
|
||
PATTERN parameter must be a Python object which supports the buffer
|
||
protocol, i.e., a string, an array or the object returned from
|
||
'gdb.read_memory'. Returns a Python 'Long' containing the address
|
||
where the pattern was found, or 'None' if the pattern could not be
|
||
found.
|
||
|
||
-- Function: Inferior.thread_from_handle (handle)
|
||
Return the thread object corresponding to HANDLE, a thread library
|
||
specific data structure such as 'pthread_t' for pthreads library
|
||
implementations.
|
||
|
||
The function 'Inferior.thread_from_thread_handle' provides the same
|
||
functionality, but use of 'Inferior.thread_from_thread_handle' is
|
||
deprecated.
|
||
|
||
|
||
File: gdb.info, Node: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API
|
||
|
||
23.2.2.17 Events In Python
|
||
..........................
|
||
|
||
GDB provides a general event facility so that Python code can be
|
||
notified of various state changes, particularly changes that occur in
|
||
the inferior.
|
||
|
||
An "event" is just an object that describes some state change. The
|
||
type of the object and its attributes will vary depending on the details
|
||
of the change. All the existing events are described below.
|
||
|
||
In order to be notified of an event, you must register an event
|
||
handler with an "event registry". An event registry is an object in the
|
||
'gdb.events' module which dispatches particular events. A registry
|
||
provides methods to register and unregister event handlers:
|
||
|
||
-- Function: EventRegistry.connect (object)
|
||
Add the given callable OBJECT to the registry. This object will be
|
||
called when an event corresponding to this registry occurs.
|
||
|
||
-- Function: EventRegistry.disconnect (object)
|
||
Remove the given OBJECT from the registry. Once removed, the
|
||
object will no longer receive notifications of events.
|
||
|
||
Here is an example:
|
||
|
||
def exit_handler (event):
|
||
print "event type: exit"
|
||
print "exit code: %d" % (event.exit_code)
|
||
|
||
gdb.events.exited.connect (exit_handler)
|
||
|
||
In the above example we connect our handler 'exit_handler' to the
|
||
registry 'events.exited'. Once connected, 'exit_handler' gets called
|
||
when the inferior exits. The argument "event" in this example is of
|
||
type 'gdb.ExitedEvent'. As you can see in the example the 'ExitedEvent'
|
||
object has an attribute which indicates the exit code of the inferior.
|
||
|
||
The following is a listing of the event registries that are available
|
||
and details of the events they emit:
|
||
|
||
'events.cont'
|
||
Emits 'gdb.ThreadEvent'.
|
||
|
||
Some events can be thread specific when GDB is running in non-stop
|
||
mode. When represented in Python, these events all extend
|
||
'gdb.ThreadEvent'. Note, this event is not emitted directly;
|
||
instead, events which are emitted by this or other modules might
|
||
extend this event. Examples of these events are
|
||
'gdb.BreakpointEvent' and 'gdb.ContinueEvent'.
|
||
|
||
-- Variable: ThreadEvent.inferior_thread
|
||
In non-stop mode this attribute will be set to the specific
|
||
thread which was involved in the emitted event. Otherwise, it
|
||
will be set to 'None'.
|
||
|
||
Emits 'gdb.ContinueEvent' which extends 'gdb.ThreadEvent'.
|
||
|
||
This event indicates that the inferior has been continued after a
|
||
stop. For inherited attribute refer to 'gdb.ThreadEvent' above.
|
||
|
||
'events.exited'
|
||
Emits 'events.ExitedEvent' which indicates that the inferior has
|
||
exited. 'events.ExitedEvent' has two attributes:
|
||
-- Variable: ExitedEvent.exit_code
|
||
An integer representing the exit code, if available, which the
|
||
inferior has returned. (The exit code could be unavailable
|
||
if, for example, GDB detaches from the inferior.) If the exit
|
||
code is unavailable, the attribute does not exist.
|
||
-- Variable: ExitedEvent.inferior
|
||
A reference to the inferior which triggered the 'exited'
|
||
event.
|
||
|
||
'events.stop'
|
||
Emits 'gdb.StopEvent' which extends 'gdb.ThreadEvent'.
|
||
|
||
Indicates that the inferior has stopped. All events emitted by
|
||
this registry extend StopEvent. As a child of 'gdb.ThreadEvent',
|
||
'gdb.StopEvent' will indicate the stopped thread when GDB is
|
||
running in non-stop mode. Refer to 'gdb.ThreadEvent' above for
|
||
more details.
|
||
|
||
Emits 'gdb.SignalEvent' which extends 'gdb.StopEvent'.
|
||
|
||
This event indicates that the inferior or one of its threads has
|
||
received as signal. 'gdb.SignalEvent' has the following
|
||
attributes:
|
||
|
||
-- Variable: SignalEvent.stop_signal
|
||
A string representing the signal received by the inferior. A
|
||
list of possible signal values can be obtained by running the
|
||
command 'info signals' in the GDB command prompt.
|
||
|
||
Also emits 'gdb.BreakpointEvent' which extends 'gdb.StopEvent'.
|
||
|
||
'gdb.BreakpointEvent' event indicates that one or more breakpoints
|
||
have been hit, and has the following attributes:
|
||
|
||
-- Variable: BreakpointEvent.breakpoints
|
||
A sequence containing references to all the breakpoints (type
|
||
'gdb.Breakpoint') that were hit. *Note Breakpoints In
|
||
Python::, for details of the 'gdb.Breakpoint' object.
|
||
-- Variable: BreakpointEvent.breakpoint
|
||
A reference to the first breakpoint that was hit. This
|
||
function is maintained for backward compatibility and is now
|
||
deprecated in favor of the 'gdb.BreakpointEvent.breakpoints'
|
||
attribute.
|
||
|
||
'events.new_objfile'
|
||
Emits 'gdb.NewObjFileEvent' which indicates that a new object file
|
||
has been loaded by GDB. 'gdb.NewObjFileEvent' has one attribute:
|
||
|
||
-- Variable: NewObjFileEvent.new_objfile
|
||
A reference to the object file ('gdb.Objfile') which has been
|
||
loaded. *Note Objfiles In Python::, for details of the
|
||
'gdb.Objfile' object.
|
||
|
||
'events.clear_objfiles'
|
||
Emits 'gdb.ClearObjFilesEvent' which indicates that the list of
|
||
object files for a program space has been reset.
|
||
'gdb.ClearObjFilesEvent' has one attribute:
|
||
|
||
-- Variable: ClearObjFilesEvent.progspace
|
||
A reference to the program space ('gdb.Progspace') whose
|
||
objfile list has been cleared. *Note Progspaces In Python::.
|
||
|
||
'events.inferior_call'
|
||
Emits events just before and after a function in the inferior is
|
||
called by GDB. Before an inferior call, this emits an event of
|
||
type 'gdb.InferiorCallPreEvent', and after an inferior call, this
|
||
emits an event of type 'gdb.InferiorCallPostEvent'.
|
||
|
||
'gdb.InferiorCallPreEvent'
|
||
Indicates that a function in the inferior is about to be
|
||
called.
|
||
|
||
-- Variable: InferiorCallPreEvent.ptid
|
||
The thread in which the call will be run.
|
||
|
||
-- Variable: InferiorCallPreEvent.address
|
||
The location of the function to be called.
|
||
|
||
'gdb.InferiorCallPostEvent'
|
||
Indicates that a function in the inferior has just been
|
||
called.
|
||
|
||
-- Variable: InferiorCallPostEvent.ptid
|
||
The thread in which the call was run.
|
||
|
||
-- Variable: InferiorCallPostEvent.address
|
||
The location of the function that was called.
|
||
|
||
'events.memory_changed'
|
||
Emits 'gdb.MemoryChangedEvent' which indicates that the memory of
|
||
the inferior has been modified by the GDB user, for instance via a
|
||
command like 'set *addr = value'. The event has the following
|
||
attributes:
|
||
|
||
-- Variable: MemoryChangedEvent.address
|
||
The start address of the changed region.
|
||
|
||
-- Variable: MemoryChangedEvent.length
|
||
Length in bytes of the changed region.
|
||
|
||
'events.register_changed'
|
||
Emits 'gdb.RegisterChangedEvent' which indicates that a register in
|
||
the inferior has been modified by the GDB user.
|
||
|
||
-- Variable: RegisterChangedEvent.frame
|
||
A gdb.Frame object representing the frame in which the
|
||
register was modified.
|
||
-- Variable: RegisterChangedEvent.regnum
|
||
Denotes which register was modified.
|
||
|
||
'events.breakpoint_created'
|
||
This is emitted when a new breakpoint has been created. The
|
||
argument that is passed is the new 'gdb.Breakpoint' object.
|
||
|
||
'events.breakpoint_modified'
|
||
This is emitted when a breakpoint has been modified in some way.
|
||
The argument that is passed is the new 'gdb.Breakpoint' object.
|
||
|
||
'events.breakpoint_deleted'
|
||
This is emitted when a breakpoint has been deleted. The argument
|
||
that is passed is the 'gdb.Breakpoint' object. When this event is
|
||
emitted, the 'gdb.Breakpoint' object will already be in its invalid
|
||
state; that is, the 'is_valid' method will return 'False'.
|
||
|
||
'events.before_prompt'
|
||
This event carries no payload. It is emitted each time GDB
|
||
presents a prompt to the user.
|
||
|
||
'events.new_inferior'
|
||
This is emitted when a new inferior is created. Note that the
|
||
inferior is not necessarily running; in fact, it may not even have
|
||
an associated executable.
|
||
|
||
The event is of type 'gdb.NewInferiorEvent'. This has a single
|
||
attribute:
|
||
|
||
-- Variable: NewInferiorEvent.inferior
|
||
The new inferior, a 'gdb.Inferior' object.
|
||
|
||
'events.inferior_deleted'
|
||
This is emitted when an inferior has been deleted. Note that this
|
||
is not the same as process exit; it is notified when the inferior
|
||
itself is removed, say via 'remove-inferiors'.
|
||
|
||
The event is of type 'gdb.InferiorDeletedEvent'. This has a single
|
||
attribute:
|
||
|
||
-- Variable: NewInferiorEvent.inferior
|
||
The inferior that is being removed, a 'gdb.Inferior' object.
|
||
|
||
'events.new_thread'
|
||
This is emitted when GDB notices a new thread. The event is of
|
||
type 'gdb.NewThreadEvent', which extends 'gdb.ThreadEvent'. This
|
||
has a single attribute:
|
||
|
||
-- Variable: NewThreadEvent.inferior_thread
|
||
The new thread.
|
||
|
||
|
||
File: gdb.info, Node: Threads In Python, Next: Recordings In Python, Prev: Events In Python, Up: Python API
|
||
|
||
23.2.2.18 Threads In Python
|
||
...........................
|
||
|
||
Python scripts can access information about, and manipulate inferior
|
||
threads controlled by GDB, via objects of the 'gdb.InferiorThread'
|
||
class.
|
||
|
||
The following thread-related functions are available in the 'gdb'
|
||
module:
|
||
|
||
-- Function: gdb.selected_thread ()
|
||
This function returns the thread object for the selected thread.
|
||
If there is no selected thread, this will return 'None'.
|
||
|
||
To get the list of threads for an inferior, use the
|
||
'Inferior.threads()' method. *Note Inferiors In Python::
|
||
|
||
A 'gdb.InferiorThread' object has the following attributes:
|
||
|
||
-- Variable: InferiorThread.name
|
||
The name of the thread. If the user specified a name using 'thread
|
||
name', then this returns that name. Otherwise, if an OS-supplied
|
||
name is available, then it is returned. Otherwise, this returns
|
||
'None'.
|
||
|
||
This attribute can be assigned to. The new value must be a string
|
||
object, which sets the new name, or 'None', which removes any
|
||
user-specified thread name.
|
||
|
||
-- Variable: InferiorThread.num
|
||
The per-inferior number of the thread, as assigned by GDB.
|
||
|
||
-- Variable: InferiorThread.global_num
|
||
The global ID of the thread, as assigned by GDB. You can use this
|
||
to make Python breakpoints thread-specific, for example (*note The
|
||
Breakpoint.thread attribute: python_breakpoint_thread.).
|
||
|
||
-- Variable: InferiorThread.ptid
|
||
ID of the thread, as assigned by the operating system. This
|
||
attribute is a tuple containing three integers. The first is the
|
||
Process ID (PID); the second is the Lightweight Process ID (LWPID),
|
||
and the third is the Thread ID (TID). Either the LWPID or TID may
|
||
be 0, which indicates that the operating system does not use that
|
||
identifier.
|
||
|
||
-- Variable: InferiorThread.inferior
|
||
The inferior this thread belongs to. This attribute is represented
|
||
as a 'gdb.Inferior' object. This attribute is not writable.
|
||
|
||
A 'gdb.InferiorThread' object has the following methods:
|
||
|
||
-- Function: InferiorThread.is_valid ()
|
||
Returns 'True' if the 'gdb.InferiorThread' object is valid, 'False'
|
||
if not. A 'gdb.InferiorThread' object will become invalid if the
|
||
thread exits, or the inferior that the thread belongs is deleted.
|
||
All other 'gdb.InferiorThread' methods will throw an exception if
|
||
it is invalid at the time the method is called.
|
||
|
||
-- Function: InferiorThread.switch ()
|
||
This changes GDB's currently selected thread to the one represented
|
||
by this object.
|
||
|
||
-- Function: InferiorThread.is_stopped ()
|
||
Return a Boolean indicating whether the thread is stopped.
|
||
|
||
-- Function: InferiorThread.is_running ()
|
||
Return a Boolean indicating whether the thread is running.
|
||
|
||
-- Function: InferiorThread.is_exited ()
|
||
Return a Boolean indicating whether the thread is exited.
|
||
|
||
-- Function: InferiorThread.handle ()
|
||
Return the thread object's handle, represented as a Python 'bytes'
|
||
object. A 'gdb.Value' representation of the handle may be
|
||
constructed via 'gdb.Value(bufobj, type)' where BUFOBJ is the
|
||
Python 'bytes' representation of the handle and TYPE is a
|
||
'gdb.Type' for the handle type.
|
||
|
||
|
||
File: gdb.info, Node: Recordings In Python, Next: Commands In Python, Prev: Threads In Python, Up: Python API
|
||
|
||
23.2.2.19 Recordings In Python
|
||
..............................
|
||
|
||
The following recordings-related functions (*note Process Record and
|
||
Replay::) are available in the 'gdb' module:
|
||
|
||
-- Function: gdb.start_recording ([method], [format])
|
||
Start a recording using the given METHOD and FORMAT. If no FORMAT
|
||
is given, the default format for the recording method is used. If
|
||
no METHOD is given, the default method will be used. Returns a
|
||
'gdb.Record' object on success. Throw an exception on failure.
|
||
|
||
The following strings can be passed as METHOD:
|
||
|
||
* '"full"'
|
||
* '"btrace"': Possible values for FORMAT: '"pt"', '"bts"' or
|
||
leave out for default format.
|
||
|
||
-- Function: gdb.current_recording ()
|
||
Access a currently running recording. Return a 'gdb.Record' object
|
||
on success. Return 'None' if no recording is currently active.
|
||
|
||
-- Function: gdb.stop_recording ()
|
||
Stop the current recording. Throw an exception if no recording is
|
||
currently active. All record objects become invalid after this
|
||
call.
|
||
|
||
A 'gdb.Record' object has the following attributes:
|
||
|
||
-- Variable: Record.method
|
||
A string with the current recording method, e.g. 'full' or
|
||
'btrace'.
|
||
|
||
-- Variable: Record.format
|
||
A string with the current recording format, e.g. 'bt', 'pts' or
|
||
'None'.
|
||
|
||
-- Variable: Record.begin
|
||
A method specific instruction object representing the first
|
||
instruction in this recording.
|
||
|
||
-- Variable: Record.end
|
||
A method specific instruction object representing the current
|
||
instruction, that is not actually part of the recording.
|
||
|
||
-- Variable: Record.replay_position
|
||
The instruction representing the current replay position. If there
|
||
is no replay active, this will be 'None'.
|
||
|
||
-- Variable: Record.instruction_history
|
||
A list with all recorded instructions.
|
||
|
||
-- Variable: Record.function_call_history
|
||
A list with all recorded function call segments.
|
||
|
||
A 'gdb.Record' object has the following methods:
|
||
|
||
-- Function: Record.goto (instruction)
|
||
Move the replay position to the given INSTRUCTION.
|
||
|
||
The common 'gdb.Instruction' class that recording method specific
|
||
instruction objects inherit from, has the following attributes:
|
||
|
||
-- Variable: Instruction.pc
|
||
An integer representing this instruction's address.
|
||
|
||
-- Variable: Instruction.data
|
||
A buffer with the raw instruction data. In Python 3, the return
|
||
value is a 'memoryview' object.
|
||
|
||
-- Variable: Instruction.decoded
|
||
A human readable string with the disassembled instruction.
|
||
|
||
-- Variable: Instruction.size
|
||
The size of the instruction in bytes.
|
||
|
||
Additionally 'gdb.RecordInstruction' has the following attributes:
|
||
|
||
-- Variable: RecordInstruction.number
|
||
An integer identifying this instruction. 'number' corresponds to
|
||
the numbers seen in 'record instruction-history' (*note Process
|
||
Record and Replay::).
|
||
|
||
-- Variable: RecordInstruction.sal
|
||
A 'gdb.Symtab_and_line' object representing the associated symtab
|
||
and line of this instruction. May be 'None' if no debug
|
||
information is available.
|
||
|
||
-- Variable: RecordInstruction.is_speculative
|
||
A boolean indicating whether the instruction was executed
|
||
speculatively.
|
||
|
||
If an error occured during recording or decoding a recording, this
|
||
error is represented by a 'gdb.RecordGap' object in the instruction
|
||
list. It has the following attributes:
|
||
|
||
-- Variable: RecordGap.number
|
||
An integer identifying this gap. 'number' corresponds to the
|
||
numbers seen in 'record instruction-history' (*note Process Record
|
||
and Replay::).
|
||
|
||
-- Variable: RecordGap.error_code
|
||
A numerical representation of the reason for the gap. The value is
|
||
specific to the current recording method.
|
||
|
||
-- Variable: RecordGap.error_string
|
||
A human readable string with the reason for the gap.
|
||
|
||
A 'gdb.RecordFunctionSegment' object has the following attributes:
|
||
|
||
-- Variable: RecordFunctionSegment.number
|
||
An integer identifying this function segment. 'number' corresponds
|
||
to the numbers seen in 'record function-call-history' (*note
|
||
Process Record and Replay::).
|
||
|
||
-- Variable: RecordFunctionSegment.symbol
|
||
A 'gdb.Symbol' object representing the associated symbol. May be
|
||
'None' if no debug information is available.
|
||
|
||
-- Variable: RecordFunctionSegment.level
|
||
An integer representing the function call's stack level. May be
|
||
'None' if the function call is a gap.
|
||
|
||
-- Variable: RecordFunctionSegment.instructions
|
||
A list of 'gdb.RecordInstruction' or 'gdb.RecordGap' objects
|
||
associated with this function call.
|
||
|
||
-- Variable: RecordFunctionSegment.up
|
||
A 'gdb.RecordFunctionSegment' object representing the caller's
|
||
function segment. If the call has not been recorded, this will be
|
||
the function segment to which control returns. If neither the call
|
||
nor the return have been recorded, this will be 'None'.
|
||
|
||
-- Variable: RecordFunctionSegment.prev
|
||
A 'gdb.RecordFunctionSegment' object representing the previous
|
||
segment of this function call. May be 'None'.
|
||
|
||
-- Variable: RecordFunctionSegment.next
|
||
A 'gdb.RecordFunctionSegment' object representing the next segment
|
||
of this function call. May be 'None'.
|
||
|
||
The following example demonstrates the usage of these objects and
|
||
functions to create a function that will rewind a record to the last
|
||
time a function in a different file was executed. This would typically
|
||
be used to track the execution of user provided callback functions in a
|
||
library which typically are not visible in a back trace.
|
||
|
||
def bringback ():
|
||
rec = gdb.current_recording ()
|
||
if not rec:
|
||
return
|
||
|
||
insn = rec.instruction_history
|
||
if len (insn) == 0:
|
||
return
|
||
|
||
try:
|
||
position = insn.index (rec.replay_position)
|
||
except:
|
||
position = -1
|
||
try:
|
||
filename = insn[position].sal.symtab.fullname ()
|
||
except:
|
||
filename = None
|
||
|
||
for i in reversed (insn[:position]):
|
||
try:
|
||
current = i.sal.symtab.fullname ()
|
||
except:
|
||
current = None
|
||
|
||
if filename == current:
|
||
continue
|
||
|
||
rec.goto (i)
|
||
return
|
||
|
||
Another possible application is to write a function that counts the
|
||
number of code executions in a given line range. This line range can
|
||
contain parts of functions or span across several functions and is not
|
||
limited to be contiguous.
|
||
|
||
def countrange (filename, linerange):
|
||
count = 0
|
||
|
||
def filter_only (file_name):
|
||
for call in gdb.current_recording ().function_call_history:
|
||
try:
|
||
if file_name in call.symbol.symtab.fullname ():
|
||
yield call
|
||
except:
|
||
pass
|
||
|
||
for c in filter_only (filename):
|
||
for i in c.instructions:
|
||
try:
|
||
if i.sal.line in linerange:
|
||
count += 1
|
||
break;
|
||
except:
|
||
pass
|
||
|
||
return count
|
||
|
||
|
||
File: gdb.info, Node: Commands In Python, Next: Parameters In Python, Prev: Recordings In Python, Up: Python API
|
||
|
||
23.2.2.20 Commands In Python
|
||
............................
|
||
|
||
You can implement new GDB CLI commands in Python. A CLI command is
|
||
implemented using an instance of the 'gdb.Command' class, most commonly
|
||
using a subclass.
|
||
|
||
-- Function: Command.__init__ (name, COMMAND_CLASS [, COMPLETER_CLASS
|
||
[, PREFIX]])
|
||
The object initializer for 'Command' registers the new command with
|
||
GDB. This initializer is normally invoked from the subclass' own
|
||
'__init__' method.
|
||
|
||
NAME is the name of the command. If NAME consists of multiple
|
||
words, then the initial words are looked for as prefix commands.
|
||
In this case, if one of the prefix commands does not exist, an
|
||
exception is raised.
|
||
|
||
There is no support for multi-line commands.
|
||
|
||
COMMAND_CLASS should be one of the 'COMMAND_' constants defined
|
||
below. This argument tells GDB how to categorize the new command
|
||
in the help system.
|
||
|
||
COMPLETER_CLASS is an optional argument. If given, it should be
|
||
one of the 'COMPLETE_' constants defined below. This argument
|
||
tells GDB how to perform completion for this command. If not
|
||
given, GDB will attempt to complete using the object's 'complete'
|
||
method (see below); if no such method is found, an error will occur
|
||
when completion is attempted.
|
||
|
||
PREFIX is an optional argument. If 'True', then the new command is
|
||
a prefix command; sub-commands of this command may be registered.
|
||
|
||
The help text for the new command is taken from the Python
|
||
documentation string for the command's class, if there is one. If
|
||
no documentation string is provided, the default value "This
|
||
command is not documented." is used.
|
||
|
||
-- Function: Command.dont_repeat ()
|
||
By default, a GDB command is repeated when the user enters a blank
|
||
line at the command prompt. A command can suppress this behavior
|
||
by invoking the 'dont_repeat' method. This is similar to the user
|
||
command 'dont-repeat', see *note dont-repeat: Define.
|
||
|
||
-- Function: Command.invoke (argument, from_tty)
|
||
This method is called by GDB when this command is invoked.
|
||
|
||
ARGUMENT is a string. It is the argument to the command, after
|
||
leading and trailing whitespace has been stripped.
|
||
|
||
FROM_TTY is a boolean argument. When true, this means that the
|
||
command was entered by the user at the terminal; when false it
|
||
means that the command came from elsewhere.
|
||
|
||
If this method throws an exception, it is turned into a GDB 'error'
|
||
call. Otherwise, the return value is ignored.
|
||
|
||
To break ARGUMENT up into an argv-like string use
|
||
'gdb.string_to_argv'. This function behaves identically to GDB's
|
||
internal argument lexer 'buildargv'. It is recommended to use this
|
||
for consistency. Arguments are separated by spaces and may be
|
||
quoted. Example:
|
||
|
||
print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"")
|
||
['1', '2 "3', '4 "5', "6 '7"]
|
||
|
||
-- Function: Command.complete (text, word)
|
||
This method is called by GDB when the user attempts completion on
|
||
this command. All forms of completion are handled by this method,
|
||
that is, the <TAB> and <M-?> key bindings (*note Completion::), and
|
||
the 'complete' command (*note complete: Help.).
|
||
|
||
The arguments TEXT and WORD are both strings; TEXT holds the
|
||
complete command line up to the cursor's location, while WORD holds
|
||
the last word of the command line; this is computed using a
|
||
word-breaking heuristic.
|
||
|
||
The 'complete' method can return several values:
|
||
* If the return value is a sequence, the contents of the
|
||
sequence are used as the completions. It is up to 'complete'
|
||
to ensure that the contents actually do complete the word. A
|
||
zero-length sequence is allowed, it means that there were no
|
||
completions available. Only string elements of the sequence
|
||
are used; other elements in the sequence are ignored.
|
||
|
||
* If the return value is one of the 'COMPLETE_' constants
|
||
defined below, then the corresponding GDB-internal completion
|
||
function is invoked, and its result is used.
|
||
|
||
* All other results are treated as though there were no
|
||
available completions.
|
||
|
||
When a new command is registered, it must be declared as a member of
|
||
some general class of commands. This is used to classify top-level
|
||
commands in the on-line help system; note that prefix commands are not
|
||
listed under their own category but rather that of their top-level
|
||
command. The available classifications are represented by constants
|
||
defined in the 'gdb' module:
|
||
|
||
'gdb.COMMAND_NONE'
|
||
The command does not belong to any particular class. A command in
|
||
this category will not be displayed in any of the help categories.
|
||
|
||
'gdb.COMMAND_RUNNING'
|
||
The command is related to running the inferior. For example,
|
||
'start', 'step', and 'continue' are in this category. Type 'help
|
||
running' at the GDB prompt to see a list of commands in this
|
||
category.
|
||
|
||
'gdb.COMMAND_DATA'
|
||
The command is related to data or variables. For example, 'call',
|
||
'find', and 'print' are in this category. Type 'help data' at the
|
||
GDB prompt to see a list of commands in this category.
|
||
|
||
'gdb.COMMAND_STACK'
|
||
The command has to do with manipulation of the stack. For example,
|
||
'backtrace', 'frame', and 'return' are in this category. Type
|
||
'help stack' at the GDB prompt to see a list of commands in this
|
||
category.
|
||
|
||
'gdb.COMMAND_FILES'
|
||
This class is used for file-related commands. For example, 'file',
|
||
'list' and 'section' are in this category. Type 'help files' at
|
||
the GDB prompt to see a list of commands in this category.
|
||
|
||
'gdb.COMMAND_SUPPORT'
|
||
This should be used for "support facilities", generally meaning
|
||
things that are useful to the user when interacting with GDB, but
|
||
not related to the state of the inferior. For example, 'help',
|
||
'make', and 'shell' are in this category. Type 'help support' at
|
||
the GDB prompt to see a list of commands in this category.
|
||
|
||
'gdb.COMMAND_STATUS'
|
||
The command is an 'info'-related command, that is, related to the
|
||
state of GDB itself. For example, 'info', 'macro', and 'show' are
|
||
in this category. Type 'help status' at the GDB prompt to see a
|
||
list of commands in this category.
|
||
|
||
'gdb.COMMAND_BREAKPOINTS'
|
||
The command has to do with breakpoints. For example, 'break',
|
||
'clear', and 'delete' are in this category. Type 'help
|
||
breakpoints' at the GDB prompt to see a list of commands in this
|
||
category.
|
||
|
||
'gdb.COMMAND_TRACEPOINTS'
|
||
The command has to do with tracepoints. For example, 'trace',
|
||
'actions', and 'tfind' are in this category. Type 'help
|
||
tracepoints' at the GDB prompt to see a list of commands in this
|
||
category.
|
||
|
||
'gdb.COMMAND_USER'
|
||
The command is a general purpose command for the user, and
|
||
typically does not fit in one of the other categories. Type 'help
|
||
user-defined' at the GDB prompt to see a list of commands in this
|
||
category, as well as the list of gdb macros (*note Sequences::).
|
||
|
||
'gdb.COMMAND_OBSCURE'
|
||
The command is only used in unusual circumstances, or is not of
|
||
general interest to users. For example, 'checkpoint', 'fork', and
|
||
'stop' are in this category. Type 'help obscure' at the GDB prompt
|
||
to see a list of commands in this category.
|
||
|
||
'gdb.COMMAND_MAINTENANCE'
|
||
The command is only useful to GDB maintainers. The 'maintenance'
|
||
and 'flushregs' commands are in this category. Type 'help
|
||
internals' at the GDB prompt to see a list of commands in this
|
||
category.
|
||
|
||
A new command can use a predefined completion function, either by
|
||
specifying it via an argument at initialization, or by returning it from
|
||
the 'complete' method. These predefined completion constants are all
|
||
defined in the 'gdb' module:
|
||
|
||
'gdb.COMPLETE_NONE'
|
||
This constant means that no completion should be done.
|
||
|
||
'gdb.COMPLETE_FILENAME'
|
||
This constant means that filename completion should be performed.
|
||
|
||
'gdb.COMPLETE_LOCATION'
|
||
This constant means that location completion should be done. *Note
|
||
Specify Location::.
|
||
|
||
'gdb.COMPLETE_COMMAND'
|
||
This constant means that completion should examine GDB command
|
||
names.
|
||
|
||
'gdb.COMPLETE_SYMBOL'
|
||
This constant means that completion should be done using symbol
|
||
names as the source.
|
||
|
||
'gdb.COMPLETE_EXPRESSION'
|
||
This constant means that completion should be done on expressions.
|
||
Often this means completing on symbol names, but some language
|
||
parsers also have support for completing on field names.
|
||
|
||
The following code snippet shows how a trivial CLI command can be
|
||
implemented in Python:
|
||
|
||
class HelloWorld (gdb.Command):
|
||
"""Greet the whole world."""
|
||
|
||
def __init__ (self):
|
||
super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
|
||
|
||
def invoke (self, arg, from_tty):
|
||
print "Hello, World!"
|
||
|
||
HelloWorld ()
|
||
|
||
The last line instantiates the class, and is necessary to trigger the
|
||
registration of the command with GDB. Depending on how the Python code
|
||
is read into GDB, you may need to import the 'gdb' module explicitly.
|
||
|
||
|
||
File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: Commands In Python, Up: Python API
|
||
|
||
23.2.2.21 Parameters In Python
|
||
..............................
|
||
|
||
You can implement new GDB parameters using Python. A new parameter is
|
||
implemented as an instance of the 'gdb.Parameter' class.
|
||
|
||
Parameters are exposed to the user via the 'set' and 'show' commands.
|
||
*Note Help::.
|
||
|
||
There are many parameters that already exist and can be set in GDB.
|
||
Two examples are: 'set follow fork' and 'set charset'. Setting these
|
||
parameters influences certain behavior in GDB. Similarly, you can
|
||
define parameters that can be used to influence behavior in custom
|
||
Python scripts and commands.
|
||
|
||
-- Function: Parameter.__init__ (name, COMMAND-CLASS, PARAMETER-CLASS
|
||
[, ENUM-SEQUENCE])
|
||
The object initializer for 'Parameter' registers the new parameter
|
||
with GDB. This initializer is normally invoked from the subclass'
|
||
own '__init__' method.
|
||
|
||
NAME is the name of the new parameter. If NAME consists of
|
||
multiple words, then the initial words are looked for as prefix
|
||
parameters. An example of this can be illustrated with the 'set
|
||
print' set of parameters. If NAME is 'print foo', then 'print'
|
||
will be searched as the prefix parameter. In this case the
|
||
parameter can subsequently be accessed in GDB as 'set print foo'.
|
||
|
||
If NAME consists of multiple words, and no prefix parameter group
|
||
can be found, an exception is raised.
|
||
|
||
COMMAND-CLASS should be one of the 'COMMAND_' constants (*note
|
||
Commands In Python::). This argument tells GDB how to categorize
|
||
the new parameter in the help system.
|
||
|
||
PARAMETER-CLASS should be one of the 'PARAM_' constants defined
|
||
below. This argument tells GDB the type of the new parameter; this
|
||
information is used for input validation and completion.
|
||
|
||
If PARAMETER-CLASS is 'PARAM_ENUM', then ENUM-SEQUENCE must be a
|
||
sequence of strings. These strings represent the possible values
|
||
for the parameter.
|
||
|
||
If PARAMETER-CLASS is not 'PARAM_ENUM', then the presence of a
|
||
fourth argument will cause an exception to be thrown.
|
||
|
||
The help text for the new parameter is taken from the Python
|
||
documentation string for the parameter's class, if there is one.
|
||
If there is no documentation string, a default value is used.
|
||
|
||
-- Variable: Parameter.set_doc
|
||
If this attribute exists, and is a string, then its value is used
|
||
as the help text for this parameter's 'set' command. The value is
|
||
examined when 'Parameter.__init__' is invoked; subsequent changes
|
||
have no effect.
|
||
|
||
-- Variable: Parameter.show_doc
|
||
If this attribute exists, and is a string, then its value is used
|
||
as the help text for this parameter's 'show' command. The value is
|
||
examined when 'Parameter.__init__' is invoked; subsequent changes
|
||
have no effect.
|
||
|
||
-- Variable: Parameter.value
|
||
The 'value' attribute holds the underlying value of the parameter.
|
||
It can be read and assigned to just as any other attribute. GDB
|
||
does validation when assignments are made.
|
||
|
||
There are two methods that may be implemented in any 'Parameter'
|
||
class. These are:
|
||
|
||
-- Function: Parameter.get_set_string (self)
|
||
If this method exists, GDB will call it when a PARAMETER's value
|
||
has been changed via the 'set' API (for example, 'set foo off').
|
||
The 'value' attribute has already been populated with the new value
|
||
and may be used in output. This method must return a string. If
|
||
the returned string is not empty, GDB will present it to the user.
|
||
|
||
If this method raises the 'gdb.GdbError' exception (*note Exception
|
||
Handling::), then GDB will print the exception's string and the
|
||
'set' command will fail. Note, however, that the 'value' attribute
|
||
will not be reset in this case. So, if your parameter must
|
||
validate values, it should store the old value internally and reset
|
||
the exposed value, like so:
|
||
|
||
class ExampleParam (gdb.Parameter):
|
||
def __init__ (self, name):
|
||
super (ExampleParam, self).__init__ (name,
|
||
gdb.COMMAND_DATA,
|
||
gdb.PARAM_BOOLEAN)
|
||
self.value = True
|
||
self.saved_value = True
|
||
def validate(self):
|
||
return False
|
||
def get_set_string (self):
|
||
if not self.validate():
|
||
self.value = self.saved_value
|
||
raise gdb.GdbError('Failed to validate')
|
||
self.saved_value = self.value
|
||
|
||
-- Function: Parameter.get_show_string (self, svalue)
|
||
GDB will call this method when a PARAMETER's 'show' API has been
|
||
invoked (for example, 'show foo'). The argument 'svalue' receives
|
||
the string representation of the current value. This method must
|
||
return a string.
|
||
|
||
When a new parameter is defined, its type must be specified. The
|
||
available types are represented by constants defined in the 'gdb'
|
||
module:
|
||
|
||
'gdb.PARAM_BOOLEAN'
|
||
The value is a plain boolean. The Python boolean values, 'True'
|
||
and 'False' are the only valid values.
|
||
|
||
'gdb.PARAM_AUTO_BOOLEAN'
|
||
The value has three possible states: true, false, and 'auto'. In
|
||
Python, true and false are represented using boolean constants, and
|
||
'auto' is represented using 'None'.
|
||
|
||
'gdb.PARAM_UINTEGER'
|
||
The value is an unsigned integer. The value of 0 should be
|
||
interpreted to mean "unlimited".
|
||
|
||
'gdb.PARAM_INTEGER'
|
||
The value is a signed integer. The value of 0 should be
|
||
interpreted to mean "unlimited".
|
||
|
||
'gdb.PARAM_STRING'
|
||
The value is a string. When the user modifies the string, any
|
||
escape sequences, such as '\t', '\f', and octal escapes, are
|
||
translated into corresponding characters and encoded into the
|
||
current host charset.
|
||
|
||
'gdb.PARAM_STRING_NOESCAPE'
|
||
The value is a string. When the user modifies the string, escapes
|
||
are passed through untranslated.
|
||
|
||
'gdb.PARAM_OPTIONAL_FILENAME'
|
||
The value is a either a filename (a string), or 'None'.
|
||
|
||
'gdb.PARAM_FILENAME'
|
||
The value is a filename. This is just like
|
||
'PARAM_STRING_NOESCAPE', but uses file names for completion.
|
||
|
||
'gdb.PARAM_ZINTEGER'
|
||
The value is an integer. This is like 'PARAM_INTEGER', except 0 is
|
||
interpreted as itself.
|
||
|
||
'gdb.PARAM_ZUINTEGER'
|
||
The value is an unsigned integer. This is like 'PARAM_INTEGER',
|
||
except 0 is interpreted as itself, and the value cannot be
|
||
negative.
|
||
|
||
'gdb.PARAM_ZUINTEGER_UNLIMITED'
|
||
The value is a signed integer. This is like 'PARAM_ZUINTEGER',
|
||
except the special value -1 should be interpreted to mean
|
||
"unlimited". Other negative values are not allowed.
|
||
|
||
'gdb.PARAM_ENUM'
|
||
The value is a string, which must be one of a collection string
|
||
constants provided when the parameter is created.
|
||
|
||
|
||
File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API
|
||
|
||
23.2.2.22 Writing new convenience functions
|
||
...........................................
|
||
|
||
You can implement new convenience functions (*note Convenience Vars::)
|
||
in Python. A convenience function is an instance of a subclass of the
|
||
class 'gdb.Function'.
|
||
|
||
-- Function: Function.__init__ (name)
|
||
The initializer for 'Function' registers the new function with GDB.
|
||
The argument NAME is the name of the function, a string. The
|
||
function will be visible to the user as a convenience variable of
|
||
type 'internal function', whose name is the same as the given NAME.
|
||
|
||
The documentation for the new function is taken from the
|
||
documentation string for the new class.
|
||
|
||
-- Function: Function.invoke (*ARGS)
|
||
When a convenience function is evaluated, its arguments are
|
||
converted to instances of 'gdb.Value', and then the function's
|
||
'invoke' method is called. Note that GDB does not predetermine the
|
||
arity of convenience functions. Instead, all available arguments
|
||
are passed to 'invoke', following the standard Python calling
|
||
convention. In particular, a convenience function can have default
|
||
values for parameters without ill effect.
|
||
|
||
The return value of this method is used as its value in the
|
||
enclosing expression. If an ordinary Python value is returned, it
|
||
is converted to a 'gdb.Value' following the usual rules.
|
||
|
||
The following code snippet shows how a trivial convenience function
|
||
can be implemented in Python:
|
||
|
||
class Greet (gdb.Function):
|
||
"""Return string to greet someone.
|
||
Takes a name as argument."""
|
||
|
||
def __init__ (self):
|
||
super (Greet, self).__init__ ("greet")
|
||
|
||
def invoke (self, name):
|
||
return "Hello, %s!" % name.string ()
|
||
|
||
Greet ()
|
||
|
||
The last line instantiates the class, and is necessary to trigger the
|
||
registration of the function with GDB. Depending on how the Python code
|
||
is read into GDB, you may need to import the 'gdb' module explicitly.
|
||
|
||
Now you can use the function in an expression:
|
||
|
||
(gdb) print $greet("Bob")
|
||
$1 = "Hello, Bob!"
|
||
|
||
|
||
File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API
|
||
|
||
23.2.2.23 Program Spaces In Python
|
||
..................................
|
||
|
||
A program space, or "progspace", represents a symbolic view of an
|
||
address space. It consists of all of the objfiles of the program.
|
||
*Note Objfiles In Python::. *Note program spaces: Inferiors and
|
||
Programs, for more details about program spaces.
|
||
|
||
The following progspace-related functions are available in the 'gdb'
|
||
module:
|
||
|
||
-- Function: gdb.current_progspace ()
|
||
This function returns the program space of the currently selected
|
||
inferior. *Note Inferiors and Programs::. This is identical to
|
||
'gdb.selected_inferior().progspace' (*note Inferiors In Python::)
|
||
and is included for historical compatibility.
|
||
|
||
-- Function: gdb.progspaces ()
|
||
Return a sequence of all the progspaces currently known to GDB.
|
||
|
||
Each progspace is represented by an instance of the 'gdb.Progspace'
|
||
class.
|
||
|
||
-- Variable: Progspace.filename
|
||
The file name of the progspace as a string.
|
||
|
||
-- Variable: Progspace.pretty_printers
|
||
The 'pretty_printers' attribute is a list of functions. It is used
|
||
to look up pretty-printers. A 'Value' is passed to each function
|
||
in order; if the function returns 'None', then the search
|
||
continues. Otherwise, the return value should be an object which
|
||
is used to format the value. *Note Pretty Printing API::, for more
|
||
information.
|
||
|
||
-- Variable: Progspace.type_printers
|
||
The 'type_printers' attribute is a list of type printer objects.
|
||
*Note Type Printing API::, for more information.
|
||
|
||
-- Variable: Progspace.frame_filters
|
||
The 'frame_filters' attribute is a dictionary of frame filter
|
||
objects. *Note Frame Filter API::, for more information.
|
||
|
||
A program space has the following methods:
|
||
|
||
-- Function: Progspace.block_for_pc (pc)
|
||
Return the innermost 'gdb.Block' containing the given PC value. If
|
||
the block cannot be found for the PC value specified, the function
|
||
will return 'None'.
|
||
|
||
-- Function: Progspace.find_pc_line (pc)
|
||
Return the 'gdb.Symtab_and_line' object corresponding to the PC
|
||
value. *Note Symbol Tables In Python::. If an invalid value of PC
|
||
is passed as an argument, then the 'symtab' and 'line' attributes
|
||
of the returned 'gdb.Symtab_and_line' object will be 'None' and 0
|
||
respectively.
|
||
|
||
-- Function: Progspace.is_valid ()
|
||
Returns 'True' if the 'gdb.Progspace' object is valid, 'False' if
|
||
not. A 'gdb.Progspace' object can become invalid if the program
|
||
space file it refers to is not referenced by any inferior. All
|
||
other 'gdb.Progspace' methods will throw an exception if it is
|
||
invalid at the time the method is called.
|
||
|
||
-- Function: Progspace.objfiles ()
|
||
Return a sequence of all the objfiles referenced by this program
|
||
space. *Note Objfiles In Python::.
|
||
|
||
-- Function: Progspace.solib_name (address)
|
||
Return the name of the shared library holding the given ADDRESS as
|
||
a string, or 'None'.
|
||
|
||
One may add arbitrary attributes to 'gdb.Progspace' objects in the
|
||
usual Python way. This is useful if, for example, one needs to do some
|
||
extra record keeping associated with the program space.
|
||
|
||
In this contrived example, we want to perform some processing when an
|
||
objfile with a certain symbol is loaded, but we only want to do this
|
||
once because it is expensive. To achieve this we record the results
|
||
with the program space because we can't predict when the desired objfile
|
||
will be loaded.
|
||
|
||
(gdb) python
|
||
def clear_objfiles_handler(event):
|
||
event.progspace.expensive_computation = None
|
||
def expensive(symbol):
|
||
"""A mock routine to perform an "expensive" computation on symbol."""
|
||
print "Computing the answer to the ultimate question ..."
|
||
return 42
|
||
def new_objfile_handler(event):
|
||
objfile = event.new_objfile
|
||
progspace = objfile.progspace
|
||
if not hasattr(progspace, 'expensive_computation') or \
|
||
progspace.expensive_computation is None:
|
||
# We use 'main' for the symbol to keep the example simple.
|
||
# Note: There's no current way to constrain the lookup
|
||
# to one objfile.
|
||
symbol = gdb.lookup_global_symbol('main')
|
||
if symbol is not None:
|
||
progspace.expensive_computation = expensive(symbol)
|
||
gdb.events.clear_objfiles.connect(clear_objfiles_handler)
|
||
gdb.events.new_objfile.connect(new_objfile_handler)
|
||
end
|
||
(gdb) file /tmp/hello
|
||
Reading symbols from /tmp/hello...done.
|
||
Computing the answer to the ultimate question ...
|
||
(gdb) python print gdb.current_progspace().expensive_computation
|
||
42
|
||
(gdb) run
|
||
Starting program: /tmp/hello
|
||
Hello.
|
||
[Inferior 1 (process 4242) exited normally]
|
||
|
||
|
||
File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API
|
||
|
||
23.2.2.24 Objfiles In Python
|
||
............................
|
||
|
||
GDB loads symbols for an inferior from various symbol-containing files
|
||
(*note Files::). These include the primary executable file, any shared
|
||
libraries used by the inferior, and any separate debug info files (*note
|
||
Separate Debug Files::). GDB calls these symbol-containing files
|
||
"objfiles".
|
||
|
||
The following objfile-related functions are available in the 'gdb'
|
||
module:
|
||
|
||
-- Function: gdb.current_objfile ()
|
||
When auto-loading a Python script (*note Python Auto-loading::),
|
||
GDB sets the "current objfile" to the corresponding objfile. This
|
||
function returns the current objfile. If there is no current
|
||
objfile, this function returns 'None'.
|
||
|
||
-- Function: gdb.objfiles ()
|
||
Return a sequence of objfiles referenced by the current program
|
||
space. *Note Objfiles In Python::, and *note Progspaces In
|
||
Python::. This is identical to
|
||
'gdb.selected_inferior().progspace.objfiles()' and is included for
|
||
historical compatibility.
|
||
|
||
-- Function: gdb.lookup_objfile (name [, by_build_id])
|
||
Look up NAME, a file name or build ID, in the list of objfiles for
|
||
the current program space (*note Progspaces In Python::). If the
|
||
objfile is not found throw the Python 'ValueError' exception.
|
||
|
||
If NAME is a relative file name, then it will match any source file
|
||
name with the same trailing components. For example, if NAME is
|
||
'gcc/expr.c', then it will match source file name of
|
||
'/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or
|
||
'/build/trunk/gcc/x-expr.c'.
|
||
|
||
If BY_BUILD_ID is provided and is 'True' then NAME is the build ID
|
||
of the objfile. Otherwise, NAME is a file name. This is supported
|
||
only on some operating systems, notably those which use the ELF
|
||
format for binary files and the GNU Binutils. For more details
|
||
about this feature, see the description of the '--build-id'
|
||
command-line option in *note Command Line Options: (ld)Options.
|
||
|
||
Each objfile is represented by an instance of the 'gdb.Objfile'
|
||
class.
|
||
|
||
-- Variable: Objfile.filename
|
||
The file name of the objfile as a string, with symbolic links
|
||
resolved.
|
||
|
||
The value is 'None' if the objfile is no longer valid. See the
|
||
'gdb.Objfile.is_valid' method, described below.
|
||
|
||
-- Variable: Objfile.username
|
||
The file name of the objfile as specified by the user as a string.
|
||
|
||
The value is 'None' if the objfile is no longer valid. See the
|
||
'gdb.Objfile.is_valid' method, described below.
|
||
|
||
-- Variable: Objfile.owner
|
||
For separate debug info objfiles this is the corresponding
|
||
'gdb.Objfile' object that debug info is being provided for.
|
||
Otherwise this is 'None'. Separate debug info objfiles are added
|
||
with the 'gdb.Objfile.add_separate_debug_file' method, described
|
||
below.
|
||
|
||
-- Variable: Objfile.build_id
|
||
The build ID of the objfile as a string. If the objfile does not
|
||
have a build ID then the value is 'None'.
|
||
|
||
This is supported only on some operating systems, notably those
|
||
which use the ELF format for binary files and the GNU Binutils.
|
||
For more details about this feature, see the description of the
|
||
'--build-id' command-line option in *note Command Line Options:
|
||
(ld)Options.
|
||
|
||
-- Variable: Objfile.progspace
|
||
The containing program space of the objfile as a 'gdb.Progspace'
|
||
object. *Note Progspaces In Python::.
|
||
|
||
-- Variable: Objfile.pretty_printers
|
||
The 'pretty_printers' attribute is a list of functions. It is used
|
||
to look up pretty-printers. A 'Value' is passed to each function
|
||
in order; if the function returns 'None', then the search
|
||
continues. Otherwise, the return value should be an object which
|
||
is used to format the value. *Note Pretty Printing API::, for more
|
||
information.
|
||
|
||
-- Variable: Objfile.type_printers
|
||
The 'type_printers' attribute is a list of type printer objects.
|
||
*Note Type Printing API::, for more information.
|
||
|
||
-- Variable: Objfile.frame_filters
|
||
The 'frame_filters' attribute is a dictionary of frame filter
|
||
objects. *Note Frame Filter API::, for more information.
|
||
|
||
One may add arbitrary attributes to 'gdb.Objfile' objects in the
|
||
usual Python way. This is useful if, for example, one needs to do some
|
||
extra record keeping associated with the objfile.
|
||
|
||
In this contrived example we record the time when GDB loaded the
|
||
objfile.
|
||
|
||
(gdb) python
|
||
import datetime
|
||
def new_objfile_handler(event):
|
||
# Set the time_loaded attribute of the new objfile.
|
||
event.new_objfile.time_loaded = datetime.datetime.today()
|
||
gdb.events.new_objfile.connect(new_objfile_handler)
|
||
end
|
||
(gdb) file ./hello
|
||
Reading symbols from ./hello...done.
|
||
(gdb) python print gdb.objfiles()[0].time_loaded
|
||
2014-10-09 11:41:36.770345
|
||
|
||
A 'gdb.Objfile' object has the following methods:
|
||
|
||
-- Function: Objfile.is_valid ()
|
||
Returns 'True' if the 'gdb.Objfile' object is valid, 'False' if
|
||
not. A 'gdb.Objfile' object can become invalid if the object file
|
||
it refers to is not loaded in GDB any longer. All other
|
||
'gdb.Objfile' methods will throw an exception if it is invalid at
|
||
the time the method is called.
|
||
|
||
-- Function: Objfile.add_separate_debug_file (file)
|
||
Add FILE to the list of files that GDB will search for debug
|
||
information for the objfile. This is useful when the debug info
|
||
has been removed from the program and stored in a separate file.
|
||
GDB has built-in support for finding separate debug info files
|
||
(*note Separate Debug Files::), but if the file doesn't live in one
|
||
of the standard places that GDB searches then this function can be
|
||
used to add a debug info file from a different place.
|
||
|
||
-- Function: Objfile.lookup_global_symbol (name [, domain])
|
||
Search for a global symbol named NAME in this objfile. Optionally,
|
||
the search scope can be restricted with the DOMAIN argument. The
|
||
DOMAIN argument must be a domain constant defined in the 'gdb'
|
||
module and described in *note Symbols In Python::. This function
|
||
is similar to 'gdb.lookup_global_symbol', except that the search is
|
||
limited to this objfile.
|
||
|
||
The result is a 'gdb.Symbol' object or 'None' if the symbol is not
|
||
found.
|
||
|
||
-- Function: Objfile.lookup_static_symbol (name [, domain])
|
||
Like 'Objfile.lookup_global_symbol', but searches for a global
|
||
symbol with static linkage named NAME in this objfile.
|
||
|
||
|
||
File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API
|
||
|
||
23.2.2.25 Accessing inferior stack frames from Python
|
||
.....................................................
|
||
|
||
When the debugged program stops, GDB is able to analyze its call stack
|
||
(*note Stack frames: Frames.). The 'gdb.Frame' class represents a frame
|
||
in the stack. A 'gdb.Frame' object is only valid while its
|
||
corresponding frame exists in the inferior's stack. If you try to use
|
||
an invalid frame object, GDB will throw a 'gdb.error' exception (*note
|
||
Exception Handling::).
|
||
|
||
Two 'gdb.Frame' objects can be compared for equality with the '=='
|
||
operator, like:
|
||
|
||
(gdb) python print gdb.newest_frame() == gdb.selected_frame ()
|
||
True
|
||
|
||
The following frame-related functions are available in the 'gdb'
|
||
module:
|
||
|
||
-- Function: gdb.selected_frame ()
|
||
Return the selected frame object. (*note Selecting a Frame:
|
||
Selection.).
|
||
|
||
-- Function: gdb.newest_frame ()
|
||
Return the newest frame object for the selected thread.
|
||
|
||
-- Function: gdb.frame_stop_reason_string (reason)
|
||
Return a string explaining the reason why GDB stopped unwinding
|
||
frames, as expressed by the given REASON code (an integer, see the
|
||
'unwind_stop_reason' method further down in this section).
|
||
|
||
-- Function: gdb.invalidate_cached_frames
|
||
GDB internally keeps a cache of the frames that have been unwound.
|
||
This function invalidates this cache.
|
||
|
||
This function should not generally be called by ordinary Python
|
||
code. It is documented for the sake of completeness.
|
||
|
||
A 'gdb.Frame' object has the following methods:
|
||
|
||
-- Function: Frame.is_valid ()
|
||
Returns true if the 'gdb.Frame' object is valid, false if not. A
|
||
frame object can become invalid if the frame it refers to doesn't
|
||
exist anymore in the inferior. All 'gdb.Frame' methods will throw
|
||
an exception if it is invalid at the time the method is called.
|
||
|
||
-- Function: Frame.name ()
|
||
Returns the function name of the frame, or 'None' if it can't be
|
||
obtained.
|
||
|
||
-- Function: Frame.architecture ()
|
||
Returns the 'gdb.Architecture' object corresponding to the frame's
|
||
architecture. *Note Architectures In Python::.
|
||
|
||
-- Function: Frame.type ()
|
||
Returns the type of the frame. The value can be one of:
|
||
'gdb.NORMAL_FRAME'
|
||
An ordinary stack frame.
|
||
|
||
'gdb.DUMMY_FRAME'
|
||
A fake stack frame that was created by GDB when performing an
|
||
inferior function call.
|
||
|
||
'gdb.INLINE_FRAME'
|
||
A frame representing an inlined function. The function was
|
||
inlined into a 'gdb.NORMAL_FRAME' that is older than this one.
|
||
|
||
'gdb.TAILCALL_FRAME'
|
||
A frame representing a tail call. *Note Tail Call Frames::.
|
||
|
||
'gdb.SIGTRAMP_FRAME'
|
||
A signal trampoline frame. This is the frame created by the
|
||
OS when it calls into a signal handler.
|
||
|
||
'gdb.ARCH_FRAME'
|
||
A fake stack frame representing a cross-architecture call.
|
||
|
||
'gdb.SENTINEL_FRAME'
|
||
This is like 'gdb.NORMAL_FRAME', but it is only used for the
|
||
newest frame.
|
||
|
||
-- Function: Frame.unwind_stop_reason ()
|
||
Return an integer representing the reason why it's not possible to
|
||
find more frames toward the outermost frame. Use
|
||
'gdb.frame_stop_reason_string' to convert the value returned by
|
||
this function to a string. The value can be one of:
|
||
|
||
'gdb.FRAME_UNWIND_NO_REASON'
|
||
No particular reason (older frames should be available).
|
||
|
||
'gdb.FRAME_UNWIND_NULL_ID'
|
||
The previous frame's analyzer returns an invalid result. This
|
||
is no longer used by GDB, and is kept only for backward
|
||
compatibility.
|
||
|
||
'gdb.FRAME_UNWIND_OUTERMOST'
|
||
This frame is the outermost.
|
||
|
||
'gdb.FRAME_UNWIND_UNAVAILABLE'
|
||
Cannot unwind further, because that would require knowing the
|
||
values of registers or memory that have not been collected.
|
||
|
||
'gdb.FRAME_UNWIND_INNER_ID'
|
||
This frame ID looks like it ought to belong to a NEXT frame,
|
||
but we got it for a PREV frame. Normally, this is a sign of
|
||
unwinder failure. It could also indicate stack corruption.
|
||
|
||
'gdb.FRAME_UNWIND_SAME_ID'
|
||
This frame has the same ID as the previous one. That means
|
||
that unwinding further would almost certainly give us another
|
||
frame with exactly the same ID, so break the chain. Normally,
|
||
this is a sign of unwinder failure. It could also indicate
|
||
stack corruption.
|
||
|
||
'gdb.FRAME_UNWIND_NO_SAVED_PC'
|
||
The frame unwinder did not find any saved PC, but we needed
|
||
one to unwind further.
|
||
|
||
'gdb.FRAME_UNWIND_MEMORY_ERROR'
|
||
The frame unwinder caused an error while trying to access
|
||
memory.
|
||
|
||
'gdb.FRAME_UNWIND_FIRST_ERROR'
|
||
Any stop reason greater or equal to this value indicates some
|
||
kind of error. This special value facilitates writing code
|
||
that tests for errors in unwinding in a way that will work
|
||
correctly even if the list of the other values is modified in
|
||
future GDB versions. Using it, you could write:
|
||
reason = gdb.selected_frame().unwind_stop_reason ()
|
||
reason_str = gdb.frame_stop_reason_string (reason)
|
||
if reason >= gdb.FRAME_UNWIND_FIRST_ERROR:
|
||
print "An error occured: %s" % reason_str
|
||
|
||
-- Function: Frame.pc ()
|
||
Returns the frame's resume address.
|
||
|
||
-- Function: Frame.block ()
|
||
Return the frame's code block. *Note Blocks In Python::. If the
|
||
frame does not have a block - for example, if there is no debugging
|
||
information for the code in question - then this will throw an
|
||
exception.
|
||
|
||
-- Function: Frame.function ()
|
||
Return the symbol for the function corresponding to this frame.
|
||
*Note Symbols In Python::.
|
||
|
||
-- Function: Frame.older ()
|
||
Return the frame that called this frame.
|
||
|
||
-- Function: Frame.newer ()
|
||
Return the frame called by this frame.
|
||
|
||
-- Function: Frame.find_sal ()
|
||
Return the frame's symtab and line object. *Note Symbol Tables In
|
||
Python::.
|
||
|
||
-- Function: Frame.read_register (register)
|
||
Return the value of REGISTER in this frame. The REGISTER argument
|
||
must be a string (e.g., ''sp'' or ''rax''). Returns a 'Gdb.Value'
|
||
object. Throws an exception if REGISTER does not exist.
|
||
|
||
-- Function: Frame.read_var (variable [, block])
|
||
Return the value of VARIABLE in this frame. If the optional
|
||
argument BLOCK is provided, search for the variable from that
|
||
block; otherwise start at the frame's current block (which is
|
||
determined by the frame's current program counter). The VARIABLE
|
||
argument must be a string or a 'gdb.Symbol' object; BLOCK must be a
|
||
'gdb.Block' object.
|
||
|
||
-- Function: Frame.select ()
|
||
Set this frame to be the selected frame. *Note Examining the
|
||
Stack: Stack.
|
||
|
||
|
||
File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API
|
||
|
||
23.2.2.26 Accessing blocks from Python
|
||
......................................
|
||
|
||
In GDB, symbols are stored in blocks. A block corresponds roughly to a
|
||
scope in the source code. Blocks are organized hierarchically, and are
|
||
represented individually in Python as a 'gdb.Block'. Blocks rely on
|
||
debugging information being available.
|
||
|
||
A frame has a block. Please see *note Frames In Python::, for a more
|
||
in-depth discussion of frames.
|
||
|
||
The outermost block is known as the "global block". The global block
|
||
typically holds public global variables and functions.
|
||
|
||
The block nested just inside the global block is the "static block".
|
||
The static block typically holds file-scoped variables and functions.
|
||
|
||
GDB provides a method to get a block's superblock, but there is
|
||
currently no way to examine the sub-blocks of a block, or to iterate
|
||
over all the blocks in a symbol table (*note Symbol Tables In Python::).
|
||
|
||
Here is a short example that should help explain blocks:
|
||
|
||
/* This is in the global block. */
|
||
int global;
|
||
|
||
/* This is in the static block. */
|
||
static int file_scope;
|
||
|
||
/* 'function' is in the global block, and 'argument' is
|
||
in a block nested inside of 'function'. */
|
||
int function (int argument)
|
||
{
|
||
/* 'local' is in a block inside 'function'. It may or may
|
||
not be in the same block as 'argument'. */
|
||
int local;
|
||
|
||
{
|
||
/* 'inner' is in a block whose superblock is the one holding
|
||
'local'. */
|
||
int inner;
|
||
|
||
/* If this call is expanded by the compiler, you may see
|
||
a nested block here whose function is 'inline_function'
|
||
and whose superblock is the one holding 'inner'. */
|
||
inline_function ();
|
||
}
|
||
}
|
||
|
||
A 'gdb.Block' is iterable. The iterator returns the symbols (*note
|
||
Symbols In Python::) local to the block. Python programs should not
|
||
assume that a specific block object will always contain a given symbol,
|
||
since changes in GDB features and infrastructure may cause symbols move
|
||
across blocks in a symbol table. You can also use Python's "dictionary
|
||
syntax" to access variables in this block, e.g.:
|
||
|
||
symbol = some_block['variable'] # symbol is of type gdb.Symbol
|
||
|
||
The following block-related functions are available in the 'gdb'
|
||
module:
|
||
|
||
-- Function: gdb.block_for_pc (pc)
|
||
Return the innermost 'gdb.Block' containing the given PC value. If
|
||
the block cannot be found for the PC value specified, the function
|
||
will return 'None'. This is identical to
|
||
'gdb.current_progspace().block_for_pc(pc)' and is included for
|
||
historical compatibility.
|
||
|
||
A 'gdb.Block' object has the following methods:
|
||
|
||
-- Function: Block.is_valid ()
|
||
Returns 'True' if the 'gdb.Block' object is valid, 'False' if not.
|
||
A block object can become invalid if the block it refers to doesn't
|
||
exist anymore in the inferior. All other 'gdb.Block' methods will
|
||
throw an exception if it is invalid at the time the method is
|
||
called. The block's validity is also checked during iteration over
|
||
symbols of the block.
|
||
|
||
A 'gdb.Block' object has the following attributes:
|
||
|
||
-- Variable: Block.start
|
||
The start address of the block. This attribute is not writable.
|
||
|
||
-- Variable: Block.end
|
||
One past the last address that appears in the block. This
|
||
attribute is not writable.
|
||
|
||
-- Variable: Block.function
|
||
The name of the block represented as a 'gdb.Symbol'. If the block
|
||
is not named, then this attribute holds 'None'. This attribute is
|
||
not writable.
|
||
|
||
For ordinary function blocks, the superblock is the static block.
|
||
However, you should note that it is possible for a function block
|
||
to have a superblock that is not the static block - for instance
|
||
this happens for an inlined function.
|
||
|
||
-- Variable: Block.superblock
|
||
The block containing this block. If this parent block does not
|
||
exist, this attribute holds 'None'. This attribute is not
|
||
writable.
|
||
|
||
-- Variable: Block.global_block
|
||
The global block associated with this block. This attribute is not
|
||
writable.
|
||
|
||
-- Variable: Block.static_block
|
||
The static block associated with this block. This attribute is not
|
||
writable.
|
||
|
||
-- Variable: Block.is_global
|
||
'True' if the 'gdb.Block' object is a global block, 'False' if not.
|
||
This attribute is not writable.
|
||
|
||
-- Variable: Block.is_static
|
||
'True' if the 'gdb.Block' object is a static block, 'False' if not.
|
||
This attribute is not writable.
|
||
|
||
|
||
File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API
|
||
|
||
23.2.2.27 Python representation of Symbols
|
||
..........................................
|
||
|
||
GDB represents every variable, function and type as an entry in a symbol
|
||
table. *Note Examining the Symbol Table: Symbols. Similarly, Python
|
||
represents these symbols in GDB with the 'gdb.Symbol' object.
|
||
|
||
The following symbol-related functions are available in the 'gdb'
|
||
module:
|
||
|
||
-- Function: gdb.lookup_symbol (name [, block [, domain]])
|
||
This function searches for a symbol by name. The search scope can
|
||
be restricted to the parameters defined in the optional domain and
|
||
block arguments.
|
||
|
||
NAME is the name of the symbol. It must be a string. The optional
|
||
BLOCK argument restricts the search to symbols visible in that
|
||
BLOCK. The BLOCK argument must be a 'gdb.Block' object. If
|
||
omitted, the block for the current frame is used. The optional
|
||
DOMAIN argument restricts the search to the domain type. The
|
||
DOMAIN argument must be a domain constant defined in the 'gdb'
|
||
module and described later in this chapter.
|
||
|
||
The result is a tuple of two elements. The first element is a
|
||
'gdb.Symbol' object or 'None' if the symbol is not found. If the
|
||
symbol is found, the second element is 'True' if the symbol is a
|
||
field of a method's object (e.g., 'this' in C++), otherwise it is
|
||
'False'. If the symbol is not found, the second element is
|
||
'False'.
|
||
|
||
-- Function: gdb.lookup_global_symbol (name [, domain])
|
||
This function searches for a global symbol by name. The search
|
||
scope can be restricted to by the domain argument.
|
||
|
||
NAME is the name of the symbol. It must be a string. The optional
|
||
DOMAIN argument restricts the search to the domain type. The
|
||
DOMAIN argument must be a domain constant defined in the 'gdb'
|
||
module and described later in this chapter.
|
||
|
||
The result is a 'gdb.Symbol' object or 'None' if the symbol is not
|
||
found.
|
||
|
||
-- Function: gdb.lookup_static_symbol (name [, domain])
|
||
This function searches for a global symbol with static linkage by
|
||
name. The search scope can be restricted to by the domain
|
||
argument.
|
||
|
||
NAME is the name of the symbol. It must be a string. The optional
|
||
DOMAIN argument restricts the search to the domain type. The
|
||
DOMAIN argument must be a domain constant defined in the 'gdb'
|
||
module and described later in this chapter.
|
||
|
||
The result is a 'gdb.Symbol' object or 'None' if the symbol is not
|
||
found.
|
||
|
||
Note that this function will not find function-scoped static
|
||
variables. To look up such variables, iterate over the variables
|
||
of the function's 'gdb.Block' and check that 'block.addr_class' is
|
||
'gdb.SYMBOL_LOC_STATIC'.
|
||
|
||
There can be multiple global symbols with static linkage with the
|
||
same name. This function will only return the first matching
|
||
symbol that it finds. Which symbol is found depends on where GDB
|
||
is currently stopped, as GDB will first search for matching symbols
|
||
in the current object file, and then search all other object files.
|
||
If the application is not yet running then GDB will search all
|
||
object files in the order they appear in the debug information.
|
||
|
||
-- Function: gdb.lookup_static_symbols (name [, domain])
|
||
Similar to 'gdb.lookup_static_symbol', this function searches for
|
||
global symbols with static linkage by name, and optionally
|
||
restricted by the domain argument. However, this function returns
|
||
a list of all matching symbols found, not just the first one.
|
||
|
||
NAME is the name of the symbol. It must be a string. The optional
|
||
DOMAIN argument restricts the search to the domain type. The
|
||
DOMAIN argument must be a domain constant defined in the 'gdb'
|
||
module and described later in this chapter.
|
||
|
||
The result is a list of 'gdb.Symbol' objects which could be empty
|
||
if no matching symbols were found.
|
||
|
||
Note that this function will not find function-scoped static
|
||
variables. To look up such variables, iterate over the variables
|
||
of the function's 'gdb.Block' and check that 'block.addr_class' is
|
||
'gdb.SYMBOL_LOC_STATIC'.
|
||
|
||
A 'gdb.Symbol' object has the following attributes:
|
||
|
||
-- Variable: Symbol.type
|
||
The type of the symbol or 'None' if no type is recorded. This
|
||
attribute is represented as a 'gdb.Type' object. *Note Types In
|
||
Python::. This attribute is not writable.
|
||
|
||
-- Variable: Symbol.symtab
|
||
The symbol table in which the symbol appears. This attribute is
|
||
represented as a 'gdb.Symtab' object. *Note Symbol Tables In
|
||
Python::. This attribute is not writable.
|
||
|
||
-- Variable: Symbol.line
|
||
The line number in the source code at which the symbol was defined.
|
||
This is an integer.
|
||
|
||
-- Variable: Symbol.name
|
||
The name of the symbol as a string. This attribute is not
|
||
writable.
|
||
|
||
-- Variable: Symbol.linkage_name
|
||
The name of the symbol, as used by the linker (i.e., may be
|
||
mangled). This attribute is not writable.
|
||
|
||
-- Variable: Symbol.print_name
|
||
The name of the symbol in a form suitable for output. This is
|
||
either 'name' or 'linkage_name', depending on whether the user
|
||
asked GDB to display demangled or mangled names.
|
||
|
||
-- Variable: Symbol.addr_class
|
||
The address class of the symbol. This classifies how to find the
|
||
value of a symbol. Each address class is a constant defined in the
|
||
'gdb' module and described later in this chapter.
|
||
|
||
-- Variable: Symbol.needs_frame
|
||
This is 'True' if evaluating this symbol's value requires a frame
|
||
(*note Frames In Python::) and 'False' otherwise. Typically, local
|
||
variables will require a frame, but other symbols will not.
|
||
|
||
-- Variable: Symbol.is_argument
|
||
'True' if the symbol is an argument of a function.
|
||
|
||
-- Variable: Symbol.is_constant
|
||
'True' if the symbol is a constant.
|
||
|
||
-- Variable: Symbol.is_function
|
||
'True' if the symbol is a function or a method.
|
||
|
||
-- Variable: Symbol.is_variable
|
||
'True' if the symbol is a variable.
|
||
|
||
A 'gdb.Symbol' object has the following methods:
|
||
|
||
-- Function: Symbol.is_valid ()
|
||
Returns 'True' if the 'gdb.Symbol' object is valid, 'False' if not.
|
||
A 'gdb.Symbol' object can become invalid if the symbol it refers to
|
||
does not exist in GDB any longer. All other 'gdb.Symbol' methods
|
||
will throw an exception if it is invalid at the time the method is
|
||
called.
|
||
|
||
-- Function: Symbol.value ([frame])
|
||
Compute the value of the symbol, as a 'gdb.Value'. For functions,
|
||
this computes the address of the function, cast to the appropriate
|
||
type. If the symbol requires a frame in order to compute its
|
||
value, then FRAME must be given. If FRAME is not given, or if
|
||
FRAME is invalid, then this method will throw an exception.
|
||
|
||
The available domain categories in 'gdb.Symbol' are represented as
|
||
constants in the 'gdb' module:
|
||
|
||
'gdb.SYMBOL_UNDEF_DOMAIN'
|
||
This is used when a domain has not been discovered or none of the
|
||
following domains apply. This usually indicates an error either in
|
||
the symbol information or in GDB's handling of symbols.
|
||
|
||
'gdb.SYMBOL_VAR_DOMAIN'
|
||
This domain contains variables, function names, typedef names and
|
||
enum type values.
|
||
|
||
'gdb.SYMBOL_STRUCT_DOMAIN'
|
||
This domain holds struct, union and enum type names.
|
||
|
||
'gdb.SYMBOL_LABEL_DOMAIN'
|
||
This domain contains names of labels (for gotos).
|
||
|
||
'gdb.SYMBOL_MODULE_DOMAIN'
|
||
This domain contains names of Fortran module types.
|
||
|
||
'gdb.SYMBOL_COMMON_BLOCK_DOMAIN'
|
||
This domain contains names of Fortran common blocks.
|
||
|
||
The available address class categories in 'gdb.Symbol' are
|
||
represented as constants in the 'gdb' module:
|
||
|
||
'gdb.SYMBOL_LOC_UNDEF'
|
||
If this is returned by address class, it indicates an error either
|
||
in the symbol information or in GDB's handling of symbols.
|
||
|
||
'gdb.SYMBOL_LOC_CONST'
|
||
Value is constant int.
|
||
|
||
'gdb.SYMBOL_LOC_STATIC'
|
||
Value is at a fixed address.
|
||
|
||
'gdb.SYMBOL_LOC_REGISTER'
|
||
Value is in a register.
|
||
|
||
'gdb.SYMBOL_LOC_ARG'
|
||
Value is an argument. This value is at the offset stored within
|
||
the symbol inside the frame's argument list.
|
||
|
||
'gdb.SYMBOL_LOC_REF_ARG'
|
||
Value address is stored in the frame's argument list. Just like
|
||
'LOC_ARG' except that the value's address is stored at the offset,
|
||
not the value itself.
|
||
|
||
'gdb.SYMBOL_LOC_REGPARM_ADDR'
|
||
Value is a specified register. Just like 'LOC_REGISTER' except the
|
||
register holds the address of the argument instead of the argument
|
||
itself.
|
||
|
||
'gdb.SYMBOL_LOC_LOCAL'
|
||
Value is a local variable.
|
||
|
||
'gdb.SYMBOL_LOC_TYPEDEF'
|
||
Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all
|
||
have this class.
|
||
|
||
'gdb.SYMBOL_LOC_BLOCK'
|
||
Value is a block.
|
||
|
||
'gdb.SYMBOL_LOC_CONST_BYTES'
|
||
Value is a byte-sequence.
|
||
|
||
'gdb.SYMBOL_LOC_UNRESOLVED'
|
||
Value is at a fixed address, but the address of the variable has to
|
||
be determined from the minimal symbol table whenever the variable
|
||
is referenced.
|
||
|
||
'gdb.SYMBOL_LOC_OPTIMIZED_OUT'
|
||
The value does not actually exist in the program.
|
||
|
||
'gdb.SYMBOL_LOC_COMPUTED'
|
||
The value's address is a computed location.
|
||
|
||
'gdb.SYMBOL_LOC_COMPUTED'
|
||
The value's address is a symbol. This is only used for Fortran
|
||
common blocks.
|
||
|
||
|
||
File: gdb.info, Node: Symbol Tables In Python, Next: Line Tables In Python, Prev: Symbols In Python, Up: Python API
|
||
|
||
23.2.2.28 Symbol table representation in Python
|
||
...............................................
|
||
|
||
Access to symbol table data maintained by GDB on the inferior is exposed
|
||
to Python via two objects: 'gdb.Symtab_and_line' and 'gdb.Symtab'.
|
||
Symbol table and line data for a frame is returned from the 'find_sal'
|
||
method in 'gdb.Frame' object. *Note Frames In Python::.
|
||
|
||
For more information on GDB's symbol table management, see *note
|
||
Examining the Symbol Table: Symbols, for more information.
|
||
|
||
A 'gdb.Symtab_and_line' object has the following attributes:
|
||
|
||
-- Variable: Symtab_and_line.symtab
|
||
The symbol table object ('gdb.Symtab') for this frame. This
|
||
attribute is not writable.
|
||
|
||
-- Variable: Symtab_and_line.pc
|
||
Indicates the start of the address range occupied by code for the
|
||
current source line. This attribute is not writable.
|
||
|
||
-- Variable: Symtab_and_line.last
|
||
Indicates the end of the address range occupied by code for the
|
||
current source line. This attribute is not writable.
|
||
|
||
-- Variable: Symtab_and_line.line
|
||
Indicates the current line number for this object. This attribute
|
||
is not writable.
|
||
|
||
A 'gdb.Symtab_and_line' object has the following methods:
|
||
|
||
-- Function: Symtab_and_line.is_valid ()
|
||
Returns 'True' if the 'gdb.Symtab_and_line' object is valid,
|
||
'False' if not. A 'gdb.Symtab_and_line' object can become invalid
|
||
if the Symbol table and line object it refers to does not exist in
|
||
GDB any longer. All other 'gdb.Symtab_and_line' methods will throw
|
||
an exception if it is invalid at the time the method is called.
|
||
|
||
A 'gdb.Symtab' object has the following attributes:
|
||
|
||
-- Variable: Symtab.filename
|
||
The symbol table's source filename. This attribute is not
|
||
writable.
|
||
|
||
-- Variable: Symtab.objfile
|
||
The symbol table's backing object file. *Note Objfiles In
|
||
Python::. This attribute is not writable.
|
||
|
||
-- Variable: Symtab.producer
|
||
The name and possibly version number of the program that compiled
|
||
the code in the symbol table. The contents of this string is up to
|
||
the compiler. If no producer information is available then 'None'
|
||
is returned. This attribute is not writable.
|
||
|
||
A 'gdb.Symtab' object has the following methods:
|
||
|
||
-- Function: Symtab.is_valid ()
|
||
Returns 'True' if the 'gdb.Symtab' object is valid, 'False' if not.
|
||
A 'gdb.Symtab' object can become invalid if the symbol table it
|
||
refers to does not exist in GDB any longer. All other 'gdb.Symtab'
|
||
methods will throw an exception if it is invalid at the time the
|
||
method is called.
|
||
|
||
-- Function: Symtab.fullname ()
|
||
Return the symbol table's source absolute file name.
|
||
|
||
-- Function: Symtab.global_block ()
|
||
Return the global block of the underlying symbol table. *Note
|
||
Blocks In Python::.
|
||
|
||
-- Function: Symtab.static_block ()
|
||
Return the static block of the underlying symbol table. *Note
|
||
Blocks In Python::.
|
||
|
||
-- Function: Symtab.linetable ()
|
||
Return the line table associated with the symbol table. *Note Line
|
||
Tables In Python::.
|
||
|
||
|
||
File: gdb.info, Node: Line Tables In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API
|
||
|
||
23.2.2.29 Manipulating line tables using Python
|
||
...............................................
|
||
|
||
Python code can request and inspect line table information from a symbol
|
||
table that is loaded in GDB. A line table is a mapping of source lines
|
||
to their executable locations in memory. To acquire the line table
|
||
information for a particular symbol table, use the 'linetable' function
|
||
(*note Symbol Tables In Python::).
|
||
|
||
A 'gdb.LineTable' is iterable. The iterator returns 'LineTableEntry'
|
||
objects that correspond to the source line and address for each line
|
||
table entry. 'LineTableEntry' objects have the following attributes:
|
||
|
||
-- Variable: LineTableEntry.line
|
||
The source line number for this line table entry. This number
|
||
corresponds to the actual line of source. This attribute is not
|
||
writable.
|
||
|
||
-- Variable: LineTableEntry.pc
|
||
The address that is associated with the line table entry where the
|
||
executable code for that source line resides in memory. This
|
||
attribute is not writable.
|
||
|
||
As there can be multiple addresses for a single source line, you may
|
||
receive multiple 'LineTableEntry' objects with matching 'line'
|
||
attributes, but with different 'pc' attributes. The iterator is sorted
|
||
in ascending 'pc' order. Here is a small example illustrating iterating
|
||
over a line table.
|
||
|
||
symtab = gdb.selected_frame().find_sal().symtab
|
||
linetable = symtab.linetable()
|
||
for line in linetable:
|
||
print "Line: "+str(line.line)+" Address: "+hex(line.pc)
|
||
|
||
This will have the following output:
|
||
|
||
Line: 33 Address: 0x4005c8L
|
||
Line: 37 Address: 0x4005caL
|
||
Line: 39 Address: 0x4005d2L
|
||
Line: 40 Address: 0x4005f8L
|
||
Line: 42 Address: 0x4005ffL
|
||
Line: 44 Address: 0x400608L
|
||
Line: 42 Address: 0x40060cL
|
||
Line: 45 Address: 0x400615L
|
||
|
||
In addition to being able to iterate over a 'LineTable', it also has
|
||
the following direct access methods:
|
||
|
||
-- Function: LineTable.line (line)
|
||
Return a Python 'Tuple' of 'LineTableEntry' objects for any entries
|
||
in the line table for the given LINE, which specifies the source
|
||
code line. If there are no entries for that source code LINE, the
|
||
Python 'None' is returned.
|
||
|
||
-- Function: LineTable.has_line (line)
|
||
Return a Python 'Boolean' indicating whether there is an entry in
|
||
the line table for this source line. Return 'True' if an entry is
|
||
found, or 'False' if not.
|
||
|
||
-- Function: LineTable.source_lines ()
|
||
Return a Python 'List' of the source line numbers in the symbol
|
||
table. Only lines with executable code locations are returned.
|
||
The contents of the 'List' will just be the source line entries
|
||
represented as Python 'Long' values.
|
||
|
||
|
||
File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Line Tables In Python, Up: Python API
|
||
|
||
23.2.2.30 Manipulating breakpoints using Python
|
||
...............................................
|
||
|
||
Python code can manipulate breakpoints via the 'gdb.Breakpoint' class.
|
||
|
||
A breakpoint can be created using one of the two forms of the
|
||
'gdb.Breakpoint' constructor. The first one accepts a string like one
|
||
would pass to the 'break' (*note Setting Breakpoints: Set Breaks.) and
|
||
'watch' (*note Setting Watchpoints: Set Watchpoints.) commands, and can
|
||
be used to create both breakpoints and watchpoints. The second accepts
|
||
separate Python arguments similar to *note Explicit Locations::, and can
|
||
only be used to create breakpoints.
|
||
|
||
-- Function: Breakpoint.__init__ (spec [, type ][, wp_class ][,
|
||
internal ][, temporary ][, qualified ])
|
||
Create a new breakpoint according to SPEC, which is a string naming
|
||
the location of a breakpoint, or an expression that defines a
|
||
watchpoint. The string should describe a location in a format
|
||
recognized by the 'break' command (*note Setting Breakpoints: Set
|
||
Breaks.) or, in the case of a watchpoint, by the 'watch' command
|
||
(*note Setting Watchpoints: Set Watchpoints.).
|
||
|
||
The optional TYPE argument specifies the type of the breakpoint to
|
||
create, as defined below.
|
||
|
||
The optional WP_CLASS argument defines the class of watchpoint to
|
||
create, if TYPE is 'gdb.BP_WATCHPOINT'. If WP_CLASS is omitted, it
|
||
defaults to 'gdb.WP_WRITE'.
|
||
|
||
The optional INTERNAL argument allows the breakpoint to become
|
||
invisible to the user. The breakpoint will neither be reported
|
||
when created, nor will it be listed in the output from 'info
|
||
breakpoints' (but will be listed with the 'maint info breakpoints'
|
||
command).
|
||
|
||
The optional TEMPORARY argument makes the breakpoint a temporary
|
||
breakpoint. Temporary breakpoints are deleted after they have been
|
||
hit. Any further access to the Python breakpoint after it has been
|
||
hit will result in a runtime error (as that breakpoint has now been
|
||
automatically deleted).
|
||
|
||
The optional QUALIFIED argument is a boolean that allows
|
||
interpreting the function passed in 'spec' as a fully-qualified
|
||
name. It is equivalent to 'break''s '-qualified' flag (*note
|
||
Linespec Locations:: and *note Explicit Locations::).
|
||
|
||
-- Function: Breakpoint.__init__ ([ source ][, function ][, label ][,
|
||
line ], ][ internal ][, temporary ][, qualified ])
|
||
This second form of creating a new breakpoint specifies the
|
||
explicit location (*note Explicit Locations::) using keywords. The
|
||
new breakpoint will be created in the specified source file SOURCE,
|
||
at the specified FUNCTION, LABEL and LINE.
|
||
|
||
INTERNAL, TEMPORARY and QUALIFIED have the same usage as explained
|
||
previously.
|
||
|
||
The available types are represented by constants defined in the 'gdb'
|
||
module:
|
||
|
||
'gdb.BP_BREAKPOINT'
|
||
Normal code breakpoint.
|
||
|
||
'gdb.BP_WATCHPOINT'
|
||
Watchpoint breakpoint.
|
||
|
||
'gdb.BP_HARDWARE_WATCHPOINT'
|
||
Hardware assisted watchpoint.
|
||
|
||
'gdb.BP_READ_WATCHPOINT'
|
||
Hardware assisted read watchpoint.
|
||
|
||
'gdb.BP_ACCESS_WATCHPOINT'
|
||
Hardware assisted access watchpoint.
|
||
|
||
The available watchpoint types represented by constants are defined
|
||
in the 'gdb' module:
|
||
|
||
'gdb.WP_READ'
|
||
Read only watchpoint.
|
||
|
||
'gdb.WP_WRITE'
|
||
Write only watchpoint.
|
||
|
||
'gdb.WP_ACCESS'
|
||
Read/Write watchpoint.
|
||
|
||
-- Function: Breakpoint.stop (self)
|
||
The 'gdb.Breakpoint' class can be sub-classed and, in particular,
|
||
you may choose to implement the 'stop' method. If this method is
|
||
defined in a sub-class of 'gdb.Breakpoint', it will be called when
|
||
the inferior reaches any location of a breakpoint which
|
||
instantiates that sub-class. If the method returns 'True', the
|
||
inferior will be stopped at the location of the breakpoint,
|
||
otherwise the inferior will continue.
|
||
|
||
If there are multiple breakpoints at the same location with a
|
||
'stop' method, each one will be called regardless of the return
|
||
status of the previous. This ensures that all 'stop' methods have
|
||
a chance to execute at that location. In this scenario if one of
|
||
the methods returns 'True' but the others return 'False', the
|
||
inferior will still be stopped.
|
||
|
||
You should not alter the execution state of the inferior (i.e.,
|
||
step, next, etc.), alter the current frame context (i.e., change
|
||
the current active frame), or alter, add or delete any breakpoint.
|
||
As a general rule, you should not alter any data within GDB or the
|
||
inferior at this time.
|
||
|
||
Example 'stop' implementation:
|
||
|
||
class MyBreakpoint (gdb.Breakpoint):
|
||
def stop (self):
|
||
inf_val = gdb.parse_and_eval("foo")
|
||
if inf_val == 3:
|
||
return True
|
||
return False
|
||
|
||
-- Function: Breakpoint.is_valid ()
|
||
Return 'True' if this 'Breakpoint' object is valid, 'False'
|
||
otherwise. A 'Breakpoint' object can become invalid if the user
|
||
deletes the breakpoint. In this case, the object still exists, but
|
||
the underlying breakpoint does not. In the cases of watchpoint
|
||
scope, the watchpoint remains valid even if execution of the
|
||
inferior leaves the scope of that watchpoint.
|
||
|
||
-- Function: Breakpoint.delete ()
|
||
Permanently deletes the GDB breakpoint. This also invalidates the
|
||
Python 'Breakpoint' object. Any further access to this object's
|
||
attributes or methods will raise an error.
|
||
|
||
-- Variable: Breakpoint.enabled
|
||
This attribute is 'True' if the breakpoint is enabled, and 'False'
|
||
otherwise. This attribute is writable. You can use it to enable
|
||
or disable the breakpoint.
|
||
|
||
-- Variable: Breakpoint.silent
|
||
This attribute is 'True' if the breakpoint is silent, and 'False'
|
||
otherwise. This attribute is writable.
|
||
|
||
Note that a breakpoint can also be silent if it has commands and
|
||
the first command is 'silent'. This is not reported by the
|
||
'silent' attribute.
|
||
|
||
-- Variable: Breakpoint.pending
|
||
This attribute is 'True' if the breakpoint is pending, and 'False'
|
||
otherwise. *Note Set Breaks::. This attribute is read-only.
|
||
|
||
-- Variable: Breakpoint.thread
|
||
If the breakpoint is thread-specific, this attribute holds the
|
||
thread's global id. If the breakpoint is not thread-specific, this
|
||
attribute is 'None'. This attribute is writable.
|
||
|
||
-- Variable: Breakpoint.task
|
||
If the breakpoint is Ada task-specific, this attribute holds the
|
||
Ada task id. If the breakpoint is not task-specific (or the
|
||
underlying language is not Ada), this attribute is 'None'. This
|
||
attribute is writable.
|
||
|
||
-- Variable: Breakpoint.ignore_count
|
||
This attribute holds the ignore count for the breakpoint, an
|
||
integer. This attribute is writable.
|
||
|
||
-- Variable: Breakpoint.number
|
||
This attribute holds the breakpoint's number -- the identifier used
|
||
by the user to manipulate the breakpoint. This attribute is not
|
||
writable.
|
||
|
||
-- Variable: Breakpoint.type
|
||
This attribute holds the breakpoint's type -- the identifier used
|
||
to determine the actual breakpoint type or use-case. This
|
||
attribute is not writable.
|
||
|
||
-- Variable: Breakpoint.visible
|
||
This attribute tells whether the breakpoint is visible to the user
|
||
when set, or when the 'info breakpoints' command is run. This
|
||
attribute is not writable.
|
||
|
||
-- Variable: Breakpoint.temporary
|
||
This attribute indicates whether the breakpoint was created as a
|
||
temporary breakpoint. Temporary breakpoints are automatically
|
||
deleted after that breakpoint has been hit. Access to this
|
||
attribute, and all other attributes and functions other than the
|
||
'is_valid' function, will result in an error after the breakpoint
|
||
has been hit (as it has been automatically deleted). This
|
||
attribute is not writable.
|
||
|
||
-- Variable: Breakpoint.hit_count
|
||
This attribute holds the hit count for the breakpoint, an integer.
|
||
This attribute is writable, but currently it can only be set to
|
||
zero.
|
||
|
||
-- Variable: Breakpoint.location
|
||
This attribute holds the location of the breakpoint, as specified
|
||
by the user. It is a string. If the breakpoint does not have a
|
||
location (that is, it is a watchpoint) the attribute's value is
|
||
'None'. This attribute is not writable.
|
||
|
||
-- Variable: Breakpoint.expression
|
||
This attribute holds a breakpoint expression, as specified by the
|
||
user. It is a string. If the breakpoint does not have an
|
||
expression (the breakpoint is not a watchpoint) the attribute's
|
||
value is 'None'. This attribute is not writable.
|
||
|
||
-- Variable: Breakpoint.condition
|
||
This attribute holds the condition of the breakpoint, as specified
|
||
by the user. It is a string. If there is no condition, this
|
||
attribute's value is 'None'. This attribute is writable.
|
||
|
||
-- Variable: Breakpoint.commands
|
||
This attribute holds the commands attached to the breakpoint. If
|
||
there are commands, this attribute's value is a string holding all
|
||
the commands, separated by newlines. If there are no commands,
|
||
this attribute is 'None'. This attribute is writable.
|
||
|
||
|
||
File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API
|
||
|
||
23.2.2.31 Finish Breakpoints
|
||
............................
|
||
|
||
A finish breakpoint is a temporary breakpoint set at the return address
|
||
of a frame, based on the 'finish' command. 'gdb.FinishBreakpoint'
|
||
extends 'gdb.Breakpoint'. The underlying breakpoint will be disabled
|
||
and deleted when the execution will run out of the breakpoint scope
|
||
(i.e. 'Breakpoint.stop' or 'FinishBreakpoint.out_of_scope' triggered).
|
||
Finish breakpoints are thread specific and must be create with the right
|
||
thread selected.
|
||
|
||
-- Function: FinishBreakpoint.__init__ ([frame] [, internal])
|
||
Create a finish breakpoint at the return address of the 'gdb.Frame'
|
||
object FRAME. If FRAME is not provided, this defaults to the
|
||
newest frame. The optional INTERNAL argument allows the breakpoint
|
||
to become invisible to the user. *Note Breakpoints In Python::,
|
||
for further details about this argument.
|
||
|
||
-- Function: FinishBreakpoint.out_of_scope (self)
|
||
In some circumstances (e.g. 'longjmp', C++ exceptions, GDB 'return'
|
||
command, ...), a function may not properly terminate, and thus
|
||
never hit the finish breakpoint. When GDB notices such a
|
||
situation, the 'out_of_scope' callback will be triggered.
|
||
|
||
You may want to sub-class 'gdb.FinishBreakpoint' and override this
|
||
method:
|
||
|
||
class MyFinishBreakpoint (gdb.FinishBreakpoint)
|
||
def stop (self):
|
||
print "normal finish"
|
||
return True
|
||
|
||
def out_of_scope ():
|
||
print "abnormal finish"
|
||
|
||
-- Variable: FinishBreakpoint.return_value
|
||
When GDB is stopped at a finish breakpoint and the frame used to
|
||
build the 'gdb.FinishBreakpoint' object had debug symbols, this
|
||
attribute will contain a 'gdb.Value' object corresponding to the
|
||
return value of the function. The value will be 'None' if the
|
||
function return type is 'void' or if the return value was not
|
||
computable. This attribute is not writable.
|
||
|
||
|
||
File: gdb.info, Node: Lazy Strings In Python, Next: Architectures In Python, Prev: Finish Breakpoints in Python, Up: Python API
|
||
|
||
23.2.2.32 Python representation of lazy strings
|
||
...............................................
|
||
|
||
A "lazy string" is a string whose contents is not retrieved or encoded
|
||
until it is needed.
|
||
|
||
A 'gdb.LazyString' is represented in GDB as an 'address' that points
|
||
to a region of memory, an 'encoding' that will be used to encode that
|
||
region of memory, and a 'length' to delimit the region of memory that
|
||
represents the string. The difference between a 'gdb.LazyString' and a
|
||
string wrapped within a 'gdb.Value' is that a 'gdb.LazyString' will be
|
||
treated differently by GDB when printing. A 'gdb.LazyString' is
|
||
retrieved and encoded during printing, while a 'gdb.Value' wrapping a
|
||
string is immediately retrieved and encoded on creation.
|
||
|
||
A 'gdb.LazyString' object has the following functions:
|
||
|
||
-- Function: LazyString.value ()
|
||
Convert the 'gdb.LazyString' to a 'gdb.Value'. This value will
|
||
point to the string in memory, but will lose all the delayed
|
||
retrieval, encoding and handling that GDB applies to a
|
||
'gdb.LazyString'.
|
||
|
||
-- Variable: LazyString.address
|
||
This attribute holds the address of the string. This attribute is
|
||
not writable.
|
||
|
||
-- Variable: LazyString.length
|
||
This attribute holds the length of the string in characters. If
|
||
the length is -1, then the string will be fetched and encoded up to
|
||
the first null of appropriate width. This attribute is not
|
||
writable.
|
||
|
||
-- Variable: LazyString.encoding
|
||
This attribute holds the encoding that will be applied to the
|
||
string when the string is printed by GDB. If the encoding is not
|
||
set, or contains an empty string, then GDB will select the most
|
||
appropriate encoding when the string is printed. This attribute is
|
||
not writable.
|
||
|
||
-- Variable: LazyString.type
|
||
This attribute holds the type that is represented by the lazy
|
||
string's type. For a lazy string this is a pointer or array type.
|
||
To resolve this to the lazy string's character type, use the type's
|
||
'target' method. *Note Types In Python::. This attribute is not
|
||
writable.
|
||
|
||
|
||
File: gdb.info, Node: Architectures In Python, Prev: Lazy Strings In Python, Up: Python API
|
||
|
||
23.2.2.33 Python representation of architectures
|
||
................................................
|
||
|
||
GDB uses architecture specific parameters and artifacts in a number of
|
||
its various computations. An architecture is represented by an instance
|
||
of the 'gdb.Architecture' class.
|
||
|
||
A 'gdb.Architecture' class has the following methods:
|
||
|
||
-- Function: Architecture.name ()
|
||
Return the name (string value) of the architecture.
|
||
|
||
-- Function: Architecture.disassemble (START_PC [, END_PC [, COUNT]])
|
||
Return a list of disassembled instructions starting from the memory
|
||
address START_PC. The optional arguments END_PC and COUNT
|
||
determine the number of instructions in the returned list. If both
|
||
the optional arguments END_PC and COUNT are specified, then a list
|
||
of at most COUNT disassembled instructions whose start address
|
||
falls in the closed memory address interval from START_PC to END_PC
|
||
are returned. If END_PC is not specified, but COUNT is specified,
|
||
then COUNT number of instructions starting from the address
|
||
START_PC are returned. If COUNT is not specified but END_PC is
|
||
specified, then all instructions whose start address falls in the
|
||
closed memory address interval from START_PC to END_PC are
|
||
returned. If neither END_PC nor COUNT are specified, then a single
|
||
instruction at START_PC is returned. For all of these cases, each
|
||
element of the returned list is a Python 'dict' with the following
|
||
string keys:
|
||
|
||
'addr'
|
||
The value corresponding to this key is a Python long integer
|
||
capturing the memory address of the instruction.
|
||
|
||
'asm'
|
||
The value corresponding to this key is a string value which
|
||
represents the instruction with assembly language mnemonics.
|
||
The assembly language flavor used is the same as that
|
||
specified by the current CLI variable 'disassembly-flavor'.
|
||
*Note Machine Code::.
|
||
|
||
'length'
|
||
The value corresponding to this key is the length (integer
|
||
value) of the instruction in bytes.
|
||
|
||
|
||
File: gdb.info, Node: Python Auto-loading, Next: Python modules, Prev: Python API, Up: Python
|
||
|
||
23.2.3 Python Auto-loading
|
||
--------------------------
|
||
|
||
When a new object file is read (for example, due to the 'file' command,
|
||
or because the inferior has loaded a shared library), GDB will look for
|
||
Python support scripts in several ways: 'OBJFILE-gdb.py' and
|
||
'.debug_gdb_scripts' section. *Note Auto-loading extensions::.
|
||
|
||
The auto-loading feature is useful for supplying application-specific
|
||
debugging commands and scripts.
|
||
|
||
Auto-loading can be enabled or disabled, and the list of auto-loaded
|
||
scripts can be printed.
|
||
|
||
'set auto-load python-scripts [on|off]'
|
||
Enable or disable the auto-loading of Python scripts.
|
||
|
||
'show auto-load python-scripts'
|
||
Show whether auto-loading of Python scripts is enabled or disabled.
|
||
|
||
'info auto-load python-scripts [REGEXP]'
|
||
Print the list of all Python scripts that GDB auto-loaded.
|
||
|
||
Also printed is the list of Python scripts that were mentioned in
|
||
the '.debug_gdb_scripts' section and were either not found (*note
|
||
dotdebug_gdb_scripts section::) or were not auto-loaded due to
|
||
'auto-load safe-path' rejection (*note Auto-loading::). This is
|
||
useful because their names are not printed when GDB tries to load
|
||
them and fails. There may be many of them, and printing an error
|
||
message for each one is problematic.
|
||
|
||
If REGEXP is supplied only Python scripts with matching names are
|
||
printed.
|
||
|
||
Example:
|
||
|
||
(gdb) info auto-load python-scripts
|
||
Loaded Script
|
||
Yes py-section-script.py
|
||
full name: /tmp/py-section-script.py
|
||
No my-foo-pretty-printers.py
|
||
|
||
When reading an auto-loaded file or script, GDB sets the "current
|
||
objfile". This is available via the 'gdb.current_objfile' function
|
||
(*note Objfiles In Python::). This can be useful for registering
|
||
objfile-specific pretty-printers and frame-filters.
|
||
|
||
|
||
File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python
|
||
|
||
23.2.4 Python modules
|
||
---------------------
|
||
|
||
GDB comes with several modules to assist writing Python code.
|
||
|
||
* Menu:
|
||
|
||
* gdb.printing:: Building and registering pretty-printers.
|
||
* gdb.types:: Utilities for working with types.
|
||
* gdb.prompt:: Utilities for prompt value substitution.
|
||
|
||
|
||
File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules
|
||
|
||
23.2.4.1 gdb.printing
|
||
.....................
|
||
|
||
This module provides a collection of utilities for working with
|
||
pretty-printers.
|
||
|
||
'PrettyPrinter (NAME, SUBPRINTERS=None)'
|
||
This class specifies the API that makes 'info pretty-printer',
|
||
'enable pretty-printer' and 'disable pretty-printer' work.
|
||
Pretty-printers should generally inherit from this class.
|
||
|
||
'SubPrettyPrinter (NAME)'
|
||
For printers that handle multiple types, this class specifies the
|
||
corresponding API for the subprinters.
|
||
|
||
'RegexpCollectionPrettyPrinter (NAME)'
|
||
Utility class for handling multiple printers, all recognized via
|
||
regular expressions. *Note Writing a Pretty-Printer::, for an
|
||
example.
|
||
|
||
'FlagEnumerationPrinter (NAME)'
|
||
A pretty-printer which handles printing of 'enum' values. Unlike
|
||
GDB's built-in 'enum' printing, this printer attempts to work
|
||
properly when there is some overlap between the enumeration
|
||
constants. The argument NAME is the name of the printer and also
|
||
the name of the 'enum' type to look up.
|
||
|
||
'register_pretty_printer (OBJ, PRINTER, REPLACE=False)'
|
||
Register PRINTER with the pretty-printer list of OBJ. If REPLACE
|
||
is 'True' then any existing copy of the printer is replaced.
|
||
Otherwise a 'RuntimeError' exception is raised if a printer with
|
||
the same name already exists.
|
||
|
||
|
||
File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules
|
||
|
||
23.2.4.2 gdb.types
|
||
..................
|
||
|
||
This module provides a collection of utilities for working with
|
||
'gdb.Type' objects.
|
||
|
||
'get_basic_type (TYPE)'
|
||
Return TYPE with const and volatile qualifiers stripped, and with
|
||
typedefs and C++ references converted to the underlying type.
|
||
|
||
C++ example:
|
||
|
||
typedef const int const_int;
|
||
const_int foo (3);
|
||
const_int& foo_ref (foo);
|
||
int main () { return 0; }
|
||
|
||
Then in gdb:
|
||
|
||
(gdb) start
|
||
(gdb) python import gdb.types
|
||
(gdb) python foo_ref = gdb.parse_and_eval("foo_ref")
|
||
(gdb) python print gdb.types.get_basic_type(foo_ref.type)
|
||
int
|
||
|
||
'has_field (TYPE, FIELD)'
|
||
Return 'True' if TYPE, assumed to be a type with fields (e.g., a
|
||
structure or union), has field FIELD.
|
||
|
||
'make_enum_dict (ENUM_TYPE)'
|
||
Return a Python 'dictionary' type produced from ENUM_TYPE.
|
||
|
||
'deep_items (TYPE)'
|
||
Returns a Python iterator similar to the standard
|
||
'gdb.Type.iteritems' method, except that the iterator returned by
|
||
'deep_items' will recursively traverse anonymous struct or union
|
||
fields. For example:
|
||
|
||
struct A
|
||
{
|
||
int a;
|
||
union {
|
||
int b0;
|
||
int b1;
|
||
};
|
||
};
|
||
|
||
Then in GDB:
|
||
(gdb) python import gdb.types
|
||
(gdb) python struct_a = gdb.lookup_type("struct A")
|
||
(gdb) python print struct_a.keys ()
|
||
{['a', '']}
|
||
(gdb) python print [k for k,v in gdb.types.deep_items(struct_a)]
|
||
{['a', 'b0', 'b1']}
|
||
|
||
'get_type_recognizers ()'
|
||
Return a list of the enabled type recognizers for the current
|
||
context. This is called by GDB during the type-printing process
|
||
(*note Type Printing API::).
|
||
|
||
'apply_type_recognizers (recognizers, type_obj)'
|
||
Apply the type recognizers, RECOGNIZERS, to the type object
|
||
TYPE_OBJ. If any recognizer returns a string, return that string.
|
||
Otherwise, return 'None'. This is called by GDB during the
|
||
type-printing process (*note Type Printing API::).
|
||
|
||
'register_type_printer (locus, printer)'
|
||
This is a convenience function to register a type printer PRINTER.
|
||
The printer must implement the type printer protocol. The LOCUS
|
||
argument is either a 'gdb.Objfile', in which case the printer is
|
||
registered with that objfile; a 'gdb.Progspace', in which case the
|
||
printer is registered with that progspace; or 'None', in which case
|
||
the printer is registered globally.
|
||
|
||
'TypePrinter'
|
||
This is a base class that implements the type printer protocol.
|
||
Type printers are encouraged, but not required, to derive from this
|
||
class. It defines a constructor:
|
||
|
||
-- Method on TypePrinter: __init__ (self, name)
|
||
Initialize the type printer with the given name. The new
|
||
printer starts in the enabled state.
|
||
|
||
|
||
File: gdb.info, Node: gdb.prompt, Prev: gdb.types, Up: Python modules
|
||
|
||
23.2.4.3 gdb.prompt
|
||
...................
|
||
|
||
This module provides a method for prompt value-substitution.
|
||
|
||
'substitute_prompt (STRING)'
|
||
Return STRING with escape sequences substituted by values. Some
|
||
escape sequences take arguments. You can specify arguments inside
|
||
"{}" immediately following the escape sequence.
|
||
|
||
The escape sequences you can pass to this function are:
|
||
|
||
'\\'
|
||
Substitute a backslash.
|
||
'\e'
|
||
Substitute an ESC character.
|
||
'\f'
|
||
Substitute the selected frame; an argument names a frame
|
||
parameter.
|
||
'\n'
|
||
Substitute a newline.
|
||
'\p'
|
||
Substitute a parameter's value; the argument names the
|
||
parameter.
|
||
'\r'
|
||
Substitute a carriage return.
|
||
'\t'
|
||
Substitute the selected thread; an argument names a thread
|
||
parameter.
|
||
'\v'
|
||
Substitute the version of GDB.
|
||
'\w'
|
||
Substitute the current working directory.
|
||
'\['
|
||
Begin a sequence of non-printing characters. These sequences
|
||
are typically used with the ESC character, and are not counted
|
||
in the string length. Example: "\[\e[0;34m\](gdb)\[\e[0m\]"
|
||
will return a blue-colored "(gdb)" prompt where the length is
|
||
five.
|
||
'\]'
|
||
End a sequence of non-printing characters.
|
||
|
||
For example:
|
||
|
||
substitute_prompt ("frame: \f, args: \p{print frame-arguments}")
|
||
|
||
will return the string:
|
||
|
||
"frame: main, args: scalars"
|
||
|
||
|
||
File: gdb.info, Node: Guile, Next: Auto-loading extensions, Prev: Python, Up: Extending GDB
|
||
|
||
23.3 Extending GDB using Guile
|
||
==============================
|
||
|
||
You can extend GDB using the Guile implementation of the Scheme
|
||
programming language (http://www.gnu.org/software/guile/). This feature
|
||
is available only if GDB was configured using '--with-guile'.
|
||
|
||
* Menu:
|
||
|
||
* Guile Introduction:: Introduction to Guile scripting in GDB
|
||
* Guile Commands:: Accessing Guile from GDB
|
||
* Guile API:: Accessing GDB from Guile
|
||
* Guile Auto-loading:: Automatically loading Guile code
|
||
* Guile Modules:: Guile modules provided by GDB
|
||
|
||
|
||
File: gdb.info, Node: Guile Introduction, Next: Guile Commands, Up: Guile
|
||
|
||
23.3.1 Guile Introduction
|
||
-------------------------
|
||
|
||
Guile is an implementation of the Scheme programming language and is the
|
||
GNU project's official extension language.
|
||
|
||
Guile support in GDB follows the Python support in GDB reasonably
|
||
closely, so concepts there should carry over. However, some things are
|
||
done differently where it makes sense.
|
||
|
||
GDB requires Guile version 2.0 or greater. Older versions are not
|
||
supported.
|
||
|
||
Guile scripts used by GDB should be installed in
|
||
'DATA-DIRECTORY/guile', where DATA-DIRECTORY is the data directory as
|
||
determined at GDB startup (*note Data Files::). This directory, known
|
||
as the "guile directory", is automatically added to the Guile Search
|
||
Path in order to allow the Guile interpreter to locate all scripts
|
||
installed at this location.
|
||
|
||
|
||
File: gdb.info, Node: Guile Commands, Next: Guile API, Prev: Guile Introduction, Up: Guile
|
||
|
||
23.3.2 Guile Commands
|
||
---------------------
|
||
|
||
GDB provides two commands for accessing the Guile interpreter:
|
||
|
||
'guile-repl'
|
||
'gr'
|
||
The 'guile-repl' command can be used to start an interactive Guile
|
||
prompt or "repl". To return to GDB, type ',q' or the 'EOF'
|
||
character (e.g., 'Ctrl-D' on an empty prompt). These commands do
|
||
not take any arguments.
|
||
|
||
'guile [SCHEME-EXPRESSION]'
|
||
'gu [SCHEME-EXPRESSION]'
|
||
The 'guile' command can be used to evaluate a Scheme expression.
|
||
|
||
If given an argument, GDB will pass the argument to the Guile
|
||
interpreter for evaluation.
|
||
|
||
(gdb) guile (display (+ 20 3)) (newline)
|
||
23
|
||
|
||
The result of the Scheme expression is displayed using normal Guile
|
||
rules.
|
||
|
||
(gdb) guile (+ 20 3)
|
||
23
|
||
|
||
If you do not provide an argument to 'guile', it will act as a
|
||
multi-line command, like 'define'. In this case, the Guile script
|
||
is made up of subsequent command lines, given after the 'guile'
|
||
command. This command list is terminated using a line containing
|
||
'end'. For example:
|
||
|
||
(gdb) guile
|
||
>(display 23)
|
||
>(newline)
|
||
>end
|
||
23
|
||
|
||
It is also possible to execute a Guile script from the GDB
|
||
interpreter:
|
||
|
||
'source script-name'
|
||
The script name must end with '.scm' and GDB must be configured to
|
||
recognize the script language based on filename extension using the
|
||
'script-extension' setting. *Note Extending GDB: Extending GDB.
|
||
|
||
'guile (load "script-name")'
|
||
This method uses the 'load' Guile function. It takes a string
|
||
argument that is the name of the script to load. See the Guile
|
||
documentation for a description of this function. (*note
|
||
(guile)Loading::).
|
||
|
||
|
||
File: gdb.info, Node: Guile API, Next: Guile Auto-loading, Prev: Guile Commands, Up: Guile
|
||
|
||
23.3.3 Guile API
|
||
----------------
|
||
|
||
You can get quick online help for GDB's Guile API by issuing the command
|
||
'help guile', or by issuing the command ',help' from an interactive
|
||
Guile session. Furthermore, most Guile procedures provided by GDB have
|
||
doc strings which can be obtained with ',describe PROCEDURE-NAME' or ',d
|
||
PROCEDURE-NAME' from the Guile interactive prompt.
|
||
|
||
* Menu:
|
||
|
||
* Basic Guile:: Basic Guile Functions
|
||
* Guile Configuration:: Guile configuration variables
|
||
* GDB Scheme Data Types:: Scheme representations of GDB objects
|
||
* Guile Exception Handling:: How Guile exceptions are translated
|
||
* Values From Inferior In Guile:: Guile representation of values
|
||
* Arithmetic In Guile:: Arithmetic in Guile
|
||
* Types In Guile:: Guile representation of types
|
||
* Guile Pretty Printing API:: Pretty-printing values with Guile
|
||
* Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer
|
||
* Writing a Guile Pretty-Printer:: Writing a pretty-printer
|
||
* Commands In Guile:: Implementing new commands in Guile
|
||
* Parameters In Guile:: Adding new GDB parameters
|
||
* Progspaces In Guile:: Program spaces
|
||
* Objfiles In Guile:: Object files in Guile
|
||
* Frames In Guile:: Accessing inferior stack frames from Guile
|
||
* Blocks In Guile:: Accessing blocks from Guile
|
||
* Symbols In Guile:: Guile representation of symbols
|
||
* Symbol Tables In Guile:: Guile representation of symbol tables
|
||
* Breakpoints In Guile:: Manipulating breakpoints using Guile
|
||
* Lazy Strings In Guile:: Guile representation of lazy strings
|
||
* Architectures In Guile:: Guile representation of architectures
|
||
* Disassembly In Guile:: Disassembling instructions from Guile
|
||
* I/O Ports in Guile:: GDB I/O ports
|
||
* Memory Ports in Guile:: Accessing memory through ports and bytevectors
|
||
* Iterators In Guile:: Basic iterator support
|
||
|
||
|
||
File: gdb.info, Node: Basic Guile, Next: Guile Configuration, Up: Guile API
|
||
|
||
23.3.3.1 Basic Guile
|
||
....................
|
||
|
||
At startup, GDB overrides Guile's 'current-output-port' and
|
||
'current-error-port' to print using GDB's output-paging streams. A
|
||
Guile program which outputs to one of these streams may have its output
|
||
interrupted by the user (*note Screen Size::). In this situation, a
|
||
Guile 'signal' exception is thrown with value 'SIGINT'.
|
||
|
||
Guile's history mechanism uses the same naming as GDB's, namely the
|
||
user of dollar-variables (e.g., $1, $2, etc.). The results of
|
||
evaluations in Guile and in GDB are counted separately, '$1' in Guile is
|
||
not the same value as '$1' in GDB.
|
||
|
||
GDB is not thread-safe. If your Guile program uses multiple threads,
|
||
you must be careful to only call GDB-specific functions in the GDB
|
||
thread.
|
||
|
||
Some care must be taken when writing Guile code to run in GDB. Two
|
||
things are worth noting in particular:
|
||
|
||
* GDB installs handlers for 'SIGCHLD' and 'SIGINT'. Guile code must
|
||
not override these, or even change the options using 'sigaction'.
|
||
If your program changes the handling of these signals, GDB will
|
||
most likely stop working correctly. Note that it is unfortunately
|
||
common for GUI toolkits to install a 'SIGCHLD' handler.
|
||
|
||
* GDB takes care to mark its internal file descriptors as
|
||
close-on-exec. However, this cannot be done in a thread-safe way
|
||
on all platforms. Your Guile programs should be aware of this and
|
||
should both create new file descriptors with the close-on-exec flag
|
||
set and arrange to close unneeded file descriptors before starting
|
||
a child process.
|
||
|
||
GDB introduces a new Guile module, named 'gdb'. All methods and
|
||
classes added by GDB are placed in this module. GDB does not
|
||
automatically 'import' the 'gdb' module, scripts must do this
|
||
themselves. There are various options for how to import a module, so
|
||
GDB leaves the choice of how the 'gdb' module is imported to the user.
|
||
To simplify interactive use, it is recommended to add one of the
|
||
following to your ~/.gdbinit.
|
||
|
||
guile (use-modules (gdb))
|
||
|
||
guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:)))
|
||
|
||
Which one to choose depends on your preference. The second one adds
|
||
'gdb:' as a prefix to all module functions and variables.
|
||
|
||
The rest of this manual assumes the 'gdb' module has been imported
|
||
without any prefix. See the Guile documentation for 'use-modules' for
|
||
more information (*note (guile)Using Guile Modules::).
|
||
|
||
Example:
|
||
|
||
(gdb) guile (value-type (make-value 1))
|
||
ERROR: Unbound variable: value-type
|
||
Error while executing Scheme code.
|
||
(gdb) guile (use-modules (gdb))
|
||
(gdb) guile (value-type (make-value 1))
|
||
int
|
||
(gdb)
|
||
|
||
The '(gdb)' module provides these basic Guile functions.
|
||
|
||
-- Scheme Procedure: execute command [#:from-tty boolean] [#:to-string
|
||
boolean]
|
||
Evaluate COMMAND, a string, as a GDB CLI command. If a GDB
|
||
exception happens while COMMAND runs, it is translated as described
|
||
in *note Guile Exception Handling: Guile Exception Handling.
|
||
|
||
FROM-TTY specifies whether GDB ought to consider this command as
|
||
having originated from the user invoking it interactively. It must
|
||
be a boolean value. If omitted, it defaults to '#f'.
|
||
|
||
By default, any output produced by COMMAND is sent to GDB's
|
||
standard output (and to the log output if logging is turned on).
|
||
If the TO-STRING parameter is '#t', then output will be collected
|
||
by 'execute' and returned as a string. The default is '#f', in
|
||
which case the return value is unspecified. If TO-STRING is '#t',
|
||
the GDB virtual terminal will be temporarily set to unlimited width
|
||
and height, and its pagination will be disabled; *note Screen
|
||
Size::.
|
||
|
||
-- Scheme Procedure: history-ref number
|
||
Return a value from GDB's value history (*note Value History::).
|
||
The NUMBER argument indicates which history element to return. If
|
||
NUMBER is negative, then GDB will take its absolute value and count
|
||
backward from the last element (i.e., the most recent element) to
|
||
find the value to return. If NUMBER is zero, then GDB will return
|
||
the most recent element. If the element specified by NUMBER
|
||
doesn't exist in the value history, a 'gdb:error' exception will be
|
||
raised.
|
||
|
||
If no exception is raised, the return value is always an instance
|
||
of '<gdb:value>' (*note Values From Inferior In Guile::).
|
||
|
||
_Note:_ GDB's value history is independent of Guile's. '$1' in
|
||
GDB's value history contains the result of evaluating an expression
|
||
from GDB's command line and '$1' from Guile's history contains the
|
||
result of evaluating an expression from Guile's command line.
|
||
|
||
-- Scheme Procedure: history-append! value
|
||
Append VALUE, an instance of '<gdb:value>', to GDB's value history.
|
||
Return its index in the history.
|
||
|
||
Putting into history values returned by Guile extensions will allow
|
||
the user convenient access to those values via CLI history
|
||
facilities.
|
||
|
||
-- Scheme Procedure: parse-and-eval expression
|
||
Parse EXPRESSION as an expression in the current language, evaluate
|
||
it, and return the result as a '<gdb:value>'. The EXPRESSION must
|
||
be a string.
|
||
|
||
This function can be useful when implementing a new command (*note
|
||
Commands In Guile::), as it provides a way to parse the command's
|
||
arguments as an expression. It is also is useful when computing
|
||
values. For example, it is the only way to get the value of a
|
||
convenience variable (*note Convenience Vars::) as a '<gdb:value>'.
|
||
|
||
|
||
File: gdb.info, Node: Guile Configuration, Next: GDB Scheme Data Types, Prev: Basic Guile, Up: Guile API
|
||
|
||
23.3.3.2 Guile Configuration
|
||
............................
|
||
|
||
GDB provides these Scheme functions to access various configuration
|
||
parameters.
|
||
|
||
-- Scheme Procedure: data-directory
|
||
Return a string containing GDB's data directory. This directory
|
||
contains GDB's ancillary files.
|
||
|
||
-- Scheme Procedure: guile-data-directory
|
||
Return a string containing GDB's Guile data directory. This
|
||
directory contains the Guile modules provided by GDB.
|
||
|
||
-- Scheme Procedure: gdb-version
|
||
Return a string containing the GDB version.
|
||
|
||
-- Scheme Procedure: host-config
|
||
Return a string containing the host configuration. This is the
|
||
string passed to '--host' when GDB was configured.
|
||
|
||
-- Scheme Procedure: target-config
|
||
Return a string containing the target configuration. This is the
|
||
string passed to '--target' when GDB was configured.
|
||
|
||
|
||
File: gdb.info, Node: GDB Scheme Data Types, Next: Guile Exception Handling, Prev: Guile Configuration, Up: Guile API
|
||
|
||
23.3.3.3 GDB Scheme Data Types
|
||
..............................
|
||
|
||
The values exposed by GDB to Guile are known as "GDB objects". There
|
||
are several kinds of GDB object, and each is disjoint from all other
|
||
types known to Guile.
|
||
|
||
-- Scheme Procedure: gdb-object-kind object
|
||
Return the kind of the GDB object, e.g., '<gdb:breakpoint>', as a
|
||
symbol.
|
||
|
||
GDB defines the following object types:
|
||
|
||
'<gdb:arch>'
|
||
*Note Architectures In Guile::.
|
||
|
||
'<gdb:block>'
|
||
*Note Blocks In Guile::.
|
||
|
||
'<gdb:block-symbols-iterator>'
|
||
*Note Blocks In Guile::.
|
||
|
||
'<gdb:breakpoint>'
|
||
*Note Breakpoints In Guile::.
|
||
|
||
'<gdb:command>'
|
||
*Note Commands In Guile::.
|
||
|
||
'<gdb:exception>'
|
||
*Note Guile Exception Handling::.
|
||
|
||
'<gdb:frame>'
|
||
*Note Frames In Guile::.
|
||
|
||
'<gdb:iterator>'
|
||
*Note Iterators In Guile::.
|
||
|
||
'<gdb:lazy-string>'
|
||
*Note Lazy Strings In Guile::.
|
||
|
||
'<gdb:objfile>'
|
||
*Note Objfiles In Guile::.
|
||
|
||
'<gdb:parameter>'
|
||
*Note Parameters In Guile::.
|
||
|
||
'<gdb:pretty-printer>'
|
||
*Note Guile Pretty Printing API::.
|
||
|
||
'<gdb:pretty-printer-worker>'
|
||
*Note Guile Pretty Printing API::.
|
||
|
||
'<gdb:progspace>'
|
||
*Note Progspaces In Guile::.
|
||
|
||
'<gdb:symbol>'
|
||
*Note Symbols In Guile::.
|
||
|
||
'<gdb:symtab>'
|
||
*Note Symbol Tables In Guile::.
|
||
|
||
'<gdb:sal>'
|
||
*Note Symbol Tables In Guile::.
|
||
|
||
'<gdb:type>'
|
||
*Note Types In Guile::.
|
||
|
||
'<gdb:field>'
|
||
*Note Types In Guile::.
|
||
|
||
'<gdb:value>'
|
||
*Note Values From Inferior In Guile::.
|
||
|
||
The following GDB objects are managed internally so that the Scheme
|
||
function 'eq?' may be applied to them.
|
||
|
||
'<gdb:arch>'
|
||
'<gdb:block>'
|
||
'<gdb:breakpoint>'
|
||
'<gdb:frame>'
|
||
'<gdb:objfile>'
|
||
'<gdb:progspace>'
|
||
'<gdb:symbol>'
|
||
'<gdb:symtab>'
|
||
'<gdb:type>'
|
||
|
||
|
||
File: gdb.info, Node: Guile Exception Handling, Next: Values From Inferior In Guile, Prev: GDB Scheme Data Types, Up: Guile API
|
||
|
||
23.3.3.4 Guile Exception Handling
|
||
.................................
|
||
|
||
When executing the 'guile' command, Guile exceptions uncaught within the
|
||
Guile code are translated to calls to the GDB error-reporting mechanism.
|
||
If the command that called 'guile' does not handle the error, GDB will
|
||
terminate it and report the error according to the setting of the 'guile
|
||
print-stack' parameter.
|
||
|
||
The 'guile print-stack' parameter has three settings:
|
||
|
||
'none'
|
||
Nothing is printed.
|
||
|
||
'message'
|
||
An error message is printed containing the Guile exception name,
|
||
the associated value, and the Guile call stack backtrace at the
|
||
point where the exception was raised. Example:
|
||
|
||
(gdb) guile (display foo)
|
||
ERROR: In procedure memoize-variable-access!:
|
||
ERROR: Unbound variable: foo
|
||
Error while executing Scheme code.
|
||
|
||
'full'
|
||
In addition to an error message a full backtrace is printed.
|
||
|
||
(gdb) set guile print-stack full
|
||
(gdb) guile (display foo)
|
||
Guile Backtrace:
|
||
In ice-9/boot-9.scm:
|
||
157: 10 [catch #t #<catch-closure 2c76e20> ...]
|
||
In unknown file:
|
||
?: 9 [apply-smob/1 #<catch-closure 2c76e20>]
|
||
In ice-9/boot-9.scm:
|
||
157: 8 [catch #t #<catch-closure 2c76d20> ...]
|
||
In unknown file:
|
||
?: 7 [apply-smob/1 #<catch-closure 2c76d20>]
|
||
?: 6 [call-with-input-string "(display foo)" ...]
|
||
In ice-9/boot-9.scm:
|
||
2320: 5 [save-module-excursion #<procedure 2c2dc30 ... ()>]
|
||
In ice-9/eval-string.scm:
|
||
44: 4 [read-and-eval #<input: string 27cb410> #:lang ...]
|
||
37: 3 [lp (display foo)]
|
||
In ice-9/eval.scm:
|
||
387: 2 [eval # ()]
|
||
393: 1 [eval #<memoized foo> ()]
|
||
In unknown file:
|
||
?: 0 [memoize-variable-access! #<memoized foo> ...]
|
||
|
||
ERROR: In procedure memoize-variable-access!:
|
||
ERROR: Unbound variable: foo
|
||
Error while executing Scheme code.
|
||
|
||
GDB errors that happen in GDB commands invoked by Guile code are
|
||
converted to Guile exceptions. The type of the Guile exception depends
|
||
on the error.
|
||
|
||
Guile procedures provided by GDB can throw the standard Guile
|
||
exceptions like 'wrong-type-arg' and 'out-of-range'.
|
||
|
||
User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) is
|
||
translated to a Guile 'signal' exception with value 'SIGINT'.
|
||
|
||
GDB Guile procedures can also throw these exceptions:
|
||
|
||
'gdb:error'
|
||
This exception is a catch-all for errors generated from within GDB.
|
||
|
||
'gdb:invalid-object'
|
||
This exception is thrown when accessing Guile objects that wrap
|
||
underlying GDB objects have become invalid. For example, a
|
||
'<gdb:breakpoint>' object becomes invalid if the user deletes it
|
||
from the command line. The object still exists in Guile, but the
|
||
object it represents is gone. Further operations on this
|
||
breakpoint will throw this exception.
|
||
|
||
'gdb:memory-error'
|
||
This exception is thrown when an operation tried to access invalid
|
||
memory in the inferior.
|
||
|
||
'gdb:pp-type-error'
|
||
This exception is thrown when a Guile pretty-printer passes a bad
|
||
object to GDB.
|
||
|
||
The following exception-related procedures are provided by the
|
||
'(gdb)' module.
|
||
|
||
-- Scheme Procedure: make-exception key args
|
||
Return a '<gdb:exception>' object given by its KEY and ARGS, which
|
||
are the standard Guile parameters of an exception. See the Guile
|
||
documentation for more information (*note (guile)Exceptions::).
|
||
|
||
-- Scheme Procedure: exception? object
|
||
Return '#t' if OBJECT is a '<gdb:exception>' object. Otherwise
|
||
return '#f'.
|
||
|
||
-- Scheme Procedure: exception-key exception
|
||
Return the ARGS field of a '<gdb:exception>' object.
|
||
|
||
-- Scheme Procedure: exception-args exception
|
||
Return the ARGS field of a '<gdb:exception>' object.
|
||
|
||
|
||
File: gdb.info, Node: Values From Inferior In Guile, Next: Arithmetic In Guile, Prev: Guile Exception Handling, Up: Guile API
|
||
|
||
23.3.3.5 Values From Inferior In Guile
|
||
......................................
|
||
|
||
GDB provides values it obtains from the inferior program in an object of
|
||
type '<gdb:value>'. GDB uses this object for its internal bookkeeping
|
||
of the inferior's values, and for fetching values when necessary.
|
||
|
||
GDB does not memoize '<gdb:value>' objects. 'make-value' always
|
||
returns a fresh object.
|
||
|
||
(gdb) guile (eq? (make-value 1) (make-value 1))
|
||
$1 = #f
|
||
(gdb) guile (equal? (make-value 1) (make-value 1))
|
||
$1 = #t
|
||
|
||
A '<gdb:value>' that represents a function can be executed via
|
||
inferior function call with 'value-call'. Any arguments provided to the
|
||
call must match the function's prototype, and must be provided in the
|
||
order specified by that prototype.
|
||
|
||
For example, 'some-val' is a '<gdb:value>' instance representing a
|
||
function that takes two integers as arguments. To execute this
|
||
function, call it like so:
|
||
|
||
(define result (value-call some-val 10 20))
|
||
|
||
Any values returned from a function call are '<gdb:value>' objects.
|
||
|
||
Note: Unlike Python scripting in GDB, inferior values that are simple
|
||
scalars cannot be used directly in Scheme expressions that are valid for
|
||
the value's data type. For example, '(+ (parse-and-eval "int_variable")
|
||
2)' does not work. And inferior values that are structures or instances
|
||
of some class cannot be accessed using any special syntax, instead
|
||
'value-field' must be used.
|
||
|
||
The following value-related procedures are provided by the '(gdb)'
|
||
module.
|
||
|
||
-- Scheme Procedure: value? object
|
||
Return '#t' if OBJECT is a '<gdb:value>' object. Otherwise return
|
||
'#f'.
|
||
|
||
-- Scheme Procedure: make-value value [#:type type]
|
||
Many Scheme values can be converted directly to a '<gdb:value>'
|
||
with this procedure. If TYPE is specified, the result is a value
|
||
of this type, and if VALUE can't be represented with this type an
|
||
exception is thrown. Otherwise the type of the result is
|
||
determined from VALUE as described below.
|
||
|
||
*Note Architectures In Guile::, for a list of the builtin types for
|
||
an architecture.
|
||
|
||
Here's how Scheme values are converted when TYPE argument to
|
||
'make-value' is not specified:
|
||
|
||
Scheme boolean
|
||
A Scheme boolean is converted the boolean type for the current
|
||
language.
|
||
|
||
Scheme integer
|
||
A Scheme integer is converted to the first of a C 'int',
|
||
'unsigned int', 'long', 'unsigned long', 'long long' or
|
||
'unsigned long long' type for the current architecture that
|
||
can represent the value.
|
||
|
||
If the Scheme integer cannot be represented as a target
|
||
integer an 'out-of-range' exception is thrown.
|
||
|
||
Scheme real
|
||
A Scheme real is converted to the C 'double' type for the
|
||
current architecture.
|
||
|
||
Scheme string
|
||
A Scheme string is converted to a string in the current target
|
||
language using the current target encoding. Characters that
|
||
cannot be represented in the current target encoding are
|
||
replaced with the corresponding escape sequence. This is
|
||
Guile's 'SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE' conversion
|
||
strategy (*note (guile)Strings::).
|
||
|
||
Passing TYPE is not supported in this case, if it is provided
|
||
a 'wrong-type-arg' exception is thrown.
|
||
|
||
'<gdb:lazy-string>'
|
||
If VALUE is a '<gdb:lazy-string>' object (*note Lazy Strings
|
||
In Guile::), then the 'lazy-string->value' procedure is
|
||
called, and its result is used.
|
||
|
||
Passing TYPE is not supported in this case, if it is provided
|
||
a 'wrong-type-arg' exception is thrown.
|
||
|
||
Scheme bytevector
|
||
If VALUE is a Scheme bytevector and TYPE is provided, VALUE
|
||
must be the same size, in bytes, of values of type TYPE, and
|
||
the result is essentially created by using 'memcpy'.
|
||
|
||
If VALUE is a Scheme bytevector and TYPE is not provided, the
|
||
result is an array of type 'uint8' of the same length.
|
||
|
||
-- Scheme Procedure: value-optimized-out? value
|
||
Return '#t' if the compiler optimized out VALUE, thus it is not
|
||
available for fetching from the inferior. Otherwise return '#f'.
|
||
|
||
-- Scheme Procedure: value-address value
|
||
If VALUE is addressable, returns a '<gdb:value>' object
|
||
representing the address. Otherwise, '#f' is returned.
|
||
|
||
-- Scheme Procedure: value-type value
|
||
Return the type of VALUE as a '<gdb:type>' object (*note Types In
|
||
Guile::).
|
||
|
||
-- Scheme Procedure: value-dynamic-type value
|
||
Return the dynamic type of VALUE. This uses C++ run-time type
|
||
information (RTTI) to determine the dynamic type of the value. If
|
||
the value is of class type, it will return the class in which the
|
||
value is embedded, if any. If the value is of pointer or reference
|
||
to a class type, it will compute the dynamic type of the referenced
|
||
object, and return a pointer or reference to that type,
|
||
respectively. In all other cases, it will return the value's
|
||
static type.
|
||
|
||
Note that this feature will only work when debugging a C++ program
|
||
that includes RTTI for the object in question. Otherwise, it will
|
||
just return the static type of the value as in 'ptype foo'. *Note
|
||
ptype: Symbols.
|
||
|
||
-- Scheme Procedure: value-cast value type
|
||
Return a new instance of '<gdb:value>' that is the result of
|
||
casting VALUE to the type described by TYPE, which must be a
|
||
'<gdb:type>' object. If the cast cannot be performed for some
|
||
reason, this method throws an exception.
|
||
|
||
-- Scheme Procedure: value-dynamic-cast value type
|
||
Like 'value-cast', but works as if the C++ 'dynamic_cast' operator
|
||
were used. Consult a C++ reference for details.
|
||
|
||
-- Scheme Procedure: value-reinterpret-cast value type
|
||
Like 'value-cast', but works as if the C++ 'reinterpret_cast'
|
||
operator were used. Consult a C++ reference for details.
|
||
|
||
-- Scheme Procedure: value-dereference value
|
||
For pointer data types, this method returns a new '<gdb:value>'
|
||
object whose contents is the object pointed to by VALUE. For
|
||
example, if 'foo' is a C pointer to an 'int', declared in your C
|
||
program as
|
||
|
||
int *foo;
|
||
|
||
then you can use the corresponding '<gdb:value>' to access what
|
||
'foo' points to like this:
|
||
|
||
(define bar (value-dereference foo))
|
||
|
||
The result 'bar' will be a '<gdb:value>' object holding the value
|
||
pointed to by 'foo'.
|
||
|
||
A similar function 'value-referenced-value' exists which also
|
||
returns '<gdb:value>' objects corresponding to the values pointed
|
||
to by pointer values (and additionally, values referenced by
|
||
reference values). However, the behavior of 'value-dereference'
|
||
differs from 'value-referenced-value' by the fact that the behavior
|
||
of 'value-dereference' is identical to applying the C unary
|
||
operator '*' on a given value. For example, consider a reference
|
||
to a pointer 'ptrref', declared in your C++ program as
|
||
|
||
typedef int *intptr;
|
||
...
|
||
int val = 10;
|
||
intptr ptr = &val;
|
||
intptr &ptrref = ptr;
|
||
|
||
Though 'ptrref' is a reference value, one can apply the method
|
||
'value-dereference' to the '<gdb:value>' object corresponding to it
|
||
and obtain a '<gdb:value>' which is identical to that corresponding
|
||
to 'val'. However, if you apply the method
|
||
'value-referenced-value', the result would be a '<gdb:value>'
|
||
object identical to that corresponding to 'ptr'.
|
||
|
||
(define scm-ptrref (parse-and-eval "ptrref"))
|
||
(define scm-val (value-dereference scm-ptrref))
|
||
(define scm-ptr (value-referenced-value scm-ptrref))
|
||
|
||
The '<gdb:value>' object 'scm-val' is identical to that
|
||
corresponding to 'val', and 'scm-ptr' is identical to that
|
||
corresponding to 'ptr'. In general, 'value-dereference' can be
|
||
applied whenever the C unary operator '*' can be applied to the
|
||
corresponding C value. For those cases where applying both
|
||
'value-dereference' and 'value-referenced-value' is allowed, the
|
||
results obtained need not be identical (as we have seen in the
|
||
above example). The results are however identical when applied on
|
||
'<gdb:value>' objects corresponding to pointers ('<gdb:value>'
|
||
objects with type code 'TYPE_CODE_PTR') in a C/C++ program.
|
||
|
||
-- Scheme Procedure: value-referenced-value value
|
||
For pointer or reference data types, this method returns a new
|
||
'<gdb:value>' object corresponding to the value referenced by the
|
||
pointer/reference value. For pointer data types,
|
||
'value-dereference' and 'value-referenced-value' produce identical
|
||
results. The difference between these methods is that
|
||
'value-dereference' cannot get the values referenced by reference
|
||
values. For example, consider a reference to an 'int', declared in
|
||
your C++ program as
|
||
|
||
int val = 10;
|
||
int &ref = val;
|
||
|
||
then applying 'value-dereference' to the '<gdb:value>' object
|
||
corresponding to 'ref' will result in an error, while applying
|
||
'value-referenced-value' will result in a '<gdb:value>' object
|
||
identical to that corresponding to 'val'.
|
||
|
||
(define scm-ref (parse-and-eval "ref"))
|
||
(define err-ref (value-dereference scm-ref)) ;; error
|
||
(define scm-val (value-referenced-value scm-ref)) ;; ok
|
||
|
||
The '<gdb:value>' object 'scm-val' is identical to that
|
||
corresponding to 'val'.
|
||
|
||
-- Scheme Procedure: value-field value field-name
|
||
Return field FIELD-NAME from '<gdb:value>' object VALUE.
|
||
|
||
-- Scheme Procedure: value-subscript value index
|
||
Return the value of array VALUE at index INDEX. The VALUE argument
|
||
must be a subscriptable '<gdb:value>' object.
|
||
|
||
-- Scheme Procedure: value-call value arg-list
|
||
Perform an inferior function call, taking VALUE as a pointer to the
|
||
function to call. Each element of list ARG-LIST must be a
|
||
<gdb:value> object or an object that can be converted to a value.
|
||
The result is the value returned by the function.
|
||
|
||
-- Scheme Procedure: value->bool value
|
||
Return the Scheme boolean representing '<gdb:value>' VALUE. The
|
||
value must be "integer like". Pointers are ok.
|
||
|
||
-- Scheme Procedure: value->integer
|
||
Return the Scheme integer representing '<gdb:value>' VALUE. The
|
||
value must be "integer like". Pointers are ok.
|
||
|
||
-- Scheme Procedure: value->real
|
||
Return the Scheme real number representing '<gdb:value>' VALUE.
|
||
The value must be a number.
|
||
|
||
-- Scheme Procedure: value->bytevector
|
||
Return a Scheme bytevector with the raw contents of '<gdb:value>'
|
||
VALUE. No transformation, endian or otherwise, is performed.
|
||
|
||
-- Scheme Procedure: value->string value [#:encoding encoding]
|
||
[#:errors errors] [#:length length]
|
||
If VALUE> represents a string, then this method converts the
|
||
contents to a Guile string. Otherwise, this method will throw an
|
||
exception.
|
||
|
||
Values are interpreted as strings according to the rules of the
|
||
current language. If the optional length argument is given, the
|
||
string will be converted to that length, and will include any
|
||
embedded zeroes that the string may contain. Otherwise, for
|
||
languages where the string is zero-terminated, the entire string
|
||
will be converted.
|
||
|
||
For example, in C-like languages, a value is a string if it is a
|
||
pointer to or an array of characters or ints of type 'wchar_t',
|
||
'char16_t', or 'char32_t'.
|
||
|
||
If the optional ENCODING argument is given, it must be a string
|
||
naming the encoding of the string in the '<gdb:value>', such as
|
||
'"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same
|
||
encodings as the corresponding argument to Guile's
|
||
'scm_from_stringn' function, and the Guile codec machinery will be
|
||
used to convert the string. If ENCODING is not given, or if
|
||
ENCODING is the empty string, then either the 'target-charset'
|
||
(*note Character Sets::) will be used, or a language-specific
|
||
encoding will be used, if the current language is able to supply
|
||
one.
|
||
|
||
The optional ERRORS argument is one of '#f', 'error' or
|
||
'substitute'. 'error' and 'substitute' must be symbols. If ERRORS
|
||
is not specified, or if its value is '#f', then the default
|
||
conversion strategy is used, which is set with the Scheme function
|
||
'set-port-conversion-strategy!'. If the value is ''error' then an
|
||
exception is thrown if there is any conversion error. If the value
|
||
is ''substitute' then any conversion error is replaced with
|
||
question marks. *Note (guile)Strings::.
|
||
|
||
If the optional LENGTH argument is given, the string will be
|
||
fetched and converted to the given length. The length must be a
|
||
Scheme integer and not a '<gdb:value>' integer.
|
||
|
||
-- Scheme Procedure: value->lazy-string value [#:encoding encoding]
|
||
[#:length length]
|
||
If this '<gdb:value>' represents a string, then this method
|
||
converts VALUE to a '<gdb:lazy-string' (*note Lazy Strings In
|
||
Guile::). Otherwise, this method will throw an exception.
|
||
|
||
If the optional ENCODING argument is given, it must be a string
|
||
naming the encoding of the '<gdb:lazy-string'. Some examples are:
|
||
'"ascii"', '"iso-8859-6"' or '"utf-8"'. If the ENCODING argument
|
||
is an encoding that GDB does not recognize, GDB will raise an
|
||
error.
|
||
|
||
When a lazy string is printed, the GDB encoding machinery is used
|
||
to convert the string during printing. If the optional ENCODING
|
||
argument is not provided, or is an empty string, GDB will
|
||
automatically select the encoding most suitable for the string
|
||
type. For further information on encoding in GDB please see *note
|
||
Character Sets::.
|
||
|
||
If the optional LENGTH argument is given, the string will be
|
||
fetched and encoded to the length of characters specified. If the
|
||
LENGTH argument is not provided, the string will be fetched and
|
||
encoded until a null of appropriate width is found. The length
|
||
must be a Scheme integer and not a '<gdb:value>' integer.
|
||
|
||
-- Scheme Procedure: value-lazy? value
|
||
Return '#t' if VALUE has not yet been fetched from the inferior.
|
||
Otherwise return '#f'. GDB does not fetch values until necessary,
|
||
for efficiency. For example:
|
||
|
||
(define myval (parse-and-eval "somevar"))
|
||
|
||
The value of 'somevar' is not fetched at this time. It will be
|
||
fetched when the value is needed, or when the 'fetch-lazy'
|
||
procedure is invoked.
|
||
|
||
-- Scheme Procedure: make-lazy-value type address
|
||
Return a '<gdb:value>' that will be lazily fetched from the target.
|
||
The object of type '<gdb:type>' whose value to fetch is specified
|
||
by its TYPE and its target memory ADDRESS, which is a Scheme
|
||
integer.
|
||
|
||
-- Scheme Procedure: value-fetch-lazy! value
|
||
If VALUE is a lazy value ('(value-lazy? value)' is '#t'), then the
|
||
value is fetched from the inferior. Any errors that occur in the
|
||
process will produce a Guile exception.
|
||
|
||
If VALUE is not a lazy value, this method has no effect.
|
||
|
||
The result of this function is unspecified.
|
||
|
||
-- Scheme Procedure: value-print value
|
||
Return the string representation (print form) of '<gdb:value>'
|
||
VALUE.
|
||
|