mirror of https://github.com/python/cpython
137 lines
4.8 KiB
ReStructuredText
137 lines
4.8 KiB
ReStructuredText
:mod:`faulthandler` --- Dump the Python traceback
|
|
=================================================
|
|
|
|
.. module:: faulthandler
|
|
:synopsis: Dump the Python traceback.
|
|
|
|
This module contains functions to dump Python tracebacks explicitly, on a fault,
|
|
after a timeout, or on a user signal. Call :func:`faulthandler.enable` to
|
|
install fault handlers for the :const:`SIGSEGV`, :const:`SIGFPE`,
|
|
:const:`SIGABRT`, :const:`SIGBUS`, and :const:`SIGILL` signals. You can also
|
|
enable them at startup by setting the :envvar:`PYTHONFAULTHANDLER` environment
|
|
variable or by using :option:`-X` ``faulthandler`` command line option.
|
|
|
|
The fault handler is compatible with system fault handlers like Apport or the
|
|
Windows fault handler. The module uses an alternative stack for signal handlers
|
|
if the :c:func:`sigaltstack` function is available. This allows it to dump the
|
|
traceback even on a stack overflow.
|
|
|
|
The fault handler is called on catastrophic cases and therefore can only use
|
|
signal-safe functions (e.g. it cannot allocate memory on the heap). Because of
|
|
this limitation traceback dumping is minimal compared to normal Python
|
|
tracebacks:
|
|
|
|
* Only ASCII is supported. The ``backslashreplace`` error handler is used on
|
|
encoding.
|
|
* Each string is limited to 500 characters.
|
|
* Only the filename, the function name and the line number are
|
|
displayed. (no source code)
|
|
* It is limited to 100 frames and 100 threads.
|
|
|
|
By default, the Python traceback is written to :data:`sys.stderr`. To see
|
|
tracebacks, applications must be run in the terminal. A log file can
|
|
alternatively be passed to :func:`faulthandler.enable`.
|
|
|
|
The module is implemented in C, so tracebacks can be dumped on a crash or when
|
|
Python is deadlocked.
|
|
|
|
.. versionadded:: 3.3
|
|
|
|
|
|
Dump the traceback
|
|
------------------
|
|
|
|
.. function:: dump_traceback(file=sys.stderr, all_threads=True)
|
|
|
|
Dump the tracebacks of all threads into *file*. If *all_threads* is
|
|
``False``, dump only the current thread.
|
|
|
|
|
|
Fault handler state
|
|
-------------------
|
|
|
|
.. function:: enable(file=sys.stderr, all_threads=True)
|
|
|
|
Enable the fault handler: install handlers for the :const:`SIGSEGV`,
|
|
:const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and :const:`SIGILL`
|
|
signals to dump the Python traceback. If *all_threads* is ``True``,
|
|
produce tracebacks for every running thread. Otherwise, dump only the current
|
|
thread.
|
|
|
|
.. function:: disable()
|
|
|
|
Disable the fault handler: uninstall the signal handlers installed by
|
|
:func:`enable`.
|
|
|
|
.. function:: is_enabled()
|
|
|
|
Check if the fault handler is enabled.
|
|
|
|
|
|
Dump the tracebacks after a timeout
|
|
-----------------------------------
|
|
|
|
.. function:: dump_tracebacks_later(timeout, repeat=False, file=sys.stderr, exit=False)
|
|
|
|
Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or
|
|
every *timeout* seconds if *repeat* is ``True``. If *exit* is ``True``, call
|
|
:c:func:`_exit` with status=1 after dumping the tracebacks. (Note
|
|
:c:func:`_exit` exits the process immediately, which means it doesn't do any
|
|
cleanup like flushing file buffers.) If the function is called twice, the new
|
|
call replaces previous parameters and resets the timeout. The timer has a
|
|
sub-second resolution.
|
|
|
|
This function is implemented using a watchdog thread and therefore is not
|
|
available if Python is compiled with threads disabled.
|
|
|
|
.. function:: cancel_dump_tracebacks_later()
|
|
|
|
Cancel the last call to :func:`dump_tracebacks_later`.
|
|
|
|
|
|
Dump the traceback on a user signal
|
|
-----------------------------------
|
|
|
|
.. function:: register(signum, file=sys.stderr, all_threads=True, chain=False)
|
|
|
|
Register a user signal: install a handler for the *signum* signal to dump
|
|
the traceback of all threads, or of the current thread if *all_threads* is
|
|
``False``, into *file*. Call the previous handler if chain is ``True``.
|
|
|
|
Not available on Windows.
|
|
|
|
.. function:: unregister(signum)
|
|
|
|
Unregister a user signal: uninstall the handler of the *signum* signal
|
|
installed by :func:`register`. Return ``True`` if the signal was registered,
|
|
``False`` otherwise.
|
|
|
|
Not available on Windows.
|
|
|
|
|
|
File descriptor issue
|
|
---------------------
|
|
|
|
:func:`enable`, :func:`dump_tracebacks_later` and :func:`register` keep the
|
|
file descriptor of their *file* argument. If the file is closed and its file
|
|
descriptor is reused by a new file, or if :func:`os.dup2` is used to replace
|
|
the file descriptor, the traceback will be written into a different file. Call
|
|
these functions again each time that the file is replaced.
|
|
|
|
|
|
Example
|
|
-------
|
|
|
|
Example of a segmentation fault on Linux: ::
|
|
|
|
$ python -q -X faulthandler
|
|
>>> import ctypes
|
|
>>> ctypes.string_at(0)
|
|
Fatal Python error: Segmentation fault
|
|
|
|
Current thread 0x00007fb899f39700:
|
|
File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
|
|
File "<stdin>", line 1 in <module>
|
|
Segmentation fault
|
|
|