`os` — 杂项操作系统接口¶

源代码: Lib/os.py

此模块提供了一种使用与操作系统相关的功能的可移植方式。如果您只想读写文件，请参阅 open()；如果您想操作路径，请参阅 os.path 模块；如果您想读取命令行上所有文件的所有行，请参阅 fileinput 模块。有关创建临时文件和目录，请参阅 tempfile 模块；有关高级文件和目录处理，请参阅 shutil 模块。

关于这些函数的可用性说明

Python 的所有内置操作系统相关模块的设计宗旨是，只要功能相同，就使用相同的接口；例如，函数 os.stat(path) 以相同的格式（碰巧源自 POSIX 接口）返回关于 *path* 的统计信息。
特定操作系统特有的扩展功能也可以通过 os 模块获取，但使用它们当然会损害可移植性。
所有接受路径或文件名的函数都接受字节和字符串对象，如果返回路径或文件名，则返回相同类型的对象。
在 VxWorks 上，不支持 os.popen、os.fork、os.execv 和 os.spawn*p*。
在 WebAssembly 平台、Android 和 iOS 上，os 模块的很大一部分不可用或行为不同。与进程（例如 fork()、execve()）和资源（例如 nice()）相关的 API 不可用。其他 API，如 getuid() 和 getpid()，是模拟或存根。WebAssembly 平台也缺乏对信号（例如 kill()、wait()）的支持。

备注

此模块中的所有函数在遇到无效或不可访问的文件名和路径，或具有正确类型但操作系统不接受的其他参数时，都会引发 OSError（或其子类）。

exception os.error¶: 内置 OSError 异常的别名。

os.name¶: 导入的操作系统相关模块的名称。目前已注册的名称有：'posix'、'nt'、'java'。

参见

sys.platform 具有更精细的粒度。os.uname() 提供系统相关的版本信息。

platform 模块提供对系统身份的详细检查。

文件名、命令行参数和环境变量¶

在 Python 中，文件名、命令行参数和环境变量使用字符串类型表示。在某些系统上，在将这些字符串传递给操作系统之前，需要将它们编码为字节并从字节解码。Python 使用文件系统编码和错误处理程序来执行此转换（参见 sys.getfilesystemencoding()）。

文件系统编码和错误处理程序在 Python 启动时通过 PyConfig_Read() 函数进行配置：参见 filesystem_encoding 和 filesystem_errors 的成员 PyConfig。

版本 3.1 中的变更: 在某些系统上，使用文件系统编码进行转换可能会失败。在这种情况下，Python 使用 surrogateescape 编码错误处理程序，这意味着不可解码的字节在解码时被替换为 Unicode 字符 U+DC*xx*，然后在编码时再次转换回原始字节。

文件系统编码必须保证成功解码所有低于 128 的字节。如果文件系统编码未能提供此保证，API 函数可能会引发 UnicodeError。

另请参阅区域设置编码。

Python UTF-8 模式¶

版本 3.7 新增: 有关更多详细信息，请参阅 PEP 540。

Python UTF-8 模式忽略区域设置编码并强制使用 UTF-8 编码

使用 UTF-8 作为文件系统编码。
sys.getfilesystemencoding() 返回 'utf-8'。
locale.getpreferredencoding() 返回 'utf-8'（do_setlocale 参数无效）。
sys.stdin、sys.stdout 和 sys.stderr 都使用 UTF-8 作为其文本编码，其中 surrogateescape 错误处理程序对于 sys.stdin 和 sys.stdout 启用（sys.stderr 继续使用 backslashreplace，就像在默认的区域设置感知模式中一样）
在 Unix 上，os.device_encoding() 返回 'utf-8' 而不是设备编码。

请注意，UTF-8 模式下的标准流设置可以通过 PYTHONIOENCODING 覆盖（就像在默认的区域设置感知模式中一样）。

由于这些底层 API 的更改，其他高级 API 也表现出不同的默认行为

命令行参数、环境变量和文件名使用 UTF-8 编码解码为文本。
os.fsdecode() 和 os.fsencode() 使用 UTF-8 编码。
open()、io.open() 和 codecs.open() 默认使用 UTF-8 编码。但是，它们仍然默认使用严格错误处理程序，因此尝试以文本模式打开二进制文件很可能会引发异常，而不是产生无意义的数据。

如果 Python 启动时 LC_CTYPE 区域设置为 C 或 POSIX，则启用 Python UTF-8 模式（参见 PyConfig_Read() 函数）。

可以使用 -X utf8 命令行选项和 PYTHONUTF8 环境变量启用或禁用它。

如果完全没有设置 PYTHONUTF8 环境变量，则解释器默认为使用当前区域设置，*除非* 当前区域设置被识别为旧版基于 ASCII 的区域设置（如 PYTHONCOERCECLOCALE 所述），并且区域设置强制转换被禁用或失败。在这些旧版区域设置中，解释器将默认启用 UTF-8 模式，除非明确指示不这样做。

Python UTF-8 模式只能在 Python 启动时启用。其值可以从 sys.flags.utf8_mode 读取。

另请参阅 Windows 上的 UTF-8 模式和文件系统编码和错误处理程序。

参见

PEP 686: Python 3.15 将默认启用 Python UTF-8 模式。

进程参数¶

这些函数和数据项提供有关当前进程和用户的信息并对其进行操作。

os.ctermid()¶: 返回与进程的控制终端对应的文件名。

可用性: Unix，不包括 WASI。

os.environ¶

一个映射对象，其键和值是表示进程环境的字符串。例如，environ['HOME'] 是您的主目录的路径名（在某些平台上），相当于 C 中的 getenv("HOME")。

此映射在 os 模块首次导入时（通常在 Python 启动期间作为处理 site.py 的一部分）被捕获。此后对环境所做的更改不会反映在 os.environ 中，除非是通过直接修改 os.environ 所做的更改。

此映射可用于修改环境以及查询环境。修改映射时会自动调用 putenv()。

在 Unix 上，键和值使用 sys.getfilesystemencoding() 和 'surrogateescape' 错误处理程序。如果您想使用不同的编码，请使用 environb。

在 Windows 上，键会转换为大写。这在获取、设置或删除项目时也适用。例如，environ['monty'] = 'python' 将键 'MONTY' 映射到值 'python'。

备注

直接调用 putenv() 不会更改 os.environ，因此最好修改 os.environ。

备注

在某些平台（包括 FreeBSD 和 macOS）上，设置 environ 可能会导致内存泄漏。请参阅 putenv() 的系统文档。

您可以删除此映射中的项目以取消设置环境变量。当项目从 os.environ 中删除时，以及调用 pop() 或 clear() 方法之一时，会自动调用 unsetenv()。

参见

os.reload_environ() 函数。

版本 3.9 中的变更: 更新以支持 PEP 584 的合并 (|) 和更新 (|=) 运算符。

os.environb¶

environ 的字节版本：一个映射对象，其键和值都是表示进程环境的 bytes 对象。environ 和 environb 是同步的（修改 environb 会更新 environ，反之亦然）。

environb 仅在 supports_bytes_environ 为 True 时可用。

在 3.2 版本加入。

版本 3.9 中的变更: 更新以支持 PEP 584 的合并 (|) 和更新 (|=) 运算符。

os.reload_environ()¶: os.environ 和 os.environb 映射是 Python 启动时环境变量的缓存。因此，如果在 Python 外部或通过 os.putenv() 或 os.unsetenv() 对当前进程环境进行更改，则不会反映这些更改。使用 os.reload_environ() 更新 os.environ 和 os.environb 以反映当前进程环境中的任何此类更改。

警告

此函数不是线程安全的。在另一个线程中修改环境时调用它会导致未定义行为。在重新加载时从 os.environ 或 os.environb 读取，或调用 os.getenv()，可能会返回空结果。

在 3.14 版本加入。

os.chdir(path)
os.fchdir(fd)
os.getcwd(): 这些函数在文件和目录中描述。

os.fsencode(filename)¶

使用文件系统编码和错误处理程序编码路径类 *filename*；返回未更改的 bytes。

fsdecode() 是反向函数。

在 3.2 版本加入。

版本 3.6 中的变更: 添加了支持，以接受实现 os.PathLike 接口的对象。

os.fsdecode(filename)¶

使用文件系统编码和错误处理程序解码路径类 *filename*；返回未更改的 str。

fsencode() 是反向函数。

在 3.2 版本加入。

版本 3.6 中的变更: 添加了支持，以接受实现 os.PathLike 接口的对象。

os.fspath(path)¶

返回路径的文件系统表示。

如果传入的是 str 或 bytes，则原样返回。否则，将调用 __fspath__()，并返回其值，只要它是一个 str 或 bytes 对象。在所有其他情况下，会引发 TypeError。

在 3.6 版本加入。

class os.PathLike¶

表示文件系统路径的对象的抽象基类，例如 pathlib.PurePath。

在 3.6 版本加入。

abstractmethod __fspath__()¶

返回对象的 filesystem 路径表示。

该方法应只返回 str 或 bytes 对象，首选 str。

os.getenv(key, default=None)¶

如果环境变量 *key* 存在，则以字符串形式返回其值，否则返回 *default*。*key* 是一个字符串。请注意，由于 getenv() 使用 os.environ，因此 getenv() 的映射在导入时也被捕获，函数可能不会反映未来的环境变化。

在 Unix 上，键和值使用 sys.getfilesystemencoding() 和 'surrogateescape' 错误处理程序进行解码。如果您想使用不同的编码，请使用 os.getenvb()。

可用性: Unix, Windows。

os.getenvb(key, default=None)¶

如果环境变量 *key* 存在，则以字节形式返回其值，否则返回 *default*。*key* 必须是字节。请注意，由于 getenvb() 使用 os.environb，因此 getenvb() 的映射在导入时也被捕获，函数可能不会反映未来的环境变化。

getenvb() 仅在 supports_bytes_environ 为 True 时可用。

可用性: Unix。

在 3.2 版本加入。

os.get_exec_path(env=None)¶: 返回在启动进程时，类似于 shell，将搜索指定可执行文件的目录列表。如果指定了 *env*，它应该是一个环境变量字典，用于查找 PATH。默认情况下，当 *env* 为 None 时，使用 environ。

在 3.2 版本加入。

os.getegid()¶: 返回当前进程的有效组 ID。这对应于当前进程中正在执行的文件的“set id”位。

可用性: Unix，不包括 WASI。

os.geteuid()¶: 返回当前进程的有效用户 ID。

可用性: Unix，不包括 WASI。

os.getgid()¶: 返回当前进程的真实组 ID。

可用性: Unix。

此函数在 WASI 上是一个存根，有关更多信息，请参见 WebAssembly 平台。

os.getgrouplist(user, group, /)¶: 返回用户所属的组 ID 列表。如果 *group* 不在列表中，则会包含它；通常，*group* 被指定为 *user* 的密码记录中的组 ID 字段，因为否则该组 ID 可能会被省略。

可用性: Unix，不包括 WASI。

在 3.3 版本加入。

os.getgroups()¶: 返回与当前进程关联的补充组 ID 列表。

可用性: Unix，不包括 WASI。

备注

在 macOS 上，getgroups() 的行为与其他 Unix 平台有所不同。如果 Python 解释器使用 10.5 或更早的部署目标构建，getgroups() 返回与当前用户进程关联的有效组 ID 列表；此列表受系统定义条目数的限制，通常为 16，如果具有足够权限，可以通过调用 setgroups() 进行修改。如果使用大于 10.5 的部署目标构建，getgroups() 返回与进程有效用户 ID 关联的用户的当前组访问列表；组访问列表可能会在进程的生命周期内发生变化，它不受调用 setgroups() 的影响，并且其长度不受 16 的限制。部署目标值 MACOSX_DEPLOYMENT_TARGET 可以通过 sysconfig.get_config_var() 获取。

os.getlogin()¶: 返回登录到进程控制终端的用户的名称。在大多数情况下，使用 getpass.getuser() 更为有用，因为后者会检查环境变量 LOGNAME 或 USERNAME 以查找用户是谁，并回退到 pwd.getpwuid(os.getuid())[0] 以获取当前真实用户 ID 的登录名。

可用性: Unix, Windows, 但不包括 WASI。

os.getpgid(pid)¶: 返回进程 ID 为 *pid* 的进程的进程组 ID。如果 *pid* 为 0，则返回当前进程的进程组 ID。

可用性: Unix，不包括 WASI。

os.getpgrp()¶: 返回当前进程组的 ID。

可用性: Unix，不包括 WASI。

os.getpid()¶

返回当前进程 ID。

此函数在 WASI 上是一个存根，有关更多信息，请参见 WebAssembly 平台。

os.getppid()¶: 返回父进程的 ID。当父进程退出时，在 Unix 上返回的 ID 是 init 进程 (1) 的 ID，在 Windows 上它仍然是相同的 ID，可能已经被另一个进程重用。

可用性: Unix, Windows, 但不包括 WASI。

版本 3.2 中的变更: 添加了对 Windows 的支持。

os.getpriority(which, who)¶: 获取程序调度优先级。*which* 的值为 PRIO_PROCESS、PRIO_PGRP 或 PRIO_USER 之一，*who* 相对于 *which* 进行解释（PRIO_PROCESS 为进程标识符，PRIO_PGRP 为进程组标识符，PRIO_USER 为用户 ID）。*who* 为零表示（分别）调用进程、调用进程的进程组或调用进程的真实用户 ID。

可用性: Unix，不包括 WASI。

在 3.3 版本加入。

os.PRIO_PROCESS¶
os.PRIO_PGRP¶
os.PRIO_USER¶: 函数 getpriority() 和 setpriority() 的参数。

可用性: Unix，不包括 WASI。

在 3.3 版本加入。

os.PRIO_DARWIN_THREAD¶
os.PRIO_DARWIN_PROCESS¶
os.PRIO_DARWIN_BG¶
os.PRIO_DARWIN_NONUI¶: 函数 getpriority() 和 setpriority() 的参数。

可用性: macOS

3.12 新版功能.

os.getresuid()¶: 返回一个元组 (ruid, euid, suid)，表示当前进程的真实用户 ID、有效用户 ID 和保存的用户 ID。

可用性: Unix，不包括 WASI。

在 3.2 版本加入。

os.getresgid()¶: 返回一个元组 (rgid, egid, sgid)，表示当前进程的真实组 ID、有效组 ID 和保存的组 ID。

可用性: Unix，不包括 WASI。

在 3.2 版本加入。

os.getuid()¶: 返回当前进程的真实用户 ID。

可用性: Unix。

此函数在 WASI 上是一个存根，有关更多信息，请参见 WebAssembly 平台。

os.initgroups(username, gid, /)¶: 调用系统 initgroups() 以初始化组访问列表，其中包含指定用户所属的所有组，以及指定的组 ID。

可用性: Unix，不包括 WASI，不包括 Android。

在 3.2 版本加入。

os.putenv(key, value, /)¶

将环境变量 *key* 设置为字符串 *value*。对环境的此类更改会影响使用 os.system()、popen() 或 fork() 和 execv() 启动的子进程。

对 os.environ 中项目的赋值会自动转换为对 putenv() 的相应调用；但是，对 putenv() 的调用不会更新 os.environ，因此实际上最好对 os.environ 的项目进行赋值。这也适用于 getenv() 和 getenvb()，它们在实现中分别使用 os.environ 和 os.environb。

另请参阅 os.reload_environ() 函数。

备注

在某些平台（包括 FreeBSD 和 macOS）上，设置 environ 可能会导致内存泄漏。请参阅 putenv() 的系统文档。

使用参数 key、value 触发审计事件 os.putenv。

版本 3.9 中的变更: 该函数现在始终可用。

os.setegid(egid, /)¶: 设置当前进程的有效组 ID。

可用性: Unix，不包括 WASI，不包括 Android。

os.seteuid(euid, /)¶: 设置当前进程的有效用户 ID。

可用性: Unix，不包括 WASI，不包括 Android。

os.setgid(gid, /)¶: 设置当前进程的组 ID。

可用性: Unix，不包括 WASI，不包括 Android。

os.setgroups(groups, /)¶: 将与当前进程关联的补充组 ID 列表设置为 *groups*。*groups* 必须是一个序列，每个元素必须是一个标识组的整数。此操作通常仅适用于超级用户。

可用性: Unix，不包括 WASI。

备注

在 macOS 上，*groups* 的长度不得超过系统定义的有效组 ID 最大数量，通常为 16。有关 getgroups() 可能不返回通过调用 setgroups() 设置的相同组列表的情况，请参阅其文档。

os.setns(fd, nstype=0)¶

将当前线程重新关联到 Linux 命名空间。有关更多详细信息，请参阅 setns(2) 和 namespaces(7) 手册页。

如果 *fd* 指的是 /proc/pid/ns/ 链接，setns() 会将调用线程重新关联到与该链接关联的命名空间，*nstype* 可以设置为 CLONE_NEW* 常量之一以对操作施加约束（0 表示无约束）。

从 Linux 5.8 开始，*fd* 可以引用从 pidfd_open() 获取的 PID 文件描述符。在这种情况下，setns() 将调用线程重新关联到 *fd* 所引用的线程的一个或多个相同命名空间中。这受 *nstype* 施加的任何约束，*nstype* 是一个位掩码，结合了一个或多个 CLONE_NEW* 常量，例如 setns(fd, os.CLONE_NEWUTS | os.CLONE_NEWPID)。调用者在未指定命名空间中的成员身份保持不变。

*fd* 可以是任何具有 fileno() 方法的对象，或原始文件描述符。

此示例将线程重新关联到 init 进程的网络命名空间

fd = os.open("/proc/1/ns/net", os.O_RDONLY)
os.setns(fd, os.CLONE_NEWNET)
os.close(fd)

可用性: Linux >= 3.0，glibc >= 2.14。

3.12 新版功能.

参见

unshare() 函数。

os.setpgrp()¶: 调用系统调用 setpgrp() 或 setpgrp(0, 0)，具体取决于哪个版本已实现（如果有）。有关语义，请参阅 Unix 手册。

可用性: Unix，不包括 WASI。

os.setpgid(pid, pgrp, /)¶: 调用系统调用 setpgid() 将进程 ID 为 *pid* 的进程的进程组 ID 设置为进程组 ID 为 *pgrp* 的进程组。有关语义，请参阅 Unix 手册。

可用性: Unix，不包括 WASI。

os.setpriority(which, who, priority)¶: 设置程序调度优先级。*which* 的值是 PRIO_PROCESS、PRIO_PGRP 或 PRIO_USER 之一，*who* 的解释相对于 *which*（PRIO_PROCESS 的进程标识符，PRIO_PGRP 的进程组标识符，以及 PRIO_USER 的用户 ID）。*who* 的零值表示（分别）调用进程、调用进程的进程组或调用进程的真实用户 ID。*priority* 是一个在 -20 到 19 范围内的值。默认优先级为 0；较低的优先级会导致更有利的调度。

可用性: Unix，不包括 WASI。

在 3.3 版本加入。

os.setregid(rgid, egid, /)¶: 设置当前进程的真实和有效组 ID。

可用性: Unix，不包括 WASI，不包括 Android。

os.setresgid(rgid, egid, sgid, /)¶: 设置当前进程的真实、有效和保存的组 ID。

可用性: Unix，不包括 WASI，不包括 Android。

在 3.2 版本加入。

os.setresuid(ruid, euid, suid, /)¶: 设置当前进程的真实、有效和保存的用户 ID。

可用性: Unix，不包括 WASI，不包括 Android。

在 3.2 版本加入。

os.setreuid(ruid, euid, /)¶: 设置当前进程的真实和有效用户 ID。

可用性: Unix，不包括 WASI，不包括 Android。

os.getsid(pid, /)¶: 调用系统调用 getsid()。有关其语义，请参阅 Unix 手册。

可用性: Unix，不包括 WASI。

os.setsid()¶: 调用系统调用 setsid()。有关其语义，请参阅 Unix 手册。

可用性: Unix，不包括 WASI。

os.setuid(uid, /)¶: 设置当前进程的用户 ID。

可用性: Unix，不包括 WASI，不包括 Android。

os.strerror(code, /)¶: 返回与 *code* 中错误代码对应的错误消息。在某些平台中，如果 strerror() 在给定未知错误号时返回 NULL，则会引发 ValueError。

