操作系统实用程序

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)

如果标准 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() 允许注册自定义 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，则将不包括空字符的宽字符数量写入 *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 编码。

系统函数

这些是实用函数，它们使来自 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，在这种情况下，name 将从 sys 模块中删除。成功返回 0，失败返回 -1。

void PySys_ResetWarnOptions()

是 稳定 ABI 的一部分。

将 sys.warnoptions 重置为空列表。此函数可以在调用 Py_Initialize() 之前调用。

void PySys_AddWarnOption(const wchar_t *s)

是 稳定 ABI 的一部分。

此 API 保持向后兼容性：应改用设置 PyConfig.warnoptions，请参阅 Python 初始化配置。

将 s 附加到 sys.warnoptions。此函数必须在调用 Py_Initialize() 之前调用，以影响警告过滤器列表。

自版本 3.11 起已弃用。

void PySys_AddWarnOptionUnicode(PyObject *unicode)

是 稳定 ABI 的一部分。

此 API 保持向后兼容性：应改用设置 PyConfig.warnoptions，请参阅 Python 初始化配置。

将 unicode 附加到 sys.warnoptions。

注意：此函数目前无法从 CPython 实现之外使用，因为它必须在 warnings 在 Py_Initialize() 中隐式导入之前调用才能生效，但不能在运行时初始化到足以允许创建 Unicode 对象之前调用。

自版本 3.11 起已弃用。

void PySys_SetPath(const wchar_t *path)

是 稳定 ABI 的一部分。

此 API 保持向后兼容性：应改用设置 PyConfig.module_search_paths 和 PyConfig.module_search_paths_set，请参阅 Python 初始化配置。

将 sys.path 设置为在 path 中找到的路径列表对象，path 应该是用平台的搜索路径分隔符（在 Unix 上为 :，在 Windows 上为 ;）分隔的路径列表。

自版本 3.11 起已弃用。

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 版本中添加。

void PySys_AddXOption(const wchar_t *s)

自版本 3.7 起，作为 稳定 ABI 的一部分。

此 API 保持向后兼容性：应改为设置 PyConfig.xoptions，请参阅 Python 初始化配置。

将 *s* 解析为一组 -X 选项，并将它们添加到当前选项映射中，如 PySys_GetXOptions() 所返回。此函数可以在 Py_Initialize() 之前调用。

在 3.2 版本中添加。

自版本 3.11 起已弃用。

PyObject *PySys_GetXOptions()

返回值：借用引用。 自 3.7 版本起，是 稳定 ABI 的一部分。

返回当前的 -X 选项字典，类似于 sys._xoptions。如果发生错误，则返回 NULL 并设置异常。

在 3.2 版本中添加。

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

使用任何活动的钩子引发审计事件。成功返回零，失败返回非零值，并在失败时设置异常。

如果添加了任何钩子，format 和其他参数将用于构建一个元组以传递。除了 N 之外，还可以使用与 Py_BuildValue() 中相同的格式字符。如果构建的值不是元组，它将被添加到一个单元素元组中。（N 格式选项消耗一个引用，但由于无法知道此函数的参数是否会被消耗，因此使用它可能会导致引用泄漏。）

请注意，# 格式字符应始终被视为 Py_ssize_t，无论是否定义了 PY_SSIZE_T_CLEAN。

sys.audit() 从 Python 代码执行相同的函数。

在版本 3.8 中添加。

在版本 3.8.2 中更改： 要求 Py_ssize_t 用于 # 格式字符。以前，会引发不可避免的弃用警告。

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() 的 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() 函数将被替换为一个宏，该宏会自动记录当前函数的名称。

Changed in version 3.9: 自动记录函数名称。

void Py_Exit(int status)

是 稳定 ABI 的一部分。

退出当前进程。这将调用 Py_FinalizeEx()，然后调用标准 C 库函数 exit(status)。如果 Py_FinalizeEx() 指示错误，则退出状态将设置为 120。

Changed in version 3.6: 不再忽略来自最终化的错误。

int Py_AtExit(void (*func)())

是 稳定 ABI 的一部分。

注册一个清理函数，由 Py_FinalizeEx() 调用。清理函数将被调用，不带任何参数，也不应该返回任何值。最多可以注册 32 个清理函数。当注册成功时，Py_AtExit() 返回 0；如果失败，则返回 -1。最后注册的清理函数将首先被调用。每个清理函数最多会被调用一次。由于 Python 的内部最终化将在清理函数之前完成，因此 func 不应该调用任何 Python API。