`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 平台 wasm32-emscripten 和 wasm32-wasi 上，os 模块的大部分内容不可用或行为不同。与进程相关的 API（例如 fork()、execve()）、信号（例如 kill()、wait()）和资源（例如 nice()）不可用。其他像 getuid() 和 getpid() 是模拟的或存根。

注意

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

异常 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 作为其文本编码，并为 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，非 Emscripten，非 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，反之亦然）。

environb 仅在 supports_bytes_environ 为 True 时可用。

版本 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，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix。

该函数在 Emscripten 和 WASI 上是一个存根，有关详细信息，请参阅WebAssembly 平台。

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

可用性：Unix，非 Emscripten，非 WASI。

3.3 版新增。

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

可用性：Unix，非 Emscripten，非 WASI。

注意

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

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

可用性：Unix、Windows，不支持 Emscripten 和 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

os.getpid()¶

返回当前进程 ID。

该函数在 Emscripten 和 WASI 上是一个存根，有关详细信息，请参阅WebAssembly 平台。

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

可用性：Unix、Windows，不支持 Emscripten 和 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，非 Emscripten，非 WASI。

3.3 版新增。

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

可用性：Unix，非 Emscripten，非 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，非 Emscripten，非 WASI。

版本 3.2 中的新功能。

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

可用性：Unix，非 Emscripten，非 WASI。

版本 3.2 中的新功能。

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

可用性：Unix。

该函数在 Emscripten 和 WASI 上是一个存根，有关详细信息，请参阅WebAssembly 平台。

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

可用性：Unix，非 Emscripten，非 WASI。

版本 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，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 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)

可用性：使用 glibc >= 2.14 的 Linux >= 3.0。

添加于版本 3.12。

另请参阅

unshare() 函数。

os.setpgrp()¶: 根据实现的版本（如果有），调用系统调用 setpgrp() 或 setpgrp(0, 0)。有关语义，请参阅 Unix 手册。

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 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，非 Emscripten，非 WASI。

3.3 版新增。

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

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

版本 3.2 中的新功能。

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

可用性：Unix，非 Emscripten，非 WASI。

版本 3.2 中的新功能。

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

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

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

可用性：Unix，非 Emscripten，非 WASI。

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

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

版本 3.2 中的新功能。

os.umask(mask, /)¶

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

该函数在 Emscripten 和 WASI 上是一个存根，有关详细信息，请参阅WebAssembly 平台。

os.uname()¶

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

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

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

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

可用性：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。

此复制操作无需将数据从内核传输到用户空间，然后再传回内核，从而节省了额外的成本。此外，某些文件系统可以实现额外的优化，例如使用引用链接（即，两个或多个 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。

该函数在 Emscripten 和 WASI 上受到限制，有关详细信息，请参阅 WebAssembly 平台。

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。

该函数在 Emscripten 和 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。

该函数在 Emscripten 和 WASI 上受到限制，有关详细信息，请参阅 WebAssembly 平台。

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

3.5 版新增。

在 3.12 版更改: 添加了对 Windows 上管道的支持。

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，非 Emscripten，非 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 参数的选项。它们可以使用按位 OR 运算符 | 组合。其中一些并非在所有平台上都可用。有关其可用性和使用的说明，请参阅 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()¶: 打开一个新的伪终端对。返回一对文件描述符 (master, slave)，分别用于 pty 和 tty。新的文件描述符是不可继承的。有关（稍微）更便携的方法，请使用 pty 模块。

可用性：Unix，非 Emscripten，非 WASI。

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

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

可用性：Unix、Windows。

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

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

可用性：Unix，非 Emscripten，非 WASI。

3.3 版新增。

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

可用性：Unix，不是 Emscripten。

3.3 版新增。

os.posix_fadvise(fd, offset, len, advice, /)¶: 宣布以特定模式访问数据的意图，从而允许内核进行优化。该建议适用于从 offset 开始，为 fd 指定的文件区域，并持续 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 中最多读取 n 个字节，从 offset 位置开始，文件偏移量保持不变。

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

可用性：Unix。

3.3 版新增。

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。

使用 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.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。

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

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

将文件描述符 *in_fd* 中的 *count* 个字节从 *offset* 开始复制到文件描述符 *out_fd*。返回发送的字节数。到达 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，非 Emscripten，非 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，非 Emscripten，非 WASI。

3.3 版新增。

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

可用性：Unix，非 Emscripten，非 WASI。

3.11 版新增。

os.set_blocking(fd, blocking, /)¶

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

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

可用性：Unix、Windows。

该函数在 Emscripten 和 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* 读取数据到多个可变的类字节对象 *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.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 平台 wasm32-emscripten 和 wasm32-wasi 上，文件描述符无法修改。

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* 可以采用以下值的组合（按位或运算）（在 stat 模块中定义）：

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

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

可用性：Unix，非 Emscripten，非 WASI。

版本 3.3 中的变化：添加了 *follow_symlinks* 参数。

版本 3.6 中的变化：接受类路径对象。

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

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

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

注意

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

该函数在 Emscripten 和 WASI 上受到限制，有关详细信息，请参阅 WebAssembly 平台。

引发带有参数 path、mode、dir_fd 的审计事件 os.chmod。

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

版本 3.6 中的变化：接受类路径对象。

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。

该函数在 Emscripten 和 WASI 上受到限制，有关详细信息，请参阅 WebAssembly 平台。

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

版本 3.6 中的变化：支持类路径对象。

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

可用性：Unix，非 Emscripten，非 WASI。

版本 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，非 Emscripten，非 WASI。

版本 3.6 中的变化：接受类路径对象。

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，不是 Linux，FreeBSD >= 1.3，NetBSD >= 1.3，不是 OpenBSD

版本 3.6 中的变化：接受类路径对象。

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 以提供相对于目录描述符的路径，以及不跟随符号链接。

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

可用性：Unix、Windows，不是 Emscripten。

版本 3.2 中的变化：添加了 Windows 支持。

版本 3.3 中的变化：添加了 src_dir_fd、dst_dir_fd 和 follow_symlinks 参数。

版本 3.6 中的变化：接受类路径对象作为 src 和 dst。

os.listdir(path='.')¶

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

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

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

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

注意

要将 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。

使用参数 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 中的变化：接受类路径对象。

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

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

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

如果目录已存在，则会引发 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.12.4 版更改: 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)¶

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

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

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

可用性：Unix，非 Emscripten，非 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，非 Emscripten，非 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 上接受类路径对象。

在 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 中的变化：接受类路径对象。

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。

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。

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() 系统调用的操作。可以通过 PathLike 接口直接或间接地将 path 指定为字符串或字节，也可以指定为打开的文件描述符。返回 stat_result 对象。

此函数通常跟随符号链接；要统计符号链接，请添加参数 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 中的变化：接受类路径对象。

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/derivatives 添加了 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 模块中的哪些函数在其本地平台上接受 follow_symlinks 参数为 False。不同的平台提供不同的功能，Python 用于实现 follow_symlinks 的底层功能并非在 Python 支持的所有平台上都可用。为了保持一致性，可能支持 follow_symlinks 的函数始终允许指定该参数，但如果在本地不可用时使用该功能，则会引发异常。（在所有平台上始终支持为 follow_symlinks 指定 True。）

要检查特定函数是否接受 follow_symlinks 参数为 False，请对 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。

引发带有参数 src、dst、dir_fd 的审计事件 os.symlink。

可用性：Unix、Windows。

该函数在 Emscripten 和 WASI 上受到限制，有关详细信息，请参阅 WebAssembly 平台。

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

版本 3.3 中的变化：添加了 dir_fd 参数，现在允许在非 Windows 平台上使用 target_is_directory。

版本 3.6 中的变化：接受类路径对象作为 src 和 dst。

版本 3.8 中的变化：添加了对在启用了开发者模式的 Windows 上使用非提升权限的符号链接的支持。

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

可用性：Unix。

3.3 版新增。

os.truncate(path, length)¶

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

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

引发带有参数 path、length 的审计事件 os.truncate。

可用性：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，则它必须是形式为 (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 参数一起使用。

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

引发带有参数 path、times、ns、dir_fd 的审计事件 os.utime。

版本 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))

引发带有参数 top、topdown、onerror、followlinks 的审计事件 os.walk。

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

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

可用性：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])¶

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

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

*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() 文件描述符读取数据提供类似信号量的语义。读取时，内部计数器减一。

可用性：Linux >= 2.6.30

3.10 版新增。

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。

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

注意

低于 2.6.39 的 Linux 内核版本中的一个错误导致在某些文件系统上忽略 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 的更多信息，请参阅微软文档。

引发带有参数 path 的审计事件 os.add_dll_directory。

可用性：Windows。

3.8 版新增: 以前版本的 CPython 会使用当前进程的默认行为来解析 DLL。这会导致不一致，例如有时只搜索 PATH 或当前工作目录，以及 AddDllDirectory 等操作系统函数不起作用。

在 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 环境变量来定位程序文件。当环境被替换时（使用 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，不支持 Emscripten 和 WASI。

在 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，非 Emscripten，非 WASI。

os.EX_DATAERR¶: 表示输入数据不正确的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_NOINPUT¶: 表示输入文件不存在或不可读的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_NOUSER¶: 表示指定的用户不存在的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_NOHOST¶: 表示指定的主机不存在的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_UNAVAILABLE¶: 表示所需的服務不可用的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_SOFTWARE¶: 表示检测到内部软件错误的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_OSERR¶: 表示检测到操作系统错误的退出代码，例如无法 fork 或创建管道。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_OSFILE¶: 表示某些系统文件不存在、无法打开或有其他类型的错误的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_CANTCREAT¶: 表示无法创建用户指定的输出文件的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_IOERR¶: 表示在对某个文件执行 I/O 时发生错误的退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_TEMPFAIL¶: 退出代码，表示发生了临时故障。这表示可能并非真正错误，例如在可重试操作期间无法建立网络连接。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_PROTOCOL¶: 退出代码，表示协议交换不合法、无效或无法理解。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_NOPERM¶: 退出代码，表示执行操作的权限不足（但不用于文件系统问题）。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_CONFIG¶: 退出代码，表示发生了某种配置错误。

可用性：Unix，非 Emscripten，非 WASI。

os.EX_NOTFOUND¶: 退出代码，表示类似于“未找到条目”。

可用性：Unix，非 Emscripten，非 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 用户或使用 libc 或 malloc 实现（而不是迄今为止在 glibc 中常见的实现）的用户更有可能在运行此类代码时遇到死锁。

有关我们为什么要向开发人员公开这个长期存在的平台兼容性问题的技术细节，请参阅关于 fork 与线程不兼容的讨论。

可用性：POSIX，而非 Emscripten，也非 WASI。

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，非 Emscripten，非 WASI。

os.kill(pid, sig, /)¶

向进程 *pid* 发送信号 *sig*。主机平台上可用的特定信号的常量在 signal 模块中定义。

Windows：signal.CTRL_C_EVENT 和 signal.CTRL_BREAK_EVENT 信号是特殊信号，只能发送到共享同一个控制台窗口的控制台进程，例如某些子进程。*sig* 的任何其他值都将导致进程被 TerminateProcess API 无条件终止，并且退出代码将设置为 *sig*。Windows 版本的 kill() 还接受要终止的进程句柄。

另请参阅 signal.pthread_kill()。

引发一个带有参数 pid、sig 的审计事件 os.kill。

可用性：Unix、Windows，不支持 Emscripten 和 WASI。

版本 3.2 中的变化：添加了 Windows 支持。

os.killpg(pgid, sig, /)¶

向进程组 *pgid* 发送信号 *sig*。

引发一个带有参数 pgid、sig 的审计事件 os.killpg。

可用性：Unix，非 Emscripten，非 WASI。

os.nice(increment, /)¶: 将 increment 添加到进程的“优先级”中。返回新的优先级。

可用性：Unix，非 Emscripten，非 WASI。

os.pidfd_open(pid, flags=0)¶

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

有关更多详细信息，请参阅 pidfd_open(2) 联机帮助页。

可用性：Linux >= 5.3

在 3.9 版中添加。

os.PIDFD_NONBLOCK¶: 此标志表示文件描述符将是非阻塞的。如果文件描述符引用的进程尚未终止，则尝试使用 waitid(2) 等待文件描述符将立即返回错误 EAGAIN，而不是阻塞。

可用性：Linux >= 5.10

添加于版本 3.12。

os.plock(op, /)¶: 将程序段锁定到内存中。op 的值（在 <sys/lock.h> 中定义）确定锁定哪些段。

可用性：Unix，非 Emscripten，非 WASI。

os.popen(cmd, mode='r', buffering=-1)¶

打开到命令 cmd 或从命令 cmd 打开的管道。返回值是一个连接到管道的打开文件对象，可以根据 mode 是 'r'（默认值）还是 'w' 来读取或写入。buffering 参数的含义与内置 open() 函数的相应参数相同。返回的文件对象读取或写入文本字符串而不是字节。

如果子进程成功退出，则 close 方法返回 None；如果出现错误，则返回子进程的返回代码。在 POSIX 系统上，如果返回代码为正，则表示进程的返回值左移一个字节。如果返回代码为负，则进程由返回代码的负值给出的信号终止。（例如，如果子进程被终止，则返回值可能是 - signal.SIGKILL。）在 Windows 系统上，返回值包含来自子进程的有符号整数返回代码。

在 Unix 上，如果 close 方法结果（退出状态）不为 None，则可以使用 waitstatus_to_exitcode() 将其转换为退出代码。在 Windows 上，close 方法结果直接是退出代码（或 None）。

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

可用性：非 Emscripten，非 WASI。

注意

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

包装 posix_spawn() C 库 API 以供 Python 使用。

大多数用户应该使用 subprocess.run() 而不是 posix_spawn()。

仅限位置参数 path、args 和 env 类似于 execve()。

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

这些元组对应于 C 库 posix_spawn_file_actions_addopen()、posix_spawn_file_actions_addclose() 和 posix_spawn_file_actions_adddup2() API 调用，用于准备 posix_spawn() 调用本身。

setpgroup 参数会将子进程的进程组设置为指定的值。如果指定的值为 0，则子进程的进程组 ID 将与其进程 ID 相同。如果未设置 setpgroup 的值，则子进程将继承父进程的进程组 ID。此参数对应于 C 库 POSIX_SPAWN_SETPGROUP 标志。

如果 resetids 参数为 True，它会将子进程的有效 UID 和 GID 重置为父进程的真实 UID 和 GID。如果参数为 False，则子进程保留父进程的有效 UID 和 GID。无论哪种情况，如果在可执行文件上启用了设置用户 ID 和设置组 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 版中添加。

可用性：Unix，非 Emscripten，非 WASI。

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)¶

包装 posix_spawnp() C 库 API 以供 Python 使用。

与 posix_spawn() 类似，不同之处在于系统在 PATH 环境变量指定的目录列表中搜索 *可执行*文件（与 execvp(3) 相同）。

引发带有参数 path、argv 和 env 的审计事件 os.posix_spawn。

在 3.8 版中添加。

可用性：POSIX，而非 Emscripten，也非 WASI。

请参阅 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，非 Emscripten，非 WASI。

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，不支持 Emscripten 和 WASI。

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 资源管理器中双击文件，或在交互式命令行中将文件名作为参数提供给 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 上，返回值是在运行 command 后系统 shell 返回的值。 shell 由 Windows 环境变量 COMSPEC 给出：它通常是 cmd.exe，它返回运行的命令的退出状态；在使用非原生 shell 的系统上，请查阅你的 shell 文档。

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

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

引发带有参数 command 的审计事件 os.system。

可用性：Unix、Windows，不支持 Emscripten 和 WASI。

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，非 Emscripten，非 WASI。

另请参阅

下面记录的其他 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，非 Emscripten，非 WASI。

注意

此函数在 macOS 上不可用。

3.3 版新增。

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，不支持 Emscripten 和 WASI。

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

os.wait3(options)¶

与 waitpid() 类似，但不提供进程 ID 参数，并返回一个包含子进程 ID、退出状态指示和资源使用信息的 3 元素元组。有关资源使用信息的详细信息，请参阅 resource.getrusage()。options 参数与提供给 waitpid() 和 wait4() 的参数相同。

waitstatus_to_exitcode() 可用于将退出状态转换为退出代码。

可用性：Unix，非 Emscripten，非 WASI。

os.wait4(pid, options)¶

与 waitpid() 类似，但返回一个包含子进程 ID、退出状态指示和资源使用信息的 3 元素元组。有关资源使用信息的详细信息，请参阅 resource.getrusage()。wait4() 的参数与提供给 waitpid() 的参数相同。

waitstatus_to_exitcode() 可用于将退出状态转换为退出代码。

可用性：Unix，非 Emscripten，非 WASI。

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，非 Emscripten，非 WASI。

注意

P_PIDFD 仅在 Linux >= 5.4 上可用。

3.3 版新增。

3.9 版新增： P_PIDFD 常量。

os.WCONTINUED¶: waitpid()、wait3()、wait4() 和 waitid() 的此 options 标志会导致报告自上次报告后从作业控制停止状态继续的子进程。

可用性：Unix，非 Emscripten，非 WASI。

os.WEXITED¶

waitid() 的此 options 标志会导致报告已终止的子进程。

其他 wait* 函数始终会报告已终止的子进程，因此此选项不适用于它们。

可用性：Unix，非 Emscripten，非 WASI。

3.3 版新增。

os.WSTOPPED¶

waitid() 的此 options 标志会导致报告因传递信号而停止的子进程。

此选项不适用于其他 wait* 函数。

可用性：Unix，非 Emscripten，非 WASI。

3.3 版新增。

os.WUNTRACED¶

waitpid()、wait3() 和 wait4() 的此 options 标志还会导致报告已停止但自停止后未报告其当前状态的子进程。

此选项不适用于 waitid()。

可用性：Unix，非 Emscripten，非 WASI。

os.WNOHANG¶: 如果当前没有可用的子进程状态，此 options 标志会导致 waitpid()、wait3()、wait4() 和 waitid() 立即返回。

可用性：Unix，非 Emscripten，非 WASI。

os.WNOWAIT¶

此 options 标志会导致 waitid() 将子进程保留在可等待状态，以便可以使用后面的 wait*() 调用再次检索子进程状态信息。

此选项不适用于其他 wait* 函数。

可用性：Unix，非 Emscripten，非 WASI。

os.CLD_EXITED¶
os.CLD_KILLED¶
os.CLD_DUMPED¶
os.CLD_TRAPPED¶
os.CLD_STOPPED¶
os.CLD_CONTINUED¶: 这些是 waitid() 返回的结果中 si_code 的可能值。

可用性：Unix，非 Emscripten，非 WASI。

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，不支持 Emscripten 和 WASI。

在 3.9 版中添加。

以下函数将 system()、wait() 或 waitpid() 返回的进程状态代码作为参数。它们可用于确定进程的处置。

os.WCOREDUMP(status, /)¶

如果为进程生成了核心转储，则返回 True，否则返回 False。

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

可用性：Unix，非 Emscripten，非 WASI。

os.WIFCONTINUED(status)¶

如果已停止的子进程已通过传递 SIGCONT 恢复（如果进程已从作业控制停止中继续），则返回 True，否则返回 False。

请参阅 WCONTINUED 选项。

可用性：Unix，非 Emscripten，非 WASI。

os.WIFSTOPPED(status)¶

如果进程因传递信号而停止，则返回 True，否则返回 False。

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

可用性：Unix，非 Emscripten，非 WASI。

os.WIFSIGNALED(status)¶: 如果进程被信号终止，则返回 True，否则返回 False。

可用性：Unix，非 Emscripten，非 WASI。

os.WIFEXITED(status)¶: 如果进程通过调用 exit() 或 _exit() 或从 main() 返回而正常终止，则返回 True；否则返回 False。

可用性：Unix，非 Emscripten，非 WASI。

os.WEXITSTATUS(status)¶

返回进程退出状态。

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

可用性：Unix，非 Emscripten，非 WASI。

os.WSTOPSIG(status)¶

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

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

可用性：Unix，非 Emscripten，非 WASI。

os.WTERMSIG(status)¶

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

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

可用性：Unix，非 Emscripten，非 WASI。

调度程序接口¶

这些函数控制操作系统如何为进程分配 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¶: 此标志可以与任何其他调度策略进行“或”运算。当设置了此标志的进程 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 集。

杂项系统信息¶

os.confstr(name, /)¶

返回字符串值的系统配置值。 name 指定要检索的配置值；它可以是一个字符串，它是已定义系统值的名称；这些名称在许多标准（POSIX、Unix 95、Unix 98 和其他标准）中都有指定。一些平台也定义了额外的名称。主机操作系统已知的名称作为 confstr_names 字典的键给出。对于未包含在该映射中的配置变量，也接受为 name 传递一个整数。

如果未定义 name 指定的配置值，则返回 None。

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

可用性：Unix。

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

可用性：Unix。

os.cpu_count()¶

返回系统中逻辑 CPU 的数量。如果无法确定，则返回 None。

此数字不等于当前进程可以使用的逻辑 CPU 数量。 len(os.sched_getaffinity(0)) 获取当前进程的调用线程被限制的逻辑 CPU 数量。

3.4 版新增。

os.getloadavg()¶: 返回系统运行队列中进程数量在过去 1、5 和 15 分钟内的平均值，如果无法获取负载平均值，则引发 OSError。

可用性：Unix。

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` — 杂项操作系统接口¶