faulthandler
— 转储 Python 回溯
¶
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
，和
SIGILL
signals. You can also enable them at startup by setting the
PYTHONFAULTHANDLER
environment variable or by using the
-X
faulthandler
命令行选项。
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.
The fault handler is called on catastrophic cases and therefore can only use signal-safe functions (e.g. it cannot allocate memory on the heap). Because of this limitation traceback dumping is minimal compared to normal Python tracebacks:
backslashreplace
error handler is used on
编码。
By default, the Python traceback is written to
sys.stderr
. To see tracebacks, applications must be run in the terminal. A log file can alternatively be passed to
faulthandler.enable()
.
The module is implemented in C, so tracebacks can be dumped on a crash or when Python is deadlocked.
faulthandler.
dump_traceback
(
file=sys.stderr
,
all_threads=True
)
¶
Dump the tracebacks of all threads into
file
。若
all_threads
is
False
, dump only the current thread.
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.
faulthandler.
disable
(
)
¶
Disable the fault handler: uninstall the signal handlers installed by
enable()
.
faulthandler.
is_enabled
(
)
¶
Check if the fault handler 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
。若
exit
is
True
，调用
_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.
This function is implemented using a watchdog thread and therefore is not available if Python is compiled with threads disabled.
faulthandler.
cancel_dump_traceback_later
(
)
¶
Cancel the last call to
dump_traceback_later()
.
faulthandler.
register
(
signum
,
file=sys.stderr
,
all_threads=True
,
chain=False
)
¶
Register a user signal: install a handler for the
signum
signal to dump the traceback of all threads, or of the current thread if
all_threads
is
False
，进
file
. Call the previous handler if chain is
True
.
不可用于 Windows。
faulthandler.
unregister
(
signum
)
¶
Unregister a user signal: uninstall the handler of the
signum
signal installed by
register()
。返回
True
if the signal was registered,
False
否则。
不可用于 Windows。
enable()
,
dump_traceback_later()
and
register()
keep the file descriptor of their
file
argument. If the file is closed and its file descriptor is reused by a new file, or if
os.dup2()
is used to replace the file descriptor, the traceback will be written into a different file. Call these functions again each time that the file is replaced.
Example of a segmentation fault on Linux with and without enabling the fault handler:
$ 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