# 운영 체제 유틸리티

PyObject *PyOS_FSPath(PyObject *path)
  반환값: 새 참조. Part of the 안정 ABI 버전 3.6 이후로.

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

  Added in version 3.6.

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

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

  This function must not be called before Python is initialized.

void PyOS_BeforeFork()
  Part of the 안정 ABI on platforms with fork() 버전 3.7 이후로.

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

  경고

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

  Added in version 3.7.

void PyOS_AfterFork_Parent()
  Part of the 안정 ABI on platforms with fork() 버전 3.7 이후로.

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

  경고

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

  Added in version 3.7.

void PyOS_AfterFork_Child()
  Part of the 안정 ABI on platforms with fork() 버전 3.7 이후로.

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

  경고

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

  Added in version 3.7.

  더 보기

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

void PyOS_AfterFork()
  Part of the 안정 ABI on platforms with fork().

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

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

int PyOS_CheckStack()
  Part of the 안정 ABI on platforms with USE_STACKCHECK 버전 3.7 이후로.

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

typedef void (*PyOS_sighandler_t)(int)
  Part of the 안정 ABI.

PyOS_sighandler_t PyOS_getsig(int i)
  Part of the 안정 ABI.

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

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
  Part of the 안정 ABI.

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

int PyOS_InterruptOccurred(void)
  Part of the 안정 ABI.

  Check if a `SIGINT` signal has been received.

  Returns `1` if a `SIGINT` has occurred and clears the signal flag, or `0` otherwise.

  In most cases, you should prefer `PyErr_CheckSignals()` over this function. `PyErr_CheckSignals()` invokes the appropriate signal handlers for all pending signals, allowing Python code to handle the signal properly. This function only detects `SIGINT` and does not invoke any Python signal handlers.

  This function is async-signal-safe and this function cannot fail. The caller must hold an attached thread state.

wchar_t *Py_DecodeLocale(const char *arg, size_t *size)
  Part of the 안정 ABI 버전 3.7 이후로.

  경고

  This function should not be called directly: use the `PyConfig` API with the `PyConfig_SetBytesString()` function which ensures that Python is preinitialized.

  This function must not be called before Python is preinitialized and so that the LC_CTYPE locale is properly configured: see the `Py_PreInitialize()` function.

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

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

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

  The filesystem encoding and error handler are selected by `PyConfig_Read()`: see `filesystem_encoding` and `filesystem_errors` members of `PyConfig`.

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

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

  더 보기

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

  Added in version 3.5.

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

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

char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
  Part of the 안정 ABI 버전 3.7 이후로.

  와이드 문자(wide character) 문자열을 파일시스템 인코딩과 에러 처리기로 인코딩합니다. 에러 처리기가 surrogateescape 에러 처리기면 U+DC80..U+DCFF 범위의 서로게이트 문자는 바이트 0x80..0xFF로 변환됩니다.

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

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

  The filesystem encoding and error handler are selected by `PyConfig_Read()`: see `filesystem_encoding` and `filesystem_errors` members of `PyConfig`.

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

  경고

  This function must not be called before Python is preinitialized and so that the LC_CTYPE locale is properly configured: see the `Py_PreInitialize()` function.

  더 보기

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

  Added in version 3.5.

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

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

FILE *Py_fopen(PyObject *path, const char *mode)

  Similar to `fopen()`, but path is a Python object and an exception is set on error.

  path must be a `str` object, a `bytes` object, or a path-like object.

  On success, return the new file pointer. On error, set an exception and return `NULL`.

  The file must be closed by `Py_fclose()` rather than calling directly `fclose()`.

  The file descriptor is created non-inheritable (PEP 446).

  The caller must have an attached thread state.

  Added in version 3.14.

int Py_fclose(FILE *file)

  Close a file that was opened by `Py_fopen()`.

  On success, return `0`. On error, return `EOF` and `errno` is set to indicate the error. In either case, any further access (including another call to `Py_fclose()`) to the stream results in undefined behavior.

  Added in version 3.14.

# 시스템 함수

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

PyObject *PySys_GetAttr(PyObject *name)
  Part of the 안정 ABI 버전 3.15 이후로.

  Get the attribute name of the `sys` module. Return a strong reference. Raise `RuntimeError` and return `NULL` if it does not exist or if the `sys` module cannot be found.

  If the non-existing object should not be treated as a failure, you can use `PySys_GetOptionalAttr()` instead.

  Added in version 3.15.

