操作系统实用工具

PyObject *PyOS_FSPath(PyObject *path)

返回值：新的引用。 属于 稳定 ABI 自 3.6 版起.

返回 path 在文件系统中的表示形式。如果该对象是一个 str 或 bytes 对象，则返回一个新的 strong reference。如果对象实现了 os.PathLike 接口，则只要它是一个 str 或 bytes 对象就将返回 __fspath__()。在其他情况下将引发 TypeError 并返回 NULL。

Added in version 3.6.

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

如果名称为 filename 的标准 I/O 文件 fp 被确认为可交互的则返回真（非零）值。所有 isatty(fileno(fp)) 为真值的文件都属于这种情况。如果 PyConfig.interactive 为非零值，此函数在 filename 指针为 NULL 或者其名称等于字符串 '<stdin>' 或 '???' 之一时也将返回真值。

此函数不可在 Python 被初始化之前调用。

void PyOS_BeforeFork()

属于 稳定 ABI on platforms with fork() 自 3.7 版起.

在进程分叉之前准备某些内部状态的函数。此函数应当在调用 fork() 或者任何类似的克隆当前进程的函数之前被调用。只适用于定义了 fork() 的系统。

警告

C fork() 调用应当只在 "main" 线程 (位于 "main" 解释器) 中进行。对于 PyOS_BeforeFork() 来说也是如此。

Added in version 3.7.

void PyOS_AfterFork_Parent()

属于 稳定 ABI on platforms with fork() 自 3.7 版起.

在进程分叉之后更新某些内部状态的函数。此函数应当在调用 fork() 或任何类似的克隆当前进程的函数之后从父进程中被调用，无论进程克隆是否成功。只适用于定义了 fork() 的系统。

警告

C fork() 调用应当只在 "main" 线程 (位于 "main" 解释器) 中进行。对于 PyOS_AfterFork_Parent() 来说也是如此。

Added in version 3.7.

void PyOS_AfterFork_Child()

属于 稳定 ABI on platforms with fork() 自 3.7 版起.

在进程分叉之后更新内部解释器状态的函数。此函数必须在调用 fork() 或任何类似的克隆当前进程的函数之后在子进程中被调用，如果该进程有机会回调到 Python 解释器的话。只适用于定义了 fork() 的系统。

警告

C fork() 调用应当只在 "main" 线程 (位于 "main" 解释器) 中进行。对于 PyOS_AfterFork_Child() 来说也是如此。

Added in version 3.7.

参见

os.register_at_fork() 允许注册可被 PyOS_BeforeFork(), PyOS_AfterFork_Parent() 和 PyOS_AfterFork_Child() 调用的自定义 Python 函数。

void PyOS_AfterFork()

属于 稳定 ABI on platforms with fork().

在进程分叉之后更新某些内部状态的函数；如果要继续使用 Python 解释器则此函数应当在新进程中被调用。如果已将一个新的可执行文件载入到新进程中，则不需要调用此函数。

自 3.7 版本弃用: 此函数已被 PyOS_AfterFork_Child() 取代。

int PyOS_CheckStack()

属于 稳定 ABI on platforms with USE_STACKCHECK 自 3.7 版起.

当解释器耗尽栈空间时返回真值。这是一个可靠的检测，但仅在定义了 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() 的简单包装器。请不要直接调用这两个函数！

int PyOS_InterruptOccurred(void)

属于 稳定 ABI.

检测是否已收到 SIGINT 信号。

如果 SIGINT 已发生则返回 1 并清空信号旗标，否则返回 0。

在大多数情况下，你都应当选择 PyErr_CheckSignals() 而不是此函数。PyErr_CheckSignals() 会为所有待处理信号调用合适的信号处理器，以允许 Python 代码正确地处理信号。此函数只能检测 SIGINT 并且不能调用任何 Python 信号处理器。

此函数是异步信号安全的并且此函数执行不会失败。调用方必须持有 attached thread state。

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

属于 稳定 ABI 自 3.7 版起.

警告

此函数不应当被直接调用：请使用 PyConfig API 以及可确保 对 Python 进行预初始化 的 PyConfig_SetBytesString() 函数。

此函数不可在 对 Python 进行预初始化 之前被调用以便正确地配置 LC_CTYPE 语言区域：请参阅 Py_PreInitialize() 函数。

