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