os.supports_bytes_environ¶: 如果环境的本机操作系统类型是字节（例如，Windows 上为 False），则为 True。

在 3.2 版本加入。

os.umask(mask, /)¶

设置当前数字 umask 并返回之前的 umask。

此函数在 WASI 上是一个存根，有关更多信息，请参见 WebAssembly 平台。

os.uname()¶

返回标识当前操作系统的信息。返回值是一个具有五个属性的对象

sysname - 操作系统名称
nodename - 网络上机器的名称（实现定义）
release - 操作系统版本
version - 操作系统版本
machine - 硬件标识符

为了向后兼容，此对象也是可迭代的，其行为类似于一个包含 sysname、nodename、release、version 和 machine 的五元组。

某些系统将 nodename 截断为 8 个字符或其前导部分；获取主机名更好的方法是 socket.gethostname() 甚至 socket.gethostbyaddr(socket.gethostname())。

在 macOS、iOS 和 Android 上，这会返回 *内核* 名称和版本（即，macOS 和 iOS 上为 'Darwin'；Android 上为 'Linux'）。platform.uname() 可用于在 iOS 和 Android 上获取面向用户的操作系统名称和版本。

可用性: Unix。

3.3 版本中的变化: 返回类型从元组变为具有命名属性的类元组对象。

os.unsetenv(key, /)¶

取消设置（删除）名为 *key* 的环境变量。对环境的此类更改会影响使用 os.system()、popen() 或 fork() 和 execv() 启动的子进程。

删除 os.environ 中的项会自动转换为对 unsetenv() 的相应调用；但是，对 unsetenv() 的调用不会更新 os.environ，因此实际上最好删除 os.environ 的项。

另请参阅 os.reload_environ() 函数。

使用参数 key 引发审计事件 os.unsetenv。

3.9 版本中的变化: 该函数现在始终可用，并且在 Windows 上也可用。

os.unshare(flags)¶: 解除进程执行上下文的部分关联，并将它们移动到新创建的命名空间中。有关更多详细信息，请参阅 unshare(2) 手册页。*flags* 参数是一个位掩码，结合了零个或多个 CLONE_* 常量，它指定了执行上下文的哪些部分应该与其现有关联解除关联并移动到新的命名空间。如果 *flags* 参数为 0，则不会对调用进程的执行上下文进行任何更改。

可用性：Linux >= 2.6.16。

3.12 新版功能.

参见

setns() 函数。

unshare() 函数的标志，如果实现支持它们。有关它们的精确效果和可用性，请参阅 Linux 手册中的 unshare(2)。

os.CLONE_FILES¶
os.CLONE_FS¶
os.CLONE_NEWCGROUP¶
os.CLONE_NEWIPC¶
os.CLONE_NEWNET¶
os.CLONE_NEWNS¶
os.CLONE_NEWPID¶
os.CLONE_NEWTIME¶
os.CLONE_NEWUSER¶
os.CLONE_NEWUTS¶
os.CLONE_SIGHAND¶
os.CLONE_SYSVSEM¶
os.CLONE_THREAD¶
os.CLONE_VM¶

文件对象创建¶

这些函数创建新的文件对象。（另请参阅 open() 以打开文件描述符。）

os.fdopen(fd, *args, **kwargs)¶: 返回连接到文件描述符 *fd* 的打开文件对象。这是 open() 内置函数的别名，并接受相同的参数。唯一的区别是 fdopen() 的第一个参数必须始终是整数。

文件描述符操作¶

这些函数对使用文件描述符引用的 I/O 流进行操作。

文件描述符是对应于当前进程已打开的文件的小整数。例如，标准输入通常是文件描述符 0，标准输出是 1，标准错误是 2。进程打开的更多文件将依次分配 3、4、5 等。名称“文件描述符”有些误导；在 Unix 平台上，套接字和管道也由文件描述符引用。

当需要时，可以使用 fileno() 方法获取与文件对象关联的文件描述符。请注意，直接使用文件描述符将绕过文件对象方法，忽略诸如数据的内部缓冲等方面。

os.close(fd)¶: 关闭文件描述符 *fd*。

备注

此函数旨在用于低级 I/O，并且必须应用于由 os.open() 或 pipe() 返回的文件描述符。要关闭由内置函数 open() 或由 popen() 或 fdopen() 返回的“文件对象”，请使用其 close() 方法。

os.closerange(fd_low, fd_high, /)¶

关闭从 *fd_low*（包含）到 *fd_high*（不包含）的所有文件描述符，忽略错误。等同于（但比以下更快）

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass

os.copy_file_range(src, dst, count, offset_src=None, offset_dst=None)¶

从文件描述符 *src* 复制 *count* 字节，从 *offset_src* 偏移量开始，到文件描述符 *dst*，从 *offset_dst* 偏移量开始。如果 *offset_src* 为 None，则从当前位置读取 *src*；*offset_dst* 同理。

在 Linux 内核 5.3 之前的版本中，*src* 和 *dst* 指向的文件必须位于同一文件系统中，否则会引发 OSError，其中 errno 设置为 errno.EXDEV。

此复制在不增加数据从内核传输到用户空间再返回内核的额外开销的情况下完成。此外，某些文件系统可以实现额外的优化，例如使用 reflinks（即，共享指向相同写时复制磁盘块指针的两个或多个索引节点；支持的文件系统包括 btrfs 和 XFS）和服务器端复制（在 NFS 的情况下）。

该函数在两个文件描述符之间复制字节。文本选项（如编码和行尾）将被忽略。

返回值是复制的字节数。这可能小于请求的数量。

备注

在 Linux 上，os.copy_file_range() 不应用于从 procfs 和 sysfs 等特殊文件系统复制伪文件的范围。由于已知的 Linux 内核问题，它将始终复制零字节并返回 0，就像文件为空一样。

可用性：Linux >= 4.5，glibc >= 2.27。

在 3.8 版本加入。

os.device_encoding(fd)¶

如果与 *fd* 关联的设备连接到终端，则返回描述该设备编码的字符串；否则返回 None。

在 Unix 上，如果启用了 Python UTF-8 模式，则返回 'UTF-8' 而不是设备编码。

3.10 版本中的变化: 在 Unix 上，该函数现在实现了 Python UTF-8 模式。

os.dup(fd, /)¶

返回文件描述符 *fd* 的副本。新的文件描述符是不可继承的。

在 Windows 上，当复制标准流（0：stdin，1：stdout，2：stderr）时，新的文件描述符是可继承的。

可用性：非 WASI。

3.4 版本中的变化: 新的文件描述符现在是不可继承的。

os.dup2(fd, fd2, inheritable=True)¶: 将文件描述符 *fd* 复制到 *fd2*，如果需要则首先关闭 *fd2*。返回 *fd2*。新的文件描述符默认为可继承的，如果 *inheritable* 为 False 则为不可继承的。

可用性：非 WASI。

3.4 版本中的变化: 添加了可选的 *inheritable* 参数。

3.7 版本中的变化: 成功时返回 *fd2*。以前，总是返回 None。

os.fchmod(fd, mode)¶

将由 *fd* 给定的文件的模式更改为数字 *mode*。有关 *mode* 的可能值，请参阅 chmod() 的文档。从 Python 3.3 开始，这等同于 os.chmod(fd, mode)。

使用参数 path、mode、dir_fd 引发审计事件 os.chmod。

可用性: Unix, Windows。

该功能在 WASI 上受到限制，详情请参阅 WebAssembly 平台。

3.13 版本中的变化: 添加了对 Windows 的支持。

os.fchown(fd, uid, gid)¶

将由 *fd* 给定的文件的所有者和组 ID 更改为数字 *uid* 和 *gid*。要使其中一个 ID 保持不变，请将其设置为 -1。请参阅 chown()。从 Python 3.3 开始，这等同于 os.chown(fd, uid, gid)。

使用参数 path、uid、gid、dir_fd 引发审计事件 os.chown。

可用性: Unix。

该功能在 WASI 上受到限制，详情请参阅 WebAssembly 平台。

os.fdatasync(fd)¶: 强制将文件描述符 *fd* 的文件写入磁盘。不强制更新元数据。

可用性: Unix。

备注

此函数在 MacOS 上不可用。

os.fpathconf(fd, name, /)¶

返回与打开文件相关的系统配置信息。*name* 指定要检索的配置值；它可能是一个字符串，是定义的系统值的名称；这些名称在许多标准中指定（POSIX.1、Unix 95、Unix 98 等）。某些平台还定义了其他名称。主机操作系统已知的名称在 pathconf_names 字典中给出。对于未包含在该映射中的配置变量，也接受将整数作为 *name* 传递。

如果 *name* 是字符串且未知，则引发 ValueError。如果主机系统不支持 *name* 的特定值，即使它包含在 pathconf_names 中，也会引发 OSError，错误号为 errno.EINVAL。

从 Python 3.3 开始，这等同于 os.pathconf(fd, name)。

可用性: Unix。

os.fstat(fd)¶

获取文件描述符 *fd* 的状态。返回 stat_result 对象。

从 Python 3.3 开始，这等同于 os.stat(fd)。

参见

stat() 函数。

os.fstatvfs(fd, /)¶: 返回有关包含与文件描述符 *fd* 关联的文件的文件系统的信息，类似于 statvfs()。从 Python 3.3 开始，这等同于 os.statvfs(fd)。

可用性: Unix。

os.fsync(fd)¶

强制将文件描述符 *fd* 的文件写入磁盘。在 Unix 上，这会调用本机 fsync() 函数；在 Windows 上，是 MS _commit() 函数。

如果您从一个缓冲的 Python 文件对象 *f* 开始，首先执行 f.flush()，然后执行 os.fsync(f.fileno())，以确保与 *f* 关联的所有内部缓冲区都写入磁盘。

可用性: Unix, Windows。

os.ftruncate(fd, length, /)¶

截断与文件描述符 *fd* 对应的文件，使其大小最多为 *length* 字节。从 Python 3.3 开始，这等同于 os.truncate(fd, length)。

使用参数 fd、length 引发审计事件 os.truncate。

可用性: Unix, Windows。

3.5 版本中的变化: 增加了对 Windows 的支持

os.get_blocking(fd, /)¶

获取文件描述符的阻塞模式：如果设置了 O_NONBLOCK 标志则为 False，如果清除了该标志则为 True。

另请参阅 set_blocking() 和 socket.socket.setblocking()。

可用性: Unix, Windows。

该功能在 WASI 上受到限制，详情请参阅 WebAssembly 平台。

在 Windows 上，此函数仅限于管道。

在 3.5 版本加入。

3.12 版本中的变化: 增加了对 Windows 上管道的支持。

os.grantpt(fd, /)¶

授予访问与文件描述符 *fd* 引用主伪终端设备相关联的从属伪终端设备的权限。文件描述符 *fd* 在失败时不会关闭。

调用 C 标准库函数 grantpt()。

可用性: Unix，不包括 WASI。

在 3.13 版本加入。

os.isatty(fd, /)¶: 如果文件描述符 *fd* 已打开并连接到 tty（或类似）设备，则返回 True，否则返回 False。

os.lockf(fd, cmd, len, /)¶

对打开的文件描述符应用、测试或移除 POSIX 锁。*fd* 是一个打开的文件描述符。*cmd* 指定要使用的命令 - F_LOCK、F_TLOCK、F_ULOCK 或 F_TEST 之一。*len* 指定要锁定的文件部分。

使用参数 fd、cmd、len 引发审计事件 os.lockf。

可用性: Unix。

在 3.3 版本加入。

os.F_LOCK¶
os.F_TLOCK¶
os.F_ULOCK¶
os.F_TEST¶: 指定 lockf() 将执行什么操作的标志。

可用性: Unix。

在 3.3 版本加入。

os.login_tty(fd, /)¶: 为新的登录会话准备文件描述符 fd 所属的 tty。使调用进程成为会话领导者；使 tty 成为调用进程的控制 tty、标准输入、标准输出和标准错误；关闭 fd。

可用性: Unix，不包括 WASI。

在 3.11 版本中新增。

os.lseek(fd, pos, whence, /)¶

将文件描述符 *fd* 的当前位置设置为 *pos*，并由 *whence* 修改，并返回相对于文件开头的以字节为单位的新位置。*whence* 的有效值为

SEEK_SET 或 0 – 将 *pos* 设置为相对于文件开头的位置
SEEK_CUR 或 1 – 将 *pos* 设置为相对于当前文件位置的位置
SEEK_END 或 2 – 将 *pos* 设置为相对于文件末尾的位置
SEEK_HOLE – 将 *pos* 设置为相对于 *pos* 的下一个数据位置
SEEK_DATA – 将 *pos* 设置为相对于 *pos* 的下一个数据空洞

3.3 版本中的变化: 增加了对 SEEK_HOLE 和 SEEK_DATA 的支持。

os.SEEK_SET¶

os.SEEK_CUR¶

os.SEEK_END¶

用于 lseek() 函数和 seek() 方法在文件类对象上调整文件位置指示器的 *whence* 参数。

SEEK_SET: 将文件位置调整到文件开头。
SEEK_CUR: 将文件位置调整到当前文件位置。
SEEK_END: 将文件位置调整到文件末尾。

它们的值分别为 0、1 和 2。

os.SEEK_HOLE¶

os.SEEK_DATA¶

用于 lseek() 函数和 seek() 方法在文件类对象上，用于在稀疏分配文件上查找文件数据和空洞的参数。

SEEK_DATA: 将文件偏移量调整到下一个包含数据的位置，相对于查找位置。
SEEK_HOLE: 将文件偏移量调整到下一个包含空洞的位置，相对于查找位置。空洞定义为一系列零。

备注

这些操作仅对支持它们的文件系统有意义。

可用性：Linux >= 3.1, macOS, Unix

在 3.3 版本加入。

os.open(path, flags, mode=0o777, *, dir_fd=None)¶

打开文件 *path* 并根据 *flags* 设置各种标志，并可能根据 *mode* 设置其模式。在计算 *mode* 时，首先会掩盖当前 umask 值。返回新打开文件的文件描述符。新的文件描述符是不可继承的。

有关标志和模式值的描述，请参阅 C 运行时文档；标志常量（如 O_RDONLY 和 O_WRONLY）在 os 模块中定义。特别是在 Windows 上，需要添加 O_BINARY 才能以二进制模式打开文件。

此函数可以通过 *dir_fd* 参数支持相对于目录描述符的路径。

使用参数 path、mode、flags 引发审计事件 open。

3.4 版本中的变化: 新的文件描述符现在是不可继承的。

备注

此函数旨在用于低级 I/O。对于正常使用，请使用内置函数 open()，它返回一个具有 read() 和 write() 方法（以及更多）的文件对象。要将文件描述符包装在文件对象中，请使用 fdopen()。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

3.5 版本中的变化: 如果系统调用被中断并且信号处理程序没有引发异常，该函数现在会重试系统调用，而不是引发 InterruptedError 异常（请参阅 PEP 475 以了解其原理）。

在 3.6 版本发生变更: 接受 path-like object。

以下常量是 open() 函数的 *flags* 参数的选项。它们可以使用位或运算符 | 组合。其中一些并非在所有平台上都可用。有关它们的可用性和使用的描述，请参阅 Unix 上的 open(2) 手册页或 Windows 上的 MSDN。

os.O_RDONLY¶
os.O_WRONLY¶
os.O_RDWR¶
os.O_APPEND¶
os.O_CREAT¶
os.O_EXCL¶
os.O_TRUNC¶: 以上常量在 Unix 和 Windows 上都可用。

os.O_DSYNC¶
os.O_RSYNC¶
os.O_SYNC¶
os.O_NDELAY¶
os.O_NONBLOCK¶
os.O_NOCTTY¶
os.O_CLOEXEC¶: 以上常量仅在 Unix 上可用。

3.3 版本中的变化: 添加了 O_CLOEXEC 常量。

os.O_BINARY¶
os.O_NOINHERIT¶
os.O_SHORT_LIVED¶
os.O_TEMPORARY¶
os.O_RANDOM¶
os.O_SEQUENTIAL¶
os.O_TEXT¶: 以上常量仅在 Windows 上可用。

os.O_EVTONLY¶
os.O_FSYNC¶
os.O_SYMLINK¶
os.O_NOFOLLOW_ANY¶: 以上常量仅在 macOS 上可用。

3.10 版本中的变化: 添加了 O_EVTONLY、O_FSYNC、O_SYMLINK 和 O_NOFOLLOW_ANY 常量。

os.O_ASYNC¶
os.O_DIRECT¶
os.O_DIRECTORY¶
os.O_NOFOLLOW¶
os.O_NOATIME¶
os.O_PATH¶
os.O_TMPFILE¶
os.O_SHLOCK¶
os.O_EXLOCK¶: 以上常量是扩展，如果 C 库未定义，则不存在。

3.4 版本中的变化: 在支持的系统上添加了 O_PATH。添加了 O_TMPFILE，仅在 Linux 内核 3.11 或更高版本上可用。

os.openpty()¶: 打开一个新的伪终端对。返回 pty 和 tty 的文件描述符对 (master, slave)。新的文件描述符是不可继承的。对于（稍微）更具可移植性的方法，请使用 pty 模块。

可用性: Unix，不包括 WASI。

3.4 版本中的变化: 新的文件描述符现在是不可继承的。

os.pipe()¶: 创建一个管道。返回一对可用于读写的文件描述符 (r, w)。新的文件描述符是不可继承的。

可用性: Unix, Windows。

3.4 版本中的变化: 新的文件描述符现在是不可继承的。

os.pipe2(flags, /)¶: 以原子方式设置 *flags* 创建一个管道。*flags* 可以通过将一个或多个以下值进行或运算来构造：O_NONBLOCK、O_CLOEXEC。返回一对可用于读写的文件描述符 (r, w)。

可用性: Unix，不包括 WASI。

在 3.3 版本加入。

os.posix_fallocate(fd, offset, len, /)¶: 确保为由 *fd* 指定的文件分配足够的磁盘空间，从 *offset* 开始并持续 *len* 字节。

可用性: Unix。

在 3.3 版本加入。

os.posix_fadvise(fd, offset, len, advice, /)¶: 宣布以特定模式访问数据的意图，从而允许内核进行优化。该建议适用于由 *fd* 指定的文件区域，从 *offset* 开始并持续 *len* 字节。*advice* 是 POSIX_FADV_NORMAL、POSIX_FADV_SEQUENTIAL、POSIX_FADV_RANDOM、POSIX_FADV_NOREUSE、POSIX_FADV_WILLNEED 或 POSIX_FADV_DONTNEED 之一。

可用性: Unix。

在 3.3 版本加入。

os.POSIX_FADV_NORMAL¶
os.POSIX_FADV_SEQUENTIAL¶
os.POSIX_FADV_RANDOM¶
os.POSIX_FADV_NOREUSE¶
os.POSIX_FADV_WILLNEED¶
os.POSIX_FADV_DONTNEED¶: 可在 posix_fadvise() 的 *advice* 中使用的标志，指定可能使用的访问模式。

可用性: Unix。

在 3.3 版本加入。

os.pread(fd, n, offset, /)¶

从文件描述符 *fd* 在位置 *offset* 处最多读取 *n* 字节，文件偏移量保持不变。

返回包含读取字节的字节串。如果已到达由 *fd* 引用的文件末尾，则返回空字节对象。

可用性: Unix。

在 3.3 版本加入。

os.posix_openpt(oflag, /)¶

打开并返回主伪终端设备的文件描述符。

调用 C 标准库函数 posix_openpt()。*oflag* 参数用于设置文件状态标志和文件访问模式，具体取决于您系统上 posix_openpt() 的手册页中的规定。

返回的文件描述符是不可继承的。如果系统上提供了值 O_CLOEXEC，则将其添加到 *oflag*。

可用性: Unix，不包括 WASI。

在 3.13 版本加入。

os.preadv(fd, buffers, offset, flags=0, /)¶

从文件描述符 *fd* 在位置 *offset* 读取到可变 bytes-like 对象 *buffers* 中，文件偏移量保持不变。将数据传输到每个缓冲区直到其已满，然后移动到序列中的下一个缓冲区以容纳其余数据。

*flags* 参数包含以下零个或多个标志的按位或

RWF_HIPRI
RWF_NOWAIT

