Debugging with GDB: Inferiors In Python

Next: Events In Python, Previous: Writing an Xmethod, Up: Python API [Contents][Index]

#### 23.3.2.16 Inferiors In Python

Programs which are being run under GDB are called inferiors (see Inferiors Connections and Programs). Python scripts can access information about and manipulate inferiors controlled by GDB via objects of the `gdb.Inferior` class.

The following inferior-related functions are available in the `gdb` module:

Function: gdb.inferiors ()

  Return a tuple containing all inferior objects.

Function: gdb.selected_inferior ()

  Return an object representing the current inferior.

A `gdb.Inferior` object has the following attributes:

Variable: Inferior.num

  ID of inferior, as assigned by GDB.

Variable: Inferior.connection_num

  ID of inferior’s connection as assigned by GDB, or None if the inferior is not connected to a target. See Inferiors Connections and Programs.

Variable: Inferior.pid

  Process ID of the inferior, as assigned by the underlying operating system.

Variable: Inferior.was_attached

  Boolean signaling whether the inferior was created using ‘attach’, or started by GDB itself.

Variable: Inferior.progspace

  The inferior’s program space. See Progspaces In Python.

A `gdb.Inferior` object has the following methods:

Function: Inferior.is_valid ()

  Returns `True` if the `gdb.Inferior` object is valid, `False` if not. A `gdb.Inferior` object will become invalid if the inferior no longer exists within GDB. All other `gdb.Inferior` methods will throw an exception if it is invalid at the time the method is called.

Function: Inferior.threads ()

  This method returns a tuple holding all the threads which are valid when it is called. If there are no valid threads, the method will return an empty tuple.

Function: Inferior.architecture ()

  Return the `gdb.Architecture` (see Architectures In Python) for this inferior. This represents the architecture of the inferior as a whole. Some platforms can have multiple architectures in a single address space, so this may not match the architecture of a particular frame (see Frames In Python).

Function: Inferior.read_memory (address, length)

  Read length addressable memory units from the inferior, starting at address. Returns a buffer object, which behaves much like an array or a string. It can be modified and given to the `Inferior.write_memory` function. In Python 3, the return value is a `memoryview` object.

Function: Inferior.write_memory (address, buffer [, length])

  Write the contents of buffer to the inferior, starting at address. The buffer parameter must be a Python object which supports the buffer protocol, i.e., a string, an array or the object returned from `Inferior.read_memory`. If given, length determines the number of addressable memory units from buffer to be written.

Function: Inferior.search_memory (address, length, pattern)

  Search a region of the inferior memory starting at address with the given length using the search pattern supplied in pattern. The pattern parameter must be a Python object which supports the buffer protocol, i.e., a string, an array or the object returned from `gdb.read_memory`. Returns a Python `Long` containing the address where the pattern was found, or `None` if the pattern could not be found.

Function: Inferior.thread_from_handle (handle)

  Return the thread object corresponding to handle, a thread library specific data structure such as `pthread_t` for pthreads library implementations.

  The function `Inferior.thread_from_thread_handle` provides the same functionality, but use of `Inferior.thread_from_thread_handle` is deprecated.

Next: Events In Python, Previous: Writing an Xmethod, Up: Python API [Contents][Index]