Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 1 | :mod:`faulthandler` --- Dump the Python traceback |
| 2 | ================================================= |
| 3 | |
| 4 | .. module:: faulthandler |
| 5 | :synopsis: Dump the Python traceback. |
| 6 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 7 | .. versionadded:: 3.3 |
| 8 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 9 | ---------------- |
| 10 | |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 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 |
Victor Stinner | 215ad66 | 2014-03-25 12:33:56 +0100 | [diff] [blame] | 16 | variable or by using the :option:`-X` ``faulthandler`` command line option. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 17 | |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 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. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 22 | |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 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: |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 27 | |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 28 | * Only ASCII is supported. The ``backslashreplace`` error handler is used on |
| 29 | encoding. |
Victor Stinner | 1713f9a | 2012-07-31 03:25:28 +0200 | [diff] [blame] | 30 | * Each string is limited to 500 characters. |
Victor Stinner | 2510d9e | 2011-06-19 16:07:20 +0200 | [diff] [blame] | 31 | * Only the filename, the function name and the line number are |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 32 | displayed. (no source code) |
| 33 | * It is limited to 100 frames and 100 threads. |
Guido van Rossum | 2063aaf | 2013-10-20 19:15:19 -0700 | [diff] [blame] | 34 | * The order is reversed: the most recent call is shown first. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 35 | |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 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. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 42 | |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 43 | |
Victor Stinner | 215ad66 | 2014-03-25 12:33:56 +0100 | [diff] [blame] | 44 | Dumping the traceback |
| 45 | --------------------- |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 46 | |
Victor Stinner | 7bba62f | 2011-05-07 12:43:00 +0200 | [diff] [blame] | 47 | .. function:: dump_traceback(file=sys.stderr, all_threads=True) |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 48 | |
Benjamin Peterson | defe6f6 | 2011-06-19 09:37:18 -0500 | [diff] [blame] | 49 | Dump the tracebacks of all threads into *file*. If *all_threads* is |
| 50 | ``False``, dump only the current thread. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 51 | |
Victor Stinner | 95bb714 | 2015-03-12 15:32:03 +0100 | [diff] [blame] | 52 | .. versionchanged:: 3.5 |
| 53 | Added support for passing file descriptor to this function. |
| 54 | |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 55 | |
| 56 | Fault handler state |
| 57 | ------------------- |
| 58 | |
Victor Stinner | 7bba62f | 2011-05-07 12:43:00 +0200 | [diff] [blame] | 59 | .. function:: enable(file=sys.stderr, all_threads=True) |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 60 | |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 61 | Enable the fault handler: install handlers for the :const:`SIGSEGV`, |
Victor Stinner | d727e23 | 2011-04-01 12:13:55 +0200 | [diff] [blame] | 62 | :const:`SIGFPE`, :const:`SIGABRT`, :const:`SIGBUS` and :const:`SIGILL` |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 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. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 66 | |
Victor Stinner | 95bb714 | 2015-03-12 15:32:03 +0100 | [diff] [blame] | 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 | |
Victor Stinner | 404cdc5 | 2016-03-23 10:39:17 +0100 | [diff] [blame] | 73 | .. versionchanged:: 3.6 |
| 74 | On Windows, a handler for Windows exception is also installed. |
| 75 | |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 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 | |
Victor Stinner | 215ad66 | 2014-03-25 12:33:56 +0100 | [diff] [blame] | 86 | Dumping the tracebacks after a timeout |
| 87 | -------------------------------------- |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 88 | |
Georg Brandl | deb92b5 | 2012-09-22 08:58:55 +0200 | [diff] [blame] | 89 | .. function:: dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False) |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 90 | |
| 91 | Dump the tracebacks of all threads, after a timeout of *timeout* seconds, or |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 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 |
Benjamin Peterson | defe6f6 | 2011-06-19 09:37:18 -0500 | [diff] [blame] | 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. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 98 | |
Victor Stinner | 95bb714 | 2015-03-12 15:32:03 +0100 | [diff] [blame] | 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 | |
Benjamin Peterson | 8519875 | 2011-06-17 19:54:52 -0500 | [diff] [blame] | 103 | This function is implemented using a watchdog thread and therefore is not |
| 104 | available if Python is compiled with threads disabled. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 105 | |
Victor Stinner | 95bb714 | 2015-03-12 15:32:03 +0100 | [diff] [blame] | 106 | .. versionchanged:: 3.5 |
| 107 | Added support for passing file descriptor to this function. |
| 108 | |
Georg Brandl | deb92b5 | 2012-09-22 08:58:55 +0200 | [diff] [blame] | 109 | .. function:: cancel_dump_traceback_later() |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 110 | |
Georg Brandl | deb92b5 | 2012-09-22 08:58:55 +0200 | [diff] [blame] | 111 | Cancel the last call to :func:`dump_traceback_later`. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 112 | |
| 113 | |
Victor Stinner | 215ad66 | 2014-03-25 12:33:56 +0100 | [diff] [blame] | 114 | Dumping the traceback on a user signal |
| 115 | -------------------------------------- |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 116 | |
Victor Stinner | a9a9dab | 2011-07-13 23:39:53 +0200 | [diff] [blame] | 117 | .. function:: register(signum, file=sys.stderr, all_threads=True, chain=False) |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 118 | |
| 119 | Register a user signal: install a handler for the *signum* signal to dump |
Victor Stinner | 7bba62f | 2011-05-07 12:43:00 +0200 | [diff] [blame] | 120 | the traceback of all threads, or of the current thread if *all_threads* is |
Victor Stinner | a9a9dab | 2011-07-13 23:39:53 +0200 | [diff] [blame] | 121 | ``False``, into *file*. Call the previous handler if chain is ``True``. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 122 | |
Victor Stinner | 95bb714 | 2015-03-12 15:32:03 +0100 | [diff] [blame] | 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 | |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 126 | Not available on Windows. |
| 127 | |
Victor Stinner | 95bb714 | 2015-03-12 15:32:03 +0100 | [diff] [blame] | 128 | .. versionchanged:: 3.5 |
| 129 | Added support for passing file descriptor to this function. |
| 130 | |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 131 | .. function:: unregister(signum) |
| 132 | |
| 133 | Unregister a user signal: uninstall the handler of the *signum* signal |
Victor Stinner | cfa7123 | 2011-04-08 12:48:15 +0200 | [diff] [blame] | 134 | installed by :func:`register`. Return ``True`` if the signal was registered, |
| 135 | ``False`` otherwise. |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 136 | |
| 137 | Not available on Windows. |
| 138 | |
| 139 | |
Victor Stinner | 95bb714 | 2015-03-12 15:32:03 +0100 | [diff] [blame] | 140 | .. _faulthandler-fd: |
| 141 | |
Victor Stinner | 215ad66 | 2014-03-25 12:33:56 +0100 | [diff] [blame] | 142 | Issue with file descriptors |
| 143 | --------------------------- |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 144 | |
Georg Brandl | deb92b5 | 2012-09-22 08:58:55 +0200 | [diff] [blame] | 145 | :func:`enable`, :func:`dump_traceback_later` and :func:`register` keep the |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 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 | |
Victor Stinner | 215ad66 | 2014-03-25 12:33:56 +0100 | [diff] [blame] | 155 | Example of a segmentation fault on Linux with and without enabling the fault |
Serhiy Storchaka | 46936d5 | 2018-04-08 19:18:04 +0300 | [diff] [blame] | 156 | handler: |
| 157 | |
| 158 | .. code-block:: shell-session |
Victor Stinner | 215ad66 | 2014-03-25 12:33:56 +0100 | [diff] [blame] | 159 | |
| 160 | $ python3 -c "import ctypes; ctypes.string_at(0)" |
| 161 | Segmentation fault |
| 162 | |
| 163 | $ python3 -q -X faulthandler |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 164 | >>> import ctypes |
| 165 | >>> ctypes.string_at(0) |
| 166 | Fatal Python error: Segmentation fault |
| 167 | |
Guido van Rossum | 2063aaf | 2013-10-20 19:15:19 -0700 | [diff] [blame] | 168 | Current thread 0x00007fb899f39700 (most recent call first): |
Victor Stinner | 024e37a | 2011-03-31 01:31:06 +0200 | [diff] [blame] | 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 | |