# 운영 체제 유틸리티

PyObject* `PyOS_FSPath`(PyObject *path)
  Return value: New reference.

  path에 대한 파일 시스템 표현을 반환합니다. 객체가 `str`이나 `bytes` 객체이면, 참조 횟수가 증가합니다. 객체가 `os.PathLike` 인터페이스를 구현하면, `__fspath__()`가 `str`나 `bytes` 객체일 때 반환됩니다. 그렇지 않으면, `TypeError`가 발생하고 `NULL`이 반환됩니다.

  버전 3.6에 추가.

int `Py_FdIsInteractive`(FILE *fp, const char *filename)

  이름이 filename인 표준 I/O 파일 fp를 대화식으로 간주하면 참(0이 아닙니다)을 반환합니다. `isatty(fileno(fp))`가 참인 파일의 경우입니다. 전역 플래그 `Py_InteractiveFlag`가 참이면, 이 함수는 filename 포인터가 `NULL`이거나 이름이 문자열 `'<stdin>'`이나 `'???'` 중 하나와 같을 때도 참을 반환합니다.

void `PyOS_BeforeFork`()

  프로세스 포크 전에 내부 상태를 준비하는 함수. `fork()`나 현재 프로세스를 복제하는 유사한 함수를 호출하기 전에 호출해야 합니다. `fork()`가 정의된 시스템에서만 사용 가능합니다.

  경고

  C `fork()` 호출은 (“메인” 인터프리터의) “메인” 스레드에서만 이루어져야 합니다. `PyOS_BeforeFork()`도 마찬가지입니다.

  버전 3.7에 추가.

void `PyOS_AfterFork_Parent`()

  프로세스 포크 후 일부 내부 상태를 갱신하는 함수. 프로세스 복제가 성공했는지와 관계없이, `fork()`나 현재 프로세스를 복제하는 유사한 함수를 호출한 후 부모 프로세스에서 호출해야 합니다. `fork()`가 정의된 시스템에서만 사용 가능합니다.

  경고

  C `fork()` 호출은 (“메인” 인터프리터의) “메인” 스레드에서만 이루어져야 합니다. `PyOS_AfterFork_Parent()`도 마찬가지입니다.

  버전 3.7에 추가.

void `PyOS_AfterFork_Child`()

  프로세스 포크 후 내부 인터프리터 상태를 갱신하는 함수. `fork()`나 현재 프로세스를 복제하는 유사한 함수를 호출한 후, 프로세스가 파이썬 인터프리터를 다시 호출할 가능성이 있으면 자식 프로세스에서 호출해야 합니다. `fork()`가 정의된 시스템에서만 사용 가능합니다.

  경고

  C `fork()` 호출은 (“메인” 인터프리터의) “메인” 스레드에서만 이루어져야 합니다. `PyOS_AfterFork_Child()`도 마찬가지입니다.

  버전 3.7에 추가.

  더 보기

  `os.register_at_fork()`를 사용하면 `PyOS_BeforeFork()`, `PyOS_AfterFork_Parent()` 및 `PyOS_AfterFork_Child()`에서 호출될 사용자 정의 파이썬 함수를 등록 할 수 있습니다.

void `PyOS_AfterFork`()

  프로세스 포크 후 일부 내부 상태를 갱신하는 함수; 파이썬 인터프리터가 계속 사용된다면 새로운 프로세스에서 호출되어야 합니다. 새 실행 파일이 새 프로세스에 로드되면, 이 함수를 호출할 필요가 없습니다.

  버전 3.7부터 폐지: 이 함수는 `PyOS_AfterFork_Child()`로 대체되었습니다.

int `PyOS_CheckStack`()

  인터프리터에 스택 공간이 부족하면 참을 반환합니다. 이것은 신뢰성 있는 확인이지만, `USE_STACKCHECK`이 정의되어 있을 때만 사용할 수 있습니다 (현재 마이크로소프트 Visual C++ 컴파일러를 사용하는 윈도우에서). `USE_STACKCHECK`은 자동으로 정의됩니다; 여러분 자신의 코드에서 정의를 변경해서는 안 됩니다.

PyOS_sighandler_t `PyOS_getsig`(int i)

  시그널 i에 대한 현재 시그널 처리기를 반환합니다. 이것은 `sigaction()`이나 `signal()`을 감싸는 얇은 래퍼입니다. 그 함수들을 직접 호출하지 마십시오! `PyOS_sighandler_t`는 `void (*)(int)`의 typedef 별칭입니다.

PyOS_sighandler_t `PyOS_setsig`(int i, PyOS_sighandler_t h)

  시그널 i의 시그널 처리기를 h로 설정합니다; 이전 시그널 처리기를 반환합니다. 이것은 `sigaction()`이나 `signal()`을 감싸는 얇은 래퍼입니다. 그 함수들을 직접 호출하지 마십시오! `PyOS_sighandler_t`는 `void (*)(int)`의 typedef 별칭입니다.

