Debian Codegraph @

Doc/library/faulthandler.rst

raw
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 Dumping the C stack
70 -------------------
71
72 .. versionadded:: 3.14
73
74 .. function:: dump_c_stack(file=sys.stderr)
75
76 Dump the C stack trace of the current thread into *file*.
77
78 If the Python build does not support it or the operating system
79 does not provide a stack trace, then this prints an error in place
80 of a dumped C stack.
81
82 .. _c-stack-compatibility:
83
84 C Stack Compatibility
85 *********************
86
87 If the system does not support the C-level :manpage:`backtrace(3)`
88 or :manpage:`dladdr1(3)`, then C stack dumps will not work.
89 An error will be printed instead of the stack.
90
91 Additionally, some compilers do not support :term:`CPython's <CPython>`
92 implementation of C stack dumps. As a result, a different error may be printed
93 instead of the stack, even if the operating system supports dumping stacks.
94
95 .. note::
96
97 Dumping C stacks can be arbitrarily slow, depending on the DWARF level
98 of the binaries in the call stack.
99
100 Fault handler state
101 -------------------
102
103 .. function:: enable(file=sys.stderr, all_threads=True, c_stack=True)
104
105 Enable the fault handler: install handlers for the :const:`~signal.SIGSEGV`,
106 :const:`~signal.SIGFPE`, :const:`~signal.SIGABRT`, :const:`~signal.SIGBUS`
107 and :const:`~signal.SIGILL`
108 signals to dump the Python traceback. If *all_threads* is ``True``,
109 produce tracebacks for every running thread. Otherwise, dump only the current
110 thread.
111
112 The *file* must be kept open until the fault handler is disabled: see
113 :ref:`issue with file descriptors <faulthandler-fd>`.
114
115 If *c_stack* is ``True``, then the C stack trace is printed after the Python
116 traceback, unless the system does not support it. See :func:`dump_c_stack` for
117 more information on compatibility.
118
119 .. versionchanged:: 3.5
120 Added support for passing file descriptor to this function.
121
122 .. versionchanged:: 3.6
123 On Windows, a handler for Windows exception is also installed.
124
125 .. versionchanged:: 3.10
126 The dump now mentions if a garbage collector collection is running
127 if *all_threads* is true.
128
129 .. versionchanged:: 3.14
130 Only the current thread is dumped if the :term:`GIL` is disabled to
131 prevent the risk of data races.
132
133 .. versionchanged:: 3.14
134 The dump now displays the C stack trace if *c_stack* is true.
135
136 .. function:: disable()
137
138 Disable the fault handler: uninstall the signal handlers installed by
139 :func:`enable`.
140
141 .. function:: is_enabled()
142
143 Check if the fault handler is enabled.
144
145
146 Dumping the tracebacks after a timeout
147 --------------------------------------
148
149 .. function:: dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)
150
151 Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or
152 every *timeout* seconds if *repeat* is ``True``. If *exit* is ``True``, call
153 :c:func:`!_exit` with status=1 after dumping the tracebacks. (Note
154 :c:func:`!_exit` exits the process immediately, which means it doesn't do any
155 cleanup like flushing file buffers.) If the function is called twice, the new
156 call replaces previous parameters and resets the timeout. The timer has a
157 sub-second resolution.
158
159 The *file* must be kept open until the traceback is dumped or
160 :func:`cancel_dump_traceback_later` is called: see :ref:`issue with file
161 descriptors <faulthandler-fd>`.
162
163 This function is implemented using a watchdog thread.
164
165 .. versionchanged:: 3.5
166 Added support for passing file descriptor to this function.
167
168 .. versionchanged:: 3.7
169 This function is now always available.
170
171 .. function:: cancel_dump_traceback_later()
172
173 Cancel the last call to :func:`dump_traceback_later`.
174
175
176 Dumping the traceback on a user signal
177 --------------------------------------
178
179 .. function:: register(signum, file=sys.stderr, all_threads=True, chain=False)
180
181 Register a user signal: install a handler for the *signum* signal to dump
182 the traceback of all threads, or of the current thread if *all_threads* is
183 ``False``, into *file*. Call the previous handler if chain is ``True``.
184
185 The *file* must be kept open until the signal is unregistered by
186 :func:`unregister`: see :ref:`issue with file descriptors <faulthandler-fd>`.
187
188 Not available on Windows.
189
190 .. versionchanged:: 3.5
191 Added support for passing file descriptor to this function.
192
193 .. function:: unregister(signum)
194
195 Unregister a user signal: uninstall the handler of the *signum* signal
196 installed by :func:`register`. Return ``True`` if the signal was registered,
197 ``False`` otherwise.
198
199 Not available on Windows.
200
201
202 .. _faulthandler-fd:
203
204 Issue with file descriptors
205 ---------------------------
206
207 :func:`enable`, :func:`dump_traceback_later` and :func:`register` keep the
208 file descriptor of their *file* argument. If the file is closed and its file
209 descriptor is reused by a new file, or if :func:`os.dup2` is used to replace
210 the file descriptor, the traceback will be written into a different file. Call
211 these functions again each time that the file is replaced.
212
213
214 Example
215 -------
216
217 Example of a segmentation fault on Linux with and without enabling the fault
218 handler:
219
220 .. code-block:: shell-session
221
222 $ python -c "import ctypes; ctypes.string_at(0)"
223 Segmentation fault
224
225 $ python -q -X faulthandler
226 >>> import ctypes
227 >>> ctypes.string_at(0)
228 Fatal Python error: Segmentation fault
229
230 Current thread 0x00007fb899f39700 (most recent call first):
231 File "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at
232 File "<stdin>", line 1 in <module>
233
234 Current thread's C stack trace (most recent call first):
235 Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e]
236 Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd]
237 Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a]
238 Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0]
239 Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c]
240 Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6]
241 Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976]
242 Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c]
243 Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e]
244 Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
245 Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
246 Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624]
247 Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883]
248 Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6]
249 Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04]
250 Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302]
251 Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
252 Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
253 Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3]
254 Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957]
255 Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4]
256 Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634]
257 Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
258 Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
259 Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1]
260 Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348]
261 Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626]
262 Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e]
263 Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a]
264 Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8]
265 Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b]
266 Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe]
267 <truncated rest of calls>
268 Segmentation fault