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