返回实际读取的总字节数，这可能小于所有对象的总容量。

操作系统可能会对可使用的缓冲区数量设置限制（sysconf() 值 'SC_IOV_MAX'）。

结合了 os.readv() 和 os.pread() 的功能。

可用性：Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1。

使用 flags 需要 Linux >= 4.6。

在 3.7 版本加入。

os.RWF_NOWAIT¶

不等待不可立即获得的数据。如果指定此标志，如果系统调用需要从后端存储读取数据或等待锁，它将立即返回。

如果成功读取了一些数据，它将返回读取的字节数。如果没有读取任何字节，它将返回 -1 并将 errno 设置为 errno.EAGAIN。

可用性：Linux >= 4.14。

在 3.7 版本加入。

os.RWF_HIPRI¶

高优先级读/写。允许基于块的文件系统使用设备轮询，这提供了更低的延迟，但可能使用额外的资源。

目前在 Linux 上，此功能仅适用于使用 O_DIRECT 标志打开的文件描述符。

可用性：Linux >= 4.6。

在 3.7 版本加入。

os.ptsname(fd, /)¶

返回与文件描述符 fd 所引用的主伪终端设备关联的从伪终端设备的名称。文件描述符 fd 在失败时不会关闭。

如果可重入的 C 标准库函数 ptsname_r() 可用，则调用它；否则，调用 C 标准库函数 ptsname()，该函数不保证是线程安全的。

可用性: Unix，不包括 WASI。

在 3.13 版本加入。

os.pwrite(fd, str, offset, /)¶

将字节串 str 写入文件描述符 fd 的 offset 位置，文件偏移量保持不变。

返回实际写入的字节数。

可用性: Unix。

在 3.3 版本加入。

os.pwritev(fd, buffers, offset, flags=0, /)¶

将 buffers 的内容写入文件描述符 fd 的偏移量 offset 处，文件偏移量保持不变。buffers 必须是 bytes-like objects 的序列。缓冲区按数组顺序处理。第一个缓冲区的全部内容写入完成后才处理第二个缓冲区，以此类推。

*flags* 参数包含以下零个或多个标志的按位或

RWF_DSYNC
RWF_SYNC
RWF_APPEND

返回实际写入的总字节数。

操作系统可能会对可使用的缓冲区数量设置限制（sysconf() 值 'SC_IOV_MAX'）。

结合了 os.writev() 和 os.pwrite() 的功能。

可用性：Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1。

使用 flags 需要 Linux >= 4.6。

在 3.7 版本加入。

os.RWF_DSYNC¶: 提供等效于 O_DSYNC os.open() 标志的每次写入行为。此标志的效果仅适用于系统调用写入的数据范围。

可用性：Linux >= 4.7。

在 3.7 版本加入。

os.RWF_SYNC¶: 提供等效于 O_SYNC os.open() 标志的每次写入行为。此标志的效果仅适用于系统调用写入的数据范围。

可用性：Linux >= 4.7。

在 3.7 版本加入。

os.RWF_APPEND¶: 提供等效于 O_APPEND os.open() 标志的每次写入行为。此标志仅对 os.pwritev() 有意义，其效果仅适用于系统调用写入的数据范围。offset 参数不影响写入操作；数据总是附加到文件末尾。但是，如果 offset 参数为 -1，则当前文件 offset 会更新。

可用性：Linux >= 4.16。

在 3.10 版本加入。

os.read(fd, n, /)¶

从文件描述符 fd 读取最多 n 个字节。

返回包含读取字节的字节串。如果已到达由 *fd* 引用的文件末尾，则返回空字节对象。

备注

此函数用于低级 I/O，必须应用于 os.open() 或 pipe() 返回的文件描述符。要读取内置函数 open() 或 popen() 或 fdopen() 返回的“文件对象”，或者 sys.stdin，请使用其 read() 或 readline() 方法。

3.5 版中变更: 如果系统调用被中断且信号处理程序未引发异常，则该函数现在会重试系统调用，而不是引发 InterruptedError 异常（有关原因，请参阅 PEP 475）。

os.readinto(fd, buffer, /)¶

从文件描述符 fd 读取到可变的缓冲区对象 buffer 中。

buffer 应该是可变的且为 bytes-like 类型。成功时，返回读取的字节数。读取的字节数可能小于缓冲区的大小。底层系统调用在被信号中断时会重试，除非信号处理程序引发异常。其他错误不会重试，并且会引发错误。

如果 fd 位于文件末尾或提供的 buffer 长度为 0（这可用于检查错误而不读取数据），则返回 0。从不返回负值。

备注

此函数用于低级 I/O，必须应用于 os.open() 或 os.pipe() 返回的文件描述符。要读取内置函数 open() 或 sys.stdin 返回的“文件对象”，请使用其成员函数，例如 io.BufferedIOBase.readinto()、io.BufferedIOBase.read() 或 io.TextIOBase.read()

在 3.14 版本加入。

os.sendfile(out_fd, in_fd, offset, count)¶

os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

从文件描述符 in_fd 的 offset 位置开始，复制 count 字节到文件描述符 out_fd。返回发送的字节数。到达文件末尾时返回 0。

第一个函数符号受所有定义了 sendfile() 的平台支持。

在 Linux 上，如果 offset 给定为 None，则从 in_fd 的当前位置读取字节，并更新 in_fd 的位置。

在 macOS 和 FreeBSD 上可以使用第二种情况，其中 headers 和 trailers 是任意的缓冲区序列，在写入来自 in_fd 的数据之前和之后写入。它返回与第一种情况相同的值。

在 macOS 和 FreeBSD 上，count 的值 0 表示发送直到到达 in_fd 的末尾。

所有平台都支持将套接字作为 out_fd 文件描述符，某些平台也允许其他类型（例如普通文件、管道）。

跨平台应用程序不应使用 headers、trailers 和 flags 参数。

可用性: Unix，不包括 WASI。

备注

有关 sendfile() 的更高级别包装器，请参阅 socket.socket.sendfile()。

在 3.3 版本加入。

3.9 版中变更: 参数 out 和 in 已重命名为 out_fd 和 in_fd。

os.SF_NODISKIO¶
os.SF_MNOWAIT¶
os.SF_SYNC¶: sendfile() 函数的参数，如果实现支持它们的话。

可用性: Unix，不包括 WASI。

在 3.3 版本加入。

os.SF_NOCACHE¶: sendfile() 函数的参数，如果实现支持它。数据不会被缓存在虚拟内存中，并且之后会被释放。

可用性: Unix，不包括 WASI。

在 3.11 版本中新增。

os.set_blocking(fd, blocking, /)¶

设置指定文件描述符的阻塞模式。如果 blocking 为 False，则设置 O_NONBLOCK 标志，否则清除该标志。

另请参阅 get_blocking() 和 socket.socket.setblocking()。

可用性: Unix, Windows。

该功能在 WASI 上受到限制，详情请参阅 WebAssembly 平台。

在 Windows 上，此函数仅限于管道。

在 3.5 版本加入。

3.12 版本中的变化: 增加了对 Windows 上管道的支持。

os.splice(src, dst, count, offset_src=None, offset_dst=None, flags=0)¶

将 count 字节从文件描述符 src（从 offset_src 开始）传输到文件描述符 dst（从 offset_dst 开始）。

可以通过指定 flags 值来修改拼接行为。可以使用以下任何变量，通过位或运算符（| 运算符）组合它们

如果指定了 SPLICE_F_MOVE，则请求内核移动页面而不是复制，但如果内核无法从管道移动页面，仍然可以复制页面。
如果指定了 SPLICE_F_NONBLOCK，则请求内核不阻塞 I/O。这使得拼接管道操作非阻塞，但由于被拼接的文件描述符可能会阻塞，拼接仍然可能阻塞。
如果指定了 SPLICE_F_MORE，它会向内核提示后续拼接中将会有更多数据。

至少一个文件描述符必须引用一个管道。如果 offset_src 为 None，则从当前位置读取 src；对于 offset_dst 也是如此。引用管道的文件描述符的偏移量必须为 None。src 和 dst 所指向的文件必须位于同一文件系统中，否则会引发 OSError，并将 errno 设置为 errno.EXDEV。

此复制是在没有将数据从内核传输到用户空间再返回内核的额外开销的情况下完成的。此外，某些文件系统可以实现额外的优化。复制操作就像两个文件都以二进制模式打开一样。

成功完成后，返回拼接进出管道的字节数。返回值为 0 表示输入结束。如果 src 引用一个管道，则这意味着没有数据可传输，并且由于没有写入器连接到管道的写入端，因此阻塞没有意义。

参见

splice(2) 手册页。

可用性：Linux >= 2.6.17，且 glibc >= 2.5

在 3.10 版本加入。

os.SPLICE_F_MOVE¶
os.SPLICE_F_NONBLOCK¶
os.SPLICE_F_MORE¶: 在 3.10 版本加入。

os.readv(fd, buffers, /)¶

从文件描述符 fd 读取数据到多个可变的 bytes-like objects buffers 中。将数据传输到每个缓冲区直到其满，然后继续传输到序列中的下一个缓冲区以容纳剩余数据。

返回实际读取的总字节数，这可能小于所有对象的总容量。

操作系统可能会对可使用的缓冲区数量设置限制（sysconf() 值 'SC_IOV_MAX'）。

可用性: Unix。

在 3.3 版本加入。

os.tcgetpgrp(fd, /)¶: 返回与 fd（由 os.open() 返回的已打开文件描述符）给定的终端关联的进程组。

可用性: Unix，不包括 WASI。

os.tcsetpgrp(fd, pg, /)¶: 将与 fd（由 os.open() 返回的已打开文件描述符）给定的终端关联的进程组设置为 pg。

可用性: Unix，不包括 WASI。

os.ttyname(fd, /)¶: 返回一个字符串，该字符串指定与文件描述符 fd 关联的终端设备。如果 fd 未与终端设备关联，则会引发异常。

可用性: Unix。

os.unlockpt(fd, /)¶

解锁与文件描述符 fd 所引用的主伪终端设备关联的从伪终端设备。文件描述符 fd 在失败时不会关闭。

调用 C 标准库函数 unlockpt()。

可用性: Unix，不包括 WASI。

在 3.13 版本加入。

os.write(fd, str, /)¶

将字节串 str 写入文件描述符 fd。

返回实际写入的字节数。

备注

此函数用于低级 I/O，必须应用于 os.open() 或 pipe() 返回的文件描述符。要写入内置函数 open() 或 popen() 或 fdopen() 返回的“文件对象”，或者 sys.stdout 或 sys.stderr，请使用其 write() 方法。

3.5 版中变更: 如果系统调用被中断且信号处理程序未引发异常，则该函数现在会重试系统调用，而不是引发 InterruptedError 异常（有关原因，请参阅 PEP 475）。

os.writev(fd, buffers, /)¶

将 buffers 的内容写入文件描述符 fd。buffers 必须是 bytes-like objects 的序列。缓冲区按数组顺序处理。第一个缓冲区的全部内容写入完成后才处理第二个缓冲区，以此类推。

返回实际写入的总字节数。

操作系统可能会对可使用的缓冲区数量设置限制（sysconf() 值 'SC_IOV_MAX'）。

可用性: Unix。

在 3.3 版本加入。

查询终端大小

在 3.3 版本加入。

os.get_terminal_size(fd=STDOUT_FILENO, /)¶

以 (columns, lines) 的形式返回终端窗口的大小，这是一个 terminal_size 类型的元组。

可选参数 fd（默认为 STDOUT_FILENO，即标准输出）指定应查询哪个文件描述符。

如果文件描述符未连接到终端，则会引发 OSError。

shutil.get_terminal_size() 是通常应该使用的高级函数，os.get_terminal_size 是低级实现。

可用性: Unix, Windows。

class os.terminal_size¶

一个元组的子类，包含终端窗口大小的 (columns, lines)。

columns¶: 终端窗口的字符宽度。

lines¶: 终端窗口的字符高度。

文件描述符的继承

在 3.4 版本加入。

文件描述符有一个“可继承”标志，指示文件描述符是否可以被子进程继承。从 Python 3.4 开始，Python 创建的文件描述符默认是不可继承的。

在 UNIX 上，不可继承的文件描述符在执行新程序时会在子进程中关闭，其他文件描述符则会被继承。

在 Windows 上，不可继承的句柄和文件描述符会在子进程中关闭，除了标准流（文件描述符 0、1 和 2：stdin、stdout 和 stderr），它们总是被继承。使用 spawn* 函数时，所有可继承的句柄和所有可继承的文件描述符都会被继承。使用 subprocess 模块时，除了标准流之外的所有文件描述符都会被关闭，只有当 close_fds 参数为 False 时，可继承的句柄才会被继承。

在 WebAssembly 平台上，文件描述符无法修改。

os.get_inheritable(fd, /)¶: 获取指定文件描述符的“可继承”标志（布尔值）。

os.set_inheritable(fd, inheritable, /)¶: 设置指定文件描述符的“可继承”标志。

os.get_handle_inheritable(handle, /)¶: 获取指定句柄的“可继承”标志（布尔值）。

可用性: Windows。

os.set_handle_inheritable(handle, inheritable, /)¶: 设置指定句柄的“可继承”标志。

可用性: Windows。

文件和目录

在某些 Unix 平台上，许多这些函数支持以下一个或多个功能：

指定文件描述符：通常，提供给 os 模块中函数的 path 参数必须是指定文件路径的字符串。但是，某些函数现在可以选择接受一个打开的文件描述符作为其 path 参数。然后，该函数将在描述符所引用的文件上操作。对于 POSIX 系统，Python 将调用以 f 为前缀的函数变体（例如，调用 fchdir 而不是 chdir）。

您可以使用 os.supports_fd 检查在您的平台上某个特定函数是否可以将 path 指定为文件描述符。如果此功能不可用，使用它将引发 NotImplementedError。

如果函数还支持 dir_fd 或 follow_symlinks 参数，则在提供文件描述符作为 path 时指定其中一个参数是错误的。

相对于目录描述符的路径：如果 dir_fd 不为 None，它应该是一个引用目录的文件描述符，并且要操作的路径应该是相对路径；路径将相对于该目录。如果路径是绝对路径，则忽略 dir_fd。对于 POSIX 系统，Python 将调用带有 at 后缀并可能带有 f 前缀的函数变体（例如，调用 faccessat 而不是 access）。

您可以使用 os.supports_dir_fd 检查在您的平台上某个特定函数是否支持 dir_fd。如果它不可用，使用它将引发 NotImplementedError。

不跟随符号链接：如果 follow_symlinks 为 False，并且要操作的路径的最后一个元素是符号链接，则该函数将操作符号链接本身，而不是链接所指向的文件。对于 POSIX 系统，Python 将调用函数的 l... 变体。

您可以使用 os.supports_follow_symlinks 检查在您的平台上某个特定函数是否支持 follow_symlinks。如果它不可用，使用它将引发 NotImplementedError。

os.access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)¶

使用实际的用户 ID/组 ID 来测试对 path 的访问权限。请注意，大多数操作将使用有效的用户 ID/组 ID，因此此例程可用于 suid/sgid 环境，以测试调用用户是否对 path 具有指定的访问权限。mode 应为 F_OK 以测试 path 的存在，或者它可以是 R_OK、W_OK 和 X_OK 中的一个或多个的包含或，以测试权限。如果允许访问，则返回 True，否则返回 False。有关更多信息，请参阅 Unix 手册页 access(2)。

此函数可以支持指定相对于目录描述符的路径和不跟随符号链接。

如果 effective_ids 为 True，access() 将使用有效的 uid/gid 而不是真实的 uid/gid 执行访问检查。effective_ids 可能在您的平台上不受支持；您可以使用 os.supports_effective_ids 检查它是否可用。如果不可用，使用它将引发 NotImplementedError。

备注

使用 access() 在实际使用 open() 打开文件之前检查用户是否被授权打开文件会造成安全漏洞，因为用户可能会利用检查和打开文件之间的短暂时间间隔来操纵文件。最好使用 EAFP 技术。例如

if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"

更好的写法是

try:
    fp = open("myfile")
except PermissionError:
    return "some default data"
else:
    with fp:
        return fp.read()

备注

即使 access() 指示 I/O 操作会成功，它们仍然可能失败，特别是对于网络文件系统上的操作，这些文件系统可能具有超出通常 POSIX 权限位模型的权限语义。

3.3 版中变更: 添加了 dir_fd、effective_ids 和 follow_symlinks 参数。

在 3.6 版本发生变更: 接受 path-like object。

os.F_OK¶
os.R_OK¶
os.W_OK¶
os.X_OK¶: 用作 access() 的 mode 参数的值，分别用于测试 path 的存在性、可读性、可写性和可执行性。

os.chdir(path)¶

将当前工作目录更改为 path。

此函数可以支持指定文件描述符。描述符必须引用一个已打开的目录，而不是一个打开的文件。

此函数可能会引发 OSError 及其子类，例如 FileNotFoundError、PermissionError 和 NotADirectoryError。

使用参数 path 引发审计事件 os.chdir。

3.3 版中变更: 在某些平台上增加了对将 path 指定为文件描述符的支持。

在 3.6 版本发生变更: 接受 path-like object。

os.chflags(path, flags, *, follow_symlinks=True)¶

将 path 的标志设置为数字 flags。flags 可以采用以下值的组合（按位或）（在 stat 模块中定义）

此函数可以支持不跟随符号链接。

使用参数 path、flags 引发审计事件 os.chflags。

可用性: Unix，不包括 WASI。

3.3 版中变更: 添加了 follow_symlinks 参数。

在 3.6 版本发生变更: 接受 path-like object。

os.chmod(path, mode, *, dir_fd=None, follow_symlinks=True)¶

将 path 的模式更改为数字 mode。mode 可以是以下值（在 stat 模块中定义）之一或其按位或组合

此函数可以支持指定文件描述符、相对于目录描述符的路径和不跟随符号链接。

备注

虽然 Windows 支持 chmod()，但您只能使用它设置文件的只读标志（通过 stat.S_IWRITE 和 stat.S_IREAD 常量或相应的整数值）。所有其他位都将被忽略。在 Windows 上，follow_symlinks 的默认值为 False。

该功能在 WASI 上受到限制，详情请参阅 WebAssembly 平台。

使用参数 path、mode、dir_fd 引发审计事件 os.chmod。

3.3 版中变更: 添加了对将 path 指定为打开文件描述符的支持，以及 dir_fd 和 follow_symlinks 参数。

在 3.6 版本发生变更: 接受 path-like object。

3.13 版中变更: 在 Windows 上添加了对文件描述符和 follow_symlinks 参数的支持。

os.chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)¶

将 path 的所有者和组 ID 更改为数字 uid 和 gid。要使其中一个 ID 保持不变，请将其设置为 -1。

此函数可以支持指定文件描述符、相对于目录描述符的路径和不跟随符号链接。

有关接受名称和数字 ID 的高级函数，请参阅 shutil.chown()。

使用参数 path、uid、gid、dir_fd 引发审计事件 os.chown。

可用性: Unix。

该功能在 WASI 上受到限制，详情请参阅 WebAssembly 平台。

3.3 版中变更: 添加了对将 path 指定为打开文件描述符的支持，以及 dir_fd 和 follow_symlinks 参数。

3.6 版中变更: 支持 path-like object。

os.chroot(path)¶: 将当前进程的根目录更改为 path。

可用性: Unix，不包括 WASI，不包括 Android。

在 3.6 版本发生变更: 接受 path-like object。

os.fchdir(fd)¶

将当前工作目录更改为由文件描述符 fd 表示的目录。描述符必须引用一个已打开的目录，而不是一个打开的文件。从 Python 3.3 开始，这等同于 os.chdir(fd)。

使用参数 path 引发审计事件 os.chdir。

可用性: Unix。

os.getcwd()¶: 返回表示当前工作目录的字符串。

os.getcwdb()¶: 返回表示当前工作目录的字节串。

3.8 版中变更: 该函数现在在 Windows 上使用 UTF-8 编码，而不是 ANSI 代码页：有关原因，请参阅 PEP 529。该函数在 Windows 上不再被弃用。

os.lchflags(path, flags)¶

将 path 的标志设置为数字 flags，类似于 chflags()，但不跟随符号链接。从 Python 3.3 开始，这等同于 os.chflags(path, flags, follow_symlinks=False)。

