"faulthandler" --- 파이썬 트레이스백 덤프
*****************************************

Added in version 3.3.

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

이 모듈은 결함(fault) 시, 시간 초과 후 또는 사용자 시그널에 파이썬 트
레이스백을 명시적으로 덤프하는 함수를 포함합니다. "SIGSEGV", "SIGFPE",
"SIGABRT", "SIGBUS" 및 "SIGILL" 시그널에 대한 결함 처리기를 설치하려면
"faulthandler.enable()"를 호출하십시오. "PYTHONFAULTHANDLER" 환경 변수
를 설정하거나 "-X" "faulthandler" 명령 줄 옵션을 사용하여 시작할 때 활
성화할 수도 있습니다.

결함 처리기는 Apport나 윈도우 결함 처리기(Windows fault handler)와 같
은 시스템 결함 처리기와 호환됩니다. 이 모듈은 "sigaltstack()" 함수를
사용할 수 있으면 시그널 처리기에 대체 스택을 사용합니다. 이것은 스택
오버플로에서조차 트레이스백을 덤프할 수 있도록 합니다.

결함 처리기는 치명적일 때 호출되므로 시그널 안전한 함수만 사용할 수 있
습니다 (예를 들어, 힙에 메모리를 할당할 수 없습니다). 이 제한 때문에
일반적인 파이썬 트레이스백에 비해 트레이스백 덤프는 최소화됩니다:

* ASCII만 지원됩니다. 인코딩 시 "backslashreplace" 에러 처리기가 사용
  됩니다.

* 각 문자열은 500자로 제한됩니다.

* 파일명, 함수 이름 및 줄 번호만 표시됩니다. (소스 코드 없음)

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

* 순서가 뒤집힙니다: 가장 최근의 호출이 먼저 표시됩니다.

기본적으로, 파이썬 트레이스백은 "sys.stderr"에 기록됩니다. 트레이스백
을 보려면, 응용 프로그램이 터미널에서 실행되어야 합니다. 로그 파일을
"faulthandler.enable()"로 전달할 수도 있습니다.

모듈은 C로 구현되어 있으므로, 충돌 시나 파이썬이 교착 상태에 빠질 때
트레이스백을 덤프할 수 있습니다.

파이썬 개발 모드는 파이썬 시작 시 "faulthandler.enable()"을 호출합니다
.

더 보기:

  Module "pdb"
     Interactive source code debugger for Python programs.

  Module "traceback"
     Standard interface to extract, format and print stack traces of
     Python programs.


트레이스백 덤프하기
===================

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에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었
   습니다.

   버전 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)

   결함 처리기를 활성화합니다: "SIGSEGV", "SIGFPE", "SIGABRT",
   "SIGBUS" 및 "SIGILL" 시그널에 대한 처리기를 설치하여 파이썬 트레이
   스백을 덤프합니다. *all_threads*가 "True"면 실행 중인 모든 스레드에
   대한 트레이스백을 생성합니다. 그렇지 않으면, 현재 스레드만 덤프합니
   다.

   *file*은 결함 처리기가 비활성화될 때까지 열려 있어야 합니다: 파일
   기술자 관련 문제를 참조하십시오.

   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에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었
   습니다.

   버전 3.6에서 변경: 윈도우에서는, 윈도우 예외(Windows exception) 처
   리기도 설치됩니다.

   버전 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()

   결함 처리기가 활성화되었는지 검사합니다.


시간 초과 후에 트레이스백 덤프하기
==================================

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.

   *file*은 트레이스백이 덤프 되거나 "cancel_dump_traceback_later()"가
   호출될 때까지 열려 있어야 합니다: 파일 기술자 관련 문제를 참조하십
   시오.

   이 함수는 워치독(watchdog) 스레드를 사용하여 구현됩니다.

   버전 3.5에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었
   습니다.

   버전 3.7에서 변경: 이 함수는 이제 항상 사용할 수 있습니다.

   버전 3.15에서 변경: Added the *max_threads* keyword argument.

faulthandler.cancel_dump_traceback_later()

   마지막 "dump_traceback_later()" 호출을 취소합니다.


사용자 시그널에 트레이스백 덤프하기
===================================

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.

   *file*은 시그널이 "unregister()"로 등록 해지 될 때까지 열려 있어야
   합니다: 파일 기술자 관련 문제를 참조하십시오.

   윈도우에서는 사용할 수 없습니다.

   버전 3.5에서 변경: 이 함수에 파일 기술자를 전달하는 지원이 추가되었
   습니다.

   버전 3.15에서 변경: Added the *max_threads* keyword argument.

faulthandler.unregister(signum)

   사용자 시그널을 등록 해지합니다: "register()"로 설치된 *signum* 시
   그널 처리기를 제거합니다. 시그널이 등록되었으면 "True"를 반환하고,
   그렇지 않으면 "False"를 반환합니다.

   윈도우에서는 사용할 수 없습니다.


파일 기술자 관련 문제
=====================

"enable()", "dump_traceback_later()" 및 "register()"는 *file* 인자의
파일 기술자를 유지합니다. 파일이 닫히고 파일 기술자가 새 파일에 의해
다시 사용되거나, "os.dup2()"가 파일 기술자를 바꾸는 데 사용되면, 트레
이스백이 다른 파일에 기록됩니다. 파일을 바꿀 때마다 이 함수들을 다시
호출하십시오.


예제
====

리눅스에서 결함 처리기를 활성화하거나 그렇지 않았을 때의 세그멘테이션
결함 예제:

   $ 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
