"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자로 제한됩니다.

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

* 100프레임과 100스레드로 제한됩니다.

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

기본적으로, 파이썬 트레이스백은 "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)

   모든 스레드의 트레이스백을 *file*로 덤프합니다. *all_threads*가
   "False"면, 현재 스레드만 덤프합니다.

   더 보기:

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

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


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)

   결함 처리기를 활성화합니다: "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.

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

faulthandler.disable()

   결함 처리기를 비활성화합니다: "enable()"로 설치된 시그널 처리기를
   제거합니다.

faulthandler.is_enabled()

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


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

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

   *timeout* 초의 시간제한 후, 또는 *repeat*가 "True"면 매 *timeout*
   초마다, 모든 스레드의 트레이스백을 덤프합니다. *exit*가 "True"면,
   트레이스백을 덤프한 후 status=1 로 "_exit()"를 호출합니다.
   ("_exit()"가 프로세스를 즉시 종료함에 유의하십시오. 파일 버퍼를 플
   러시 하는 것과 같은 정리 작업을 수행하지 않습니다.) 함수가 두 번 호
   출되면, 새 호출은 이전 매개 변수를 대체하고 시간제한을 다시 설정합
   니다. 타이머는 1초 미만의 해상도를 갖습니다.

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

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

   버전 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()"로 등록 해지 될 때까지 열려 있어야
   합니다: 파일 기술자 관련 문제를 참조하십시오.

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

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

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.14/_ctypes.cpython-314d-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.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x15a33 [0x77b7315e6a33]
     Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-x86_64-linux-gnu.so", at +0x164fa [0x77b7315e74fa]
     Binary file "/opt/python/build/lib.linux-x86_64-3.14/_ctypes.cpython-314d-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