使用参数 path、flags 引发审计事件 os.chflags。

可用性: Unix，不包括 WASI。

在 3.6 版本发生变更: 接受 path-like object。

os.lchmod(path, mode)¶

将 path 的模式更改为数字 mode。如果 path 是符号链接，则此操作会影响符号链接本身而不是目标。有关 mode 的可能值，请参阅 chmod() 的文档。从 Python 3.3 开始，这等同于 os.chmod(path, mode, follow_symlinks=False)。

lchmod() 不是 POSIX 的一部分，但如果支持更改符号链接的模式，Unix 实现可能会有它。

使用参数 path、mode、dir_fd 引发审计事件 os.chmod。

可用性：Unix、Windows，不支持 Linux，FreeBSD >= 1.3，NetBSD >= 1.3，不支持 OpenBSD

在 3.6 版本发生变更: 接受 path-like object。

3.13 版本中的变化: 添加了对 Windows 的支持。

os.lchown(path, uid, gid)¶

将 path 的所有者和组 ID 更改为数字 uid 和 gid。此函数不会跟随符号链接。从 Python 3.3 开始，这等同于 os.chown(path, uid, gid, follow_symlinks=False)。

使用参数 path、uid、gid、dir_fd 引发审计事件 os.chown。

可用性: Unix。

在 3.6 版本发生变更: 接受 path-like object。

os.link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)¶

创建指向 src 的名为 dst 的硬链接。

此函数可以支持指定 src_dir_fd 和/或 dst_dir_fd 以提供相对于目录描述符的路径，以及不跟随符号链接。在 Windows 上，follow_symlinks 的默认值为 False。

使用参数 src, dst, src_dir_fd, dst_dir_fd 引发审计事件 os.link。

可用性: Unix, Windows。

3.2 版中变更: 添加了 Windows 支持。

3.3 版中变更: 添加了 src_dir_fd、dst_dir_fd 和 follow_symlinks 参数。

3.6 版中变更: 接受 src 和 dst 的 path-like object。

os.listdir(path='.')¶

返回一个列表，其中包含由 path 指定的目录中的条目名称。列表的顺序是任意的，并且不包括特殊条目 '.' 和 '..'，即使它们存在于目录中。如果在调用此函数期间从目录中删除或添加了文件，则是否包含该文件的名称是未指定的。

path 可以是 path-like object。如果 path 的类型为 bytes（直接或通过 PathLike 接口间接），则返回的文件名也将是 bytes 类型；在所有其他情况下，它们将是 str 类型。

此函数还可以支持指定文件描述符；文件描述符必须引用一个目录。

使用参数 path 引发审计事件 os.listdir。

备注

要将 str 文件名编码为 bytes，请使用 fsencode()。

参见

scandir() 函数返回目录条目以及文件属性信息，为许多常见用例提供了更好的性能。

3.2 版中变更: path 参数变为可选。

3.3 版中变更: 添加了对将 path 指定为打开文件描述符的支持。

在 3.6 版本发生变更: 接受 path-like object。

os.listdrives()¶

返回一个列表，其中包含 Windows 系统上的驱动器名称。

驱动器名称通常类似于 'C:\\'。并非每个驱动器名称都与卷关联，并且由于各种原因（包括权限、网络连接或缺少媒体），某些驱动器可能无法访问。此函数不测试访问权限。

如果收集驱动器名称时发生错误，可能会引发 OSError。

不带参数地引发审计事件 os.listdrives。

可用性: Windows

3.12 新版功能.

os.listmounts(volume)¶

返回一个列表，其中包含 Windows 系统上卷的挂载点。

volume 必须表示为 GUID 路径，例如由 os.listvolumes() 返回的那些。卷可以挂载在多个位置，或者根本不挂载。在后一种情况下，列表将为空。不与卷关联的挂载点不会由本函数返回。

本函数返回的挂载点将是绝对路径，并且可能比驱动器名称长。

如果卷无法识别或收集路径时发生错误，则引发 OSError。

使用参数 volume 引发审计事件 os.listmounts。

可用性: Windows

3.12 新版功能.

os.listvolumes()¶

返回包含系统中卷的列表。

卷通常表示为 GUID 路径，看起来像 \\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\。文件通常可以通过 GUID 路径访问，只要权限允许。但是，用户通常不熟悉它们，因此建议使用此函数通过 os.listmounts() 检索挂载点。

如果收集卷时发生错误，则可能引发 OSError。

使用无参数引发审计事件 os.listvolumes。

可用性: Windows

3.12 新版功能.

os.lstat(path, *, dir_fd=None)¶

对给定路径执行等同于 lstat() 系统调用的操作。类似于 stat()，但不遵循符号链接。返回一个 stat_result 对象。

在不支持符号链接的平台上，这等同于 stat()。

自 Python 3.3 起，这等同于 os.stat(path, dir_fd=dir_fd, follow_symlinks=False)。

此函数还可以支持相对于目录描述符的路径。

参见

stat() 函数。

3.2 版中已更改: 添加了对 Windows 6.0 (Vista) 符号链接的支持。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

在 3.6 版本发生变更: 接受 path-like object。

3.8 版中已更改: 在 Windows 上，现在打开表示另一个路径（名称代理）的重解析点，包括符号链接和目录连接点。其他类型的重解析点由操作系统像 stat() 一样解析。

os.mkdir(path, mode=0o777, *, dir_fd=None)¶

创建名为 path 的目录，并使用数字模式 mode。

如果目录已存在，则引发 FileExistsError。如果路径中的父目录不存在，则引发 FileNotFoundError。

在某些系统上，mode 被忽略。在使用它的地方，当前的 umask 值首先被屏蔽掉。如果设置了最后 9 位以外的位（即 mode 的八进制表示的最后 3 位），它们的含义取决于平台。在某些平台上，它们被忽略，您应该显式调用 chmod() 来设置它们。

在 Windows 上，0o700 的 mode 被特殊处理，以对新目录应用访问控制，以便只有当前用户和管理员才能访问。mode 的其他值被忽略。

此函数还可以支持相对于目录描述符的路径。

也可以创建临时目录；请参见 tempfile 模块的 tempfile.mkdtemp() 函数。

使用参数 path、mode、dir_fd 引发审计事件 os.mkdir。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

在 3.6 版本发生变更: 接受 path-like object。

3.13 版中已更改: Windows 现在处理 0o700 的 mode。

os.makedirs(name, mode=0o777, exist_ok=False)¶

递归目录创建函数。类似于 mkdir()，但会创建包含叶目录所需的所有中间级目录。

mode 参数传递给 mkdir() 以创建叶目录；有关其解释方式，请参见 mkdir() 说明。要设置任何新创建的父目录的文件权限位，您可以在调用 makedirs() 之前设置 umask。现有父目录的文件权限位不会更改。

如果 exist_ok 为 False（默认值），如果目标目录已存在，则引发 FileExistsError。

备注

如果要创建的路径元素包含 pardir（例如 UNIX 系统上的“..”），makedirs() 将会混淆。

此函数正确处理 UNC 路径。

使用参数 path、mode、dir_fd 引发审计事件 os.mkdir。

3.2 版中已更改: 添加了 exist_ok 参数。

3.4.1 版中已更改: 在 Python 3.4.1 之前，如果 exist_ok 为 True 且目录已存在，如果 mode 与现有目录的模式不匹配，makedirs() 仍然会引发错误。由于此行为无法安全实现，因此在 Python 3.4.1 中已删除。请参见 bpo-21082。

在 3.6 版本发生变更: 接受 path-like object。

3.7 版中已更改: mode 参数不再影响新创建的中间级目录的文件权限位。

os.mkfifo(path, mode=0o666, *, dir_fd=None)¶

使用数字模式 mode 创建一个名为 path 的 FIFO（命名管道）。当前的 umask 值首先从模式中屏蔽掉。

此函数还可以支持相对于目录描述符的路径。

FIFO 是可以像常规文件一样访问的管道。FIFO 存在直到它们被删除（例如使用 os.unlink()）。通常，FIFO 用作“客户端”和“服务器”类型进程之间的集合点：服务器打开 FIFO 以进行读取，客户端打开它以进行写入。请注意，mkfifo() 不会打开 FIFO — 它只是创建集合点。

可用性: Unix，不包括 WASI。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

在 3.6 版本发生变更: 接受 path-like object。

os.mknod(path, mode=0o600, device=0, *, dir_fd=None)¶

创建名为 path 的文件系统节点（文件、设备特殊文件或命名管道）。mode 指定要使用的权限和要创建的节点类型，与 stat.S_IFREG、stat.S_IFCHR、stat.S_IFBLK 和 stat.S_IFIFO 中的一个（这些常量可在 stat 中获得）组合（按位或）。对于 stat.S_IFCHR 和 stat.S_IFBLK，device 定义新创建的设备特殊文件（可能使用 os.makedev()），否则它将被忽略。

此函数还可以支持相对于目录描述符的路径。

可用性: Unix，不包括 WASI。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

在 3.6 版本发生变更: 接受 path-like object。

os.major(device, /)¶: 从原始设备号中提取设备主编号（通常是 stat 中的 st_dev 或 st_rdev 字段）。

os.minor(device, /)¶: 从原始设备号中提取设备次编号（通常是 stat 中的 st_dev 或 st_rdev 字段）。

os.makedev(major, minor, /)¶: 根据主设备号和次设备号组合原始设备号。

os.pathconf(path, name)¶

返回与命名文件相关的系统配置信息。name 指定要检索的配置值；它可能是一个字符串，是已定义系统值的名称；这些名称在许多标准（POSIX.1、Unix 95、Unix 98 等）中指定。某些平台也定义了其他名称。宿主操作系统已知的名称在 pathconf_names 字典中给出。对于未包含在该映射中的配置变量，也接受将整数作为 name 传递。

如果 *name* 是字符串且未知，则引发 ValueError。如果主机系统不支持 *name* 的特定值，即使它包含在 pathconf_names 中，也会引发 OSError，错误号为 errno.EINVAL。

此函数可以支持指定文件描述符。

可用性: Unix。

在 3.6 版本发生变更: 接受 path-like object。

os.pathconf_names¶: 将 pathconf() 和 fpathconf() 接受的名称映射到主机操作系统为这些名称定义的整数值的字典。这可用于确定系统已知的名称集。

可用性: Unix。

os.readlink(path, *, dir_fd=None)¶

返回一个字符串，表示符号链接指向的路径。结果可以是绝对路径名或相对路径名；如果是相对路径名，可以使用 os.path.join(os.path.dirname(path), result) 转换为绝对路径名。

如果 path 是字符串对象（直接或间接通过 PathLike 接口），结果也将是字符串对象，并且调用可能会引发 UnicodeDecodeError。如果 path 是字节对象（直接或间接），结果将是字节对象。

此函数还可以支持相对于目录描述符的路径。

当尝试解析可能包含链接的路径时，请使用 realpath() 来正确处理递归和平台差异。

可用性: Unix, Windows。

3.2 版中已更改: 添加了对 Windows 6.0 (Vista) 符号链接的支持。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

3.6 版中已更改: 在 Unix 上接受类路径对象。

3.8 版中已更改: 在 Windows 上接受类路径对象和字节对象。

添加了对目录连接点的支持，并更改为返回替换路径（通常包含 \\?\ 前缀），而不是以前返回的可选“打印名称”字段。

os.remove(path, *, dir_fd=None)¶

删除文件 path。如果 path 是目录，则引发 OSError。使用 rmdir() 删除目录。如果文件不存在，则引发 FileNotFoundError。

此函数可以支持相对于目录描述符的路径。

在 Windows 上，尝试删除正在使用的文件会导致引发异常；在 Unix 上，目录条目被删除，但分配给文件的存储空间在原始文件不再使用之前不会可用。

此函数在语义上等同于 unlink()。

使用参数 path、dir_fd 引发审计事件 os.remove。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

在 3.6 版本发生变更: 接受 path-like object。

os.removedirs(name)¶

递归删除目录。类似于 rmdir()，但如果叶目录成功删除，removedirs() 会尝试连续删除 path 中提到的每个父目录，直到引发错误（该错误被忽略，因为它通常意味着父目录不为空）。例如，os.removedirs('foo/bar/baz') 将首先删除目录 'foo/bar/baz'，然后如果 'foo/bar' 和 'foo' 为空，则删除它们。如果叶目录无法成功删除，则引发 OSError。

使用参数 path、dir_fd 引发审计事件 os.remove。

在 3.6 版本发生变更: 接受 path-like object。

os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)¶

将文件或目录 src 重命名为 dst。如果 dst 存在，该操作在多种情况下将以 OSError 的子类失败。

在 Windows 上，如果 dst 存在，则总是引发 FileExistsError。如果 src 和 dst 在不同的文件系统上，操作可能会失败。使用 shutil.move() 来支持移动到不同的文件系统。

在 Unix 上，如果 src 是文件而 dst 是目录，或反之，将分别引发 IsADirectoryError 或 NotADirectoryError。如果两者都是目录且 dst 为空，dst 将被静默替换。如果 dst 是非空目录，则引发 OSError。如果两者都是文件，如果用户有权限，dst 将被静默替换。在某些 Unix 变种上，如果 src 和 dst 在不同的文件系统上，操作可能会失败。如果成功，重命名将是原子操作（这是 POSIX 要求）。

此函数可以支持指定 src_dir_fd 和/或 dst_dir_fd 以提供相对于目录描述符的路径。

如果您希望跨平台覆盖目标，请使用 replace()。

使用参数 src、dst、src_dir_fd、dst_dir_fd 引发审计事件 os.rename。

3.3 版中已更改: 添加了 src_dir_fd 和 dst_dir_fd 参数。

3.6 版中变更: 接受 src 和 dst 的 path-like object。

os.renames(old, new)¶

递归目录或文件重命名函数。作用类似于 rename()，但会首先尝试创建使新路径名有效的任何中间目录。重命名后，将使用 removedirs() 剪除旧名称最右侧路径段对应的目录。

备注

如果您缺少删除叶目录或文件所需的权限，此函数可能会在新目录结构已创建的情况下失败。

使用参数 src、dst、src_dir_fd、dst_dir_fd 引发审计事件 os.rename。

3.6 版中已更改: 接受 old 和 new 的类路径对象。

os.replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)¶

将文件或目录 src 重命名为 dst。如果 dst 是非空目录，则会引发 OSError。如果 dst 存在且是文件，则在用户有权限的情况下会静默替换。如果 src 和 dst 位于不同的文件系统上，操作可能会失败。如果成功，重命名将是原子操作（这是 POSIX 要求）。

此函数可以支持指定 src_dir_fd 和/或 dst_dir_fd 以提供相对于目录描述符的路径。

使用参数 src、dst、src_dir_fd、dst_dir_fd 引发审计事件 os.rename。

在 3.3 版本加入。

3.6 版中变更: 接受 src 和 dst 的 path-like object。

os.rmdir(path, *, dir_fd=None)¶

移除（删除）目录 path。如果目录不存在或不为空，则分别引发 FileNotFoundError 或 OSError。为了移除整个目录树，可以使用 shutil.rmtree()。

此函数可以支持相对于目录描述符的路径。

使用参数 path、dir_fd 引发审计事件 os.rmdir。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

在 3.6 版本发生变更: 接受 path-like object。

os.scandir(path='.')¶

返回一个 os.DirEntry 对象迭代器，对应于 path 给定目录中的条目。条目以任意顺序生成，特殊条目 '.' 和 '..' 不包括在内。如果在创建迭代器后从目录中删除或添加文件，是否包含该文件的条目是未指定的。

使用 scandir() 而不是 listdir() 可以显著提高还需要文件类型或文件属性信息的代码的性能，因为 os.DirEntry 对象在扫描目录时如果操作系统提供此信息，则会公开此信息。所有 os.DirEntry 方法都可能执行系统调用，但 is_dir() 和 is_file() 通常只需要对符号链接进行系统调用；os.DirEntry.stat() 在 Unix 上总是需要系统调用，但在 Windows 上只对符号链接需要系统调用。

path 可以是类路径对象。如果 path 是 bytes 类型（直接或间接通过 PathLike 接口），则每个 os.DirEntry 的 name 和 path 属性的类型将是 bytes；在所有其他情况下，它们将是 str 类型。

此函数还可以支持指定文件描述符；文件描述符必须引用一个目录。

使用参数 path 引发审计事件 os.scandir。

scandir() 迭代器支持上下文管理器协议并具有以下方法

scandir.close()¶

关闭迭代器并释放已获取的资源。

当迭代器耗尽或被垃圾回收时，或在迭代过程中发生错误时，此函数会自动调用。但是，建议显式调用它或使用 with 语句。

在 3.6 版本加入。

以下示例展示了 scandir() 的简单用法，以显示给定 path 中不以 '.' 开头的所有文件（不包括目录）。entry.is_file() 调用通常不会进行额外的系统调用。

with os.scandir(path) as it:
    for entry in it:
        if not entry.name.startswith('.') and entry.is_file():
            print(entry.name)

备注

在基于 Unix 的系统上，scandir() 使用系统的 opendir() 和 readdir() 函数。在 Windows 上，它使用 Win32 FindFirstFileW 和 FindNextFileW 函数。

在 3.5 版本加入。

3.6 版中已更改: 添加了对上下文管理器协议和 close() 方法的支持。如果 scandir() 迭代器既未耗尽也未显式关闭，则在其析构函数中将发出 ResourceWarning。

该函数接受类路径对象。

3.7 版中已更改: 在 Unix 上添加了对文件描述符的支持。

class os.DirEntry¶

scandir() 生成的对象，用于公开目录条目的文件路径和其他文件属性。

scandir() 将在不进行额外系统调用的情况下尽可能多地提供此信息。当执行 stat() 或 lstat() 系统调用时，os.DirEntry 对象将缓存结果。

os.DirEntry 实例不应存储在长期数据结构中；如果您知道文件元数据已更改或自调用 scandir() 以来已过去很长时间，请调用 os.stat(entry.path) 以获取最新信息。

因为 os.DirEntry 方法可以进行操作系统调用，所以它们也可能引发 OSError。如果您需要对错误进行非常细粒度的控制，可以在调用 os.DirEntry 方法之一时捕获 OSError 并进行适当处理。

为了直接用作类路径对象，os.DirEntry 实现了 PathLike 接口。

os.DirEntry 实例的属性和方法如下

name¶

条目的基本文件名，相对于 scandir() path 参数。

如果 scandir() path 参数是 bytes 类型，则 name 属性将为 bytes，否则为 str。使用 fsdecode() 解码字节文件名。

path¶

条目的完整路径名：等同于 os.path.join(scandir_path, entry.name)，其中 scandir_path 是 scandir() path 参数。路径只有在 scandir() path 参数是绝对路径时才是绝对路径。如果 scandir() path 参数是文件描述符，则 path 属性与 name 属性相同。

如果 scandir() path 参数是 bytes 类型，则 path 属性将为 bytes，否则为 str。使用 fsdecode() 解码字节文件名。

inode()¶

返回条目的 inode 号。

结果缓存在 os.DirEntry 对象上。使用 os.stat(entry.path, follow_symlinks=False).st_ino 获取最新信息。

在第一次未缓存的调用中，Windows 上需要系统调用，而 Unix 上不需要。

is_dir(*, follow_symlinks=True)¶

如果此条目是目录或指向目录的符号链接，则返回 True；如果此条目是或指向任何其他类型的文件，或者它不再存在，则返回 False。

如果 follow_symlinks 为 False，则仅当此条目是目录时才返回 True（不跟随符号链接）；如果此条目是任何其他类型的文件，或者它不再存在，则返回 False。

结果缓存在 os.DirEntry 对象上，为 follow_symlinks True 和 False 分别设置了单独的缓存。调用 os.stat() 以及 stat.S_ISDIR() 以获取最新信息。

在第一次未缓存的调用中，大多数情况下不需要系统调用。具体来说，对于非符号链接，Windows 和 Unix 都不需要系统调用，除了某些 Unix 文件系统（例如网络文件系统）返回 dirent.d_type == DT_UNKNOWN 的情况。如果条目是符号链接，则除非 follow_symlinks 为 False，否则需要系统调用才能跟随符号链接。

此方法可以引发 OSError，例如 PermissionError，但 FileNotFoundError 被捕获而不会引发。

