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

源代码: Lib/os.py

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

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

Python 中所有内置的操作系统相关模块的设计原则是，只要存在相同的功能，就会使用相同的接口；例如，函数 os.stat(path) 以相同的格式（碰巧起源于 POSIX 接口）返回关于 path 的 stat 信息。
特定于特定操作系统的扩展也可以通过 os 模块获得，但使用它们当然会对可移植性构成威胁。
所有接受路径或文件名的函数都接受字节和字符串对象，并且如果返回路径或文件名，则会生成相同类型的对象。
在 VxWorks 上，不支持 os.popen、os.fork、os.execv 和 os.spawn*p*。
在 WebAssembly 平台、Android 和 iOS 上，os 模块的很大一部分不可用或行为不同。与进程相关的 API（例如 fork()、execve()）和资源相关的 API（例如 nice()）不可用。其他如 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+DCxx，而在编码时，这些字符会再次转换为原始字节。

文件系统编码必须保证成功解码所有低于 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 作为其文本编码，其中为 sys.stdin 和 sys.stdout 启用了 surrogateescape 错误处理程序（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()。

在 3.9 版本中更改: 更新以支持 PEP 584 的合并（|）和更新（|=）运算符。

os.environb¶

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

仅当 supports_bytes_environ 为 True 时，environb 才可用。

在 3.2 版本中添加。

在 3.9 版本中更改: 更新以支持 PEP 584 的合并（|）和更新（|=）运算符。

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__()¶

返回对象的文件系统路径表示形式。

该方法应仅返回 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() 的映射同样也在导入时被捕获，并且该函数可能无法反映未来的环境更改。

仅当 supports_bytes_environ 为 True 时，getenvb() 才可用。

可用性: Unix。

在 3.2 版本中添加。

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

在 3.2 版本中添加。

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

可用性：Unix，非 WASI。

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

可用性：Unix，非 WASI。

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

可用性: Unix。

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

os.getgrouplist(user, group, /)¶: 返回 _user_ 所属的组 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, not 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，该 ID 可能已被另一个进程重用。

可用性: Unix, Windows, not 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, not WASI, not 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。

注意

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

引发带有参数 key, value 的审计事件 os.putenv。

3.9 版本更改: 该函数现在始终可用。

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

可用性: Unix, not WASI, not Android。

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

可用性: Unix, not WASI, not Android。

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

可用性: Unix, not WASI, not Android。

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

可用性：Unix，非 WASI。

注意

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

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, not WASI, not Android。

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

可用性: Unix, not WASI, not Android。

在 3.2 版本中添加。

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

可用性: Unix, not WASI, not Android。

在 3.2 版本中添加。

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

可用性: Unix, not WASI, not Android。

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

可用性：Unix，非 WASI。

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

可用性：Unix，非 WASI。

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

可用性: Unix, not WASI, not 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 的项。

引发带参数 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（即，两个或多个 inode 共享指向同一写时复制磁盘块的指针；支持的文件系统包括 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。默认情况下，新的文件描述符是可继承的，如果 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 版本中更改: 接受一个路径类对象。

以下常量是 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 Kernel 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* 可以通过对一个或多个以下值进行 OR 运算来构造：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 位置读取数据到可变的类字节对象 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。

使用标志需要 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 必须是类字节对象的序列。缓冲区按数组顺序处理。在处理第二个缓冲区之前，写入第一个缓冲区的全部内容，依此类推。

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。

使用标志需要 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.sendfile(out_fd, in_fd, offset, count)¶

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

从文件描述符 in_fd 复制 count 个字节到文件描述符 out_fd，起始偏移量为 offset。返回已发送的字节数。当到达 EOF 时，返回 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)¶

将 count 个字节从文件描述符 src，从偏移量 offset_src 开始，传输到文件描述符 dst，从偏移量 offset_dst 开始。至少一个文件描述符必须引用管道。如果 offset_src 为 None，则从 src 的当前位置读取；offset_dst 也是如此。与管道关联的文件描述符的偏移量必须为 None。src 和 dst 指向的文件必须位于同一文件系统中，否则会引发 OSError，其 errno 设置为 errno.EXDEV。

