作業系統實用程式

PyObject *PyOS_FSPath(PyObject *path)

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

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

在 3.6 版本加入。

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

如果名稱為 filename 的標準 I/O 檔案 fp 被認為是互動式的，則返回 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() 允許註冊自定義 Python 函式，以便由 PyOS_BeforeFork()、PyOS_AfterFork_Parent() 和 PyOS_AfterFork_Child() 呼叫。

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，則將不包含 null 字元的寬字元數寫入 *size。

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

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

解碼錯誤不應該發生，除非 C 庫存在 bug。

使用 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 編碼。

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

與 fopen() 類似，但 path 是一個 Python 物件，並在出錯時設定異常。

path 必須是 str 物件、bytes 物件或 類路徑物件。

成功時，返回新的檔案指標。出錯時，設定異常並返回 NULL。

檔案必須由 Py_fclose() 關閉，而不是直接呼叫 fclose()。

檔案描述符建立為不可繼承（PEP 446）。

呼叫者必須具有 已附加的執行緒狀態。

在 3.14 版本加入。

int Py_fclose(FILE *file)

關閉由 Py_fopen() 開啟的檔案。

成功時，返回 0。出錯時，返回 EOF 並將 errno 設定為指示錯誤。在任何一種情況下，對流的任何進一步訪問（包括另一次呼叫 Py_fclose()）都會導致未定義的行為。

在 3.14 版本加入。

系統函式

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

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_CLEAN，# 格式字元都應始終被視為 Py_ssize_t。

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 直譯器以 已附加的執行緒狀態 呼叫。

有關審計的詳細描述，請參閱 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 引數。