"faulthandler" --- Python トレースバックをダンプする
****************************************************

Added in version 3.3.

======================================================================

このモジュールは、例外発生時、タイムアウト時、ユーザシグナルの発生時な
どのタイミングでpython tracebackを明示的にダンプするための関数を含んで
います。これらのシグナル、"SIGSEGV"、"SIGFPE"、"SIGABRT"、"SIGBUS"、
"SIGILL" に対するフォールトハンドラをインストールするには
"faulthandler.enable()" を実行してください。python起動時に有効にするに
は環境変数 "PYTHONFAULTHANDLER" を設定するか、コマンドライン引数に
"-X" "faulthandler" を指定してください。

Pythonのフォールトハンドラは、apportやWindowsのフォールトハンドラのよ
うなシステムフォールトハンドラと互換性があります。このモジュールは
"sigaltstack()" 関数が使用可能であればシグナルハンドラ用に代替スタック
を利用します。これによってスタックオーバーフロー時にもトレースバックを
出力することができます。

フォールトハンドラは絶望的なケースで呼び出されます。そのためシグナルセ
ーフな関数しか使うことができません (例: ヒープメモリ上にメモリ確保はで
きません)。この制限により、tracebackのダンプ機能は通常のPythonの
tracebackと比べてごく僅かなものです:

* ASCIIのみサポートされます。エンコード時には "backslashreplace" エラ
  ーハンドラを使用します。

* すべての文字列は500文字以内に制限されています。

* ファイル名、関数名、行数のみ表示します。(ソースコードの表示はありま
  せん)

* It is limited to 100 frames per thread, and 100 threads
  (configurable via *max_threads*).

* 順番は保持されます: 最新の呼び出しが最初に表示されます。

デフォルトでは、Pythonのtracebackは "sys.stderr" に書き出されます。
tracebackを見るには、対象アプリケーションはターミナル上で実行しなけれ
ばなりません。 "faulthandler.enable()" に渡す引数によってログファイル
を指定することができます。

モジュールはC言語で実装されているので、アプリのクラッシュ時でもPython
がデッドロックした場合でもダンプができます。

The Python Development Mode calls "faulthandler.enable()" at Python
startup.

参考:

  "pdb" モジュール
     Interactive source code debugger for Python programs.

  "traceback" モジュール
     Standard interface to extract, format and print stack traces of
     Python programs.


tracebackのダンプ
=================

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

   Dump the tracebacks of all threads into *file*. If *all_threads* is
   "False", dump only the current thread. *max_threads* caps the
   number of threads dumped.

   参考:

     "traceback.print_tb()", which can be used to print a traceback
     object.

   バージョン 3.5 で変更: Added support for passing file descriptor to
   this function.

   バージョン 3.15 で変更: Added the *max_threads* keyword argument.


Dumping the C stack
===================

Added in version 3.14.

faulthandler.dump_c_stack(file=sys.stderr)

   Dump the C stack trace of the current thread into *file*.

   If the Python build does not support it or the operating system
   does not provide a stack trace, then this prints an error in place
   of a dumped C stack.


C Stack Compatibility
---------------------

If the system does not support the C-level *backtrace(3)* or
*dladdr1(3)*, then C stack dumps will not work. An error will be
printed instead of the stack.

Additionally, some compilers do not support *CPython's* implementation
of C stack dumps. As a result, a different error may be printed
instead of the stack, even if the operating system supports dumping
stacks.

注釈:

  Dumping C stacks can be arbitrarily slow, depending on the DWARF
  level of the binaries in the call stack.


フォールトハンドラの状態
========================

faulthandler.enable(file=sys.stderr, all_threads=True, c_stack=True, *, max_threads=100)

   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.

   The *file* must be kept open until the fault handler is disabled:
   see issue with file descriptors.

   If *c_stack* is "True", then the C stack trace is printed after the
   Python traceback, unless the system does not support it. See
   "dump_c_stack()" for more information on compatibility.

   *max_threads* caps the number of threads dumped when a fatal signal
   fires.

   バージョン 3.5 で変更: Added support for passing file descriptor to
   this function.

   バージョン 3.6 で変更: On Windows, a handler for Windows exception
   is also installed.

   バージョン 3.10 で変更: The dump now mentions if a garbage
   collector collection is running if *all_threads* is true.

   バージョン 3.14 で変更: Only the current thread is dumped if the
   *GIL* is disabled to prevent the risk of data races.

   バージョン 3.14 で変更: The dump now displays the C stack trace if
   *c_stack* is true.

   バージョン 3.15 で変更: Added the *max_threads* keyword argument.

faulthandler.disable()

   フォールトハンドラを無効にします: "enable()" によってインストールさ
   れたシグナルハンドラをアンインストールします。

faulthandler.is_enabled()

   フォールトハンドラが有効かどうかチェックします。


