Next: TUI Windows In Python, 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).