운영 체제 유틸리티

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 인코딩을 사용합니다.

Return a pointer to a newly allocated byte string, use PyMem_Free() to free the memory. Return NULL on encoding error or memory allocation error.

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

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

더 보기

PyUnicode_EncodeFSDefault()와 PyUnicode_EncodeLocale() 함수.

버전 3.5에 추가.

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

버전 3.8에서 변경: The function now uses the UTF-8 encoding on Windows if Py_LegacyWindowsFSEncodingFlag is zero.

시스템 함수

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 포맷 옵션은 참조를 소비하지만, 이 함수에 대한 인자가 소비될지를 알 방법이 없기 때문에, 사용하면 참조 누수가 발생할 수 있습니다.)

Note that # format characters should always be treated as Py_ssize_t, regardless of whether PY_SSIZE_T_CLEAN was defined.

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

버전 3.8에 추가.

버전 3.8.2에서 변경: Require Py_ssize_t for # format characters. Previously, an unavoidable deprecation warning was raised.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

Append the callable hook to the list of active auditing hooks. Return zero on success and non-zero on failure. If the runtime has been initialized, also set an error on failure. Hooks added through this API are called for all interpreters created by the runtime.

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 파일을 생성하려고 시도합니다.

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

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

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를 호출하면 안 됩니다.