タイムアウト後にtracebackをダンプする
=====================================

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

   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.
   *max_threads* caps the number of threads dumped.

   The *file* must be kept open until the traceback is dumped or
   "cancel_dump_traceback_later()" is called: see issue with file
   descriptors.

   This function is implemented using a watchdog thread.

   バージョン 3.5 で変更: Added support for passing file descriptor to
   this function.

   バージョン 3.7 で変更: This function is now always available.

   バージョン 3.15 で変更: Added the *max_threads* keyword argument.

faulthandler.cancel_dump_traceback_later()

   "dump_traceback_later()" の最新の呼び出しをキャンセルします。


ユーザシグナルに対してtracebackをダンプする
===========================================

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

   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", into *file*. Call the previous handler if
   chain is "True". *max_threads* caps the number of threads dumped.

   The *file* must be kept open until the signal is unregistered by
   "unregister()": see issue with file descriptors.

   Windowsでは利用不可です。

   バージョン 3.5 で変更: Added support for passing file descriptor to
   this function.

   バージョン 3.15 で変更: Added the *max_threads* keyword argument.

faulthandler.unregister(signum)

   ユーザシグナルを登録解除します: "register()" でインストールした
   *signum* シグナルハンドラをアンインストールします。シグナルが登録さ
   れた場合は "True" を返し、そうでなければ "False" を返します。

   Windowsでは利用不可です。


ファイル記述子の問題
====================

"enable()"、"dump_traceback_later()" ならびに "register()" は引数
*file* に渡されたファイル記述子を保持します。ファイルが閉じられファイ
ル記述子が新しいファイルで再利用された場合や、"os.dup2()" の使用でファ
イル記述子が置き換えた場合、 traceback の結果は別のファイルへ書き込ま
れます。ファイルが置き換えられた場合は、毎回これらの関数を呼び出しなお
してください。


使用例
======

フォールトハンドラを有効化・無効化したときの 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 "/opt/python/Lib/ctypes/__init__.py", line 486 in string_at
     File "<stdin>", line 1 in <module>

   Current thread's C stack trace (most recent call first):
     Binary file "/opt/python/python", at _Py_DumpStack+0x42 [0x5b27f7d7147e]
     Binary file "/opt/python/python", at +0x32dcbd [0x5b27f7d85cbd]
     Binary file "/opt/python/python", at +0x32df8a [0x5b27f7d85f8a]
     Binary file "/usr/lib/libc.so.6", at +0x3def0 [0x77b73226bef0]
     Binary file "/usr/lib/libc.so.6", at +0x17ef9c [0x77b7323acf9c]
     Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0xcdf6 [0x77b7315dddf6]
     Binary file "/usr/lib/libffi.so.8", at +0x7976 [0x77b73158f976]
     Binary file "/usr/lib/libffi.so.8", at +0x413c [0x77b73158c13c]
     Binary file "/usr/lib/libffi.so.8", at ffi_call+0x12e [0x77b73158ef0e]
     Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
     Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
     Binary file "/opt/python/build/lib.linux-x86_64-3.15/_ctypes.cpython-315d-x86_64-linux-gnu.so", at +0xc624 [0x77b7315dd624]
     Binary file "/opt/python/python", at _PyObject_MakeTpCall+0xce [0x5b27f7b73883]
     Binary file "/opt/python/python", at +0x11bab6 [0x5b27f7b73ab6]
     Binary file "/opt/python/python", at PyObject_Vectorcall+0x23 [0x5b27f7b73b04]
     Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x490c [0x5b27f7cbb302]
     Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
     Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
     Binary file "/opt/python/python", at PyEval_EvalCode+0xc5 [0x5b27f7cd9ba3]
     Binary file "/opt/python/python", at +0x255957 [0x5b27f7cad957]
     Binary file "/opt/python/python", at +0x255ab4 [0x5b27f7cadab4]
     Binary file "/opt/python/python", at _PyEval_EvalFrameDefault+0x6c3e [0x5b27f7cbd634]
     Binary file "/opt/python/python", at +0x2818e6 [0x5b27f7cd98e6]
     Binary file "/opt/python/python", at +0x281aab [0x5b27f7cd9aab]
     Binary file "/opt/python/python", at +0x11b6e1 [0x5b27f7b736e1]
     Binary file "/opt/python/python", at +0x11d348 [0x5b27f7b75348]
     Binary file "/opt/python/python", at +0x11d626 [0x5b27f7b75626]
     Binary file "/opt/python/python", at PyObject_Call+0x20 [0x5b27f7b7565e]
     Binary file "/opt/python/python", at +0x32a67a [0x5b27f7d8267a]
     Binary file "/opt/python/python", at +0x32a7f8 [0x5b27f7d827f8]
     Binary file "/opt/python/python", at +0x32ac1b [0x5b27f7d82c1b]
     Binary file "/opt/python/python", at Py_RunMain+0x31 [0x5b27f7d82ebe]
     <truncated rest of calls>
   Segmentation fault
