# 27.2. `faulthandler` — 转储Python回溯

版本3.3中的新功能。

该模块包含在 段错误、超时或接收到用户信号之后显式转储Python 调用栈的功能。调用`faulthandler.enable()`为`SIGSEGV`，`SIGFPE`，`SIGABRT`，`SIGBUS`和`SIGILL`信号。您也可以在启动时通过设置 `PYTHONFAULTHANDLER`环境变量或使用`-X` `faulthandler`命令行选项。

故障处理程序与系统故障处理程序（如Apport或Windows故障处理程序）兼容。如果`sigaltstack()`函数可用，则模块使用替代堆栈用于信号处理程序。这允许它转储跟踪甚至在堆栈溢出。

故障处理器在灾难性情况下被调用，因此只能使用信号安全功能（例如，它不能在堆上分配内存）。由于这个限制，与正常的Python跟踪相比，跟踪回复转储是最小的：

- 仅支持ASCII。对编码使用`backslashreplace`错误处理程序。
- 每个字符串限制为500个字符。
- 仅显示文件名，功能名称和行​​号。（无源代码）
- 它限制为100帧和100线程。
- 顺序相反：最近的呼叫首先显示。

默认情况下，Python跟踪回写被写入到`sys.stderr`。要查看回溯，应用程序必须在终端中运行。可以将日志文件传递给`faulthandler.enable()`。

该模块在C中实现，因此traceback可以转储崩溃或当Python死锁。

## 27.2.1. 转储回溯

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

  将所有线程的追踪转储到文件中。如果all_threads为`False`，则只转储当前线程。

  在版本3.5中已更改：添加了将文件描述器传递到此函数的支持。

## 27.2.2. 错误处理程序状态

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

  启用故障处理程序：安装`SIGSEGV`，`SIGFPE`，`SIGABRT`，`SIGBUS`和`SIGILL` 如果all_threads为`True`，则为每个正在运行的线程产生追溯。否则，只转储当前线程。

  文件必须保持打开，直到故障处理程序被禁用：参见issue with file descriptors。

  在版本3.5中已更改：添加了将文件描述器传递到此函数的支持。

`faulthandler.``disable`()

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

`faulthandler.``is_enabled`()

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

## 27.2.3. 在超时后转储追溯

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

  如果重复是`True`，则在超时超时秒或每个超时 。如果退出为`True`，则在转储跟踪后调用状态= 1的`_exit()`。（注意`_exit()`立即退出该过程，这意味着它不会执行任何清理，如刷新文件缓冲区。）如果函数被调用两次，新调用将替换以前的参数并重置超时。定时器具有亚秒分辨率。

  文件必须保持打开状态，直到调用traceback或调用`cancel_dump_traceback_later()`：请参阅issue with file descriptors。

  此函数使用看门狗线程实现，因此如果Python编译时禁用线程，则不可用。

  在版本3.5中已更改：添加了将文件描述器传递到此函数的支持。

`faulthandler.``cancel_dump_traceback_later`()

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

## 27.2.4. 将追踪信息转储到用户信号上

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

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

  文件必须保持打开状态，直到`unregister()`未注册信号：请参阅文件描述器中的issue with file descriptors

  在Windows上不可用。

  在版本3.5中已更改：添加了将文件描述器传递到此函数的支持。

`faulthandler.``unregister`(signum)

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

  在Windows上不可用。

## 27.2.5. 问题与文件描述符

`enable()`，`dump_traceback_later()`和`register()`保留其文件参数的文件描述器。如果文件关闭并且其文件描述器由一个新文件重用，或者如果`os.dup2()`用于替换文件描述器，则该追溯将被写入另一个文件。每次更换文件时都调用这些函数。

## 27.2.6. 示例

Linux上启用和未启用故障处理程序的分段故障示例：

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

    $ python3 -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