作業系統實用工具

PyObject *PyOS_FSPath(PyObject *path)

返回值：新引用。自 3.6 版本起成為 穩定 ABI 的一部分。

返回 path 的檔案系統表示形式。如果物件是 str 或 bytes 物件，則返回新的 強引用。如果物件實現了 os.PathLike 介面，則只要它是 str 或 bytes 物件，就會返回 __fspath__()。否則，會引發 TypeError 並返回 NULL。

在 3.6 版本中新增。

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

如果標準 I/O 檔案 fp 的名稱 filename 被認為是互動式的，則返回 true（非零）。對於滿足 isatty(fileno(fp)) 為 true 的檔案是這種情況。如果 PyConfig.interactive 為非零，則如果 filename 指標為 NULL 或者名稱等於字串 '<stdin>' 或 '???' 之一，此函式也會返回 true。

此函式不得在 Python 初始化之前呼叫。

void PyOS_BeforeFork()

自 3.7 版本起，在具有 fork() 的平臺上成為 穩定 ABI 的一部分。

在程序 fork 之前準備一些內部狀態的函式。這應該在呼叫 fork() 或任何類似的克隆當前程序的函式之前呼叫。僅在定義了 fork() 的系統上可用。

警告

C fork() 呼叫應僅從 “主”執行緒（“主”直譯器）呼叫。PyOS_BeforeFork() 也是如此。

在 3.7 版本中新增。

void PyOS_AfterFork_Parent()

自 3.7 版本起，在具有 fork() 的平臺上成為 穩定 ABI 的一部分。

在程序 fork 之後更新一些內部狀態的函式。這應該在呼叫 fork() 或任何類似的克隆當前程序的函式之後，從父程序呼叫，無論程序克隆是否成功。僅在定義了 fork() 的系統上可用。

警告

C fork() 呼叫應僅從 “主”執行緒（“主”直譯器）呼叫。PyOS_AfterFork_Parent() 也是如此。

在 3.7 版本中新增。

void PyOS_AfterFork_Child()

自 3.7 版本起，在具有 fork() 的平臺上成為 穩定 ABI 的一部分。

在程序 fork 之後更新內部直譯器狀態的函式。如果在程序中有任何可能呼叫回 Python 直譯器的情況，則必須在呼叫 fork() 或任何類似的克隆當前程序的函式之後，從子程序呼叫此函式。僅在定義了 fork() 的系統上可用。

警告

C fork() 呼叫應僅從 “主”執行緒（“主”直譯器）呼叫。PyOS_AfterFork_Child() 也是如此。

在 3.7 版本中新增。

另請參閱

os.register_at_fork() 允許註冊由 PyOS_BeforeFork()、PyOS_AfterFork_Parent() 和 PyOS_AfterFork_Child() 呼叫的自定義 Python 函式。

void PyOS_AfterFork()

在具有 fork() 的平臺上成為 穩定 ABI 的一部分。

在程序 fork 之後更新一些內部狀態的函式；如果 Python 直譯器將繼續使用，則應在新程序中呼叫此函式。如果新程序中載入了新的可執行檔案，則無需呼叫此函式。

自 3.7 版本起棄用: 此函式被 PyOS_AfterFork_Child() 取代。

int PyOS_CheckStack()

自 3.7 版本起，在具有 USE_STACKCHECK 的平臺上成為 穩定 ABI 的一部分。

當直譯器耗盡堆疊空間時返回 true。這是一個可靠的檢查，但僅在定義了 USE_STACKCHECK 時可用（目前在使用 Microsoft Visual C++ 編譯器的某些 Windows 版本上）。USE_STACKCHECK 將自動定義；您絕不應在自己的程式碼中更改定義。

typedef void (*PyOS_sighandler_t)(int)

屬於 穩定 ABI 的一部分。

PyOS_sighandler_t PyOS_getsig(int i)

屬於 穩定 ABI 的一部分。

返回訊號 i 的當前訊號處理程式。這是對 sigaction() 或 signal() 的一個簡單封裝。請不要直接呼叫這些函式！

PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)

屬於 穩定 ABI 的一部分。

將訊號 i 的訊號處理程式設定為 h；返回舊的訊號處理程式。這是對 sigaction() 或 signal() 的一個簡單封裝。請不要直接呼叫這些函式！

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

自 3.7 版本起成為 穩定 ABI 的一部分。

警告

不應直接呼叫此函式：請使用 PyConfig API 和 PyConfig_SetBytesString() 函式，以確保 Python 已被預初始化。

必須在 Python 被預初始化 之後才能呼叫此函式，以便正確配置 LC_CTYPE 區域設定：請參閱 Py_PreInitialize() 函式。

從檔案系統編碼和錯誤處理程式解碼位元組字串。如果錯誤處理程式是 surrogateescape 錯誤處理程式，則不可解碼的位元組將解碼為 U+DC80..U+DCFF 範圍內的字元；如果一個位元組序列可以解碼為代理字元，則將使用 surrogateescape 錯誤處理程式來轉義位元組，而不是解碼它們。