此复制操作不会额外消耗将数据从内核传输到用户空间，然后再返回到内核的成本。此外，某些文件系统可以实现额外的优化。复制操作就像以二进制方式打开两个文件一样执行。

成功完成后，返回从管道拼接或拼接进管道的字节数。返回值 0 表示输入结束。如果 src 引用管道，则表示没有要传输的数据，并且阻塞是没有意义的，因为没有写入器连接到管道的写入端。

可用性：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 必须是字节类对象的序列。缓冲区按数组顺序处理。在处理第二个缓冲区之前，会先写入第一个缓冲区的全部内容，依此类推。

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

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

可用性: Unix。

3.3 版本新增。

查询终端的大小¶

3.3 版本新增。

os.get_terminal_size(fd=STDOUT_FILENO, /)¶

以 (列数, 行数) 的形式返回终端窗口的大小，类型为 terminal_size 的元组。

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

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

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

可用性: Unix, Windows。

class os.terminal_size¶

元组的子类，保存终端窗口大小的 (列数, 行数)。

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)¶

使用实际的 uid/gid 来测试对 path 的访问权限。请注意，大多数操作将使用有效的 uid/gid，因此可以在 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 版本中更改: 接受一个路径类对象。

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 版本中更改: 接受一个路径类对象。

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

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

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

引发带有参数 path, flags 的审计事件 os.chflags。

可用性：Unix，非 WASI。

在 3.3 版本中更改: 添加了 follow_symlinks 参数。

在 3.6 版本中更改: 接受一个路径类对象。

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

将 path 的模式更改为数值 mode。mode 可以采用以下值之一（定义在 stat 模块中）或它们的按位 OR 组合

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

注意

尽管 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 版本中更改: 接受一个路径类对象。

在 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 版本中更改: 支持路径类对象。

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

可用性: Unix, not WASI, not Android。

在 3.6 版本中更改: 接受一个路径类对象。

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 版本中更改: 接受一个路径类对象。

os.lchmod(path, mode)¶

将 path 的模式更改为数值 mode。如果 path 是符号链接，这将影响符号链接而不是目标。请参阅 chmod() 的文档，了解 mode 的可能值。从 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 版本中更改: 接受一个路径类对象。

在 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 版本中更改: 接受一个路径类对象。

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

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

此函数可以支持指定 src_dir_fd 和/或 dst_dir_fd 以提供相对于目录描述符的路径，以及不跟踪符号链接。

引发一个审计事件 os.link，其参数为 src、 dst、 src_dir_fd、 dst_dir_fd。

可用性: Unix, Windows。

在 3.2 版本中更改: 添加了 Windows 支持。

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

在 3.6 版本中更改: 接受 src 和 dst 的path-like 对象。

os.listdir(path='.')¶

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

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

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

引发一个审计事件 os.listdir，其参数为 path。

注意

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

另请参阅

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

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

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

在 3.6 版本中更改: 接受一个路径类对象。

os.listdrives()¶

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

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

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

引发一个审计事件 os.listdrives，不带任何参数。

可用性：Windows

3.12 版本新增。

os.listmounts(volume)¶

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

volume 必须表示为 GUID 路径，类似于 os.listvolumes() 返回的路径。卷可以挂载在多个位置，也可以根本不挂载。在后一种情况下，列表将为空。此函数不会返回与卷无关的挂载点。

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

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

引发一个审计事件 os.listmounts，其参数为 volume。

可用性：Windows

3.12 版本新增。

os.listvolumes()¶

返回一个列表，其中包含系统中的卷。

卷通常表示为类似于 \\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\ 的 GUID 路径。通常可以通过 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 版本中更改: 接受一个路径类对象。

在 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 版本中更改: 接受一个路径类对象。

在 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 版本中更改: 接受一个路径类对象。

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

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

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

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

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

可用性：Unix，非 WASI。

在 3.3 版本中更改: 添加了 dir_fd 参数。

