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