gdb provides a general event facility so that Python code can be notified of various state changes, particularly changes that occur in the inferior.
An event is just an object that describes some state change. The type of the object and its attributes will vary depending on the details of the change. All the existing events are described below.
In order to be notified of an event, you must register an event handler
with an event registry. An event registry is an object in the
gdb.events module which dispatches particular events. A registry
provides methods to register and unregister event handlers:
Add the given callable object to the registry. This object will be called when an event corresponding to this registry occurs.
Remove the given object from the registry. Once removed, the object will no longer receive notifications of events.
Here is an example:
def exit_handler (event): print "event type: exit" print "exit code: %d" % (event.exit_code) gdb.events.exited.connect (exit_handler)
In the above example we connect our handler
exit_handler to the
events.exited. Once connected,
called when the inferior exits. The argument event in this example is
gdb.ExitedEvent. As you can see in the example the
ExitedEvent object has an attribute which indicates the exit code of
The following is a listing of the event registries that are available and details of the events they emit:
Some events can be thread specific when gdb is running in non-stop
mode. When represented in Python, these events all extend
gdb.ThreadEvent. Note, this event is not emitted directly; instead,
events which are emitted by this or other modules might extend this event.
Examples of these events are
In non-stop mode this attribute will be set to the specific thread which was involved in the emitted event. Otherwise, it will be set to
gdb.ContinueEvent which extends
This event indicates that the inferior has been continued after a stop. For
inherited attribute refer to
events.ExitedEventwhich indicates that the inferior has exited.
events.ExitedEventhas two attributes:
An integer representing the exit code, if available, which the inferior has returned. (The exit code could be unavailable if, for example, gdb detaches from the inferior.) If the exit code is unavailable, the attribute does not exist.
Indicates that the inferior has stopped. All events emitted by this registry
extend StopEvent. As a child of
will indicate the stopped thread when gdb is running in non-stop
mode. Refer to
gdb.ThreadEvent above for more details.
gdb.SignalEvent which extends
This event indicates that the inferior or one of its threads has received as
gdb.SignalEvent has the following attributes:
A string representing the signal received by the inferior. A list of possible signal values can be obtained by running the command
info signalsin the gdb command prompt.
gdb.BreakpointEvent which extends
gdb.BreakpointEvent event indicates that one or more breakpoints have
been hit, and has the following attributes:
A sequence containing references to all the breakpoints (type
gdb.Breakpoint) that were hit. See Breakpoints In Python, for details of the
A reference to the first breakpoint that was hit. This function is maintained for backward compatibility and is now deprecated in favor of the
gdb.NewObjFileEventwhich indicates that a new object file has been loaded by gdb.
gdb.NewObjFileEventhas one attribute:
A reference to the object file (
gdb.Objfile) which has been loaded. See Objfiles In Python, for details of the
gdb.ClearObjFilesEventwhich indicates that the list of object files for a program space has been reset.
gdb.ClearObjFilesEventhas one attribute:
A reference to the program space (
gdb.Progspace) whose objfile list has been cleared. See Progspaces In Python.
gdb.InferiorCallPreEventwhich indicates that a function in the inferior is about to be called.
gdb.InferiorCallPostEventwhich indicates that a function in the inferior has returned.
gdb.MemoryChangedEventwhich indicates that the memory of the inferior has been modified by the gdb user, for instance via a command like
set *addr = value. The event has the following attributes:
gdb.RegisterChangedEventwhich indicates that a register in the inferior has been modified by the gdb user.
A gdb.Frame object representing the frame in which the register was modified.