在 3.6 版本中更改: 接受一个路径类对象。

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 版本中更改: 接受一个路径类对象。

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 版本中更改: 接受一个路径类对象。

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 上接受 path-like object。

3.8 版本更改: 在 Windows 上接受 path-like object 和字节对象。

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

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 版本中更改: 接受一个路径类对象。

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 版本中更改: 接受一个路径类对象。

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 将被静默替换。如果 src 和 dst 位于不同的文件系统上，则该操作在某些 Unix 版本上可能会失败。如果成功，重命名将是一个原子操作（这是 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 对象。

os.renames(old, new)¶

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

注意

如果您缺乏删除叶目录或文件所需的权限，则此函数可能会失败，并且会创建新的目录结构。

引发一个带有参数 src、dst、src_dir_fd、dst_dir_fd 的审计事件 os.rename。

3.6 版本更改: 接受 old 和 new 的 path-like object。

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 对象。

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

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

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

引发一个带有参数 path、dir_fd 的审计事件 os.rmdir。

在 3.3 版本中更改: 添加了 dir_fd 参数。

在 3.6 版本中更改: 接受一个路径类对象。

os.scandir(path='.')¶

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

使用 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 对象。默认情况下，此方法遵循符号链接；要统计符号链接，请添加 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 对象。

此函数通常会跟随符号链接；要获取符号链接的状态，请添加参数 follow_symlinks=False，或者使用 lstat()。

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

在 Windows 上，传递 follow_symlinks=False 将禁用跟随所有名称代理重分析点，包括符号链接和目录连接。其他类型的不像链接或操作系统无法跟随的重分析点将直接打开。当跟随多个链接的链时，这可能会导致返回原始链接而不是阻止完全遍历的非链接。在这种情况下，要获取最终路径的状态结果，请使用 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 版本中更改: 接受一个路径类对象。

在 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 版本中更改: st_ctime 在 Windows 上已弃用。请使用 st_birthtime 获取文件创建时间。将来，st_ctime 将包含最近一次元数据更改的时间，与其他平台相同。

st_atime_ns¶: 最近一次访问的时间（以纳秒为单位的整数）。

3.3 版本新增。

st_mtime_ns¶: 最近一次内容修改的时间（以纳秒为单位的整数）。

3.3 版本新增。

st_ctime_ns¶: 最近一次元数据更改的时间（以纳秒为单位的整数）。

3.3 版本新增。

在 3.12 版本中更改: st_ctime_ns 在 Windows 上已弃用。请使用 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 文件属性： dwFileAttributes 是 BY_HANDLE_FILE_INFORMATION 结构体的成员，由 GetFileInformationByHandle() 返回。请参阅 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 个整数的元组访问，这些整数给出了 stat 结构体中最重要（且可移植）的成员，顺序为 st_mode、 st_ino、 st_dev、 st_nlink、 st_uid、 st_gid、 st_size、 st_atime、 st_mtime、 st_ctime。某些实现可能会在末尾添加更多项。为了与旧版本的 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 （相对于 mtime/ctime 更新 atime）。

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

可用性: 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 版本中更改: 接受一个路径类对象。

在 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 模块中哪些函数在本地平台上接受 False 作为它们的 follow_symlinks 参数。不同的平台提供不同的特性，并且 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)¶

创建一个名为 dst 的符号链接，指向 src。

在 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 对象。

在 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 版本中更改: 接受一个路径类对象。

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

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

引发一个带有参数 path、dir_fd 的审计事件 os.remove。

在 3.3 版本中更改: 添加了 dir_fd 参数。

在 3.6 版本中更改: 接受一个路径类对象。

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

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

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

如果指定了 ns，则它必须是一个 2 元组，形式为 (atime_ns, mtime_ns)，其中每个成员都是一个表示纳秒的整数。
如果 times 不是 None，则它必须是一个 2 元组，形式为 (atime, mtime)，其中每个成员都是一个表示秒的整数或浮点数。
如果 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 版本中更改: 接受一个路径类对象。

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() 永远不会更改当前目录，并且假设其调用方也不会更改。

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

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS 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 版本中更改: 接受一个路径类对象。

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()）。

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

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    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 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS 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 版本中更改: 接受一个路径类对象。

