Next: Exception Handling, Up: Python API [Contents][Index]
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 (see 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:
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 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.
Evaluate command
, a string, as a GDB CLI command.
If a GDB exception happens while command
runs, it is
translated as described in 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; see Screen Size.
None
if there were no breakpoints. This peculiarity was subsequently fixed, and now gdb.breakpoints
returns an empty sequence in this case.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.
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
(see Exception Handling). Otherwise, the
parameter’s value is converted to a Python value of the appropriate
type, and returned.
Return a value from GDB’s value history (see 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
(see Values From Inferior).
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.
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
(see Values From Inferior), it is is converted using the gdb.Value
constructor.
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 (see 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.
gdb.Symtab_and_line
object corresponding to the pc
value. See 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.
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
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 (see Logging Output).
Writing to sys.stdout
or sys.stderr
will automatically
call this function and will automatically direct the output to the
relevant stream.
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 (see Logging Output).
Flushing sys.stdout
or sys.stderr
will automatically
call this function for the relevant stream.
gdb.parameter('target-charset')
in that ‘auto
’ is never returned.
gdb.parameter('target-wide-charset')
in that ‘auto
’ is never returned.
address
as a string, or None
. This is identical to gdb.current_progspace().solib_name(address)
and is included for historical compatibility.
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 (see Symbol Tables In Python). If expression
is provided, it is decoded the way that GDB’s inbuilt break
or edit
commands do (see Specify Location).
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.
Next: Exception Handling, Up: Python API [Contents][Index]