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 11This module contains functions to dump Python tracebacks explicitly, on a fault, 12after a timeout, or on a user signal. Call :func:`faulthandler.enable` to 13install 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 16enable them at startup by setting the :envvar:`PYTHONFAULTHANDLER` environment 17variable or by using the :option:`-X` ``faulthandler`` command line option. 18 19The fault handler is compatible with system fault handlers like Apport or the 20Windows fault handler. The module uses an alternative stack for signal handlers 21if the :c:func:`!sigaltstack` function is available. This allows it to dump the 22traceback even on a stack overflow. 23 24The fault handler is called on catastrophic cases and therefore can only use 25signal-safe functions (e.g. it cannot allocate memory on the heap). Because of 26this limitation traceback dumping is minimal compared to normal Python 27tracebacks: 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 37By default, the Python traceback is written to :data:`sys.stderr`. To see 38tracebacks, applications must be run in the terminal. A log file can 39alternatively be passed to :func:`faulthandler.enable`. 40 41The module is implemented in C, so tracebacks can be dumped on a crash or when 42Python is deadlocked. 43 44The :ref:`Python Development Mode <devmode>` calls :func:`faulthandler.enable` 45at 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 55Dumping 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 69Fault 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 104Dumping 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 134Dumping 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 162Issue with file descriptors 163--------------------------- 164 165:func:`enable`, :func:`dump_traceback_later` and :func:`register` keep the 166file descriptor of their *file* argument. If the file is closed and its file 167descriptor is reused by a new file, or if :func:`os.dup2` is used to replace 168the file descriptor, the traceback will be written into a different file. Call 169these functions again each time that the file is replaced. 170 171 172Example 173------- 174 175Example of a segmentation fault on Linux with and without enabling the fault 176handler: 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 192