| 1 |
:mod:`!faulthandler` --- Dump the Python traceback |
| 2 |
================================================== |
| 3 |
|
| 4 |
.. module:: faulthandler |
| 5 |
:synopsis: Dump the Python traceback. |
| 6 |
|
| 7 |
.. versionadded:: 3.3 |
| 8 |
|
| 9 |
---------------- |
| 10 |
|
| 11 |
This module contains functions to dump Python tracebacks explicitly, on a fault, |
| 12 |
after a timeout, or on a user signal. Call :func:`faulthandler.enable` to |
| 13 |
install fault handlers for the :const:`~signal.SIGSEGV`, |
| 14 |
:const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS`, and |
| 15 |
:const:`~signal.SIGILL` signals. You can also |
| 16 |
enable them at startup by setting the :envvar:`PYTHONFAULTHANDLER` environment |
| 17 |
variable or by using the :option:`-X` ``faulthandler`` command line option. |
| 18 |
|
| 19 |
The fault handler is compatible with system fault handlers like Apport or the |
| 20 |
Windows fault handler. The module uses an alternative stack for signal handlers |
| 21 |
if the :c:func:`!sigaltstack` function is available. This allows it to dump the |
| 22 |
traceback even on a stack overflow. |
| 23 |
|
| 24 |
The fault handler is called on catastrophic cases and therefore can only use |
| 25 |
signal-safe functions (e.g. it cannot allocate memory on the heap). Because of |
| 26 |
this limitation traceback dumping is minimal compared to normal Python |
| 27 |
tracebacks: |
| 28 |
|
| 29 |
* Only ASCII is supported. The ``backslashreplace`` error handler is used on |
| 30 |
encoding. |
| 31 |
* Each string is limited to 500 characters. |
| 32 |
* Only the filename, the function name and the line number are |
| 33 |
displayed. (no source code) |
| 34 |
* It is limited to 100 frames and 100 threads. |
| 35 |
* The order is reversed: the most recent call is shown first. |
| 36 |
|
| 37 |
By default, the Python traceback is written to :data:`sys.stderr`. To see |
| 38 |
tracebacks, applications must be run in the terminal. A log file can |
| 39 |
alternatively be passed to :func:`faulthandler.enable`. |
| 40 |
|
| 41 |
The module is implemented in C, so tracebacks can be dumped on a crash or when |
| 42 |
Python is deadlocked. |
| 43 |
|
| 44 |
The :ref:`Python Development Mode <devmode>` calls :func:`faulthandler.enable` |
| 45 |
at Python startup. |
| 46 |
|
| 47 |
.. seealso:: |
| 48 |
|
| 49 |
Module :mod:`pdb` |
| 50 |
Interactive source code debugger for Python programs. |
| 51 |
|
| 52 |
Module :mod:`traceback` |
| 53 |
Standard interface to extract, format and print stack traces of Python programs. |
| 54 |
|
| 55 |
Dumping the traceback |
| 56 |
--------------------- |
| 57 |
|
| 58 |
.. function:: dump_traceback(file=sys.stderr, all_threads=True) |
| 59 |
|
| 60 |
Dump the tracebacks of all threads into *file*. If *all_threads* is |
| 61 |
``False``, dump only the current thread. |
| 62 |
|
| 63 |
.. seealso:: :func:`traceback.print_tb`, which can be used to print a traceback object. |
| 64 |
|
| 65 |
.. versionchanged:: 3.5 |
| 66 |
Added support for passing file descriptor to this function. |
| 67 |
|
| 68 |
|
| 69 |
Fault handler state |
| 70 |
------------------- |
| 71 |
|
| 72 |
.. function:: enable(file=sys.stderr, all_threads=True) |
| 73 |
|
| 74 |
Enable the fault handler: install handlers for the :const:`~signal.SIGSEGV`, |
| 75 |
:const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS` |
| 76 |
and :const:`~signal.SIGILL` |
| 77 |
signals to dump the Python traceback. If *all_threads* is ``True``, |
| 78 |
produce tracebacks for every running thread. Otherwise, dump only the current |
| 79 |
thread. |
| 80 |
|
| 81 |
The *file* must be kept open until the fault handler is disabled: see |
| 82 |
:ref:`issue with file descriptors <faulthandler-fd>`. |
| 83 |
|
| 84 |
.. versionchanged:: 3.5 |
| 85 |
Added support for passing file descriptor to this function. |
| 86 |
|
| 87 |
.. versionchanged:: 3.6 |
| 88 |
On Windows, a handler for Windows exception is also installed. |
| 89 |
|
| 90 |
.. versionchanged:: 3.10 |
| 91 |
The dump now mentions if a garbage collector collection is running |
| 92 |
if *all_threads* is true. |
| 93 |
|
| 94 |
.. function:: disable() |
| 95 |
|
| 96 |
Disable the fault handler: uninstall the signal handlers installed by |
| 97 |
:func:`enable`. |
| 98 |
|
| 99 |
.. function:: is_enabled() |
| 100 |
|
| 101 |
Check if the fault handler is enabled. |
| 102 |
|
| 103 |
|
| 104 |
Dumping the tracebacks after a timeout |
| 105 |
-------------------------------------- |
| 106 |
|
| 107 |
.. function:: dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False) |
| 108 |
|
| 109 |
Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or |
| 110 |
every *timeout* seconds if *repeat* is ``True``. If *exit* is ``True``, call |
| 111 |
:c:func:`!_exit` with status=1 after dumping the tracebacks. (Note |
| 112 |
:c:func:`!_exit` exits the process immediately, which means it doesn't do any |
| 113 |
cleanup like flushing file buffers.) If the function is called twice, the new |
| 114 |
call replaces previous parameters and resets the timeout. The timer has a |
| 115 |
sub-second resolution. |
| 116 |
|
| 117 |
The *file* must be kept open until the traceback is dumped or |
| 118 |
:func:`cancel_dump_traceback_later` is called: see :ref:`issue with file |
| 119 |
descriptors <faulthandler-fd>`. |
| 120 |
|
| 121 |
This function is implemented using a watchdog thread. |
| 122 |
|
| 123 |
.. versionchanged:: 3.5 |
| 124 |
Added support for passing file descriptor to this function. |
| 125 |
|
| 126 |
.. versionchanged:: 3.7 |
| 127 |
This function is now always available. |
| 128 |
|
| 129 |
.. function:: cancel_dump_traceback_later() |
| 130 |
|
| 131 |
Cancel the last call to :func:`dump_traceback_later`. |
| 132 |
|
| 133 |
|
| 134 |
Dumping the traceback on a user signal |
| 135 |
-------------------------------------- |
| 136 |
|
| 137 |
.. function:: register(signum, file=sys.stderr, all_threads=True, chain=False) |
| 138 |
|
| 139 |
Register a user signal: install a handler for the *signum* signal to dump |
| 140 |
the traceback of all threads, or of the current thread if *all_threads* is |
| 141 |
``False``, into *file*. Call the previous handler if chain is ``True``. |
| 142 |
|
| 143 |
The *file* must be kept open until the signal is unregistered by |
| 144 |
:func:`unregister`: see :ref:`issue with file descriptors <faulthandler-fd>`. |
| 145 |
|
| 146 |
Not available on Windows. |
| 147 |
|
| 148 |
.. versionchanged:: 3.5 |
| 149 |
Added support for passing file descriptor to this function. |
| 150 |
|
| 151 |
.. function:: unregister(signum) |
| 152 |
|
| 153 |
Unregister a user signal: uninstall the handler of the *signum* signal |
| 154 |
installed by :func:`register`. Return ``True`` if the signal was registered, |
| 155 |
``False`` otherwise. |
| 156 |
|
| 157 |
Not available on Windows. |
| 158 |
|
| 159 |
|
| 160 |
.. _faulthandler-fd: |
| 161 |
|
| 162 |
Issue with file descriptors |
| 163 |
--------------------------- |
| 164 |
|
| 165 |
:func:`enable`, :func:`dump_traceback_later` and :func:`register` keep the |
| 166 |
file descriptor of their *file* argument. If the file is closed and its file |
| 167 |
descriptor is reused by a new file, or if :func:`os.dup2` is used to replace |
| 168 |
the file descriptor, the traceback will be written into a different file. Call |
| 169 |
these functions again each time that the file is replaced. |
| 170 |
|
| 171 |
|
| 172 |
Example |
| 173 |
------- |
| 174 |
|
| 175 |
Example of a segmentation fault on Linux with and without enabling the fault |
| 176 |
handler: |
| 177 |
|
| 178 |
.. code-block:: shell-session |
| 179 |
|
| 180 |
$ python -c "import ctypes; ctypes.string_at(0)" |
| 181 |
Segmentation fault |
| 182 |
|
| 183 |
$ python -q -X faulthandler |
| 184 |
>>> import ctypes |
| 185 |
>>> ctypes.string_at(0) |
| 186 |
Fatal Python error: Segmentation fault |
| 187 |
|
| 188 |
Current thread 0x00007fb899f39700 (most recent call first): |
| 189 |
File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at |
| 190 |
File "<stdin>", line 1 in <module> |
| 191 |
Segmentation fault |