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