Inferiors In Python (Debugging with GDB)
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 thegdb.Inferior
object is valid,False
if not. Agdb.Inferior
object will become invalid if the inferior no longer exists within GDB. All othergdb.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 ataddress
. Returns a buffer object, which behaves much like an array or a string. It can be modified and given to theInferior.write_memory
function. In Python 3, the return value is amemoryview
object.
- Function
- Inferior.write_memory (address, buffer [, length])
- Write the contents of
buffer
to the inferior, starting ataddress
. Thebuffer
parameter must be a Python object which supports the buffer protocol, i.e., a string, an array or the object returned fromInferior.read_memory
. If given,length
determines the number of addressable memory units frombuffer
to be written.
- Function
- Inferior.search_memory (address, length, pattern)
- Search a region of the inferior memory starting at
address
with the givenlength
using the search pattern supplied inpattern
. Thepattern
parameter must be a Python object which supports the buffer protocol, i.e., a string, an array or the object returned fromgdb.read_memory
. Returns a PythonLong
containing the address where the pattern was found, orNone
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 aspthread_t
for pthreads library implementations.The function
Inferior.thread_from_thread_handle
provides the same functionality, but use ofInferior.thread_from_thread_handle
is deprecated.
Next: Events In Python, Previous: Writing an Xmethod, Up: Python API [Contents][Index]