Next: TUI Windows In Python, Previous: Registers In Python, Up: Python API [Contents][Index]
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 the gdb.TargetConnection object is valid,
False if not. A gdb.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
a Unicode string.
If packet is a Unicode string, then the string is encoded
to a bytes object using the ASCII codec. If the string
can’t be encoded then an UnicodeError is raised.
If packet is not a bytes object, or a Unicode
string, then a TypeError is raised. If packet is empty
then a ValueError is raised.
The response is returned as a bytes object. 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")
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).
Next: TUI Windows In Python, Previous: Registers In Python, Up: Python API [Contents][Index]