wchar_t* `Py_DecodeLocale`(const char* arg, size_t *size)

  surrogateescape 에러 처리기를 사용하여 로케일 인코딩에서 바이트열을 디코딩합니다: 디코딩할 수 없는 바이트열은 U+DC80..U+DCFF 범위의 문자로 디코딩됩니다. 바이트 시퀀스를 서로게이트 문자로 디코딩 할 수 있으면, 이들을 디코딩하는 대신 surrogateescape 에러 처리기를 사용하여 바이트열를 이스케이프 합니다.

  인코딩, 가장 높은 우선순위에서 가장 낮은 우선순위로:

  - `UTF-8`, 맥 OS, 안드로이드 및 VxWorks에서;

  - `UTF-8`, `Py_LegacyWindowsFSEncodingFlag`이 0일 때 윈도우에서;

  - `UTF-8`, 파이썬 UTF-8 모드가 활성화되었을 때;

  - `ASCII`, `LC_CTYPE` 로케일이 `"C"`이고, `nl_langinfo(CODESET)`이 `ASCII` 인코딩(또는 별칭)을 반환하고, `mbstowcs()`와 `wcstombs()` 함수가 `ISO-8859-1` 인코딩을 사용할 때.

  - 현재 로케일 인코딩

  새로 할당된 와이드 문자(wide character) 문자열에 대한 포인터를 반환합니다, 메모리를 해제하려면 `PyMem_RawFree()`를 사용하십시오. size가 `NULL`이 아니면, 널 문자를 제외한 와이드 문자 수를 `*size`에 기록합니다.

  디코딩 에러나 메모리 할당 에러 시 `NULL`을 반환합니다. size가 `NULL`이 아니면, 메모리 에러 시 `*size`가 `(size_t)-1`로 설정되고, 디코딩 에러 시 `(size_t)-2`로 설정됩니다.

  C 라이브러리에 버그가 없으면, 디코딩 에러가 발생하지 않아야 합니다.

  문자열을 바이트열로 다시 인코딩하려면 `Py_EncodeLocale()` 함수를 사용하십시오.

  더 보기

  `PyUnicode_DecodeFSDefaultAndSize()`와 `PyUnicode_DecodeLocaleAndSize()` 함수.

  버전 3.5에 추가.

  버전 3.7에서 변경: 이 함수는 이제 UTF-8 모드에서 UTF-8 인코딩을 사용합니다.

  버전 3.8에서 변경: 이 함수는 이제 윈도우에서 `Py_LegacyWindowsFSEncodingFlag`가 0이면 UTF-8 인코딩을 사용합니다;

char* `Py_EncodeLocale`(const wchar_t *text, size_t *error_pos)

  surrogateescape 에러 처리기를 사용하여 와이드 문자(wide character) 문자열을 로케일 인코딩으로 인코딩합니다: U+DC80..U+DCFF 범위의 서로게이트 문자는 바이트 0x80..0xFF로 변환됩니다.

  인코딩, 가장 높은 우선순위에서 가장 낮은 우선순위로:

  - `UTF-8`, 맥 OS, 안드로이드 및 VxWorks에서;

  - `UTF-8`, `Py_LegacyWindowsFSEncodingFlag`이 0일 때 윈도우에서;

  - `UTF-8`, 파이썬 UTF-8 모드가 활성화되었을 때;

  - `ASCII`, `LC_CTYPE` 로케일이 `"C"`이고, `nl_langinfo(CODESET)`이 `ASCII` 인코딩(또는 별칭)을 반환하고, `mbstowcs()`와 `wcstombs()` 함수가 `ISO-8859-1` 인코딩을 사용할 때.

  - 현재 로케일 인코딩

  이 함수는 파이썬 UTF-8 모드에서 UTF-8 인코딩을 사용합니다.

  새로 할당된 바이트열에 대한 포인터를 반환합니다, 메모리를 해제하려면 `PyMem_Free()`를 사용하십시오. 인코딩 에러나 메모리 할당 에러 시 `NULL`을 반환합니다

  error_pos가 `NULL`이 아니면, `*error_pos`는 성공 시 `(size_t)-1`로 설정되고, 인코딩 에러 시 유효하지 않은 문자의 인덱스로 설정됩니다.

  바이트열을 와이드 문자 문자열로 다시 디코딩하려면 `Py_DecodeLocale()` 함수를 사용하십시오.

  더 보기

  `PyUnicode_EncodeFSDefault()`와 `PyUnicode_EncodeLocale()` 함수.

  버전 3.5에 추가.

  버전 3.7에서 변경: 이 함수는 이제 UTF-8 모드에서 UTF-8 인코딩을 사용합니다.

  버전 3.8에서 변경: 이 함수는 이제 윈도우에서 `Py_LegacyWindowsFSEncodingFlag`가 0이면 UTF-8 인코딩을 사용합니다;