在 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 位无符号整数。请注意，尽管事件计数器是最大值为 2⁶⁴-2 的 64 位无符号整数，但初始值被限制为 32 位无符号整数。

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

如果指定了 EFD_SEMAPHORE 并且事件计数器非零，则 eventfd_read() 返回 1 并将计数器减 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() 文件描述符读取操作提供类似信号量的语义。读取时，内部计数器减 1。

可用性: Linux >= 2.6.30

在版本 3.10 中添加。

定时器文件描述符¶

在 3.13 版本中添加。

这些函数为 Linux 的定时器文件描述符 API 提供支持。自然地，它们都仅在 Linux 上可用。

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

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

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

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

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

clockid 必须是一个有效的时钟 ID，定义在 time 模块中。

time.CLOCK_REALTIME
time.CLOCK_MONOTONIC
time.CLOCK_BOOTTIME (自 Linux 3.15 起用于 timerfd_create)

如果 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 可以是字节或字符串（直接或间接通过 PathLike 接口）。如果它是字符串，则使用文件系统编码进行编码。

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

触发带有参数 path、attribute 的审计事件 os.getxattr。

在 3.6 版本中更改: 接受 path 和 attribute 的类路径对象。

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

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

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

触发带有参数 path 的审计事件 os.listxattr。

在 3.6 版本中更改: 接受一个路径类对象。

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

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

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

触发带有参数 path、attribute 的审计事件 os.removexattr。

在 3.6 版本中更改: 接受 path 和 attribute 的类路径对象。

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

将 path 上的扩展文件系统属性 attribute 设置为 value。attribute 必须是字节或字符串，且不能嵌入 NUL 字符（直接或间接通过 PathLike 接口）。如果它是字符串，则使用文件系统编码和错误处理程序进行编码。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。请注意，调用此函数不会调用使用 signal.signal() 为 SIGABRT 注册的 Python 信号处理程序。

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 版本中更改: 接受一个路径类对象。

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()¶

fork 一个子进程。在子进程中返回 0，在父进程中返回子进程的进程 id。如果发生错误，则引发 OSError。

请注意，在从线程中使用 fork() 时，包括 FreeBSD <= 6.3 和 Cygwin 在内的一些平台存在已知问题。

引发一个没有参数的审计事件 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 调用，这些 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 添加到进程的“优先级”。返回新的优先级。

可用性：Unix，非 WASI。

os.pidfd_open(pid, flags=0)¶

返回一个引用进程 pid 的文件描述符，并设置了 flags。此描述符可用于执行进程管理，而不会出现竞争和信号。

有关更多详细信息，请参阅 pidfd_open(2) 手册页。

可用性：Linux >= 5.3, Android >= build-time 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 上，如果 close 方法结果（退出状态）不是 None，可以使用 waitstatus_to_exitcode() 将其转换为退出代码。在 Windows 上，close 方法的结果直接是退出代码（或 None）。

这是使用 subprocess.Popen 实现的；有关管理和与子进程通信的更强大方法，请参阅该类的文档。

可用性：不是 WASI，不是 Android，不是 iOS。

注意

Python UTF-8 模式会影响用于 cmd 和管道内容的编码。

popen() 是 subprocess.Popen 的简单包装器。使用 subprocess.Popen 或 subprocess.run() 来控制诸如编码之类的选项。

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。在存在 posix_spawn_file_actions_addclosefrom_np() 的平台上，可以使用 os.POSIX_SPAWN_CLOSEFROM。

可用性：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 环境变量指定的目录列表中搜索 可执行 文件（与 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 创建新的子进程时执行的可调用对象。参数是可选的，并且是仅限关键字的。每个参数都指定不同的调用点。

before 是在派生子进程之前调用的函数。
after_in_parent 是在派生子进程后从父进程调用的函数。
after_in_child 是从子进程调用的函数。

只有在控制权预计会返回到 Python 解释器时，才会进行这些调用。典型的 subprocess 启动不会触发它们，因为子进程不会重新进入解释器。

