Skip to content

events ¤

Enables callbacks into functions to be automatically invoked when various events occur to the debuggee (e.g. STOP on SIGINT) by using a decorator.

Classes:

Functions:

Attributes:

DISABLED module-attribute ¤

DISABLED = 'disabled'

DISABLED_DEADLOCK module-attribute ¤

DISABLED_DEADLOCK = 'disabled-deadlock'

ENABLED module-attribute ¤

ENABLED = 'enabled'

debug module-attribute ¤

debug = add_param(
    "debug-events", False, "display internal event debugging info"
)

gdb_workaround_stop_event module-attribute ¤

gdb_workaround_stop_event = add_param('gdb-workaround-stop-event', DISABLED, "asynchronous stop events to improve 'commands' functionality", help_docstring=f'
Note that this may cause unexpected behavior with Pwndbg or gdb.execute.

Values explained:

+ `{DISABLED}` - Disable the workaround (default).
+ `{DISABLED_DEADLOCK}` - Disable only deadlock detection; deadlocks may still occur.
+ `{ENABLED}` - Enable asynchronous stop events; gdb.execute may behave unexpectedly (asynchronously).
    ', param_class=PARAM_ENUM, enum_sequence=[DISABLED, DISABLED_DEADLOCK, ENABLED])

P module-attribute ¤

P = ParamSpec('P')

T module-attribute ¤

T = TypeVar('T')

queued_events module-attribute ¤

queued_events: Deque[Callable[..., Any]] = deque()

executing_event module-attribute ¤

executing_event = False

workaround_thread_conn module-attribute ¤

workaround_thread_conn = None

registered module-attribute ¤

registered: dict[Any, dict[HandlerPriority, list[Callable[..., Any]]]] = {
    exited: {},
    cont: {},
    new_objfile: {},
    stop: {},
    start: {},
    new_thread: {},
    before_prompt: {},
    memory_changed: {},
    register_changed: {},
}

connected module-attribute ¤

connected = {}

paused module-attribute ¤

paused = defaultdict(bool)

StartEvent ¤

StartEvent()

Methods:

Attributes:

registered instance-attribute ¤

registered: list[Callable[..., Any]] = []

running instance-attribute ¤

running = False

connect ¤

connect(function: Callable[..., Any]) -> None

disconnect ¤

disconnect(function: Callable[..., Any]) -> None

on_new_objfile ¤

on_new_objfile() -> None

on_exited ¤

on_exited() -> None

on_stop ¤

on_stop() -> None

HandlerPriority ¤

Bases: Enum

A priority level for an event handler, ordered from highest to lowest priority.

Attributes:

CACHE_CLEAR class-attribute instance-attribute ¤

CACHE_CLEAR = auto()

LOW class-attribute instance-attribute ¤

LOW = auto()

wrap_safe_event_handler ¤

wrap_safe_event_handler(
    event_handler: Callable[P, T], event_type: Any
) -> Callable[P, T]

Wraps an event handler to ensure it is only executed when the event is safe. Invalid events are queued and executed later when safe.

Note: Avoid using gdb.post_event because of another bug in gdbserver where the gdb.newest_frame function may not work properly.

Workaround to fix bug in gdbserver (gdb.events.new_objfile): #2576 Workaround to fix bug in gdb (gdb.events.stop): #425

pause ¤

pause(event_registry) -> None

unpause ¤

unpause(event_registry) -> None

connect ¤

connect(
    func: Callable[[], T],
    event_handler: Any,
    name: str = "",
    priority: HandlerPriority = LOW,
) -> Callable[[], T]

exit ¤

exit(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

cont ¤

cont(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

new_objfile ¤

new_objfile(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

stop ¤

stop(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

start ¤

start(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

thread ¤

thread(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

before_prompt ¤

before_prompt(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

reg_changed ¤

reg_changed(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

mem_changed ¤

mem_changed(func: Callable[[], T], **kwargs: Any) -> Callable[[], T]

log_objfiles ¤

log_objfiles(ofile: NewObjFileEvent | None = None) -> None

invoke_event ¤

invoke_event(event: Any, *args: Any, **kwargs: Any) -> None

after_reload ¤

after_reload(fire_start: bool = True) -> None

on_reload ¤

on_reload() -> None