# 시스템 함수

`sys` 모듈의 기능을 C 코드에서 액세스 할 수 있게 하는 유틸리티 함수입니다. 모두 내부 스레드 상태 구조체에 포함된 현재 인터프리터 스레드의 `sys` 모듈의 딕셔너리에 작동합니다.

PyObject *`PySys_GetObject`(const char *name)
  Return value: Borrowed reference.

  `sys` 모듈에서 객체 name을 반환하거나, 존재하지 않으면 예외를 설정하지 않고 `NULL`을 반환합니다.

int `PySys_SetObject`(const char *name, PyObject *v)

  v가 NULL이 아닌 한 `sys` 모듈의 name을 v로 설정합니다. `NULL`이면 name은 sys 모듈에서 삭제됩니다. 성공하면 `0`, 에러 시 `-1`을 반환합니다.

void `PySys_ResetWarnOptions`()

  `sys.warnoptions`를 빈 리스트로 재설정합니다. 이 함수는 `Py_Initialize()` 이전에 호출할 수 있습니다.

void `PySys_AddWarnOption`(const wchar_t *s)

  s를 `sys.warnoptions`에 추가합니다. 경고 필터 리스트에 영향을 주려면 `Py_Initialize()` 이전에 이 함수를 호출해야 합니다.

void `PySys_AddWarnOptionUnicode`(PyObject *unicode)

  unicode를 `sys.warnoptions`에 추가합니다.

  참고: 이 함수는 현재 CPython 구현 외부에서 사용할 수 없습니다. 효과가 있으려면 `Py_Initialize()`에서 `warnings`를 묵시적으로 임포트 하기 전에 호출해야 하지만, 유니코드 객체를 만들도록 허락할 수 있을 만큼 런타임이 충분히 초기화되기 전에는 호출할 수 없기 때문입니다.

void `PySys_SetPath`(const wchar_t *path)

  `sys.path`를 플랫폼의 검색 경로 구분자(유닉스에서는 `:`, 윈도우에서는 `;`)로 구분된 경로 리스트여야 하는 path에서 찾은 경로의 리스트 객체로 설정합니다.

void `PySys_WriteStdout`(const char *format, ...)

  format으로 기술되는 출력 문자열을 `sys.stdout`에 기록합니다. 잘림이 발생하더라도 예외는 발생하지 않습니다 (아래를 참조하십시오).

  format은 포맷된 출력 문자열의 총 크기를 1000바이트 이하로 제한해야 합니다 – 1000바이트 이후에는, 출력 문자열이 잘립니다. 특히, 이것은 무제한 “%s” 포맷이 있어서는 안 됨을 의미합니다; “%.<N>s”를 사용하여 제한해야 합니다, 여기서 <N>은 <N>에 다른 포맷된 텍스트의 최대 크기를 더할 때 1000바이트를 초과하지 않도록 계산된 십진수입니다. 또한 “%f”도 주의하십시오, 아주 큰 숫자는 수백 자리를 인쇄할 수 있습니다.

  문제가 발생하거나, `sys.stdout`가 설정되어 있지 않으면, 포맷된 메시지는 실제(C 수준) stdout에 기록됩니다.

void `PySys_WriteStderr`(const char *format, ...)

  `PySys_WriteStdout()`과 같지만, 대신 `sys.stderr`이나 stderr에 씁니다.

void `PySys_FormatStdout`(const char *format, ...)

  PySys_WriteStdout()과 유사한 함수이지만, 메시지를 `PyUnicode_FromFormatV()`를 사용하여 포맷하고 메시지를 임의의 길이로 자르지 않습니다.

  버전 3.2에 추가.

void `PySys_FormatStderr`(const char *format, ...)

  `PySys_FormatStdout()`과 같지만, 대신 `sys.stderr`이나 stderr에 씁니다.

  버전 3.2에 추가.

void `PySys_AddXOption`(const wchar_t *s)

  s를 `-X` 옵션 집합으로 구문 분석하고 `PySys_GetXOptions()`가 반환하는 현재 옵션 매핑에 추가합니다. 이 함수는 `Py_Initialize()` 이전에 호출할 수 있습니다.

  버전 3.2에 추가.

PyObject *`PySys_GetXOptions`()
  Return value: Borrowed reference.

  `sys._xoptions`와 유사하게, `-X` 옵션의 현재 딕셔너리를 반환합니다. 에러가 발생하면, `NULL`이 반환되고 예외가 설정됩니다.

  버전 3.2에 추가.

