Next: , Previous: Registers In Python, Up: Python API

23.3.2.36 Connections In Python

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:

— Function: TargetConnection.is_valid ()

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:

— Variable: TargetConnection.num

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).

— Variable: TargetConnection.type

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).

— Variable: TargetConnection.description

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).

— Variable: TargetConnection.details

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:

— Function: RemoteTargetConnection.send_packet (packet)

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. 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 and str 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).