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

버전 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.dump_traceback(file=sys.stderr, all_threads=True)

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

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


결함 처리기 상태
================

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

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

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

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

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

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.7에서 변경: 이 함수는 이제 항상 사용할 수 있습니다.

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

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()"가 파일 기술자를 바꾸는 데 사용되면, 트레
이스백이 다른 파일에 기록됩니다. 파일을 바꿀 때마다 이 함수들을 다시
호출하십시오.


예제
====

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

   $ 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