使用 filesystem encoding and error handler 来解码一个字节串。如果错误处理器为 surrogateescape 错误处理器，则不可解码的字节将被解码为 U+DC80..U+DCFF 范围内的字符；而如果一个字节序列可被解码为代理字符，则其中的字节会使用 surrogateescape 错误处理器来转义而不是解码它们。

返回一个指向新分配的由宽字符组成的字符串的指针，使用 PyMem_RawFree() 来释放内存。如果 size 不为 NULL，则将排除了 null 字符的宽字符数量写入到 *size

在解码错误或内存分配错误时返回 NULL。如果 size 不为 NULL，则 *size 将在内存错误时设为 (size_t)-1 或在解码错误时设为 (size_t)-2。

filesystem encoding and error handler 是由 PyConfig_Read() 来选择的：参见 PyConfig 的 filesystem_encoding 和 filesystem_errors 等成员。

解码错误绝对不应当发生，除非 C 库有程序缺陷。

请使用 Py_EncodeLocale() 函数来将字符串编码回字节串。

参见

PyUnicode_DecodeFSDefaultAndSize() 和 PyUnicode_DecodeLocaleAndSize() 函数。

Added in version 3.5.

在 3.7 版本发生变更: 现在此函数在 Python UTF-8 模式 下将使用 UTF-8 编码格式。

在 3.8 版本发生变更: 现在如果在 Windows 上 PyPreConfig.legacy_windows_fs_encoding 为零则此函数将使用 UTF-8 编码格式；

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

属于 稳定 ABI 自 3.7 版起.

使用 filesystem encoding and error handler 将一个由宽字符组成的字符串编码为字节串。如果错误处理器为 surrogateescape 错误处理器，则在 U+DC80..U+DCFF 范围内的代理字符会被转换为字节值 0x80..0xFF。

返回一个指向新分配的字节串的指针，使用 PyMem_Free() 来释放内存。当发生编码错误或内存分配错误时返回 NULL。

如果 error_pos 不为 NULL，则成功时会将 *error_pos 设为 (size_t)-1，或是在发生编码错误时设为无效字符的索引号。

filesystem encoding and error handler 是由 PyConfig_Read() 来选择的：参见 PyConfig 的 filesystem_encoding 和 filesystem_errors 等成员。

请使用 Py_DecodeLocale() 函数来将字节串解码回由宽字符组成的字符串。

警告

此函数不可在 对 Python 进行预初始化 之前被调用以便正确地配置 LC_CTYPE 语言区域：请参阅 Py_PreInitialize() 函数。

参见

PyUnicode_EncodeFSDefault() 和 PyUnicode_EncodeLocale() 函数。

Added in version 3.5.

在 3.7 版本发生变更: 现在此函数在 Python UTF-8 模式 下将使用 UTF-8 编码格式。

在 3.8 版本发生变更: 现在如果在 Windows 上 PyPreConfig.legacy_windows_fs_encoding 为零则此函数将使用 UTF-8 编码格式。

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

类似于 fopen()，但 path 是一个 Python 对象并且会在出错时设置一个异常。

path 必须是一个 str 对象，bytes 对象或 path-like object。

成功时，返回新的文件指针。失败时，设置一个异常并返回 NULL。

文件必须通过 Py_fclose() 关闭，而不是直接调用 fclose()。

创建的文件描述符是不可继承的 (PEP 446)。

调用方必须有已附加的线程状态 attached thread state。

Added in version 3.14.

int Py_fclose(FILE *file)

关闭由 Py_fopen() 打开的文件。

如果成功，返回 0。出现错误时，返回 EOF，并设置 errno 来指示错误。在任何一种情况下，对流的任何进一步访问（包括对 Py_fclose() 的另一次调用）都会导致未定义的行为。

Added in version 3.14.

系统功能

这些是使来自 sys 模块的功能可以让 C 代码访问的工具函数。它们都可用于当前解释器线程的 sys 模块的字典，该字典包含在内部线程状态结构体中。

PyObject *PySys_GetAttr(PyObject *name)

属于 稳定 ABI 自 3.15 版起.

获取 sys 模块的 name 属性。 返回一个 strong reference。 如果该属性不存在或者如果 sys 模块无法找到则引发 RuntimeError 并返回 NULL。

如果对象不存在不应被视为执行失败，你可以改用 PySys_GetOptionalAttr()。