返回指向新分配的寬字元字串的指標，使用 PyMem_RawFree() 來釋放記憶體。如果 size 不為 NULL，則將不包括空字元的寬字元數寫入 *size

在解碼錯誤或記憶體分配錯誤時返回 NULL。如果 size 不為 NULL，則在記憶體錯誤時將 *size 設定為 (size_t)-1，或在解碼錯誤時設定為 (size_t)-2。

檔案系統編碼和錯誤處理程式由 PyConfig_Read() 選擇：請參閱 filesystem_encoding 和 filesystem_errors 的 PyConfig 成員。

除非 C 庫中存在錯誤，否則不應發生解碼錯誤。

使用 Py_EncodeLocale() 函式將字元字串編碼回字節字串。

另請參閱

請參考 PyUnicode_DecodeFSDefaultAndSize() 和 PyUnicode_DecodeLocaleAndSize() 函式。

在 3.5 版本中新增。

在 3.7 版本中更改: 該函式現在在 Python UTF-8 模式中使用 UTF-8 編碼。

在 3.8 版本中更改: 如果 PyPreConfig.legacy_windows_fs_encoding 為零，則該函式現在在 Windows 上使用 UTF-8 編碼；

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

自 3.7 版本起成為 穩定 ABI 的一部分。

將寬字元字串編碼為 檔案系統編碼和錯誤處理程式。如果錯誤處理程式是 surrogateescape 錯誤處理程式，則 U+DC80..U+DCFF 範圍內的代理字元將轉換為位元組 0x80..0xFF。

返回指向新分配的位元組字串的指標，使用 PyMem_Free() 來釋放記憶體。在編碼錯誤或記憶體分配錯誤時返回 NULL。

如果 error_pos 不為 NULL，則在成功時將 *error_pos 設定為 (size_t)-1，或在編碼錯誤時設定為無效字元的索引。

檔案系統編碼和錯誤處理程式由 PyConfig_Read() 選擇：請參閱 filesystem_encoding 和 filesystem_errors 的 PyConfig 成員。

使用 Py_DecodeLocale() 函式將位元組字串解碼回寬字元字串。

警告

必須在 Python 被預初始化 之後才能呼叫此函式，以便正確配置 LC_CTYPE 區域設定：請參閱 Py_PreInitialize() 函式。

另請參閱

請參考 PyUnicode_EncodeFSDefault() 和 PyUnicode_EncodeLocale() 函式。

在 3.5 版本中新增。

在 3.7 版本中更改: 該函式現在在 Python UTF-8 模式中使用 UTF-8 編碼。

在 3.8 版本中更改: 如果 PyPreConfig.legacy_windows_fs_encoding 為零，則該函式現在在 Windows 上使用 UTF-8 編碼。

系統函式

這些是實用函式，使 C 程式碼可以訪問 sys 模組的功能。 它們都使用當前直譯器執行緒的 sys 模組的 dict，該 dict 包含在內部執行緒狀態結構中。

PyObject *PySys_GetObject(const char *name)

返回值：借來的引用。 穩定 ABI 的一部分。

從 sys 模組返回物件 name，如果該物件不存在，則返回 NULL，而不設定異常。

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

屬於 穩定 ABI 的一部分。

將 sys 模組中的 name 設定為 v，除非 v 為 NULL，在這種情況下，將從 sys 模組中刪除 name。 成功時返回 0，錯誤時返回 -1。

void PySys_ResetWarnOptions()

屬於 穩定 ABI 的一部分。

將 sys.warnoptions 重置為空列表。此函式可以在 Py_Initialize() 之前呼叫。

自 3.13 版本起已棄用，將在 3.15 版本中移除: 請改為清除 sys.warnoptions 和 warnings.filters。

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

屬於 穩定 ABI 的一部分。

將 format 描述的輸出字串寫入 sys.stdout。即使發生截斷，也不會引發異常（請參見下文）。

format 應將格式化輸出字串的總大小限制為 1000 位元組或更少 – 超過 1000 位元組後，輸出字串將被截斷。特別是，這意味著不應出現無限制的“%s”格式；這些格式應使用“%.<N>s”來限制，其中 <N> 是一個十進位制數，計算得出 <N> 加上其他格式化文字的最大大小不超過 1000 位元組。還要注意 “%f”，它可以為非常大的數字列印數百位數字。

如果發生問題，或 sys.stdout 未設定，則格式化訊息將寫入真實的（C 級別）stdout。

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

屬於 穩定 ABI 的一部分。

與 PySys_WriteStdout() 類似，但寫入 sys.stderr 或 stderr。

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

屬於 穩定 ABI 的一部分。

函式類似於 PySys_WriteStdout()，但使用 PyUnicode_FromFormatV() 格式化訊息，並且不會將訊息截斷為任意長度。

在 3.2 版本中新增。

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