is_file(*, follow_symlinks=True)¶

如果此条目是文件或指向文件的符号链接，则返回 True；如果此条目是或指向目录或其他非文件条目，或者它不再存在，则返回 False。

如果 follow_symlinks 为 False，则仅当此条目是文件时才返回 True（不跟随符号链接）；如果此条目是目录或其他非文件条目，或者它不再存在，则返回 False。

结果缓存在 os.DirEntry 对象上。缓存、进行的系统调用和引发的异常与 is_dir() 相同。

is_symlink()¶

如果此条目是符号链接（即使已损坏），则返回 True；如果此条目指向目录或任何类型的文件，或者它不再存在，则返回 False。

结果缓存在 os.DirEntry 对象上。调用 os.path.islink() 以获取最新信息。

在第一次未缓存的调用中，大多数情况下不需要系统调用。具体来说，Windows 和 Unix 都不需要系统调用，除了某些 Unix 文件系统（例如网络文件系统）返回 dirent.d_type == DT_UNKNOWN 的情况。

此方法可以引发 OSError，例如 PermissionError，但 FileNotFoundError 被捕获而不会引发。

is_junction()¶

如果此条目是连接点（即使已损坏），则返回 True；如果此条目指向常规目录、任何类型的文件、符号链接，或者它不再存在，则返回 False。

结果缓存在 os.DirEntry 对象上。调用 os.path.isjunction() 以获取最新信息。

3.12 新版功能.

stat(*, follow_symlinks=True)¶

返回此条目的 stat_result 对象。此方法默认跟随符号链接；要对符号链接进行 stat，请添加参数 follow_symlinks=False。

在 Unix 上，此方法总是需要系统调用。在 Windows 上，它只在 follow_symlinks 为 True 且条目是重解析点（例如，符号链接或目录连接点）时才需要系统调用。

在 Windows 上，stat_result 的 st_ino、st_dev 和 st_nlink 属性总是设置为零。调用 os.stat() 获取这些属性。

结果缓存在 os.DirEntry 对象上，为 follow_symlinks True 和 False 分别设置了单独的缓存。调用 os.stat() 以获取最新信息。

请注意，os.DirEntry 的几个属性和方法与 pathlib.Path 的几个属性和方法之间存在很好的对应关系。特别是，name 属性具有相同的含义，is_dir()、is_file()、is_symlink()、is_junction() 和 stat() 方法也如此。

在 3.5 版本加入。

3.6 版中已更改: 添加了对 PathLike 接口的支持。添加了对 Windows 上 bytes 路径的支持。

3.12 版中已更改: 在 Windows 上，stat 结果的 st_ctime 属性已弃用。文件创建时间可正确作为 st_birthtime 获取，将来 st_ctime 可能会更改为返回零或元数据更改时间（如果可用）。

os.stat(path, *, dir_fd=None, follow_symlinks=True)¶

获取文件或文件描述符的状态。对给定路径执行等同于 stat() 系统调用的操作。path 可以指定为字符串或字节——直接或间接通过 PathLike 接口——或作为打开的文件描述符。返回一个 stat_result 对象。

此函数通常遵循符号链接；要对符号链接进行 stat，请添加参数 follow_symlinks=False，或使用 lstat()。

此函数可以支持指定文件描述符和不跟随符号链接。

在 Windows 上，传递 follow_symlinks=False 将禁用所有名称代理重解析点的跟随，包括符号链接和目录连接点。不类似链接或操作系统无法跟随的其他类型的重解析点将直接打开。当跟随多个链接链时，这可能会导致返回原始链接而不是阻止完全遍历的非链接。要在此情况下获取最终路径的 stat 结果，请使用 os.path.realpath() 函数尽可能地解析路径名，并对结果调用 lstat()。这不适用于悬空符号链接或连接点，它们将引发通常的异常。

示例

>>> import os
>>> statinfo = os.stat('somefile.txt')
>>> statinfo
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
st_mtime=1297230027, st_ctime=1297230027)
>>> statinfo.st_size
264

参见

fstat() 和 lstat() 函数。

3.3 版中已更改: 添加了 dir_fd 和 follow_symlinks 参数，指定文件描述符而不是路径。

在 3.6 版本发生变更: 接受 path-like object。

3.8 版中已更改: 在 Windows 上，现在遵循所有可由操作系统解析的重解析点，并且传递 follow_symlinks=False 禁用所有名称代理重解析点的跟随。如果操作系统遇到无法跟随的重解析点，stat 现在返回原始路径的信息，就像指定了 follow_symlinks=False 而不是引发错误一样。

class os.stat_result¶

其属性大致对应于 stat 结构的成员的对象。它用于 os.stat()、os.fstat() 和 os.lstat() 的结果。

属性

st_mode¶: 文件模式：文件类型和文件模式位（权限）。

st_ino¶

平台相关，但如果非零，则唯一标识给定 st_dev 值的文件。通常是

Unix 上的 inode 号，
Windows 上的文件索引

st_dev¶: 此文件所在的设备的标识符。

st_nlink¶: 硬链接数。

st_uid¶: 文件所有者的用户标识符。

st_gid¶: 文件所有者的组标识符。

st_size¶: 文件大小（以字节为单位），如果它是常规文件或符号链接。符号链接的大小是它所包含的路径名的长度，不带终止空字节。

时间戳

st_atime¶: 最近访问时间，以秒为单位表示。

st_mtime¶: 最近内容修改时间，以秒为单位表示。

st_ctime¶: 最近元数据更改时间，以秒为单位表示。

3.12 版本中已更改: Windows 上 st_ctime 已弃用。文件创建时间请使用 st_birthtime。将来，st_ctime 将包含最近元数据更改时间，与其他平台一致。

st_atime_ns¶: 最近访问时间，以纳秒为单位的整数表示。

在 3.3 版本加入。

st_mtime_ns¶: 最近内容修改时间，以纳秒为单位的整数表示。

在 3.3 版本加入。

st_ctime_ns¶: 最近元数据更改时间，以纳秒为单位的整数表示。

在 3.3 版本加入。

3.12 版本中已更改: Windows 上 st_ctime_ns 已弃用。文件创建时间请使用 st_birthtime_ns。将来，st_ctime 将包含最近元数据更改时间，与其他平台一致。

st_birthtime¶: 文件创建时间，以秒为单位表示。此属性并非总是可用，可能会引发 AttributeError。

3.12 版本中已更改: st_birthtime 现已在 Windows 上可用。

st_birthtime_ns¶: 文件创建时间，以纳秒为单位的整数表示。此属性并非总是可用，可能会引发 AttributeError。

3.12 新版功能.

备注

st_atime、st_mtime、st_ctime 和 st_birthtime 属性的确切含义和分辨率取决于操作系统和文件系统。例如，在使用 FAT32 文件系统的 Windows 系统上，st_mtime 的分辨率为 2 秒，而 st_atime 的分辨率仅为 1 天。有关详细信息，请参阅您的操作系统文档。

同样，尽管 st_atime_ns、st_mtime_ns、st_ctime_ns 和 st_birthtime_ns 总是以纳秒表示，但许多系统不提供纳秒精度。在提供纳秒精度的系统上，用于存储 st_atime、st_mtime、st_ctime 和 st_birthtime 的浮点对象无法保留所有精度，因此会略有不精确。如果需要精确的时间戳，应始终使用 st_atime_ns、st_mtime_ns、st_ctime_ns 和 st_birthtime_ns。

在某些 Unix 系统（例如 Linux）上，以下属性也可能可用

st_blocks¶: 为文件分配的 512 字节块的数量。当文件有空洞时，这可能小于 st_size/512。

st_blksize¶: 用于高效文件系统 I/O 的“首选”块大小。以较小的块写入文件可能会导致低效的读取-修改-重写。

st_rdev¶: 如果是 inode 设备，则为设备类型。

st_flags¶: 用户定义的文件标志。

在其他 Unix 系统（例如 FreeBSD）上，以下属性可能可用（但可能只有在 root 尝试使用它们时才会填充）

st_gen¶: 文件生成号。

在 Solaris 及其派生系统上，以下属性也可能可用

st_fstype¶: 唯一标识包含该文件的文件系统类型的字符串。

在 macOS 系统上，以下属性也可能可用

st_rsize¶: 文件的实际大小。

st_creator¶: 文件的创建者。

st_type¶: 文件类型。

在 Windows 系统上，以下属性也可用

st_file_attributes¶: Windows 文件属性：GetFileInformationByHandle() 返回的 BY_HANDLE_FILE_INFORMATION 结构中的 dwFileAttributes 成员。请参阅 stat 模块中的 FILE_ATTRIBUTE_* <stat.FILE_ATTRIBUTE_ARCHIVE> 常量。

在 3.5 版本加入。

st_reparse_tag¶: 当 st_file_attributes 设置了 FILE_ATTRIBUTE_REPARSE_POINT 时，此字段包含标识重解析点类型的标签。请参阅 stat 模块中的 IO_REPARSE_TAG_* 常量。

标准模块 stat 定义了用于从 stat 结构中提取信息的函数和常量。（在 Windows 上，某些项填充了虚拟值。）

为了向后兼容，stat_result 实例也可以作为至少包含 10 个整数的元组访问，这些整数按 st_mode、st_ino、st_dev、st_nlink、st_uid、st_gid、st_size、st_atime、st_mtime、st_ctime 的顺序给出 stat 结构中最重要的（和可移植的）成员。某些实现可能会在末尾添加更多项。为了与旧版 Python 兼容，将 stat_result 作为元组访问始终返回整数。

3.5 版本中已更改: Windows 现在在可用时将文件索引作为 st_ino 返回。

3.7 版本中已更改: 为 Solaris/派生系统添加了 st_fstype 成员。

3.8 版本中已更改: 在 Windows 上添加了 st_reparse_tag 成员。

3.8 版本中已更改: 在 Windows 上，st_mode 成员现在根据需要将特殊文件标识为 S_IFCHR、S_IFIFO 或 S_IFBLK。

3.12 版本中已更改: 在 Windows 上，st_ctime 已弃用。最终，为了与其他平台一致，它将包含最后一次元数据更改时间，但目前仍包含创建时间。请使用 st_birthtime 获取创建时间。

在 Windows 上，st_ino 现在可能最多为 128 位，具体取决于文件系统。以前它不会超过 64 位，较大的文件标识符将被任意打包。

在 Windows 上，st_rdev 不再返回值。以前它会包含与 st_dev 相同的值，这是不正确的。

在 Windows 上添加了 st_birthtime 成员。

os.statvfs(path)¶

对给定路径执行 statvfs() 系统调用。返回值是一个对象，其属性描述给定路径上的文件系统，并对应于 statvfs 结构的成员，即：f_bsize、f_frsize、f_blocks、f_bfree、f_bavail、f_files、f_ffree、f_favail、f_flag、f_namemax、f_fsid。

为 f_flag 属性的位标志定义了两个模块级常量：如果设置了 ST_RDONLY，则文件系统以只读方式挂载；如果设置了 ST_NOSUID，则禁用或不支持 setuid/setgid 位的语义。

为基于 GNU/glibc 的系统定义了额外的模块级常量。这些是 ST_NODEV (禁止访问设备特殊文件)、ST_NOEXEC (禁止程序执行)、ST_SYNCHRONOUS (写入立即同步)、ST_MANDLOCK (允许对文件系统进行强制锁定)、ST_WRITE (写入文件/目录/符号链接)、ST_APPEND (仅追加文件)、ST_IMMUTABLE (不可变文件)、ST_NOATIME (不更新访问时间)、ST_NODIRATIME (不更新目录访问时间)、ST_RELATIME (相对于修改/更改时间更新访问时间)。

此函数可以支持指定文件描述符。

可用性: Unix。

3.2 版本中已更改: 添加了 ST_RDONLY 和 ST_NOSUID 常量。

3.3 版中变更: 添加了对将 path 指定为打开文件描述符的支持。

3.4 版本中已更改: 添加了 ST_NODEV、ST_NOEXEC、ST_SYNCHRONOUS、ST_MANDLOCK、ST_WRITE、ST_APPEND、ST_IMMUTABLE、ST_NOATIME、ST_NODIRATIME 和 ST_RELATIME 常量。

在 3.6 版本发生变更: 接受 path-like object。

3.7 版本中已更改: 添加了 f_fsid 属性。

os.supports_dir_fd¶

一个 set 对象，指示 os 模块中的哪些函数接受文件描述符作为其 dir_fd 参数。不同的平台提供不同的功能，Python 用于实现 dir_fd 参数的基础功能并非在所有 Python 支持的平台上都可用。为了保持一致性，可能支持 dir_fd 的函数总是允许指定该参数，但如果功能在本地不可用时使用，则会引发异常。（在所有平台上始终支持为 dir_fd 指定 None。）

要检查特定函数是否接受文件描述符作为其 dir_fd 参数，请在 supports_dir_fd 上使用 in 运算符。例如，如果 os.stat() 在本地平台接受文件描述符作为 dir_fd，则此表达式评估为 True

os.stat in os.supports_dir_fd

目前 dir_fd 参数仅适用于 Unix 平台；它们在 Windows 上均不适用。

在 3.3 版本加入。

os.supports_effective_ids¶

一个 set 对象，指示 os.access() 是否允许在本地平台为其 effective_ids 参数指定 True。（在所有平台上始终支持为 effective_ids 指定 False。）如果本地平台支持，则集合将包含 os.access()；否则它将为空。

如果 os.access() 在本地平台支持 effective_ids=True，则此表达式评估为 True

os.access in os.supports_effective_ids

目前 effective_ids 仅在 Unix 平台上受支持；它在 Windows 上不适用。

在 3.3 版本加入。

os.supports_fd¶

一个 set 对象，指示 os 模块中的哪些函数允许在本地平台将其 path 参数指定为打开的文件描述符。不同的平台提供不同的功能，Python 用于接受打开文件描述符作为 path 参数的基础功能并非在所有 Python 支持的平台上都可用。

要确定特定函数是否允许将其 path 参数指定为打开的文件描述符，请在 supports_fd 上使用 in 运算符。例如，如果 os.chdir() 在您的本地平台接受文件描述符作为 path，则此表达式评估为 True

os.chdir in os.supports_fd

在 3.3 版本加入。

os.supports_follow_symlinks¶

一个 set 对象，指示 os 模块中的哪些函数允许在本地平台为其 follow_symlinks 参数接受 False。不同的平台提供不同的功能，Python 用于实现 follow_symlinks 的基础功能并非在所有 Python 支持的平台上都可用。为了保持一致性，可能支持 follow_symlinks 的函数总是允许指定该参数，但如果功能在本地不可用时使用，则会引发异常。（在所有平台上始终支持为 follow_symlinks 指定 True。）

要检查特定函数是否接受 False 作为其 follow_symlinks 参数，请在 supports_follow_symlinks 上使用 in 运算符。例如，如果可以在本地平台调用 os.stat() 时指定 follow_symlinks=False，则此表达式评估为 True

os.stat in os.supports_follow_symlinks

在 3.3 版本加入。

os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)¶

创建指向 src 且名为 dst 的符号链接。

在 Windows 上，符号链接表示文件或目录，并且不会动态变形以匹配目标。如果目标存在，将创建与目标类型匹配的符号链接。否则，如果 target_is_directory 为 True，则符号链接将创建为目录，否则创建为文件符号链接（默认）。在非 Windows 平台上，target_is_directory 被忽略。

此函数可以支持相对于目录描述符的路径。

备注

在较新版本的 Windows 10 上，如果启用了开发者模式，非特权帐户可以创建符号链接。如果开发者模式不可用/未启用，则需要 SeCreateSymbolicLinkPrivilege 权限，或者进程必须以管理员身份运行。

当由非特权用户调用此函数时，会引发 OSError。

引发审计事件 os.symlink，参数为 src、dst、dir_fd。

可用性: Unix, Windows。

该功能在 WASI 上受到限制，详情请参阅 WebAssembly 平台。

3.2 版中已更改: 添加了对 Windows 6.0 (Vista) 符号链接的支持。

3.3 版本中已更改: 添加了 dir_fd 参数，现在允许在非 Windows 平台上使用 target_is_directory。

3.6 版中变更: 接受 src 和 dst 的 path-like object。

3.8 版本中已更改: 在 Windows 上添加了对开发者模式下非提升权限符号链接的支持。

os.sync()¶: 强制将所有内容写入磁盘。

可用性: Unix。

在 3.3 版本加入。

os.truncate(path, length)¶

截断与 path 对应的文件，使其大小最多为 length 字节。

此函数可以支持指定文件描述符。

引发审计事件 os.truncate，参数为 path、length。

可用性: Unix, Windows。

在 3.3 版本加入。

3.5 版本中的变化: 增加了对 Windows 的支持

在 3.6 版本发生变更: 接受 path-like object。

os.unlink(path, *, dir_fd=None)¶

删除文件 path。此函数在语义上与 remove() 相同；unlink 名称是其传统的 Unix 名称。有关更多信息，请参阅 remove() 的文档。

使用参数 path、dir_fd 引发审计事件 os.remove。

3.3 版本中的变化: 添加了 *dir_fd* 参数。

在 3.6 版本发生变更: 接受 path-like object。

os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)¶

设置由 path 指定的文件的访问时间和修改时间。

utime() 接受两个可选参数，times 和 ns。它们指定在 path 上设置的时间，并按以下方式使用

如果指定了 ns，它必须是 (atime_ns, mtime_ns) 形式的 2 元组，其中每个成员都是表示纳秒的整数。
如果 times 不是 None，它必须是 (atime, mtime) 形式的 2 元组，其中每个成员都是表示秒的整数或浮点数。
如果 times 是 None 且 ns 未指定，则等效于指定 ns=(atime_ns, mtime_ns)，其中两个时间都是当前时间。

同时为 times 和 ns 指定元组是错误的。

请注意，您在此处设置的确切时间可能不会被随后的 stat() 调用返回，具体取决于您的操作系统记录访问和修改时间的分辨率；请参阅 stat()。保留精确时间的最佳方法是使用 os.stat() 结果对象中的 st_atime_ns 和 st_mtime_ns 字段以及 utime() 的 ns 参数。

此函数可以支持指定文件描述符、相对于目录描述符的路径和不跟随符号链接。

引发审计事件 os.utime，参数为 path、times、ns、dir_fd。

3.3 版本中已更改: 添加了支持将 path 指定为打开的文件描述符，以及 dir_fd、follow_symlinks 和 ns 参数。

在 3.6 版本发生变更: 接受 path-like object。

os.walk(top, topdown=True, onerror=None, followlinks=False)¶

通过自上而下或自下而上遍历目录树来生成目录树中的文件名。对于以目录 top 为根的树中的每个目录（包括 top 本身），它会生成一个 3 元组 (dirpath, dirnames, filenames)。

dirpath 是一个字符串，表示目录的路径。dirnames 是 dirpath 中子目录的名称列表（包括指向目录的符号链接，不包括 '.' 和 '..'）。filenames 是 dirpath 中非目录文件的名称列表。请注意，列表中的名称不包含路径组件。要获取到 dirpath 中文件或目录的完整路径（以 top 开头），请执行 os.path.join(dirpath, name)。列表是否排序取决于文件系统。如果在生成列表期间从 dirpath 目录中删除或添加了文件，则该文件的名称是否包含在内是不确定的。

如果可选参数 topdown 为 True 或未指定，则在生成任何子目录的三元组之前生成目录的三元组（目录自上而下生成）。如果 topdown 为 False，则在生成所有子目录的三元组之后生成目录的三元组（目录自下而上生成）。无论 topdown 的值如何，子目录列表在生成目录及其子目录的元组之前检索。

当 topdown 为 True 时，调用者可以就地修改 dirnames 列表（可能使用 del 或切片赋值），walk() 将只递归到 dirnames 中保留名称的子目录；这可用于修剪搜索、强制特定的访问顺序，甚至通知 walk() 有关调用者在重新开始 walk() 之前创建或重命名的目录。当 topdown 为 False 时，修改 dirnames 对遍历的行为没有影响，因为在自下而上模式下，dirnames 中的目录在 dirpath 本身生成之前生成。

