# `faulthandler` —— 转储 Python 的跟踪信息

Added in version 3.3.

This module contains functions to dump Python tracebacks explicitly, on a fault, after a timeout, or on a user signal. Call `faulthandler.enable()` to install fault handlers for the `SIGSEGV`, `SIGFPE`, `SIGABRT`, `SIGBUS`, and `SIGILL` signals. You can also enable them at startup by setting the `PYTHONFAULTHANDLER` environment variable or by using the `-X` `faulthandler` command line option.

The fault handler is compatible with system fault handlers like Apport or the Windows fault handler. The module uses an alternative stack for signal handlers if the `sigaltstack()` function is available. This allows it to dump the traceback even on a stack overflow.

故障处理程序将在灾难性场合调用，因此只能使用信号安全的函数（比如不能在堆上分配内存）。由于这一限制，与正常的 Python 跟踪相比，转储量是最小的。

- 只支持 ASCII 码。编码时会用到 `backslashreplace` 错误处理程序。

- 每个字符串限制在 500 个字符以内。

- 只会显式文件名、函数名和行号。（不显示源代码）

- 上限是 100 页内存帧和 100 个线程。

- 反序排列：最近的调用最先显示。

默认情况下，Python 的跟踪信息会写入 `sys.stderr`。为了能看到跟踪信息，应用程序必须运行于终端中。日志文件也可以传给 `faulthandler.enable()`。

本模块是用 C 语言实现的，所以才能在崩溃或 Python 死锁时转储跟踪信息。

在 Python 启动时， Python 开发模式 会调用 `faulthandler.enable()`。

也參考

`pdb` 模組

  用于 Python 程序的交互式源代码调试器。

`traceback` 模組

  提取、格式化和打印 Python 程序的栈回溯信息的标准接口。

## 转储跟踪信息

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

  将所有线程的跟踪数据转储到 file 中。如果 all_threads 为 `False`，则只转储当前线程。

  也參考

  `traceback.print_tb()`，可被用于打印回溯对象。

  在 3.5 版的變更: 增加了向本函数传入文件描述符的支持。

## 故障处理程序的状态

faulthandler.enable(file=sys.stderr, all_threads=True)

  Enable the fault handler: install handlers for the `SIGSEGV`, `SIGFPE`, `SIGABRT`, `SIGBUS` and `SIGILL` signals to dump the Python traceback. If all_threads is `True`, produce tracebacks for every running thread. Otherwise, dump only the current thread.

  file 必须保持打开状态，直至停用故障处理程序为止：参见 文件描述符相关话题。

  在 3.5 版的變更: 增加了向本函数传入文件描述符的支持。

  在 3.6 版的變更: 在 Windows 系统中，同时会安装一个 Windows 异常处理程序。

  在 3.10 版的變更: 现在如果 all_threads 为 True，则转储信息会包含垃圾收集器是否正在运行。

faulthandler.disable()

  停用故障处理程序：卸载由 `enable()` 安装的信号处理程序。

faulthandler.is_enabled()

  检查故障处理程序是否被启用。

## 一定时间后转储跟踪数据。

faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)

  Dump the tracebacks of all threads, after a timeout of timeout seconds, or every timeout seconds if repeat is `True`. If exit is `True`, call `_exit()` with status=1 after dumping the tracebacks. (Note `_exit()` exits the process immediately, which means it doesn't do any cleanup like flushing file buffers.) If the function is called twice, the new call replaces previous parameters and resets the timeout. The timer has a sub-second resolution.

  file 必须保持打开状态，直至跟踪信息转储完毕，或调用了 `cancel_dump_traceback_later()` ：参见 文件描述符相关话题。

  本函数用一个看门狗线程实现。

  在 3.5 版的變更: 增加了向本函数传入文件描述符的支持。

  在 3.7 版的變更: 该函数现在总是可用。

faulthandler.cancel_dump_traceback_later()

  取消 `dump_traceback_later()` 的最后一次调用。

## 转储用户信号的跟踪信息。

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

  注册一个用户信号：为 signum 信号安装一个处理程序，将所有线程或当前线程（all_threads 为 `False` 时）的跟踪信息转储到 file 中。如果 chain 为 `True`，则调用上一层处理程序。

  file 必须保持打开状态，直至该信号被 `unregister()` 注销：参见 文件描述符相关话题。

  Windows 中不可用。

  在 3.5 版的變更: 增加了向本函数传入文件描述符的支持。

faulthandler.unregister(signum)

  注销一个用户信号：卸载由 `register()` 安装的 signum 信号处理程序。如果信号已注册，返回 `True`，否则返回 `False`。

  Windows 中不可用。

## 文件描述符相关话题

`enable()` 、 `dump_traceback_later()` 和 `register()` 保留其 file 参数给出的文件描述符。 如果文件关闭，文件描述符将被一个新文件重新使用；或者用 `os.dup2()` 替换了文件描述符，则跟踪信息将被写入另一个文件。 每次文件被替换时，都会再次调用这些函数。

## 範例

在 Linux 中启用和停用内存段故障的默认处理程序：

    $ python -c "import ctypes; ctypes.string_at(0)"
    Segmentation fault

    $ python -q -X faulthandler
    >>> import ctypes
    >>> ctypes.string_at(0)
    Fatal Python error: Segmentation fault

    Current thread 0x00007fb899f39700 (most recent call first):
      File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
      File "<stdin>", line 1 in <module>
    Segmentation fault