屬於 穩定 ABI 的一部分。

與 PySys_FormatStdout() 類似，但寫入 sys.stderr 或 stderr。

在 3.2 版本中新增。

PyObject *PySys_GetXOptions()

返回值：借用的引用。 自 3.7 版本以來是 穩定 ABI 的一部分。

返回當前 -X 選項的字典，類似於 sys._xoptions。如果發生錯誤，則返回 NULL 並設定異常。

在 3.2 版本中新增。

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

自 3.13 版本以來是 穩定 ABI 的一部分。

使用任何活動鉤子引發審計事件。成功返回零，失敗返回非零並設定異常。

event 字串引數不得為 NULL。

如果已新增任何鉤子，則將使用 format 和其他引數來構造一個元組來傳遞。除了 N，還提供與 Py_BuildValue() 中使用的相同的格式字元。如果構建的值不是元組，則將其新增到單元素元組中。

不得使用 N 格式選項。它會消耗一個引用，但由於無法知道此函式的引數是否會被消耗，因此使用它可能會導致引用洩漏。

請注意，# 格式字元應始終被視為 Py_ssize_t，無論是否定義了 PY_SSIZE_T_CLEAN。

sys.audit() 從 Python 程式碼執行相同的功能。

另請參見 PySys_AuditTuple()。

在 3.8 版本中新增。

在 3.8.2 版本中更改: # 格式字元需要 Py_ssize_t。 以前，會引發不可避免的棄用警告。

int PySys_AuditTuple(const char *event, PyObject *args)

自 3.13 版本以來是 穩定 ABI 的一部分。

類似於 PySys_Audit()，但將引數作為 Python 物件傳遞。args 必須是 tuple。要傳遞不帶引數，args 可以為 NULL。

在 3.13 版本中新增。

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

將可呼叫 hook 附加到活動審計鉤子的列表。成功返回零，失敗返回非零。如果執行時已初始化，則在失敗時也設定錯誤。透過此 API 新增的鉤子將為執行時建立的所有直譯器呼叫。

userData 指標將傳遞到鉤子函式中。由於可以從不同的執行時呼叫鉤子函式，因此此指標不應直接引用 Python 狀態。

此函式在 Py_Initialize() 之前呼叫是安全的。在執行時初始化之後呼叫時，會通知現有的審計鉤子，並且可能會透過引發 Exception 的錯誤子類來靜默中止操作（其他錯誤不會被靜默）。

鉤子函式始終在引發事件的 Python 直譯器持有 GIL 的情況下呼叫。

有關審計的詳細說明，請參見 PEP 578。 執行時和標準庫中引發事件的函式在 審計事件表 中列出。 詳細資訊在每個函式的文件中。

如果直譯器已初始化，此函式會引發一個不帶引數的審計事件 sys.addaudithook。 如果任何現有鉤子引發了從 Exception 派生的異常，則不會新增新鉤子，並且該異常將被清除。因此，除非呼叫者控制所有現有鉤子，否則呼叫者不能假定已新增其鉤子。

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

鉤子函式的型別。event 是傳遞給 PySys_Audit() 或 PySys_AuditTuple() 的 C 字串事件引數。args 保證是一個 PyTupleObject。userData 是傳遞給 PySys_AddAuditHook() 的引數。

在 3.8 版本中新增。

程序控制

void Py_FatalError(const char *message)

屬於 穩定 ABI 的一部分。

列印一個致命錯誤訊息並終止程序。不執行清理操作。只有在檢測到繼續使用 Python 直譯器會很危險的情況下才應呼叫此函式；例如，當物件管理似乎已損壞時。在 Unix 上，將呼叫標準 C 庫函式 abort()，它將嘗試生成一個 core 檔案。

除非定義了 Py_LIMITED_API 宏，否則 Py_FatalError() 函式會被一個自動記錄當前函式名稱的宏替換。

在 3.9 版本中更改: 自動記錄函式名稱。

void Py_Exit(int status)

屬於 穩定 ABI 的一部分。

退出當前程序。此函式呼叫 Py_FinalizeEx()，然後呼叫標準 C 庫函式 exit(status)。如果 Py_FinalizeEx() 指示有錯誤，則退出狀態設定為 120。

在 3.6 版本中更改: 不再忽略來自最終化的錯誤。

int Py_AtExit(void (*func)())

屬於 穩定 ABI 的一部分。

註冊一個由 Py_FinalizeEx() 呼叫的清理函式。清理函式將在不帶引數的情況下呼叫，並且不應返回值。最多可以註冊 32 個清理函式。當註冊成功時，Py_AtExit() 返回 0；失敗時，它返回 -1。最後註冊的清理函式將首先被呼叫。每個清理函式最多隻會被呼叫一次。由於 Python 的內部最終化將在清理函式之前完成，因此 func 不應呼叫任何 Python API。

另請參閱

使用 PyUnstable_AtExit() 傳遞 void *data 引數。