默认情况下，来自 scandir() 调用的错误将被忽略。如果指定了可选参数 onerror，它应该是一个函数；它将被调用，带有一个参数，一个 OSError 实例。它可以报告错误以继续遍历，或者引发异常以中止遍历。请注意，文件名作为异常对象的 filename 属性可用。

默认情况下，walk() 不会进入解析为目录的符号链接。将 followlinks 设置为 True 可访问由符号链接指向的目录，在支持它们的系统上。

备注

请注意，将 followlinks 设置为 True 可能导致无限递归，如果链接指向其自身的父目录。walk() 不会跟踪它已经访问过的目录。

备注

如果您传递相对路径名，请不要在 walk() 的恢复之间更改当前工作目录。walk() 从不更改当前目录，并假设其调用者也不会更改。

此示例显示了起始目录下每个目录中非目录文件占用的字节数，但不查看任何 __pycache__ 子目录

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/xml'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if '__pycache__' in dirs:
        dirs.remove('__pycache__')  # don't visit __pycache__ directories

在下一个示例中（shutil.rmtree() 的简单实现），自下而上遍历树是必不可少的，rmdir() 不允许在目录清空之前删除目录

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))
os.rmdir(top)

引发审计事件 os.walk，参数为 top、topdown、onerror、followlinks。

3.5 版本中已更改: 此函数现在调用 os.scandir() 而不是 os.listdir()，通过减少对 os.stat() 的调用次数，使其更快。

在 3.6 版本发生变更: 接受 path-like object。

os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)¶

这与 walk() 的行为完全相同，只是它生成一个 4 元组 (dirpath, dirnames, filenames, dirfd)，并且它支持 dir_fd。

dirpath、dirnames 和 filenames 与 walk() 输出相同，dirfd 是指向目录 dirpath 的文件描述符。

此函数始终支持相对于目录描述符的路径和不跟随符号链接。但请注意，与其他函数不同，fwalk() 的 follow_symlinks 默认值为 False。

备注

由于 fwalk() 生成文件描述符，这些描述符仅在下一次迭代步骤之前有效，因此如果您想保留它们更长时间，应该复制它们（例如使用 dup()）。

此示例显示了起始目录下每个目录中非目录文件占用的字节数，但不查看任何 __pycache__ 子目录

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/xml'):
    print(root, "consumes", end=" ")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end=" ")
    print("bytes in", len(files), "non-directory files")
    if '__pycache__' in dirs:
        dirs.remove('__pycache__')  # don't visit __pycache__ directories

在下一个示例中，自下而上遍历树是必不可少的：rmdir() 不允许在目录清空之前删除目录

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

引发审计事件 os.fwalk，参数为 top、topdown、onerror、follow_symlinks、dir_fd。

可用性: Unix。

在 3.3 版本加入。

在 3.6 版本发生变更: 接受 path-like object。

3.7 版本中已更改: 添加了对 bytes 路径的支持。

os.memfd_create(name[, flags=os.MFD_CLOEXEC])¶

创建一个匿名文件并返回引用它的文件描述符。flags 必须是系统上可用的 os.MFD_* 常量之一（或它们的按位或组合）。默认情况下，新的文件描述符是不可继承的。

在 name 中提供的名称用作文件名，并将作为目录 /proc/self/fd/ 中相应符号链接的目标显示。显示的名称始终以 memfd: 为前缀，仅用于调试目的。名称不影响文件描述符的行为，因此多个文件可以具有相同的名称而没有任何副作用。

可用性：Linux >= 3.17，glibc >= 2.27。

在 3.8 版本加入。

os.MFD_CLOEXEC¶
os.MFD_ALLOW_SEALING¶
os.MFD_HUGETLB¶
os.MFD_HUGE_SHIFT¶
os.MFD_HUGE_MASK¶
os.MFD_HUGE_64KB¶
os.MFD_HUGE_512KB¶
os.MFD_HUGE_1MB¶
os.MFD_HUGE_2MB¶
os.MFD_HUGE_8MB¶
os.MFD_HUGE_16MB¶
os.MFD_HUGE_32MB¶
os.MFD_HUGE_256MB¶
os.MFD_HUGE_512MB¶
os.MFD_HUGE_1GB¶
os.MFD_HUGE_2GB¶
os.MFD_HUGE_16GB¶: 这些标志可以传递给 memfd_create()。

可用性：Linux >= 3.17，glibc >= 2.27

MFD_HUGE* 标志仅在 Linux 4.14 及更高版本上可用。

在 3.8 版本加入。

os.eventfd(initval[, flags=os.EFD_CLOEXEC])¶

创建并返回一个事件文件描述符。文件描述符支持原始 read() 和 write()，缓冲区大小为 8，select()、poll() 及类似函数。有关更多信息，请参阅手册页 eventfd(2)。默认情况下，新的文件描述符是不可继承的。

initval 是事件计数器的初始值。初始值必须是 32 位无符号整数。请注意，初始值限制为 32 位无符号整数，尽管事件计数器是无符号 64 位整数，最大值为 2⁶⁴-2。

flags 可以由 EFD_CLOEXEC、EFD_NONBLOCK 和 EFD_SEMAPHORE 构成。

如果指定了 EFD_SEMAPHORE 且事件计数器非零，则 eventfd_read() 返回 1 并将计数器减一。

如果未指定 EFD_SEMAPHORE 且事件计数器非零，则 eventfd_read() 返回当前事件计数器值并将计数器重置为零。

如果事件计数器为零且未指定 EFD_NONBLOCK，则 eventfd_read() 阻塞。

eventfd_write() 增加事件计数器。如果写入操作会使计数器增加到大于 2⁶⁴-2 的值，则写入会阻塞。

示例

import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
try:
    # acquire semaphore
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # release semaphore
        os.eventfd_write(fd, v)
finally:
    os.close(fd)

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.10 版本加入。

os.eventfd_read(fd)¶: 从 eventfd() 文件描述符读取值并返回一个 64 位无符号整数。此函数不验证 fd 是否为 eventfd()。

可用性：Linux >= 2.6.27

在 3.10 版本加入。

os.eventfd_write(fd, value)¶: 将值添加到 eventfd() 文件描述符。value 必须是 64 位无符号整数。此函数不验证 fd 是否为 eventfd()。

可用性：Linux >= 2.6.27

在 3.10 版本加入。

os.EFD_CLOEXEC¶: 为新的 eventfd() 文件描述符设置 close-on-exec 标志。

可用性：Linux >= 2.6.27

在 3.10 版本加入。

os.EFD_NONBLOCK¶: 为新的 eventfd() 文件描述符设置 O_NONBLOCK 状态标志。

可用性：Linux >= 2.6.27

在 3.10 版本加入。

os.EFD_SEMAPHORE¶: 为从 eventfd() 文件描述符读取提供类似信号量的语义。读取时，内部计数器减一。

可用性：Linux >= 2.6.30

在 3.10 版本加入。

定时器文件描述符¶

在 3.13 版本加入。

这些函数提供了对 Linux 的 定时器文件描述符 API 的支持。当然，它们都只在 Linux 上可用。

os.timerfd_create(clockid, /, *, flags=0)¶

创建并返回一个定时器文件描述符（timerfd）。

timerfd_create() 返回的文件描述符支持

文件描述符的 read() 方法可以以 8 字节的缓冲区大小调用。如果定时器已经过期一次或多次，read() 将以主机的字节序返回过期次数，这可以通过 int.from_bytes(x, byteorder=sys.byteorder) 转换为 int>。

select() 和 poll() 可用于等待定时器过期，直到文件描述符可读。

clockid 必须是有效的时钟 ID，如 time 模块中定义的那样

time.CLOCK_REALTIME
time.CLOCK_MONOTONIC
time.CLOCK_BOOTTIME（对于 timerfd_create，自 Linux 3.15 起）

如果 clockid 是 time.CLOCK_REALTIME，则使用可设置的系统范围实时时钟。如果系统时钟更改，则需要更新定时器设置。要在系统时钟更改时取消定时器，请参阅 TFD_TIMER_CANCEL_ON_SET。

如果 clockid 是 time.CLOCK_MONOTONIC，则使用不可设置的单调递增时钟。即使系统时钟更改，定时器设置也不会受到影响。

如果 clockid 是 time.CLOCK_BOOTTIME，则与 time.CLOCK_MONOTONIC 相同，只是它包含了系统暂停的任何时间。

可以通过指定 flags 值来修改文件描述符的行为。可以使用以下任何变量，并通过按位或（| 运算符）组合它们

TFD_NONBLOCK
TFD_CLOEXEC

如果 TFD_NONBLOCK 未设置为标志，则 read() 将阻塞直到定时器过期。如果将其设置为标志，则 read() 不会阻塞，但如果自上次调用 read 以来没有过期，则 read() 将引发 OSError 异常，其中 errno 设置为 errno.EAGAIN。

TFD_CLOEXEC 始终由 Python 自动设置。

不再需要文件描述符时，必须使用 os.close() 关闭，否则文件描述符将泄漏。

参见

timerfd_create(2) 手册页。

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

os.timerfd_settime(fd, /, *, flags=flags, initial=0.0, interval=0.0)¶

更改定时器文件描述符的内部定时器。此函数与 timerfd_settime_ns() 操作相同的间隔定时器。

fd 必须是有效的定时器文件描述符。

可以通过指定 flags 值来修改定时器的行为。可以使用以下任何变量，并通过按位或（| 运算符）组合它们

TFD_TIMER_ABSTIME
TFD_TIMER_CANCEL_ON_SET

通过将 initial 设置为零（0）来禁用定时器。如果 initial 大于或等于零，则启用定时器。如果 initial 小于零，它将引发 OSError 异常，其中 errno 设置为 errno.EINVAL

默认情况下，定时器将在 initial 秒过去后触发。（如果 initial 为零，定时器将立即触发。）

但是，如果设置了 TFD_TIMER_ABSTIME 标志，则当定时器的时钟（由 timerfd_create() 中的 clockid 设置）达到 initial 秒时，定时器将触发。

定时器的间隔由 interval float 设置。如果 interval 为零，则定时器仅在首次过期时触发一次。如果 interval 大于零，则定时器将自上次过期以来每经过 interval 秒触发一次。如果 interval 小于零，它将引发 OSError 异常，其中 errno 设置为 errno.EINVAL

如果 TFD_TIMER_CANCEL_ON_SET 标志与 TFD_TIMER_ABSTIME 一起设置，并且此定时器的时钟是 time.CLOCK_REALTIME，则如果实时时钟不连续更改，则定时器被标记为可取消。读取描述符将因错误 ECANCELED 而中止。

Linux 将系统时钟作为 UTC 管理。夏令时转换仅通过更改时间偏移来完成，不会导致系统时钟不连续更改。

以下事件将导致系统时钟不连续更改

settimeofday
clock_settime
通过 date 命令设置系统日期和时间

返回一个包含 ( next_expiration, interval) 的两项元组，表示此函数执行之前的定时器状态。

参见

timerfd_create(2), timerfd_settime(2), settimeofday(2), clock_settime(2), 和 date(1)。

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

os.timerfd_settime_ns(fd, /, *, flags=0, initial=0, interval=0)¶: 类似于 timerfd_settime()，但使用纳秒表示时间。此函数与 timerfd_settime() 操作相同的间隔定时器。

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

os.timerfd_gettime(fd, /)¶

返回一个包含浮点数 (next_expiration, interval) 的两项元组。

next_expiration 表示下次定时器触发的相对时间，无论 TFD_TIMER_ABSTIME 标志是否设置。

interval 表示定时器的间隔。如果为零，则定时器在 next_expiration 秒过去后只会触发一次。

参见

timerfd_gettime(2)

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

os.timerfd_gettime_ns(fd, /)¶: 类似于 timerfd_gettime()，但以纳秒返回时间。

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

os.TFD_NONBLOCK¶: timerfd_create() 函数的一个标志，用于为新的定时器文件描述符设置 O_NONBLOCK 状态标志。如果未将 TFD_NONBLOCK 设置为标志，则 read() 会阻塞。

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

os.TFD_CLOEXEC¶: timerfd_create() 函数的一个标志，如果将 TFD_CLOEXEC 设置为标志，则为新文件描述符设置 close-on-exec 标志。

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

os.TFD_TIMER_ABSTIME¶: timerfd_settime() 和 timerfd_settime_ns() 函数的一个标志。如果设置此标志，则 initial 将被解释为定时器时钟上的绝对值（以 Unix 纪元以来的 UTC 秒或纳秒为单位）。

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

os.TFD_TIMER_CANCEL_ON_SET¶: 与 TFD_TIMER_ABSTIME 一起用于 timerfd_settime() 和 timerfd_settime_ns() 函数的标志。当底层时钟的时间不连续变化时，定时器将被取消。

可用性：Linux >= 2.6.27，glibc >= 2.8

在 3.13 版本加入。

Linux 扩展属性¶

在 3.3 版本加入。

这些函数仅在 Linux 上可用。

os.getxattr(path, attribute, *, follow_symlinks=True)¶

返回 path 的扩展文件系统属性 attribute 的值。attribute 可以是 bytes 或 str（直接或通过 PathLike 接口间接）。如果是 str，它将使用文件系统编码进行编码。

此函数可以支持指定文件描述符和不跟随符号链接。

使用参数 path、attribute 引发审计事件 os.getxattr。

3.6 版本发生变化: 接受路径类对象作为 path 和 attribute。

os.listxattr(path=None, *, follow_symlinks=True)¶

返回 path 上的扩展文件系统属性列表。列表中的属性表示为使用文件系统编码解码的字符串。如果 path 为 None，则 listxattr() 将检查当前目录。

此函数可以支持指定文件描述符和不跟随符号链接。

使用参数 path 引发审计事件 os.listxattr。

在 3.6 版本发生变更: 接受 path-like object。

os.removexattr(path, attribute, *, follow_symlinks=True)¶

从 path 中移除扩展文件系统属性 attribute。attribute 应该是 bytes 或 str（直接或通过 PathLike 接口间接）。如果是字符串，它将使用文件系统编码和错误处理程序进行编码。

此函数可以支持指定文件描述符和不跟随符号链接。

使用参数 path、attribute 引发审计事件 os.removexattr。

3.6 版本发生变化: 接受路径类对象作为 path 和 attribute。

os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)¶

将 path 上的扩展文件系统属性 attribute 设置为 value。attribute 必须是 bytes 或不带嵌入 NUL 的 str（直接或通过 PathLike 接口间接）。如果是 str，它将使用文件系统编码和错误处理程序进行编码。flags 可以是 XATTR_REPLACE 或 XATTR_CREATE。如果给出 XATTR_REPLACE 且属性不存在，则将引发 ENODATA。如果给出 XATTR_CREATE 且属性已存在，则不会创建属性，并引发 EEXISTS。

此函数可以支持指定文件描述符和不跟随符号链接。

备注

Linux 内核版本低于 2.6.39 中的一个错误导致在某些文件系统上忽略 flags 参数。

使用参数 path、attribute、value、flags 引发审计事件 os.setxattr。

3.6 版本发生变化: 接受路径类对象作为 path 和 attribute。

os.XATTR_SIZE_MAX¶: 扩展属性的值可以达到的最大大小。目前，在 Linux 上为 64 KiB。

os.XATTR_CREATE¶: 这是 setxattr() 中 flags 参数的可能值。它指示操作必须创建属性。

os.XATTR_REPLACE¶: 这是 setxattr() 中 flags 参数的可能值。它指示操作必须替换现有属性。

进程管理¶

这些函数可用于创建和管理进程。

各种 exec* 函数为加载到进程中的新程序接受一个参数列表。在每种情况下，这些参数的第一个都作为新程序本身的名称而不是用户可能在命令行中键入的参数传递给新程序。对于 C 程序员，这是传递给程序的 main() 的 argv[0]。例如，os.execv('/bin/echo', ['foo', 'bar']) 只会在标准输出上打印 bar；foo 似乎被忽略了。

os.abort()¶: 向当前进程生成 SIGABRT 信号。在 Unix 上，默认行为是生成核心转储；在 Windows 上，进程立即返回退出代码 3。请注意，调用此函数不会调用为 SIGABRT 注册的 Python 信号处理程序，该处理程序使用 signal.signal()。

os.add_dll_directory(path)¶

将路径添加到 DLL 搜索路径。

此搜索路径用于解析导入的扩展模块（模块本身通过 sys.path 解析）的依赖项，也由 ctypes 使用。

通过对返回的对象调用 close() 或在 with 语句中使用它来删除目录。

有关 DLL 如何加载的更多信息，请参阅 Microsoft 文档。

使用参数 path 引发审计事件 os.add_dll_directory。

可用性: Windows。

3.8 新增: 以前的 CPython 版本会使用当前进程的默认行为来解析 DLL。这导致了不一致性，例如有时只搜索 PATH 或当前工作目录，并且诸如 AddDllDirectory 等 OS 函数无效。

在 3.8 中，DLL 加载的两种主要方式现在明确覆盖了进程范围的行为，以确保一致性。有关更新库的信息，请参阅移植说明。

os.execl(path, arg0, arg1, ...)¶

os.execle(path, arg0, arg1, ..., env)¶

os.execlp(file, arg0, arg1, ...)¶

os.execlpe(file, arg0, arg1, ..., env)¶

os.execv(path, args)¶

os.execve(path, args, env)¶

os.execvp(file, args)¶

os.execvpe(file, args, env)¶

这些函数都执行一个新的程序，替换当前进程；它们不会返回。在 Unix 上，新的可执行文件被加载到当前进程中，并将具有与调用者相同的进程 ID。错误将作为 OSError 异常报告。

当前进程会立即被替换。打开的文件对象和描述符不会被刷新，因此如果这些打开的文件中可能有缓冲数据，您应该在调用 exec* 函数之前使用 sys.stdout.flush() 或 os.fsync() 刷新它们。

exec* 函数的“l”和“v”变体在命令行参数传递方式上有所不同。“l”变体在编写代码时参数数量固定时可能最容易使用；单个参数只需成为 execl*() 函数的附加参数。“v”变体在参数数量可变时很好，参数以列表或元组的形式作为 args 参数传递。在这两种情况下，子进程的参数都应该以运行命令的名称开头，但这并非强制执行。

名称末尾包含“p”的变体（execlp()、execlpe()、execvp() 和 execvpe()）将使用 PATH 环境变量来定位程序 file。当环境被替换时（使用 exec*e 变体之一，在下一段中讨论），新环境将用作 PATH 变量的来源。其他变体，execl()、execle()、execv() 和 execve()，不会使用 PATH 变量来定位可执行文件；path 必须包含适当的绝对或相对路径。相对路径必须包含至少一个斜杠，即使在 Windows 上也是如此，因为纯名称将无法解析。

对于 execle()、execlpe()、execve() 和 execvpe()（请注意，这些都以“e”结尾），env 参数必须是一个映射，用于定义新进程的环境变量（这些变量取代当前进程的环境）；函数 execl()、execlp()、execv() 和 execvp() 都使新进程继承当前进程的环境。

对于某些平台上的 execve()，path 也可以指定为开放文件描述符。此功能可能在您的平台上不受支持；您可以使用 os.supports_fd 检查它是否可用。如果不可用，使用它将引发 NotImplementedError。

使用参数 path、args、env 引发审计事件 os.exec。

可用性: Unix, Windows, 不支持 WASI, 不支持 Android, 不支持 iOS。

3.3 版本发生变化: 增加了对 execve() 将 path 指定为开放文件描述符的支持。

在 3.6 版本发生变更: 接受 path-like object。

os._exit(n)¶: 以状态 n 退出进程，不调用清理处理程序，不刷新 stdio 缓冲区等。

备注

标准退出方式是 sys.exit(n)。_exit() 通常只应在 fork() 之后的子进程中使用。

以下退出代码已定义，可与 _exit() 一起使用，尽管它们并非强制。这些通常用于用 Python 编写的系统程序，例如邮件服务器的外部命令传递程序。

备注

其中一些在所有 Unix 平台上可能不可用，因为存在一些差异。这些常量是在底层平台定义它们的地方定义的。

os.EX_OK¶: 表示没有发生错误的退出代码。可能取自某些平台上的 EXIT_SUCCESS 的定义值。通常值为零。

可用性: Unix, Windows。

os.EX_USAGE¶: 表示命令使用不正确，例如给定错误的参数数量时的退出代码。

可用性: Unix，不包括 WASI。

