Next: TUI Windows In Python, Previous: Registers In Python, Up: Python API
gdb lets you run and debug multiple programs in a single session. Each program being debugged has a connection, the connection describes how gdb controls the program being debugged. Examples of different connection types are `native' and `remote'. See Inferiors Connections and Programs.
Connections in gdb are represented as instances of
gdb.TargetConnection
, or as one of its sub-classes. To get a
list of all connections use gdb.connections
(see gdb.connections).
To get the connection for a single gdb.Inferior
read its
gdb.Inferior.connection
attribute
(see gdb.Inferior.connection).
Currently there is only a single sub-class of
gdb.TargetConnection
, gdb.RemoteTargetConnection
,
however, additional sub-classes may be added in future releases of
gdb. As a result you should avoid writing code like:
conn = gdb.selected_inferior().connection if type(conn) is gdb.RemoteTargetConnection: print("This is a remote target connection")
as this may fail when more connection types are added. Instead, you should write:
conn = gdb.selected_inferior().connection if isinstance(conn, gdb.RemoteTargetConnection): print("This is a remote target connection")
A gdb.TargetConnection
has the following method:
Return
True
if thegdb.TargetConnection
object is valid,False
if not. Agdb.TargetConnection
will become invalid if the connection no longer exists within gdb, this might happen when no inferiors are using the connection, but could be delayed until the user replaces the current target.Reading any of the
gdb.TargetConnection
properties will throw an exception if the connection is invalid.
A gdb.TargetConnection
has the following read-only properties:
An integer assigned by gdb to uniquely identify this connection. This is the same value as displayed in the `Num' column of the
info connections
command output (see info connections).
A string that describes what type of connection this is. This string will be one of the valid names that can be passed to the
target
command (see target command).
A string that gives a short description of this target type. This is the same string that is displayed in the `Description' column of the
info connection
command output (see info connections).
An optional string that gives additional information about this connection. This attribute can be
None
if there are no additional details for this connection.An example of a connection type that might have additional details is the `remote' connection, in this case the details string can contain the `hostname:port' that was used to connect to the remote target.
The gdb.RemoteTargetConnection
class is a sub-class of
gdb.TargetConnection
, and is used to represent `remote'
and `extended-remote' connections. In addition to the attributes
and methods available from the gdb.TargetConnection
base class,
a gdb.RemoteTargetConnection
has the following method:
This method sends packet to the remote target and returns the response. The packet should either be a
bytes
object, or aUnicode
string.If packet is a
Unicode
string, then the string is encoded to abytes
object using the ascii codec. If the string can't be encoded then anUnicodeError
is raised.If packet is not a
bytes
object, or aUnicode
string, then aTypeError
is raised. If packet is empty then aValueError
is raised.The response is returned as a
bytes
object. For Python 3 if it is known that the response can be represented as a string then this can be decoded from the buffer. For example, if it is known that the response is an ascii string:remote_connection.send_packet("some_packet").decode("ascii")In Python 2
bytes
andstr
are aliases, so the result is already a string, if the response includes non-printable characters, or null characters, then these will be present in the result, care should be taken when processing the result to handle this case.The prefix, suffix, and checksum (as required by the remote serial protocol) are automatically added to the outgoing packet, and removed from the incoming packet before the contents of the reply are returned.
This is equivalent to the
maintenance packet
command (see maint packet).