在派生之前注册执行的函数按注册顺序的反向顺序调用。在派生之后注册执行的函数（在父进程或子进程中）按注册顺序调用。

请注意，第三方 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 版本中更改: 接受一个路径类对象。

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。

引发一个审计事件 os.startfile，参数为 path, operation。

引发一个审计事件 os.startfile/2，参数为 path、operation、arguments、cwd、show_cmd。

可用性: 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 上，返回值是运行 command 后系统 shell 返回的值。shell 由 Windows 环境变量 COMSPEC 给出：它通常是 cmd.exe，它返回运行命令的退出状态；在使用非原生 shell 的系统上，请查阅你的 shell 文档。

subprocess 模块为生成新进程和检索其结果提供了更强大的功能；使用该模块比使用此函数更好。请参阅 subprocess 文档中的使用 subprocess 模块替换较旧的函数部分，以获取一些有用的技巧。

在 Unix 上，可以使用 waitstatus_to_exitcode() 将结果（退出状态）转换为退出码。在 Windows 上，结果直接是退出码。

引发一个审计事件 os.system，参数为 command。

可用性：Unix, Windows, 不是 WASI，不是 Android，不是 iOS。

os.times()¶

返回当前全局进程时间。返回值是一个具有五个属性的对象

user - 用户时间
system - 系统时间
children_user - 所有子进程的用户时间
children_system - 所有子进程的系统时间
elapsed - 自过去某个固定点以来经过的实际时间

为了向后兼容，此对象还像一个包含 user、system、children_user、children_system 和 elapsed 的五元组（按该顺序）。

请参阅 Unix 手册页 times(2) 和 times(3) 手册页（在 Unix 上）或 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 上，如果正在跟踪进程或使用 WUNTRACED 选项调用了 waitpid()，则调用者必须首先检查 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。

仅当使用 WUNTRACED 选项调用 waitpid()，或者当进程正在被跟踪时（请参阅 ptrace(2)），WIFSTOPPED() 才会返回 True。

可用性：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() 为 true 时，才应使用此函数。

可用性：Unix，不是 WASI，不是 Android，不是 iOS。

os.WSTOPSIG(status)¶

返回导致进程停止的信号。

仅当 WIFSTOPPED() 为 true 时，才应使用此函数。

可用性：Unix，不是 WASI，不是 Android，不是 iOS。

os.WTERMSIG(status)¶

返回导致进程终止的信号编号。

仅当 WIFSIGNALED() 为真时才应使用此函数。

可用性：Unix，不是 WASI，不是 Android，不是 iOS。

调度器接口¶

这些函数控制操作系统如何为进程分配 CPU 时间。它们仅在某些 Unix 平台上可用。有关更多详细信息，请查阅您的 Unix 手册页。

3.3 版本新增。

如果操作系统支持，则会公开以下调度策略。

os.SCHED_OTHER¶: 默认调度策略。

os.SCHED_BATCH¶: 用于 CPU 密集型进程的调度策略，它尝试在计算机的其余部分保留交互性。

os.SCHED_IDLE¶: 用于极低优先级后台任务的调度策略。

os.SCHED_SPORADIC¶: 用于零星服务器程序的调度策略。

os.SCHED_FIFO¶: 先进先出调度策略。

os.SCHED_RR¶: 循环调度策略。

os.SCHED_RESET_ON_FORK¶: 此标志可以与任何其他调度策略进行 OR 运算。当设置此标志的进程 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, /)¶: 以 sched_param 实例形式返回 PID 为 *pid* 的进程的调度参数。*pid* 为 0 表示调用进程。

os.sched_rr_get_interval(pid, /)¶: 以秒为单位返回 PID 为 *pid* 的进程的循环量程。*pid* 为 0 表示调用进程。

os.sched_yield()¶: 自愿放弃 CPU。

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_count()，具体取决于 CPU 亲和性。

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 参数是一个位掩码，可以包含零个或多个以下值进行 OR 运算：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` — 杂项操作系统接口¶