int `PySys_Audit`(const char *event, const char *format, ...)

  모든 활성 훅으로 감사 이벤트를 발생시킵니다. 성공 시 0을 반환하고 실패 시 예외를 설정하여 0이 아닌 값을 반환합니다.

  훅이 추가되었으면, format과 기타 인자를 사용하여 전달할 튜플을 구성합니다. `N` 외에도, `Py_BuildValue()`에서 사용된 것과 같은 포맷 문자를 사용할 수 있습니다. 빌드된 값이 튜플이 아니면, 단일 요소 튜플에 추가됩니다. (`N` 포맷 옵션은 참조를 소비하지만, 이 함수에 대한 인자가 소비될지를 알 방법이 없기 때문에, 사용하면 참조 누수가 발생할 수 있습니다.)

  `PY_SSIZE_T_CLEAN`이 정의되었는지와 관계없이, `#` 포맷 문자는 항상 `Py_ssize_t`로 처리되어야 합니다.

  `sys.audit()`은 파이썬 코드와 동일한 기능을 수행합니다.

  버전 3.8에 추가.

  버전 3.8.2에서 변경: `#` 포맷 문자에 대해 `Py_ssize_t`를 요구합니다. 이전에는, 피할 수 없는 폐지 경고가 발생했습니다.

int `PySys_AddAuditHook`(Py_AuditHookFunction hook, void *userData)

  활성 감사 훅 리스트에 콜러블 hook을 추가합니다. 성공하면 0을, 실패하면 0이 아닌 값을 반환합니다. 런타임이 초기화되었으면, 실패 시 에러도 설정합니다. 이 API를 통해 추가된 훅은 런타임이 만든 모든 인터프리터에 대해 호출됩니다.

  userData 포인터는 훅 함수로 전달됩니다. 훅 함수는 다른 런타임에서 호출될 수 있어서, 이 포인터는 파이썬 상태를 직접 참조하면 안 됩니다.

  이 함수는 `Py_Initialize()` 이전에 호출해도 안전합니다. 런타임 초기화 후 호출되면, 기존 감사 훅에 알리고 `Exception`에서 서브 클래싱 된 에러를 발생 시켜 조용히 연산을 중단할 수 있습니다 (다른 에러는 억제되지(silenced) 않습니다).

  훅 함수는 `int (*)(const char *event, PyObject *args, void *userData)` 형입니다. 여기서 args는 `PyTupleObject` 임이 보장됩니다. 훅 함수는 항상 이벤트를 발생시킨 파이썬 인터프리터가 GIL을 잡은 채로 호출됩니다.

  감사에 대한 자세한 설명은 PEP 578을 참조하십시오. 이벤트를 발생시키는 런타임과 표준 라이브러리의 함수는 감사 이벤트 표에 나열되어 있습니다. 자세한 내용은 각 함수 설명서에 있습니다.

  인자 없이 감사 이벤트 `sys.addaudithook`을 발생시킵니다.

  버전 3.8에 추가.

# 프로세스 제어

void `Py_FatalError`(const char *message)

  치명적인 에러 메시지를 인쇄하고 프로세스를 죽입니다. 아무런 정리도 수행되지 않습니다. 이 함수는 파이썬 인터프리터를 계속 사용하는 것이 위험한 조건이 감지되었을 때만 호출해야 합니다; 예를 들어, 객체 관리가 손상된 것으로 보일 때. 유닉스에서는, 표준 C 라이브러리 함수 `abort()`가 호출되어 `core` 파일을 생성하려고 시도합니다.

void `Py_Exit`(int status)

  현재 프로세스를 종료합니다. 이것은 `Py_FinalizeEx()`를 호출한 다음 표준 C 라이브러리 함수 `exit(status)`를 호출합니다. `Py_FinalizeEx()`가 에러를 표시하면, 종료 상태는 120으로 설정됩니다.

  버전 3.6에서 변경: 파이널리제이션에서의 에러가 더는 무시되지 않습니다.

int `Py_AtExit`(void (*func)())

  `Py_FinalizeEx()`가 호출할 정리 함수를 등록합니다. 정리 함수는 인자 없이 호출되며 값을 반환하지 않아야 합니다. 최대 32개의 정리 함수를 등록할 수 있습니다. 등록이 성공하면, `Py_AtExit()`는 `0`을 반환합니다; 실패하면 `-1`을 반환합니다. 마지막에 등록된 정리 함수가 먼저 호출됩니다. 각 정리 함수는 최대 한 번 호출됩니다. 정리 함수 전에 파이썬의 내부 파이널리제이션이 완료되기 때문에, func에서 파이썬 API를 호출하면 안 됩니다.