Next: Exception Handling, Up: Python API [Contents][Index]
At startup, ROCGDB overrides Python’s sys.stdout
and
sys.stderr
to print using ROCGDB’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 ROCGDB. 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, ROCGDB will most likely stop working correctly. Note
that it is unfortunately common for GUI toolkits to install a
SIGCHLD
handler.
ROCGDB introduces a new Python module, named gdb
. All
methods and classes added by ROCGDB are placed in this module.
ROCGDB 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.
A string containing the python directory (see Extending ROCGDB using Python).
Evaluate command, a string, as a ROCGDB CLI command. If a GDB exception happens while command runs, it is translated as described in Exception Handling.
The from_tty flag specifies whether ROCGDB 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
ROCGDB’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
ROCGDB virtual terminal will be temporarily set to unlimited width
and height, and its pagination will be disabled; see Screen Size.
Return a sequence holding all of ROCGDB’s breakpoints.
See Manipulating breakpoints using Python, for more information. In ROCGDB
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.
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.
Return the value of a ROCGDB 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.
Sets the gdb parameter name to value. As with
gdb.parameter
, the parameter name string may contain spaces if
the parameter has a multi-part name.
Create a Python context manager (for use with the Python
with
statement) that temporarily sets the gdb parameter
name to value. On exit from the context, the previous
value will be restored.
This uses gdb.parameter
in its implementation, so it can throw
the same exceptions as that function.
For example, it’s sometimes useful to evaluate some Python code with a particular gdb language:
with gdb.with_parameter('language', 'pascal'): ... language-specific operations
Return a value from ROCGDB’s value history (see Value History). The number argument indicates which history element to return.
If number is negative, then ROCGDB 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 ROCGDB 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).
Takes value, an instance of gdb.Value
(see Values From Inferior), and appends the value this object represents to
ROCGDB’s value history (see Value History), and return an
integer, its history number. If value is not a
gdb.Value
, it is is converted using the gdb.Value
constructor. If value can’t be converted to a gdb.Value
then a TypeError
is raised.
When a command implemented in Python prints a single gdb.Value
as its result, then placing the value into the history will allow the
user convenient access to those values via CLI history facilities.
Return an integer indicating the number of values in ROCGDB’s value history (see Value History).
Return the value of the convenience variable (see Convenience Variables) 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.
Set the value of the convenience variable (see Convenience Variables)
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
(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 CLI Commands In Python, see GDB/MI 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.
Return the gdb.Symtab_and_line
object corresponding to the
pc value. See Symbol table representation 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
ROCGDB’s internal event queue. This callable will be invoked at
some later point, during ROCGDB’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 ROCGDB.
ROCGDB is not thread-safe. If your Python program uses multiple
threads, you must be careful to only call ROCGDB-specific
functions in the ROCGDB 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 ROCGDB’s paginated output stream. The optional stream determines the stream to print to. The default stream is ROCGDB’s standard output stream. Possible stream values are:
gdb.STDOUT
ROCGDB’s standard output stream.
gdb.STDERR
ROCGDB’s standard error stream.
gdb.STDLOG
ROCGDB’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 ROCGDB paginated stream so that the contents are displayed immediately. ROCGDB 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 ROCGDB’s standard output stream. Possible stream values are:
gdb.STDOUT
ROCGDB’s standard output stream.
gdb.STDERR
ROCGDB’s standard error stream.
gdb.STDLOG
ROCGDB’s log stream (see Logging Output).
Flushing sys.stdout
or sys.stderr
will automatically
call this function for the relevant stream.
Return the name of the current target character set (see Character Sets). This differs from gdb.parameter('target-charset')
in
that ‘auto’ is never returned.
Return the name of the current target wide character set
(see Character Sets). This differs from
gdb.parameter('target-wide-charset')
in that ‘auto’ is
never returned.
Return a string, the name of the current host character set
(see Character Sets). This differs from
gdb.parameter('host-charset')
in that ‘auto’ is never
returned.
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.
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 (see Symbol table representation in Python). If expression is
provided, it is decoded the way that ROCGDB’s inbuilt
break
or edit
commands do (see Specifying a Location).
If prompt_hook is callable, ROCGDB will call the method assigned to this operation before a prompt is displayed by ROCGDB.
The parameter current_prompt
contains the current ROCGDB
prompt. This method must return a Python string, or None
. If
a string is returned, the ROCGDB prompt will be set to that
string. If None
is returned, ROCGDB will continue to use
the current prompt.
Some prompts cannot be substituted in ROCGDB. Secondary prompts such as those used by readline for command input, and annotation related prompts are prohibited from being changed.
Return a list containing all of the architecture names that the
current build of ROCGDB supports. Each architecture name is a
string. The names returned in this list are the same names as are
returned from gdb.Architecture.name
(see Architecture.name).
Return a list of gdb.TargetConnection
objects, one for each
currently active connection (see Connections In Python). The
connection objects are in no particular order in the returned list.
Return a string in the format ‘addr <symbol+offset>’, where addr is address formatted in hexadecimal, symbol is the symbol whose address is the nearest to address and below it in memory, and offset is the offset from symbol to address in decimal.
If no suitable symbol was found, then the <symbol+offset> part is not included in the returned string, instead the returned string will just contain the address formatted as hexadecimal. How far ROCGDB looks back for a suitable symbol can be controlled with set print max-symbolic-offset (see Print Settings).
Additionally, the returned string can include file name and line number information when set print symbol-filename on (see Print Settings), in this case the format of the returned string is ‘addr <symbol+offset> at filename:line-number’.
The progspace is the gdb.Progspace in which symbol is looked up, and architecture is used when formatting addr, e.g. in order to determine the size of an address in bytes.
If neither progspace or architecture are passed, then by default ROCGDB will use the program space and architecture of the currently selected inferior, thus, the following two calls are equivalent:
gdb.format_address(address) gdb.format_address(address, gdb.selected_inferior().progspace, gdb.selected_inferior().architecture())
It is not valid to only pass one of progspace or architecture, either they must both be provided, or neither must be provided (and the defaults will be used).
This method uses the same mechanism for formatting address, symbol, and offset information as core ROCGDB does in commands such as disassemble.
Here are some examples of the possible string formats:
0x00001042 0x00001042 <symbol+16> 0x00001042 <symbol+16 at file.c:123>
Next: Exception Handling, Up: Python API [Contents][Index]