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 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