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.. seealso::
47
48   Module :mod:`pdb`
49      Interactive source code debugger for Python programs.
50
51   Module :mod:`traceback`
52      Standard interface to extract, format and print stack traces of Python programs.
53
54Dumping the traceback
55---------------------
56
57.. function:: dump_traceback(file=sys.stderr, all_threads=True)
58
59   Dump the tracebacks of all threads into *file*. If *all_threads* is
60   ``False``, dump only the current thread.
61
62   .. seealso:: :func:`traceback.print_tb`, which can be used to print a traceback object.
63
64   .. versionchanged:: 3.5
65      Added support for passing file descriptor to this function.
66
67
68Fault handler state
69-------------------
70
71.. function:: enable(file=sys.stderr, all_threads=True)
72
73   Enable the fault handler: install handlers for the :const:`SIGSEGV`,
74   :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and :const:`SIGILL`
75   signals to dump the Python traceback. If *all_threads* is ``True``,
76   produce tracebacks for every running thread. Otherwise, dump only the current
77   thread.
78
79   The *file* must be kept open until the fault handler is disabled: see
80   :ref:`issue with file descriptors <faulthandler-fd>`.
81
82   .. versionchanged:: 3.5
83      Added support for passing file descriptor to this function.
84
85   .. versionchanged:: 3.6
86      On Windows, a handler for Windows exception is also installed.
87
88   .. versionchanged:: 3.10
89      The dump now mentions if a garbage collector collection is running
90      if *all_threads* is true.
91
92.. function:: disable()
93
94   Disable the fault handler: uninstall the signal handlers installed by
95   :func:`enable`.
96
97.. function:: is_enabled()
98
99   Check if the fault handler is enabled.
100
101
102Dumping the tracebacks after a timeout
103--------------------------------------
104
105.. function:: dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)
106
107   Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or
108   every *timeout* seconds if *repeat* is ``True``.  If *exit* is ``True``, call
109   :c:func:`_exit` with status=1 after dumping the tracebacks.  (Note
110   :c:func:`_exit` exits the process immediately, which means it doesn't do any
111   cleanup like flushing file buffers.) If the function is called twice, the new
112   call replaces previous parameters and resets the timeout. The timer has a
113   sub-second resolution.
114
115   The *file* must be kept open until the traceback is dumped or
116   :func:`cancel_dump_traceback_later` is called: see :ref:`issue with file
117   descriptors <faulthandler-fd>`.
118
119   This function is implemented using a watchdog thread.
120
121   .. versionchanged:: 3.7
122      This function is now always available.
123
124   .. versionchanged:: 3.5
125      Added support for passing file descriptor to this function.
126
127.. function:: cancel_dump_traceback_later()
128
129   Cancel the last call to :func:`dump_traceback_later`.
130
131
132Dumping the traceback on a user signal
133--------------------------------------
134
135.. function:: register(signum, file=sys.stderr, all_threads=True, chain=False)
136
137   Register a user signal: install a handler for the *signum* signal to dump
138   the traceback of all threads, or of the current thread if *all_threads* is
139   ``False``, into *file*. Call the previous handler if chain is ``True``.
140
141   The *file* must be kept open until the signal is unregistered by
142   :func:`unregister`: see :ref:`issue with file descriptors <faulthandler-fd>`.
143
144   Not available on Windows.
145
146   .. versionchanged:: 3.5
147      Added support for passing file descriptor to this function.
148
149.. function:: unregister(signum)
150
151   Unregister a user signal: uninstall the handler of the *signum* signal
152   installed by :func:`register`. Return ``True`` if the signal was registered,
153   ``False`` otherwise.
154
155   Not available on Windows.
156
157
158.. _faulthandler-fd:
159
160Issue with file descriptors
161---------------------------
162
163:func:`enable`, :func:`dump_traceback_later` and :func:`register` keep the
164file descriptor of their *file* argument. If the file is closed and its file
165descriptor is reused by a new file, or if :func:`os.dup2` is used to replace
166the file descriptor, the traceback will be written into a different file. Call
167these functions again each time that the file is replaced.
168
169
170Example
171-------
172
173Example of a segmentation fault on Linux with and without enabling the fault
174handler:
175
176.. code-block:: shell-session
177
178    $ python3 -c "import ctypes; ctypes.string_at(0)"
179    Segmentation fault
180
181    $ python3 -q -X faulthandler
182    >>> import ctypes
183    >>> ctypes.string_at(0)
184    Fatal Python error: Segmentation fault
185
186    Current thread 0x00007fb899f39700 (most recent call first):
187      File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
188      File "<stdin>", line 1 in <module>
189    Segmentation fault
190