Example

Example of a segmentation fault on Linux:

$ python
>>> import faulthandler
>>> faulthandler.enable()
>>> faulthandler._sigsegv()
Fatal Python error: Segmentation fault

Traceback (most recent call first):
  File "<stdin>", line 1 in <module>
Segmentation fault

Installation

To install faulthandler module, type the following command:

python setup.py install

Then you can test your setup using the following command:

python tests.py

You need a C compiler (eg. gcc) and Python headers to build the faulthandler module. Eg. on Fedora, you have to install python-devel package (sudo yum install python-devel).

faulthandler module API

There are 4 different ways to display the Python traceback:

• enable(): on a crash
• dump_tracebacks_later(): after a timeout (useful if your program hangs)
• register(): by sending a signal (eg. SIGUSR1). It doesn't work on Windows.
• dump_traceback(): explicitly

Fault handler state (disabled by default):

• enable(file=sys.stderr, all_threads=False): enable the fault handler
• disable(): disable the fault handler
• is_enabled(): get the status of the fault handler

Dump the current traceback:

• dump_traceback(file=sys.stderr, all_threads=False): dump traceback of the current thread, or of all threads if all_threads is True, into file
• dump_tracebacks_later(timeout, repeat=False, file=sys.stderr, exit=False): dump the traceback of all threads in timeout seconds, or each timeout seconds if repeat is True. If the function is called twice, the new call replaces previous parameters. Exit immediatly if exit is True.
• cancel_dump_tracebacks_later(): cancel the previous call to dump_tracebacks_later()

dump_tracebacks_later() is implemented using the SIGALRM signal and the alarm() function: if the signal handler is called during a system call, the system call is interrupted (return EINTR). It it not available on Windows.

enable() and dump_tracebacks_later() keep an internal reference to the output file. Use disable() and cancel_dump_tracebacks_later() to clear this reference.

Dump the traceback on an user signal:

• register(signum, file=sys.stderr, all_threads=False): register an handler for the signal 'signum': dump the traceback of the current thread, or of all threads if all_threads is True, into file". Not available on Windows.
• unregister(signum): unregister the handler of the signal 'signum' registered by register(). Not available on Windows.

Functions to test the fault handler:

• _fatal_error(message): Exit Python with a fatal error, call Py_FatalError() with message.
• _read_null(): read from the NULL pointer (raise SIGSEGV or SIGBUS depending on the platform)
• _sigabrt(): raise a SIGABRT signal (Aborted)
• _sigbus(): raise a SIGBUS signal (Bus error)
• _sigfpe(): raise a SIGFPE signal (Floating point exception), do a division by zero
• _sigill(): raise a SIGILL signal (Illegal instruction)
• _sigsegv(): raise a SIGSEGV signal (Segmentation fault), read memory from NULL (address 0)
• _stack_overflow(): raise a stack overflow error. Not available on all platforms.

register(), unregister(), sigbus() and sigill() are not available on all operation systems.

faulthandler.version_info is the module version as a tuple: (major, minor), faulthandler.__version__ is the module version a string (e.g. "2.0").

Changelog

Status

• 2011-01-31: Version 1.2 tested with Python 2.5, 2.6, 2.7, 3.1 and 3.2 on Debian Sid
• 2010-12-24: Tested with Python 2.6, 3.1 and 3.2 on Debian Sid
• 2010-12-24: Tested with Python 2.6 and 3.1 on Windows XP

Similar projects

Python debuggers:

• tipper: write the traceback of the current thread into a file on SIGUSR1 signal: http://pypi.python.org/pypi/tipper/
• crier: write the traceback of the current thread into a file (eg. /tmp/dump-<pid>) if a "request" file is created (eg. /tmp/crier-<pid>). Implemented using a thread. https://gist.github.com/737056
• Python WAD (Wrapped Application Debugger), not update since 2001: http://www.dabeaz.com/papers/Python2001/python.html

Application fault handlers:

• The GNU libc has a fault handler in debug/segfault.c
• XEmacs has a fault handler displaying the Lisp traceback
• RPy has a fault handler

System-wide fault handlers:

• Ubuntu uses Apport: https://wiki.ubuntu.com/Apport
• The Linux kernel logs also segfaults into /var/log/kern.log (and /var/log/syslog). /proc/sys/kernel/core_pattern contols how coredumps are created.
• Windows opens a popup on a fatal error asking if the error should be reported to Microsoft

See also

• http://bugs.python.org/issue8863 (may 2010): Display Python backtrace on SIGSEGV, SIGFPE and fatal error
• http://bugs.python.org/issue3999 (sept. 2008): Real segmentation fault handler