++++++++++++++++++++++++++++
python-ptrace process events
++++++++++++++++++++++++++++

Process events
==============

All process events are based on ProcessEvent class.

* ProcessExit: process exited with an exitcode, killed by a signal
  or exited abnormally
* ProcessSignal: process received a signal
* NewProcessEvent: new process created, e.g. after a fork() syscall

Attributes:

* All events have a "process" attribute
* ProcessExit has "exitcode" and "signum" attributes (both can be None)
* ProcessSignal has "signum" and "name" attributes

For NewProcessEvent, use process.parent attribute to get the parent process.

Note: ProcessSignal has a display() method to display its content. Use it
just after receiving the message because it reads process memory to analyze
the reasons why the signal was sent.


Wait for any process event
==========================

The most generic function is waitProcessEvent(): it waits for any process
event (exit, signal or new process): ::

   event = debugger.waitProcessEvent()

To wait one or more signals, use waitSignals() methods. With no argument,
it waits for any signal. Events different than signal are raised as
Python exception. Examples: ::

   signal = debugger.waitSignals()
   signal = debugger.waitSignals(SIGTRAP)
   signal = debugger.waitSignals(SIGINT, SIGTERM)

Note: signal is a ProcessSignal object, use signal.signum to get
the signal number.


Wait for a specific process events
==================================

To wait any event from a process, use waitEvent() method: ::

   event = process.waitEvent()

To wait one or more signals, use waitSignals() method. With no argument,
it waits for any signal. Other process events are raised as Python
exception. Examples: ::

   signal = process.waitSignals()
   signal = process.waitSignals(SIGTRAP)
   signal = process.waitSignals(SIGINT, SIGTERM)

Note: As debugger.waitSignals(), signal is a ProcessSignal object.