os.EX_DATAERR¶: 表示输入数据不正确的退出代码。

可用性: Unix，不包括 WASI。

os.EX_NOINPUT¶: 表示输入文件不存在或不可读的退出代码。

可用性: Unix，不包括 WASI。

os.EX_NOUSER¶: 表示指定用户不存在的退出代码。

可用性: Unix，不包括 WASI。

os.EX_NOHOST¶: 表示指定主机不存在的退出代码。

可用性: Unix，不包括 WASI。

os.EX_UNAVAILABLE¶: 表示所需服务不可用的退出代码。

可用性: Unix，不包括 WASI。

os.EX_SOFTWARE¶: 表示检测到内部软件错误的退出代码。

可用性: Unix，不包括 WASI。

os.EX_OSERR¶: 表示检测到操作系统错误，例如无法 fork 或创建管道的退出代码。

可用性: Unix，不包括 WASI。

os.EX_OSFILE¶: 表示某些系统文件不存在、无法打开或存在其他类型错误的退出代码。

可用性: Unix，不包括 WASI。

os.EX_CANTCREAT¶: 表示用户指定的输出文件无法创建的退出代码。

可用性: Unix，不包括 WASI。

os.EX_IOERR¶: 表示在某个文件上进行 I/O 时发生错误的退出代码。

可用性: Unix，不包括 WASI。

os.EX_TEMPFAIL¶: 表示发生临时故障的退出代码。这表示可能不是真正的错误，例如在可重试操作期间无法建立网络连接。

可用性: Unix，不包括 WASI。

os.EX_PROTOCOL¶: 表示协议交换非法、无效或无法理解的退出代码。

可用性: Unix，不包括 WASI。

os.EX_NOPERM¶: 表示执行操作权限不足的退出代码（但并非用于文件系统问题）。

可用性: Unix，不包括 WASI。

os.EX_CONFIG¶: 表示发生某种配置错误的退出代码。

可用性: Unix，不包括 WASI。

os.EX_NOTFOUND¶: 表示“未找到条目”之类的退出代码。

可用性: Unix，不包括 WASI。

os.fork()¶

派生一个子进程。在子进程中返回 0，在父进程中返回子进程的进程 ID。如果发生错误，则引发 OSError。

请注意，包括 FreeBSD <= 6.3 和 Cygwin 在内的一些平台在使用来自线程的 fork() 时存在已知问题。

使用无参数的审计事件 os.fork 引发。

警告

如果您在调用 fork() 的应用程序中使用 TLS 套接字，请参阅 ssl 文档中的警告。

警告

在 macOS 上，当与使用更高级别的系统 API 混合使用时，使用此功能是不安全的，这包括使用 urllib.request。

3.8 版本发生变化: 不再支持在子解释器中调用 fork()（引发 RuntimeError）。

3.12 版本发生变化: 如果 Python 能够检测到您的进程有多个线程，os.fork() 现在会引发 DeprecationWarning。

我们选择在可检测时将其作为警告浮现，以便更好地告知开发人员 POSIX 平台明确指出不支持的设计问题。即使在“看起来”有效的代码中，在 POSIX 平台上将线程与 os.fork() 混合使用也从未安全过。当父进程中存在线程时，CPython 运行时本身始终进行不安全地在子进程中使用的 API 调用（例如 malloc 和 free）。

macOS 用户或使用 glibc 之外的 libc 或 malloc 实现的用户更有可能遇到运行此类代码时的死锁。

有关我们为何将此长期存在的平台兼容性问题浮现给开发人员的技术细节，请参阅有关 fork 与线程不兼容的讨论。

可用性: POSIX, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.forkpty()¶

派生一个子进程，使用新的伪终端作为子进程的控制终端。返回一对 (pid, fd)，其中 pid 在子进程中为 0，在父进程中为新的子进程的进程 ID，fd 是伪终端主端的描述符。对于更具可移植性的方法，请使用 pty 模块。如果发生错误，则引发 OSError。

使用无参数的审计事件 os.forkpty 引发。

警告

在 macOS 上，当与使用更高级别的系统 API 混合使用时，使用此功能是不安全的，这包括使用 urllib.request。

3.8 版本发生变化: 不再支持在子解释器中调用 forkpty()（引发 RuntimeError）。

3.12 版本发生变化: 如果 Python 能够检测到您的进程有多个线程，则现在会引发 DeprecationWarning。请参阅 os.fork() 上的更详细解释。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.kill(pid, sig, /)¶

向进程 pid 发送信号 sig。主机平台上可用的特定信号的常量在 signal 模块中定义。

Windows：signal.CTRL_C_EVENT 和 signal.CTRL_BREAK_EVENT 信号是特殊信号，只能发送到共享公共控制台窗口的控制台进程，例如某些子进程。sig 的任何其他值将导致进程被 TerminateProcess API 无条件终止，并且退出代码将设置为 sig。

另请参阅 signal.pthread_kill()。

使用参数 pid、sig 引发审计事件 os.kill。

可用性: Unix, Windows, 不支持 WASI, 不支持 iOS。

3.2 版中变更: 添加了 Windows 支持。

os.killpg(pgid, sig, /)¶

向进程组 pgid 发送信号 sig。

使用参数 pgid、sig 引发审计事件 os.killpg。

可用性: Unix, 不包括 WASI, 不包括 iOS。

os.nice(increment, /)¶: 将 increment 添加到进程的“nice 值”。返回新的 nice 值。

可用性: Unix，不包括 WASI。

os.pidfd_open(pid, flags=0)¶

返回一个引用进程 pid 且设置了 flags 的文件描述符。此描述符可用于无竞争和无信号地执行进程管理。

有关更多详细信息，请参阅 pidfd_open(2) 手册页。

可用性: Linux >= 5.3，Android >= 构建时 API 级别 31

在 3.9 版本中新增。

os.PIDFD_NONBLOCK¶: 此标志指示文件描述符将是非阻塞的。如果文件描述符引用的进程尚未终止，则尝试使用 waitid(2) 等待文件描述符将立即返回错误 EAGAIN，而不是阻塞。

可用性: Linux >= 5.10

3.12 新版功能.

os.plock(op, /)¶: 将程序段锁定到内存中。op 的值（在 <sys/lock.h> 中定义）确定锁定哪些段。

可用性: Unix, 不包括 WASI, 不包括 iOS。

os.popen(cmd, mode='r', buffering=-1)¶

打开到命令 cmd 的管道。返回值是一个连接到管道的开放文件对象，可以读取或写入，具体取决于 mode 是 'r'（默认）还是 'w'。buffering 参数的含义与内置 open() 函数的相应参数相同。返回的文件对象读取或写入文本字符串而不是字节。

close 方法在子进程成功退出时返回 None，如果发生错误则返回子进程的返回代码。在 POSIX 系统上，如果返回代码为正，则表示进程的返回值左移一个字节。如果返回代码为负，则进程被由返回代码的负值给出的信号终止。（例如，如果子进程被杀死，则返回值为 - signal.SIGKILL。）在 Windows 系统上，返回值包含子进程的带符号整数返回代码。

在 Unix 上，waitstatus_to_exitcode() 可用于将 close 方法结果（退出状态）转换为退出代码，如果它不是 None。在 Windows 上，close 方法结果直接是退出代码（或 None）。

这是使用 subprocess.Popen 实现的；有关管理子进程和与子进程通信的更强大方法，请参阅该类的文档。

可用性：不适用于 WASI、Android、iOS。

备注

Python UTF-8 模式影响用于 cmd 和管道内容的编码。

popen() 是 subprocess.Popen 的一个简单包装器。使用 subprocess.Popen 或 subprocess.run() 来控制编码等选项。

3.14 版本后已弃用: 该函数被软弃用，不应再用于编写新代码。subprocess 模块是推荐的替代方案。

os.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)¶

封装了 C 库 API posix_spawn()，以便在 Python 中使用。

大多数用户应使用 subprocess.run() 而不是 posix_spawn()。

位置参数 path、args 和 env 类似于 execve()。允许 env 为 None，在这种情况下使用当前进程的环境。

path 参数是可执行文件的路径。path 应包含一个目录。使用 posix_spawnp() 传递不带目录的可执行文件。

file_actions 参数可以是描述在 C 库实现中的 fork() 和 exec() 步骤之间对子进程中的特定文件描述符执行的操作的元组序列。每个元组的第一个元素必须是下面列出的三个类型指示符之一，描述其余的元组元素

os.POSIX_SPAWN_OPEN¶

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

执行 os.dup2(os.open(path, flags, mode), fd)。

os.POSIX_SPAWN_CLOSE¶

(os.POSIX_SPAWN_CLOSE, fd)

执行 os.close(fd)。

os.POSIX_SPAWN_DUP2¶

(os.POSIX_SPAWN_DUP2, fd, new_fd)

执行 os.dup2(fd, new_fd)。

os.POSIX_SPAWN_CLOSEFROM¶

(os.POSIX_SPAWN_CLOSEFROM, fd)

执行 os.closerange(fd, INF)。

这些元组对应于 C 库的 posix_spawn_file_actions_addopen()、posix_spawn_file_actions_addclose()、posix_spawn_file_actions_adddup2() 和 posix_spawn_file_actions_addclosefrom_np() API 调用，用于为 posix_spawn() 调用本身做准备。

setpgroup 参数将子进程的进程组设置为指定的值。如果指定的值为 0，则子进程的进程组 ID 将与其进程 ID 相同。如果 setpgroup 的值未设置，子进程将继承父进程的进程组 ID。此参数对应于 C 库的 POSIX_SPAWN_SETPGROUP 标志。

如果 resetids 参数为 True，它将子进程的有效 UID 和 GID 重置为父进程的实际 UID 和 GID。如果参数为 False，则子进程保留父进程的有效 UID 和 GID。在任何一种情况下，如果可执行文件上启用了 set-user-ID 和 set-group-ID 权限位，它们的效果将覆盖有效 UID 和 GID 的设置。此参数对应于 C 库的 POSIX_SPAWN_RESETIDS 标志。

如果 setsid 参数为 True，它将为 posix_spawn 创建一个新的会话 ID。setsid 需要 POSIX_SPAWN_SETSID 或 POSIX_SPAWN_SETSID_NP 标志。否则，将引发 NotImplementedError。

setsigmask 参数将信号掩码设置为指定的信号集。如果未使用该参数，则子进程继承父进程的信号掩码。此参数对应于 C 库的 POSIX_SPAWN_SETSIGMASK 标志。

sigdef 参数将重置指定集合中所有信号的处理方式。此参数对应于 C 库的 POSIX_SPAWN_SETSIGDEF 标志。

scheduler 参数必须是一个元组，包含（可选的）调度策略和 sched_param 的实例以及调度参数。调度策略位置的值为 None 表示未提供。此参数是 C 库 POSIX_SPAWN_SETSCHEDPARAM 和 POSIX_SPAWN_SETSCHEDULER 标志的组合。

使用参数 path、argv、env 引发审计事件 os.posix_spawn。

在 3.8 版本加入。

3.13 版本中已更改: env 参数接受 None。os.POSIX_SPAWN_CLOSEFROM 在存在 posix_spawn_file_actions_addclosefrom_np() 的平台上可用。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)¶

封装了 C 库 API posix_spawnp()，以便在 Python 中使用。

类似于 posix_spawn()，不同之处在于系统会在 PATH 环境变量指定的目录列表中搜索 executable 文件（与 execvp(3) 的方式相同）。

使用参数 path、argv、env 引发审计事件 os.posix_spawn。

在 3.8 版本加入。

可用性: POSIX, 不支持 WASI, 不支持 Android, 不支持 iOS。

请参阅 posix_spawn() 文档。

os.register_at_fork(*, before=None, after_in_parent=None, after_in_child=None)¶

注册可调用对象，以便在使用 os.fork() 或类似进程克隆 API fork 新子进程时执行。参数是可选的且仅限关键字。每个参数指定一个不同的调用点。

before 是在 fork 子进程之前调用的函数。
after_in_parent 是在 fork 子进程后从父进程调用的函数。
after_in_child 是从子进程调用的函数。

这些调用只有在控制权预期返回到 Python 解释器时才进行。典型的 subprocess 启动不会触发它们，因为子进程不会重新进入解释器。

注册在 fork 之前执行的函数以相反的注册顺序调用。注册在 fork 之后执行的函数（无论是在父进程还是子进程中）以注册顺序调用。

请注意，第三方 C 代码进行的 fork() 调用可能不会调用这些函数，除非它明确调用 PyOS_BeforeFork()、PyOS_AfterFork_Parent() 和 PyOS_AfterFork_Child()。

无法注销函数。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

在 3.7 版本加入。

os.spawnl(mode, path, ...)¶

os.spawnle(mode, path, ..., env)¶

os.spawnlp(mode, file, ...)¶

os.spawnlpe(mode, file, ..., env)¶

os.spawnv(mode, path, args)¶

os.spawnve(mode, path, args, env)¶

os.spawnvp(mode, file, args)¶

os.spawnvpe(mode, file, args, env)¶

在新进程中执行程序 path。

（请注意，subprocess 模块提供了更强大的功能来生成新进程并检索其结果；建议使用该模块而不是这些函数。特别是请查看使用 subprocess 模块替换旧函数部分。）

如果 mode 是 P_NOWAIT，此函数返回新进程的进程 ID；如果 mode 是 P_WAIT，如果进程正常退出，则返回进程的退出代码，否则返回 -signal，其中 signal 是杀死进程的信号。在 Windows 上，进程 ID 实际上将是进程句柄，因此可以与 waitpid() 函数一起使用。

请注意，在 VxWorks 上，当新进程被杀死时，此函数不返回 -signal。相反，它会引发 OSError 异常。

spawn* 函数的 "l" 和 "v" 变体在命令行参数的传递方式上有所不同。如果参数数量在编写代码时是固定的，则 "l" 变体可能最容易使用；单个参数简单地成为 spawnl*() 函数的额外参数。"v" 变体在参数数量可变时很好，参数以列表或元组的形式作为 args 参数传递。在这两种情况下，子进程的参数必须以正在运行的命令的名称开头。

末尾包含第二个 “p” 的变体（spawnlp()、spawnlpe()、spawnvp() 和 spawnvpe()）将使用 PATH 环境变量来定位程序 file。当环境被替换时（使用 spawn*e 变体之一，将在下一段中讨论），新环境将用作 PATH 变量的来源。其他变体，spawnl()、spawnle()、spawnv() 和 spawnve()，将不使用 PATH 变量来定位可执行文件；path 必须包含适当的绝对路径或相对路径。

对于 spawnle()、spawnlpe()、spawnve() 和 spawnvpe()（请注意，它们都以 "e" 结尾），env 参数必须是一个映射，用于定义新进程的环境变量（它们用于代替当前进程的环境）；函数 spawnl()、spawnlp()、spawnv() 和 spawnvp() 都导致新进程继承当前进程的环境。请注意，env 字典中的键和值必须是字符串；无效的键或值将导致函数失败，返回值为 127。

例如，以下对 spawnlp() 和 spawnvpe() 的调用是等效的

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

使用参数 mode、path、args、env 引发审计事件 os.spawn。

可用性: Unix, Windows, 不支持 WASI, 不支持 Android, 不支持 iOS。

spawnlp()、spawnlpe()、spawnvp() 和 spawnvpe() 在 Windows 上不可用。spawnle() 和 spawnve() 在 Windows 上不是线程安全的；我们建议您改用 subprocess 模块。

在 3.6 版本发生变更: 接受 path-like object。

3.14 版本后已弃用: 这些函数被软弃用，不应再用于编写新代码。subprocess 模块是推荐的替代方案。

os.P_NOWAIT¶
os.P_NOWAITO¶: spawn* 函数族中 mode 参数的可能值。如果给定这些值中的任何一个，spawn* 函数将在新进程创建后立即返回，并以进程 ID 作为返回值。

可用性: Unix, Windows。

os.P_WAIT¶: spawn* 函数族中 mode 参数的可能值。如果将其作为 mode 给出，spawn* 函数将直到新进程运行完成才会返回，如果运行成功，将返回进程的退出代码，如果信号杀死进程，则返回 -signal。

可用性: Unix, Windows。

os.P_DETACH¶
os.P_OVERLAY¶: spawn* 函数族中 mode 参数的可能值。这些值不如上面列出的值可移植。P_DETACH 类似于 P_NOWAIT，但新进程与调用进程的控制台分离。如果使用 P_OVERLAY，则当前进程将被替换；spawn* 函数将不返回。

可用性: Windows。

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])¶

使用关联的应用程序启动文件。

当未指定 operation 时，这就像在 Windows 资源管理器中双击文件，或者将文件名作为交互式命令 shell 中的 start 命令的参数：文件将使用其扩展名关联的任何应用程序（如果有）打开。

当给出其他 operation 时，它必须是指定对文件执行操作的“命令动词”。Microsoft 文档中常见的动词是 'open'、'print' 和 'edit'（用于文件）以及 'explore' 和 'find'（用于目录）。

启动应用程序时，将 arguments 指定为单个字符串进行传递。当使用此函数启动文档时，此参数可能不起作用。

默认工作目录是继承的，但可以通过 cwd 参数覆盖。这应该是一个绝对路径。相对 path 将根据此参数解析。

使用 show_cmd 覆盖默认窗口样式。这是否有效将取决于正在启动的应用程序。值为 Win32 ShellExecute() 函数支持的整数。

startfile() 在关联应用程序启动后立即返回。没有等待应用程序关闭的选项，也无法检索应用程序的退出状态。path 参数是相对于当前目录或 cwd 的。如果您想使用绝对路径，请确保第一个字符不是斜杠（'/'）。使用 pathlib 或 os.path.normpath() 函数以确保路径正确编码为 Win32。

为了减少解释器启动开销，Win32 ShellExecute() 函数直到首次调用此函数时才解析。如果函数无法解析，将引发 NotImplementedError。

使用参数 path、operation 引发审计事件 os.startfile。

使用参数 path、operation、arguments、cwd、show_cmd 引发审计事件 os.startfile/2。

可用性: Windows。

3.10 版本中已更改: 增加了 arguments、cwd 和 show_cmd 参数，以及 os.startfile/2 审计事件。

os.system(command)¶

在子 shell 中执行命令（字符串）。这是通过调用标准 C 函数 system() 实现的，并具有相同的限制。对 sys.stdin 等的更改不会反映在执行命令的环境中。如果 command 产生任何输出，它将被发送到解释器标准输出流。C 标准没有指定 C 函数返回值的含义，因此 Python 函数的返回值是系统相关的。

在 Unix 上，返回值是按 wait() 指定的格式编码的进程退出状态。

在 Windows 上，返回值是系统 shell 运行 command 后返回的值。shell 由 Windows 环境变量 COMSPEC 给出：它通常是 cmd.exe，它返回运行命令的退出状态；在使用非原生 shell 的系统上，请查阅您的 shell 文档。

subprocess 模块提供了更强大的功能来生成新进程并检索其结果；建议使用该模块而不是此函数。有关一些有用的食谱，请参阅 subprocess 文档中的使用 subprocess 模块替换旧函数部分。

在 Unix 上，waitstatus_to_exitcode() 可用于将结果（退出状态）转换为退出代码。在 Windows 上，结果直接是退出代码。

使用参数 command 引发审计事件 os.system。

可用性: Unix, Windows, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.times()¶

返回当前全局进程时间。返回值是一个具有五个属性的对象

user - 用户时间
system - 系统时间
children_user - 所有子进程的用户时间
children_system - 所有子进程的系统时间
elapsed - 自过去某个固定点以来经过的实际时间

为了向后兼容，此对象也表现得像一个包含 user、system、children_user、children_system 和 elapsed 的五元组，按该顺序排列。

请参阅 Unix 手册页 times(2) 和 Unix 上的 times(3) 手册页，或 Windows 上的 GetProcessTimes MSDN。在 Windows 上，只知道 user 和 system；其他属性为零。

可用性: Unix, Windows。

3.3 版本中的变化: 返回类型从元组变为具有命名属性的类元组对象。

os.wait()¶

等待子进程完成，并返回一个元组，其中包含其 pid 和退出状态指示：一个 16 位数字，其低字节是杀死进程的信号编号，其高字节是退出状态（如果信号编号为零）；如果产生了核心文件，则低字节的高位被设置。

