Expositor is scriptable time-travel debugging Python library for GDB/UndoDB.


Expositor requires UndoDB, and works best with a recent version of GDB that supports the python-interactive command (available in the CVS repository after August 22, 2012; should be released in GDB 7.6).


Currently, Expositor only debugs 32-bit applications on Linux.

Differences from ICSE paper

The design of Expositor is described in the ICSE 2013 paper; however, there are numerous API differences:

  1. The object the_execution in the paper is simply named execution in actual Expositor.

  2. The methods the_execution.cont and the_execution.get_time in the paper corresponds to execution.controller.cont and execution.controller.get_time in actual Expositor. See Source/Expositor/UndoDB/Controller.py.

  3. The method snapshot.read_retaddrs in the paper roughly corresponds to snapshot.pcs in actual Expositor: where read_retaddrs corresponds to a list of return address r-values on the stack, snapshot.pcs corresponds to a list of the current instruction pointer l-value as well as the return address l-values (i.e., values on the stack already casted to Python long). See Source/Expositor/UndoDB/Controller.py.

  4. The paper describes time as represented as a floating-point number, whereas in actual Expositor, time is represented as a tuple time ( virtual_nanosecond, block_instruction_pointer ) to avoid the costly conversion to floating-point time. Floating-point time is still accepted by Expositor, and will be automatically converted to the appropriate tuple time (particularly convenient for, e.g., foo.get_after(0)).

  5. The paper describes the item class as having the field time, whereas in Expositor, it is split into two fields, lower and upper, with lower corresponding to time, and upper to the lower bound of the next item in the trace.

  6. The paper describes the EditHAMT data structure as a single class with factory class methods, however, in actual Expositor, it is implemented as a Scala-style class cluster under the Python module Expositor.EditSetMap. See Source/Expositor/UndoDB/EditSetMap.


  1. Run Expositor's tests (optionally providing paths to undodb-gdb and gdb):

    env \
        EXPOSITOR_UNDODB=optional-path-to-undodb-gdb \
        EXPOSITOR_GDB=optional-path-to-gdb \
        make test
  2. Start Expositor on <program-to-debug> (optionally providing paths to undodb-gdb and gdb):

    env \
        EXPOSITOR_UNDODB=optional-path-to-undodb-gdb \
        EXPOSITOR_GDB=optional-path-to-gdb \
        Source/expositor-undodb <program-to-debug>
  3. In Expositor (GDB), enter the Python interactive prompt:

    (expositor-undodb) python-interactive

    or more concisely:

    (expositor-undodb) pi
  4. Create a breakpoint trace and query it:

    >>> foo = execution.breakpoints("foo")
    >>> s = foo.get_after(0)
    >>> print s


Confererence papers

Expositor: Scriptable time-travel debugging with First Class Traces. Khoo Yit Phang, Jeffrey S. Foster, and Michael Hicks. In Proceedings of the International Conference on Software Engineering (ICSE), May 2013. Preprint (Presentation).