Added in version 3.15.

PyObject *PySys_GetAttrString(const char *name)

属于 稳定 ABI 自 3.15 版起.

这与 PySys_GetAttr() 相同，但 name 被指定为 const char* UTF-8 编码的字节串，而不是 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)

属于 稳定 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)

属于 稳定 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)

返回值：借入的引用。 属于 稳定 ABI.

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

保留在调用之前设置的异常。

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

属于 稳定 ABI.

将 sys 模块中的 name 设为 v 除非 v 为 NULL，在此情况下 name 将从 sys 模块中被删除。成功时返回 0，发生错误时返回 -1。

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() 来格式化消息并且不会将消息截短至任意长度。

Added in version 3.2.

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

属于 稳定 ABI.

类似 PySys_FormatStdout()，但改为写入到 sys.stderr 或 stderr。

Added in version 3.2.

PyObject *PySys_GetXOptions()

返回值：借入的引用。 属于 稳定 ABI 自 3.7 版起.

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

Added in version 3.2.

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

属于 稳定 ABI 自 3.13 版起.

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

event 字符串参数必须不为 NULL。

如果已添加了任何钩子，则将使用 format 和其他参数来构造一个要传入的元组。除 N 以外，还可使用在 Py_BuildValue() 中使用的相同格式字符。如果构建的值不是一个元组，它将被添加到一个单元素的元组中。

不可使用 N 格式选项。它会消耗一个引用，但是由于无法获知传给此函数的参数是否会被消耗，使用它可能导致引用泄漏。

请注意 # 格式字符应当总是被当作 Py_ssize_t 来处理，无论是否定义了 PY_SSIZE_T_CLEAN。

sys.audit() 从 Python 代码执行相同的功能。

另请参阅 PySys_AuditTuple()。

Added in version 3.8.

在 3.8.2 版本发生变更: 要求 Py_ssize_t 用于 # 格式字符。在此之前，会引发一个不可避免的弃用警告。

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

属于 稳定 ABI 自 3.13 版起.

与 PySys_Audit() 类似，但会将参数作为 Python 对象传入。args 必须是一个 tuple。 如果不传入参数，则 args 可以为 NULL。

Added in version 3.13.

int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

将可调用对象 hook 添加到激活的审计钩子列表。在成功时返回零而在失败时返回非零值。如果运行时已经被初始化，还会在失败时设置一个错误。通过此 API 添加的钩子会针对在运行时创建的所有解释器被调用。

userData 指针会被传入钩子函数。由于钩子函数可能由不同的运行时调用，该指针不应直接指向 Python 状态。

This function is safe to call before Py_Initialize(). When called after runtime initialization, existing audit hooks are notified and may silently abort the operation by raising an error subclassed from RuntimeError (other errors will not be silenced).

钩子函数总是由引发事件的 Python 解释器带 attached thread state 调用。

请参阅 PEP 578 了解有关审计的详细描述。在运行时和标准库中会引发审计事件的函数清单见 审计事件表。更多细节见每个函数的文档。

If the interpreter is initialized, this function raises an auditing event sys.addaudithook with no arguments. If any existing hooks raise an exception derived from RuntimeError, the new hook will not be added and the exception is cleared. As a result, callers cannot assume that their hook has been added unless they control all existing hooks.

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

钩子函数的类型。event 是传给 PySys_Audit() 或 PySys_AuditTuple() 的 C 字符串形式的事件参数。args 会确保为一个 PyTupleObject。userData 是传给 PySys_AddAuditHook() 的参数。

Added in version 3.8.

在 3.8.1 版本发生变更: Exceptions derived from Exception but not RuntimeError are no longer suppressed.

进程控制

void Py_FatalError(const char *message)

属于 稳定 ABI.

打印一个致命错误消息并杀死进程。不会执行任何清理。此函数应当仅在检测到可能令继续使用 Python 解释器会有危险的情况时被调用；例如对象管理已被破坏的时候。在 Unix 上，会调用标准 C 库函数 abort() 并将由它来尝试生成一个 core 文件。

Py_FatalError() 函数会被替换为一个将自动记录当前函数名称的宏，除非定义了 Py_LIMITED_API 宏。

在 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 的内部最终化将在清理函数之前完成，因此 Python API 不应被 func 调用。

参见

PyUnstable_AtExit() 用于传递 void *data 参数。