如果没有可等待的子进程，则会引发 ChildProcessError。

waitstatus_to_exitcode() 可用于将退出状态转换为退出代码。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

参见

下面文档中的其他 wait*() 函数可用于等待特定子进程的完成，并且具有更多选项。waitpid() 是唯一在 Windows 上也可用。

os.waitid(idtype, id, options, /)¶

等待子进程完成。

idtype 可以是 P_PID、P_PGID、P_ALL，或者（在 Linux 上）P_PIDFD。id 的解释取决于它；请参阅它们的单独描述。

options 是标志的 OR 组合。至少需要 WEXITED、WSTOPPED 或 WCONTINUED 之一；WNOHANG 和 WNOWAIT 是附加的可选标志。

返回值是一个对象，表示 siginfo_t 结构中包含的数据，具有以下属性

si_pid (进程 ID)
si_uid (子进程的实际用户 ID)
si_signo (始终为 SIGCHLD)
si_status (退出状态或信号编号，取决于 si_code)
si_code (可能的值请参见 CLD_EXITED)

如果指定了 WNOHANG 且在请求状态中没有匹配的子进程，则返回 None。否则，如果没有可等待的匹配子进程，则会引发 ChildProcessError。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

在 3.3 版本加入。

3.13 版本中已更改: 此函数现在也可在 macOS 上使用。

os.waitpid(pid, options, /)¶

此函数的详细信息在 Unix 和 Windows 上有所不同。

在 Unix 上：等待由进程 ID pid 给出的子进程完成，并返回一个包含其进程 ID 和退出状态指示的元组（编码方式与 wait() 相同）。调用的语义受整数 options 的值影响，对于正常操作，它应为 0。

如果 pid 大于 0，waitpid() 请求该特定进程的状态信息。如果 pid 为 0，则请求是关于当前进程进程组中任何子进程的状态。如果 pid 为 -1，则请求是关于当前进程的任何子进程。如果 pid 小于 -1，则请求是关于进程组 -pid（pid 的绝对值）中任何进程的状态。

options 是标志的 OR 组合。如果它包含 WNOHANG 并且在请求状态中没有匹配的子进程，则返回 (0, 0)。否则，如果没有可等待的匹配子进程，则会引发 ChildProcessError。可以使用的其他选项是 WUNTRACED 和 WCONTINUED。

在 Windows 上：等待由进程句柄 pid 给出的进程完成，并返回一个包含 pid 及其退出状态（左移 8 位）的元组（移位使函数的跨平台使用更容易）。小于或等于 0 的 pid 在 Windows 上没有特殊含义，会引发异常。整数 options 的值没有影响。pid 可以引用其 ID 已知的任何进程，不一定是子进程。使用 P_NOWAIT 调用的 spawn* 函数返回适当的进程句柄。

waitstatus_to_exitcode() 可用于将退出状态转换为退出代码。

可用性: Unix, Windows, 不支持 WASI, 不支持 Android, 不支持 iOS。

3.5 版本中已更改: 如果系统调用被中断且信号处理程序未引发异常，该函数现在会重试系统调用，而不是引发 InterruptedError 异常（有关原因，请参阅 PEP 475）。

os.wait3(options)¶

类似于 waitpid()，但未给定进程 ID 参数，并返回一个包含子进程 ID、退出状态指示和资源使用信息的 3 元素元组。有关资源使用信息的详细信息，请参阅 resource.getrusage()。options 参数与提供给 waitpid() 和 wait4() 的相同。

waitstatus_to_exitcode() 可用于将退出状态转换为退出代码。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.wait4(pid, options)¶

类似于 waitpid()，但返回一个 3 元素元组，其中包含子进程 ID、退出状态指示和资源使用信息。有关资源使用信息的详细信息，请参阅 resource.getrusage()。wait4() 的参数与提供给 waitpid() 的相同。

waitstatus_to_exitcode() 可用于将退出状态转换为退出代码。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.P_PID¶

os.P_PGID¶

os.P_ALL¶

os.P_PIDFD¶

这些是 waitid() 中 idtype 的可能值。它们影响 id 的解释

P_PID - 等待 PID 为 id 的子进程。
P_PGID - 等待进程组 ID 为 id 的任何子进程。
P_ALL - 等待任何子进程；id 被忽略。
P_PIDFD - 等待由文件描述符 id 标识的子进程（使用 pidfd_open() 创建的进程文件描述符）。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

备注

P_PIDFD 仅在 Linux >= 5.4 上可用。

在 3.3 版本加入。

3.9 版本新增: P_PIDFD 常量。

os.WCONTINUED¶: 此 options 标志适用于 waitpid()、wait3()、wait4() 和 waitid()，它会导致子进程在上次报告后，如果已从作业控制停止中继续，则被报告。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WEXITED¶

此 options 标志适用于 waitid()，它会导致已终止的子进程被报告。

其他 wait* 函数总是报告已终止的子进程，因此此选项不适用于它们。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

在 3.3 版本加入。

os.WSTOPPED¶

此 options 标志适用于 waitid()，它会导致因接收到信号而停止的子进程被报告。

此选项不适用于其他 wait* 函数。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

在 3.3 版本加入。

os.WUNTRACED¶

此 options 标志适用于 waitpid()、wait3() 和 wait4()，它也导致子进程被报告，如果它们已停止但其当前状态自停止以来尚未报告。

此选项不适用于 waitid()。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WNOHANG¶: 此 options 标志使得 waitpid()、wait3()、wait4() 和 waitid() 在没有子进程状态立即可用时立即返回。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WNOWAIT¶

此 options 标志使得 waitid() 将子进程留在可等待状态，以便稍后的 wait*() 调用可以再次检索子进程状态信息。

此选项不适用于其他 wait* 函数。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.CLD_EXITED¶
os.CLD_KILLED¶
os.CLD_DUMPED¶
os.CLD_TRAPPED¶
os.CLD_STOPPED¶
os.CLD_CONTINUED¶: 这些是 waitid() 返回结果中 si_code 的可能值。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

在 3.3 版本加入。

3.9 版本中已更改: 增加了 CLD_KILLED 和 CLD_STOPPED 值。

os.waitstatus_to_exitcode(status)¶

将等待状态转换为退出代码。

在 Unix 上

如果进程正常退出（如果 WIFEXITED(status) 为真），返回进程退出状态（返回 WEXITSTATUS(status)）：结果大于或等于 0。
如果进程被信号终止（如果 WIFSIGNALED(status) 为真），返回 -signum，其中 signum 是导致进程终止的信号编号（返回 -WTERMSIG(status)）：结果小于 0。
否则，引发 ValueError。

在 Windows 上，返回 status 右移 8 位。

在 Unix 上，如果进程正在被跟踪，或者 waitpid() 是用 WUNTRACED 选项调用的，调用者必须首先检查 WIFSTOPPED(status) 是否为真。如果 WIFSTOPPED(status) 为真，则不得调用此函数。

参见

WIFEXITED()、WEXITSTATUS()、WIFSIGNALED()、WTERMSIG()、WIFSTOPPED()、WSTOPSIG() 函数。

可用性: Unix, Windows, 不支持 WASI, 不支持 Android, 不支持 iOS。

在 3.9 版本中新增。

以下函数将 system()、wait() 或 waitpid() 返回的进程状态码作为参数。它们可用于确定进程的处理方式。

os.WCOREDUMP(status, /)¶

如果进程生成了核心转储，则返回 True，否则返回 False。

此函数仅在 WIFSIGNALED() 为真时才应使用。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WIFCONTINUED(status)¶

如果停止的子进程已通过发送 SIGCONT 恢复（如果进程已从作业控制停止中继续），则返回 True，否则返回 False。

请参阅 WCONTINUED 选项。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WIFSTOPPED(status)¶

如果进程因收到信号而停止，则返回 True，否则返回 False。

WIFSTOPPED() 仅当 waitpid() 调用使用 WUNTRACED 选项或进程正在被跟踪时才返回 True（请参阅 ptrace(2)）。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WIFSIGNALED(status)¶: 如果进程因信号终止，则返回 True，否则返回 False。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WIFEXITED(status)¶: 如果进程正常终止，即通过调用 exit() 或 _exit()，或者从 main() 返回，则返回 True；否则返回 False。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WEXITSTATUS(status)¶

返回进程退出状态。

此函数仅在 WIFEXITED() 为真时才应使用。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WSTOPSIG(status)¶

返回导致进程停止的信号。

此函数仅在 WIFSTOPPED() 为真时才应使用。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

os.WTERMSIG(status)¶

返回导致进程终止的信号编号。

此函数仅在 WIFSIGNALED() 为真时才应使用。

可用性: Unix, 不支持 WASI, 不支持 Android, 不支持 iOS。

调度器接口¶

这些函数控制操作系统如何为进程分配 CPU 时间。它们仅在某些 Unix 平台上可用。有关更详细的信息，请查阅您的 Unix manpages。

在 3.3 版本加入。

如果操作系统支持，则公开以下调度策略。

os.SCHED_OTHER¶: 默认调度策略。

os.SCHED_BATCH¶: 用于 CPU 密集型进程的调度策略，旨在保持计算机其余部分的交互性。

os.SCHED_DEADLINE¶: 用于具有截止时间限制的任务的调度策略。

在 3.14 版本加入。

os.SCHED_IDLE¶: 用于极低优先级后台任务的调度策略。

os.SCHED_NORMAL¶: SCHED_OTHER 的别名。

在 3.14 版本加入。

os.SCHED_SPORADIC¶: 用于零星服务器程序的调度策略。

os.SCHED_FIFO¶: 先进先出调度策略。

os.SCHED_RR¶: 轮询调度策略。

os.SCHED_RESET_ON_FORK¶: 此标志可以与任何其他调度策略进行按位或操作。当设置了此标志的进程派生子进程时，其子进程的调度策略和优先级将重置为默认值。

class os.sched_param(sched_priority)¶

此类表示在 sched_setparam()、sched_setscheduler() 和 sched_getparam() 中使用的可调调度参数。它是不可变的。

目前，只有一个可能的参数

sched_priority¶: 调度策略的调度优先级。

os.sched_get_priority_min(policy)¶: 获取 policy 的最小优先级值。policy 是上面列出的调度策略常量之一。

os.sched_get_priority_max(policy)¶: 获取 policy 的最大优先级值。policy 是上面列出的调度策略常量之一。

os.sched_setscheduler(pid, policy, param, /)¶: 为 PID 为 pid 的进程设置调度策略。pid 为 0 表示调用进程。policy 是上面列出的调度策略常量之一。param 是一个 sched_param 实例。

os.sched_getscheduler(pid, /)¶: 返回 PID 为 pid 的进程的调度策略。pid 为 0 表示调用进程。结果是上面列出的调度策略常量之一。

os.sched_setparam(pid, param, /)¶: 为 PID 为 pid 的进程设置调度参数。pid 为 0 表示调用进程。param 是一个 sched_param 实例。

os.sched_getparam(pid, /)¶: 返回 PID 为 pid 的进程的调度参数，作为 sched_param 实例。pid 为 0 表示调用进程。

os.sched_rr_get_interval(pid, /)¶: 返回 PID 为 pid 的进程的轮询时间片（以秒为单位）。pid 为 0 表示调用进程。

os.sched_yield()¶: 自愿放弃 CPU。有关详细信息，请参见手册页 sched_yield(2)。

os.sched_setaffinity(pid, mask, /)¶: 将 PID 为 pid 的进程（如果为零，则为当前进程）限制到一组 CPU。mask 是一个整数可迭代对象，表示应将进程限制到的 CPU 集合。

os.sched_getaffinity(pid, /)¶

返回 PID 为 pid 的进程被限制到的 CPU 集合。

如果 pid 为零，则返回当前进程的调用线程被限制到的 CPU 集合。

另请参见 process_cpu_count() 函数。

其他系统信息¶

os.confstr(name, /)¶

返回字符串类型的系统配置值。name 指定要检索的配置值；它可能是已定义的系统值的名称字符串；这些名称在许多标准（POSIX、Unix 95、Unix 98 等）中指定。某些平台也定义了其他名称。主机操作系统已知的名称作为 confstr_names 字典的键给出。对于不包含在该映射中的配置变量，也接受将整数作为 name 传入。

如果 name 指定的配置值未定义，则返回 None。

如果 name 是字符串且未知，则会引发 ValueError。如果主机系统不支持 name 的特定值，即使它包含在 confstr_names 中，也会引发 OSError，错误号为 errno.EINVAL。

可用性: Unix。

os.confstr_names¶: 字典，将 confstr() 接受的名称映射到主机操作系统为这些名称定义的整数值。这可用于确定系统已知名称的集合。

可用性: Unix。

os.cpu_count()¶

返回系统中的逻辑 CPU 数量。如果无法确定，则返回 None。

可以使用 process_cpu_count() 函数获取当前进程的调用线程可用的逻辑 CPU 数量。

在 3.4 版本加入。

3.13 版本中的变化：如果给定 -X cpu_count 或设置了 PYTHON_CPU_COUNT，则 cpu_count() 返回被覆盖的值 n。

os.getloadavg()¶: 返回系统运行队列中过去 1、5 和 15 分钟的平均进程数，如果无法获取平均负载，则引发 OSError。

可用性: Unix。

os.process_cpu_count()¶

获取当前进程的调用线程可用的逻辑 CPU 数量。如果无法确定，则返回 None。根据 CPU 亲和性，它可能小于 cpu_count()。

可以使用 cpu_count() 函数获取系统中的逻辑 CPU 数量。

如果给定 -X cpu_count 或设置了 PYTHON_CPU_COUNT，则 process_cpu_count() 返回被覆盖的值 n。

另请参见 sched_getaffinity() 函数。

在 3.13 版本加入。

os.sysconf(name, /)¶: 返回整数类型的系统配置值。如果 name 指定的配置值未定义，则返回 -1。关于 confstr() 的 name 参数的注释也适用于此处；提供已知名称信息的字典由 sysconf_names 给出。

可用性: Unix。

os.sysconf_names¶: 字典，将 sysconf() 接受的名称映射到主机操作系统为这些名称定义的整数值。这可用于确定系统已知名称的集合。

可用性: Unix。

3.11 版本中的变化：添加 'SC_MINSIGSTKSZ' 名称。

以下数据值用于支持路径操作。这些在所有平台上都已定义。

路径名上的高级操作在 os.path 模块中定义。

os.curdir¶: 操作系统用于指代当前目录的常量字符串。Windows 和 POSIX 系统上为 '.'。也可通过 os.path 访问。

os.pardir¶: 操作系统用于指代父目录的常量字符串。Windows 和 POSIX 系统上为 '..'。也可通过 os.path 访问。

os.sep¶: 操作系统用于分隔路径名组件的字符。POSIX 系统上为 '/'，Windows 系统上为 '\\'。请注意，仅知道这一点不足以解析或连接路径名 — 请使用 os.path.split() 和 os.path.join() — 但它偶尔也很有用。也可通过 os.path 访问。

os.altsep¶: 操作系统用于分隔路径名组件的备用字符，如果只有一个分隔符字符，则为 None。在 sep 为反斜杠的 Windows 系统上，此项设置为 '/'。也可通过 os.path 访问。

os.extsep¶: 分隔基本文件名和扩展名的字符；例如，os.py 中的 '.'。也可通过 os.path 访问。

os.pathsep¶: 操作系统传统上用于分隔搜索路径组件（如 PATH）的字符，例如 POSIX 系统上的 ':' 或 Windows 系统上的 ';'。也可通过 os.path 访问。

os.defpath¶: 如果环境中没有 'PATH' 键，则 exec*p* 和 spawn*p* 使用的默认搜索路径。也可通过 os.path 访问。

os.linesep¶: 当前平台上用于分隔（或终止）行的字符串。这可能是一个字符，如 POSIX 系统上的 '\n'，也可能是多个字符，例如 Windows 系统上的 '\r\n'。在以文本模式（默认）写入文件时，请勿使用 os.linesep 作为行终止符；在所有平台上都应使用单个 '\n'。

os.devnull¶: 空设备的文件路径。例如：POSIX 系统上的 '/dev/null'，Windows 系统上的 'nul'。也可通过 os.path 访问。

os.RTLD_LAZY¶
os.RTLD_NOW¶
os.RTLD_GLOBAL¶
os.RTLD_LOCAL¶
os.RTLD_NODELETE¶
os.RTLD_NOLOAD¶
os.RTLD_DEEPBIND¶: 用于 setdlopenflags() 和 getdlopenflags() 函数的标志。有关不同标志的含义，请参见 Unix 手册页 dlopen(3)。

在 3.3 版本加入。

随机数¶

os.getrandom(size, flags=0)¶

获取最多 size 个随机字节。该函数可以返回少于请求的字节数。

这些字节可用于为用户空间的随机数生成器播种或用于加密目的。

getrandom() 依赖于从设备驱动程序和其他环境噪声源收集的熵。不必要地读取大量数据会对 /dev/random 和 /dev/urandom 设备的其它用户产生负面影响。

flags 参数是一个位掩码，可以包含以下一个或多个值的按位或组合：os.GRND_RANDOM 和 GRND_NONBLOCK。

另请参见 Linux getrandom() 手册页。

可用性：Linux >= 3.17。

在 3.6 版本加入。

os.urandom(size, /)¶

返回一个包含 size 个随机字节的字节串，适用于加密用途。

此函数从特定于操作系统的随机性源返回随机字节。返回的数据对于加密应用程序应该足够不可预测，尽管其确切质量取决于操作系统实现。

在 Linux 上，如果 getrandom() 系统调用可用，它将以阻塞模式使用：阻塞直到系统 urandom 熵池初始化（内核收集到 128 位熵）。有关理由，请参见 PEP 524。在 Linux 上，可以使用 getrandom() 函数以非阻塞模式（使用 GRND_NONBLOCK 标志）获取随机字节，或者轮询直到系统 urandom 熵池初始化。

在类 Unix 系统上，随机字节从 /dev/urandom 设备读取。如果 /dev/urandom 设备不可用或不可读，则会引发 NotImplementedError 异常。

在 Windows 上，它将使用 BCryptGenRandom()。

参见

secrets 模块提供了更高级别的函数。有关平台提供的随机数生成器的易于使用的接口，请参见 random.SystemRandom。

3.5 版本中的变化：在 Linux 3.17 及更高版本上，如果可用，现在使用 getrandom() 系统调用。在 OpenBSD 5.6 及更高版本上，现在使用 C getentropy() 函数。这些函数避免了内部文件描述符的使用。

3.5.2 版本中的变化：在 Linux 上，如果 getrandom() 系统调用阻塞（urandom 熵池尚未初始化），则回退到读取 /dev/urandom。

3.6 版本中的变化：在 Linux 上，getrandom() 现在以阻塞模式使用以提高安全性。

3.11 版本中的变化：在 Windows 上，使用 BCryptGenRandom() 代替已弃用的 CryptGenRandom()。

os.GRND_NONBLOCK¶

默认情况下，当从 /dev/random 读取时，如果没有可用的随机字节，getrandom() 会阻塞；当从 /dev/urandom 读取时，如果熵池尚未初始化，它也会阻塞。

如果设置了 GRND_NONBLOCK 标志，则 getrandom() 在这些情况下不会阻塞，而是立即引发 BlockingIOError。

在 3.6 版本加入。

os.GRND_RANDOM¶: 如果设置了此位，则随机字节将从 /dev/random 池而不是 /dev/urandom 池中抽取。

在 3.6 版本加入。

`os` — 杂项操作系统接口¶

文件名、命令行参数和环境变量¶

Python UTF-8 模式¶

进程参数¶

文件对象创建¶

文件描述符操作¶

查询终端大小

文件描述符的继承

文件和目录

定时器文件描述符¶

Linux 扩展属性¶

进程管理¶

调度器接口¶

其他系统信息¶

随机数¶

目录

上一主题

下一主题

本页

os — 杂项操作系统接口¶

文件名、命令行参数和环境变量¶

Python UTF-8 模式¶

进程参数¶

文件对象创建¶

文件描述符操作¶

查询终端大小

文件描述符的继承

文件和目录

定时器文件描述符¶

Linux 扩展属性¶

进程管理¶

调度器接口¶

其他系统信息¶

随机数¶

`os` — 杂项操作系统接口¶