os — 杂项操作系统接口¶

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

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

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

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

另请参阅 区域设置编码。

Python UTF-8 模式¶

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 模式 和 文件系统编码和错误处理程序。

进程参数¶

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

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 版本新增。

文件和目录¶

在某些 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 模块中）

• stat.UF_NODUMP

• stat.UF_IMMUTABLE

• stat.UF_APPEND

• stat.UF_OPAQUE

• stat.UF_NOUNLINK

• stat.UF_COMPRESSED

• stat.UF_HIDDEN

• stat.SF_ARCHIVED

• stat.SF_IMMUTABLE

• stat.SF_APPEND

• stat.SF_NOUNLINK

• stat.SF_SNAPSHOT

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

引发带有参数 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 组合

• stat.S_ISUID

• stat.S_ISGID

• stat.S_ENFMT

• stat.S_ISVTX

• stat.S_IREAD

• stat.S_IWRITE

• stat.S_IEXEC

• stat.S_IRWXU

• stat.S_IRUSR

• stat.S_IWUSR

• stat.S_IXUSR

• stat.S_IRWXG

• stat.S_IRGRP

• stat.S_IWGRP

• stat.S_IXGRP

• stat.S_IRWXO

• stat.S_IROTH

• stat.S_IWOTH

• stat.S_IXOTH

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

注意

尽管 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 成员。