PyObject *PySys_GetAttrString(const char *name)
  Part of the 안정 ABI 버전 3.15 이후로.

  This is the same as `PySys_GetAttr()`, but name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

  If the non-existing object should not be treated as a failure, you can use `PySys_GetOptionalAttrString()` instead.

  Added in version 3.15.

int PySys_GetOptionalAttr(PyObject *name, PyObject **result)
  Part of the 안정 ABI 버전 3.15 이후로.

  Variant of `PySys_GetAttr()` which doesn’t raise exception if the object does not exist.

  - Set *result to a new strong reference to the object and return `1` if the object exists.

  - Set *result to `NULL` and return `0` without setting an exception if the object does not exist.

  - Set an exception, set *result to `NULL`, and return `-1`, if an error occurred.

  Added in version 3.15.

int PySys_GetOptionalAttrString(const char *name, PyObject **result)
  Part of the 안정 ABI 버전 3.15 이후로.

  This is the same as `PySys_GetOptionalAttr()`, but name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

  Added in version 3.15.

PyObject *PySys_GetObject(const char *name)
  반환값: 빌린 참조. Part of the 안정 ABI.

  Similar to `PySys_GetAttrString()`, but return a borrowed reference and return `NULL` without setting exception on failure.

  Preserves exception that was set before the call.

int PySys_SetObject(const char *name, PyObject *v)
  Part of the 안정 ABI.

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

void PySys_WriteStdout(const char *format, ...)
  Part of the 안정 ABI.

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

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

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

void PySys_WriteStderr(const char *format, ...)
  Part of the 안정 ABI.

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

void PySys_FormatStdout(const char *format, ...)
  Part of the 안정 ABI.

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

  Added in version 3.2.

void PySys_FormatStderr(const char *format, ...)
  Part of the 안정 ABI.

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

  Added in version 3.2.

PyObject *PySys_GetXOptions()
  반환값: 빌린 참조. Part of the 안정 ABI 버전 3.7 이후로.

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

  Added in version 3.2.

int PySys_Audit(const char *event, const char *format, ...)
  Part of the 안정 ABI 버전 3.13 이후로.

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

  The event string argument must not be NULL.

  훅이 추가되었으면, format과 기타 인자를 사용하여 전달할 튜플을 구성합니다. `N` 외에도, `Py_BuildValue()`에서 사용된 것과 같은 포맷 문자를 사용할 수 있습니다. 빌드된 값이 튜플이 아니면, 단일 요소 튜플에 추가됩니다.

  `N` 포맷 옵션은 사용하지 않아야 합니다. 참조를 소비하지만, 이 함수에 대한 인자가 소비될지를 알 방법이 없기 때문에, 사용하면 참조 누수가 발생할 수 있습니다.

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

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

  See also `PySys_AuditTuple()`.

  Added in version 3.8.

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

int PySys_AuditTuple(const char *event, PyObject *args)
  Part of the 안정 ABI 버전 3.13 이후로.

  Similar to `PySys_Audit()`, but pass arguments as a Python object. args must be a `tuple`. To pass no arguments, args can be NULL.

  Added in version 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

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

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

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

  The hook function is always called with an attached thread state by the Python interpreter that raised the event.

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

  인터프리터가 초기화되면, 이 함수는 인자 없이 감사 이벤트 `sys.addaudithook`을 발생시킵니다. 기존 훅이 `Exception`에서 파생된 예외를 발생시키면, 새 훅이 추가되지 않고 예외가 지워집니다. 결과적으로, 호출자가 기존의 모든 훅을 제어하지 않는 한 훅이 추가되었다고 가정할 수 없습니다.

  typedef int (*Py_AuditHookFunction)(const char *event, PyObject *args, void *userData)

    The type of the hook function. event is the C string event argument passed to `PySys_Audit()` or `PySys_AuditTuple()`. args is guaranteed to be a `PyTupleObject`. userData is the argument passed to PySys_AddAuditHook().

  Added in version 3.8.

# 프로세스 제어

void Py_FatalError(const char *message)
  Part of the 안정 ABI.

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

  `Py_LIMITED_API` 매크로가 정의되어 있지 않은 한, `Py_FatalError()` 함수는 현재 함수의 이름을 자동으로 로그 하는 매크로로 대체됩니다.

  버전 3.9에서 변경: 함수 이름을 자동으로 로그 합니다.

void Py_Exit(int status)
  Part of the 안정 ABI.

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

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

int Py_AtExit(void (*func)())
  Part of the 안정 ABI.

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

  더 보기

  `PyUnstable_AtExit()` for passing a `void *data` argument.