文件描述符的继承

Added in version 3.4.

每个文件描述符都有一个 "inheritable"（可继承）标志位，该标志位控制了文件描述符是否可以由子进程继承。从 Python 3.4 开始，由 Python 创建的文件描述符默认是不可继承的。

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

在 Windows 上，不可继承的句柄和文件描述符在子进程中是关闭的，但标准流（文件描述符 0、1 和 2 即标准输入、标准输出和标准错误）是始终继承的。如果使用 spawn* 函数，所有可继承的句柄和文件描述符都将被继承。如果使用 subprocess 模块，将关闭除标准流以外的所有文件描述符，并且仅当 close_fds 参数为 False 时才继承可继承的句柄。

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

  • os.get_inheritable(fd, /)
  • 获取指定文件描述符的“可继承”标志位（为布尔值）。
  • os.set_inheritable(fd, inheritable, /)
  • 设置指定文件描述符的“可继承”标志位。
  • os.get_handle_inheritable(handle, /)
  • 获取指定句柄的“可继承”标志位（为布尔值）。

Availability: Windows.

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

Availability: Windows.

文件和目录

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

  • 指定文件描述符为参数： 通常在 os 模块中提供给函数的 path 参数必须是表示文件路径的字符串，但是，某些函数现在可以接受其 path 参数为打开文件描述符，该函数将对描述符指向的文件进行操作。（对于 POSIX 系统，Python 将调用以 f 开头的函数变体（如调用 fchdir 而不是 chdir）。）

可以用 os.supports_fd 检查某个函数在你的平台上是否支持将 path 参数指定为文件描述符。如果不支持，使用该功能将抛出 NotImplementedError 异常。

如果该函数还支持 dir_fd 或 follow_symlinks 参数，那么用文件描述符作为 path 后就不能再指定上述参数了。

  • 基于目录描述符的相对路径： 如果 dir_fd 不是 None，它就应该是一个指向目录的文件描述符，这时待操作的 path 应该是相对路径，相对路径是相对于前述目录的。如果 path 是绝对路径，则 dir_fd 将被忽略。（对于 POSIX 系统，Python 将调用该函数的变体，变体以 at 结尾，可能以 f 开头（如调用 faccessat 而不是 access）。

可以用 os.supports_dir_fd 检查某个函数在你的平台上是否支持 dir_fd。如果不支持，使用该功能将抛出 NotImplementedError 异常。

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

可以用 os.supports_follow_symlinks 检查某个函数在你的平台上是否支持 follow_symlinks。如果不支持，使用该功能将抛出 NotImplementedError 异常。

  • os.access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)
  • 使用 实际用户ID/用户组ID 测试对 path 的访问。请注意，大多数测试操作将使用 有效用户ID/用户组ID，因此可以在 suid/sgid 环境中运用此例程，来测试调用用户是否具有对 path 的指定访问权限。mode 为 F_OK 时用于测试 path 是否存在，也可以对 R_OK、W_OK 和 X_OK 中的一个或多个进行“或”运算来测试指定权限。允许访问则返回 True，否则返回 False。更多信息请参见 Unix 手册页 access(2)) [https://manpages.debian.org/access(2)]。

本函数支持指定 基于目录描述符的相对路径 和 不跟踪符号链接。

如果 effective_ids 为 True，access() 将使用 有效用户ID/用户组ID 而非 实际用户ID/用户组ID 进行访问检查。您的平台可能不支持 effective_ids，您可以使用 os.supports_effective_ids 检查它是否可用。如果不可用，使用它时会抛出 NotImplementedError 异常。

备注

使用 access() 来检查用户是否具有某项权限（如打开文件的权限），然后再使用 open() 打开文件，这样做存在一个安全漏洞，因为用户可能会在检查和打开文件之间的时间里做其他操作。推荐使用 EAFP 技术。如:

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

最好写成:

  1. try:
  2.     fp = open("myfile")
  3. except PermissionError:
  4.     return "some default data"
  5. else:
  6.     with fp:
  7.         return fp.read()

备注

即使 access() 指示 I/O 操作会成功，但实际操作仍可能失败，尤其是对网络文件系统的操作，其权限语义可能超出常规的 POSIX 权限位模型。

在 3.3 版本发生变更: 添加 dir_fd、effective_ids 和 follow_symlinks 参数。

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

  • os.F_OK
  • os.R_OK
  • os.W_OK
  • os.X_OK
  • 作为 access() 的 mode 参数的可选值，分别测试 path 的存在性、可读性、可写性和可执行性。
  • os.chdir(path)
  • 将当前工作目录更改为 path。

本函数支持 指定文件描述符为参数。其中，描述符必须指向打开的目录，不能是打开的文件。

本函数可以抛出 OSError 及其子类的异常，如 FileNotFoundError、PermissionError 和 NotADirectoryError 异常。

引发一个 审计事件 os.chdir 并附带参数 path。

在 3.3 版本发生变更: 在某些平台上新增支持将 path 参数指定为文件描述符。

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

本函数支持 不跟踪符号链接。

引发一个 审计事件 os.chflags 并附带参数 path, flags。

Availability: Unix, not WASI.

在 3.3 版本发生变更: 增加了 follow_symlinks 形参。

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

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

备注

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

此函数在 WASI 是受限的，请参阅 WebAssembly 平台 了解详情。

引发一个 审计事件 os.chmod 并附带参数 path, mode, dir_fd。

在 3.3 版本发生变更: 添加了指定 path 为文件描述符的支持，以及 dir_fd 和 follow_symlinks 参数。

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

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

  • os.chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)
  • 将 path 的用户和组 ID 分别修改为数字形式的 uid 和 gid。若要使其中某个 ID 保持不变，请将其置为 -1。

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

参见更高阶的函数 shutil.chown()，除了数字 ID 之外，它也接受名称。

引发一个 审计事件 os.chown 并附带参数 path, uid, gid, dir_fd。

Availability: Unix.

此函数在 WASI 是受限的，请参阅 WebAssembly 平台 了解详情。

在 3.3 版本发生变更: 添加了指定 path 为文件描述符的支持，以及 dir_fd 和 follow_symlinks 参数。

在 3.6 版本发生变更: 支持 类路径对象。

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

Availability: Unix, not WASI, not Android.

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

  • os.fchdir(fd)
  • 将当前工作目录更改为文件描述符 fd 指向的目录。fd 必须指向打开的目录而非文件。从 Python 3.3 开始，它等效于 os.chdir(fd)。

引发一个 审计事件 os.chdir 并附带参数 path。

Availability: Unix.

  • os.getcwd()
  • 返回表示当前工作目录的字符串。
  • os.getcwdb()
  • 返回表示当前工作目录的字节串 (bytestring)。

在 3.8 版本发生变更: 在 Windows 上，本函数现在会使用 UTF-8 编码格式而不是 ANSI 代码页：请参看 PEP 529 [https://peps.python.org/pep-0529/] 了解具体原因。 该函数在 Windows 上不再被弃用。

  • os.lchflags(path, flags)
  • 将 path 的 flags 设置为其他由数字表示的 flags，与 chflags() 类似，但不跟踪符号链接。从 Python 3.3 开始，它等效于 os.chflags(path, flags, follow_symlinks=False)。

引发一个 审计事件 os.chflags 并附带参数 path, flags。

Availability: Unix, not WASI.

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

  • os.lchmod(path, mode)
  • 将 path 的权限状态修改为 mode。如果 path 是符号链接，则影响符号链接本身而非链接目标。可以参考 chmod() 中列出 mode 的可用值。从 Python 3.3 开始，它等效于 os.chmod(path, mode, follow_symlinks=False)。

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

引发一个 审计事件 os.chmod 并附带参数 path, mode, dir_fd。

Availability: Unix, Windows, not Linux, FreeBSD >= 1.3, NetBSD >= 1.3, not OpenBSD

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

在 3.13 版本发生变更: 增加 Windows 上的支持。

  • os.lchown(path, uid, gid)
  • 将 path 的用户和组 ID 分别修改为数字形式的 uid 和 gid，本函数不跟踪符号链接。从 Python 3.3 开始，它等效于 os.chown(path, uid, gid, follow_symlinks=False)。

引发一个 审计事件 os.chown 并附带参数 path, uid, gid, dir_fd。

Availability: Unix.

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

  • os.link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)
  • 创建一个指向 src 的硬链接，名为 dst。

本函数支持将 src_dir_fd 和 dst_dir_fd 中的一个或两个指定为 基于目录描述符的相对路径，支持 不跟踪符号链接。

引发一个 审计事件 os.link 并附带参数 src、dst、src_dir_fd、dst_dir_fd。

Availability: Unix, Windows.

在 3.2 版本发生变更: 添加了对 Windows 的支持。

在 3.3 版本发生变更: 增加了 src_dir_fd, dst_dir_fd 和 follow_symlinks 形参。

在 3.6 版本发生变更: 接受一个 类路径对象 作为 src 和 dst。

  • os.listdir(path='.')
  • 返回一个包含由 path 指定目录中条目名称组成的列表。 该列表按任意顺序排列，并且不包括特殊条目 '.' 和 '..'，即使它们存在于目录中。 如果有文件在调用此函数期间在被移除或添加到目录中，是否要包括该文件的名称并没有规定。

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

本函数也支持 指定文件描述符为参数，其中描述符必须指向目录。

引发一个 审计事件 os.listdir 并附带参数 path。

备注

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

参见

scandir() 函数返回目录内文件名的同时，也返回文件属性信息，它在某些具体情况下能提供更好的性能。

在 3.2 版本发生变更: path 变为可选参数。

在 3.3 版本发生变更: 新增支持将 path 参数指定为打开的文件描述符。

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

  • os.listdrives()
  • 返回一个包括Windows系统上驱动名称的列表。

驱动器名称通常的形式如 'C:\'。 并非每个驱动器名都会关联到特定的卷，有些驱动器名可能出于各种原因而无法访问，包括权限、网络连接或介质丢失等。 本函数不会测试可访问性。

如果在收集驱动器名时发生错误则可能引发 OSError。

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

Availability: Windows

Added in version 3.12.

  • os.listmounts(volume)
  • 返回一个包含 Windows 系统上指向卷的加载点的列表。

volume 必须表示为 GUID 路径，如 os.listvolumes() 所返回的值。 卷可能被挂载到多个位置也可能根本未挂载。 在后一种情况下，该列表将为空。 此函数不会返回没有关联到卷的挂载点。

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

如果卷未被识别或者如果在获取路径时发生错误则会引发 OSError。

引发一个 审计事件 os.listmounts 并附带参数 volume。

Availability: Windows

Added in version 3.12.

  • os.listvolumes()
  • 返回一个包含系统中的卷的列表。

卷通常被表示为一个 GUID 路径如 \?\Volume{xxxxxxxxxxxx-xxxxxxxx-xxxxxxxxxxxx}\。 文件通常可通过 GUID 路径来访问，如果权限允许的话。 但是，用户往往并不熟悉这种路径，所以此函数的推荐用法是使用 os.listmounts() 来获取加载点。

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

引发一个不带参数的 审计事件 os.listvolumes。

Availability: Windows

Added in version 3.12.

  • os.lstat(path, *, dir_fd=None)
  • 在给定的路径上执行 lstat() 系统调用的等价物。 类似于 stat()，但不会跟随符号链接。 返回一个 stat_result 对象。

在不支持符号链接的平台上，本函数是 stat() 的别名。

从 Python 3.3 起，此功能等价于 os.stat(path, dir_fd=dir_fd, follow_symlinks=False)。

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

参见

stat() 函数。

在 3.2 版本发生变更: 添加对 Windows 6.0 (Vista) 符号链接的支持。

在 3.3 版本发生变更: 添加了 dir_fd 参数。

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

在 3.8 版本发生变更: 目前在 Windows 上，遇到表示另一个路径的重解析点（即名称代理，包括符号链接和目录结点），本函数将打开它。其他种类的重解析点由 stat() 交由操作系统解析。

  • os.mkdir(path, mode=0o777, *, dir_fd=None)
  • 创建一个名为 path 的目录，应用以数字表示的权限模式 mode。

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

某些系统会忽略 mode。如果没有忽略它，那么将首先从它中减去当前的 umask 值。如果除最后 9 位（即 mode 八进制的最后 3 位）之外，还设置了其他位，则其他位的含义取决于各个平台。在某些平台上，它们会被忽略，应显式调用 chmod() 进行设置。

在 Windows 系统中，mode 值 0o700 被专门用于对新目录实施访问控制，使其只有当前用户和管理员才能访问。 其他值的 mode 将被忽略。

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

如果需要创建临时目录，请参阅 tempfile 模块中的 tempfile.mkdtemp() 函数。

引发一个 审计事件 os.mkdir 并附带参数 path, mode, dir_fd。

在 3.3 版本发生变更: 添加了 dir_fd 参数。

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

在 3.13 版本发生变更: Windows系统现在使用mode值0o700

  • os.makedirs(name, mode=0o777, exist_ok=False)
  • 递归目录创建函数。与 mkdir() 类似，但会自动创建到达最后一级目录所需要的中间目录。

mode 形参会被传递给 mkdir() 用来创建最后一级目录；请参阅 mkdir() 的说明 了解其解读方式。 要设置任何新建父目录的权限你可以在唤起 makedirs() 之前设置掩码。 现有父目录的文件权限不会被更改。

如果 exist_ok 为 False (默认值)，则如果目标目录已存在将会引发 FileExistsError。

备注

如果要创建的路径元素包含 pardir (如 UNIX 系统中的 "..") makedirs() 将无法明确目标。

本函数能正确处理 UNC 路径。

引发一个 审计事件 os.mkdir 并附带参数 path, mode, dir_fd。

在 3.2 版本发生变更: 增加了 exist_ok 形参。

在 3.4.1 版本发生变更: 在 Python 3.4.1 以前，如果 exist_ok 为 True，且目录已存在，且 mode 与现有目录的权限不匹配，makedirs() 仍会抛出错误。由于无法安全地实现此行为，因此在 Python 3.4.1 中将该行为删除。请参阅 bpo-21082 [https://bugs.python.org/issue?@action=redirect&bpo=21082]。

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

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

  • os.mkfifo(path, mode=0o666, *, dir_fd=None)
  • 创建一个名为 path 的 FIFO（命名管道，一种先进先出队列），具有以数字表示的权限状态 mode。将从 mode 中首先减去当前的 umask 值。

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

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

Availability: Unix, not WASI.

在 3.3 版本发生变更: 添加了 dir_fd 参数。

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

  • os.mknod(path, mode=0o600, device=0, *, dir_fd=None)
  • 创建一个名为 path 的文件系统节点（文件，设备专用文件或命名管道）。mode 指定权限和节点类型，方法是将权限与下列节点类型 stat.S_IFREG、stat.S_IFCHR、stat.S_IFBLK 和 stat.S_IFIFO 之一（按位或）组合（这些常量可以在 stat 模块中找到）。对于 stat.S_IFCHR 和 stat.S_IFBLK，device 参数指定了新创建的设备专用文件（可能会用到 os.makedev()），否则该参数将被忽略。

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

Availability: Unix, not WASI.

在 3.3 版本发生变更: 添加了 dir_fd 参数。

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

  • os.major(device, /)
  • 根据原始设备编号提取设备主编号（通常为来自 stat 的 st_dev 或 st_rdev 字段）。
  • os.minor(device, /)
  • 根据原始设备编号提取设备次编号（通常为来自 stat 的 st_dev 或 st_rdev 字段）。
  • os.makedev(major, minor, /)
  • 将主设备号和次设备号组合成原始设备号。
  • os.pathconf(path, name)
  • 返回所给名称的文件有关的系统配置信息。name 指定要查找的配置名称，它可以是字符串，是一个系统已定义的名称，这些名称定义在不同标准（POSIX.1，Unix 95，Unix 98 等）中。一些平台还定义了额外的其他名称。当前操作系统已定义的名称在 pathconf_names 字典中给出。对于未包含在该映射中的配置名称，也可以传递一个整数作为 name。

如果 name 是一个字符串且不是已定义的名称，将抛出 ValueError 异常。如果当前系统不支持 name 指定的配置名称，即使该名称存在于 pathconf_names，也会抛出 OSError 异常，错误码为 errno.EINVAL。

本函数支持 指定文件描述符为参数。

Availability: Unix.

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

  • os.pathconf_names
  • 字典，表示映射关系，为 pathconf() 和 fpathconf() 可接受名称与操作系统为这些名称定义的整数值之间的映射。这可用于判断系统已定义了哪些名称。

Availability: Unix.

  • os.readlink(path, *, dir_fd=None)
  • 返回一个字符串，为符号链接指向的实际路径。其结果可以是绝对或相对路径。如果是相对路径，则可用 os.path.join(os.path.dirname(path), result) 转换为绝对路径。

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

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

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

Availability: Unix, Windows.

在 3.2 版本发生变更: 添加对 Windows 6.0 (Vista) 符号链接的支持。

在 3.3 版本发生变更: 添加了 dir_fd 参数。

在 3.6 版本发生变更: 在 Unix 上可以接受一个 类路径对象。

在 3.8 版本发生变更: 在 Windows 上接受 类路径对象 和字节对象。

增加了对目录链接的支持，且返回值改为了“替换路径”的形式（通常带有 \?\ 前缀），而不是先前那样返回可选的 "print name" 字段。

  • os.remove(path, *, dir_fd=None)
  • 移除（删除）文件 path。 如果 path 是目录，则会引发 OSError。 请使用 rmdir() 来移除目录。 如果文件不存在，则会引发 FileNotFoundError。

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

在 Windows 上，尝试删除正在使用的文件会抛出异常。而在 Unix 上，虽然该文件的条目会被删除，但分配给文件的存储空间仍然不可用，直到原始文件不再使用为止。

本函数在语义上与 unlink() 相同。

引发一个 审计事件 os.remove 并附带参数 path, dir_fd。

在 3.3 版本发生变更: 添加了 dir_fd 参数。

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

  • os.removedirs(name)
  • 递归删除目录。工作方式类似于 rmdir()，不同之处在于，如果成功删除了末尾一级目录，removedirs() 会尝试依次删除 path 中提到的每个父目录，直到抛出错误为止（但该错误会被忽略，因为这通常表示父目录不是空目录）。例如，os.removedirs('foo/bar/baz') 将首先删除目录 'foo/bar/baz'，然后如果 'foo/bar' 和 'foo' 为空，则继续删除它们。如果无法成功删除末尾一级目录，则抛出 OSError 异常。

引发一个 审计事件 os.remove 并附带参数 path, dir_fd。

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

  • os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
  • 将文件或目录 src 重命名为 dst。如果 dst 已存在，则下列情况下将会操作失败，并抛出 OSError 的子类：

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

在 Unix 上，如果 src 是文件而 dst 是目录，将抛出 IsADirectoryError 异常，反之则抛出 NotADirectoryError 异常。如果两者都是目录且 dst 为空，则 dst 将被静默替换。如果 dst 是非空目录，则抛出 OSError 异常。如果两者都是文件，则在用户具有权限的情况下，将对 dst 进行静默替换。如果 src 和 dst 在不同的文件系统上，则本操作在某些 Unix 分支上可能会失败。如果成功，重命名操作将是一个原子操作（这是 POSIX 的要求）。

本函数支持将 src_dir_fd 和 dst_dir_fd 中的一个或两个指定为 基于目录描述符的相对路径。

如果需要在不同平台上都能替换目标，请使用 replace()。

引发一个 审计事件 os.rename 并附带参数 src, dst, src_dir_fd, dst_dir_fd。

在 3.3 版本发生变更: 增加了 src_dir_fd 和 dst_dir_fd 形参。

在 3.6 版本发生变更: 接受一个 类路径对象 作为 src 和 dst。

  • os.renames(old, new)
  • 递归重命名目录或文件。工作方式类似 rename()，除了会首先创建新路径所需的中间目录。重命名后，将调用 removedirs() 删除旧路径中不需要的目录。

备注

如果用户没有权限删除末级的目录或文件，则本函数可能会无法建立新的目录结构。

引发一个 审计事件 os.rename 并附带参数 src, dst, src_dir_fd, dst_dir_fd。

在 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 中的一个或两个指定为 基于目录描述符的相对路径。

引发一个 审计事件 os.rename 并附带参数 src, dst, src_dir_fd, dst_dir_fd。

Added in version 3.3.

在 3.6 版本发生变更: 接受一个 类路径对象 作为 src 和 dst。

  • os.rmdir(path, *, dir_fd=None)
  • 移除（删除）目录 path。 如果目录不存在或不为空，则会分别引发 FileNotFoundError 或 OSError。 要移除整个目录树，可以使用 shutil.rmtree()。

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

引发一个 审计事件 os.rmdir 并附带参数 path, dir_fd。

在 3.3 版本发生变更: 添加了 dir_fd 参数。

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

  • os.scandir(path='.')
  • 返回一个 os.DirEntry 对象的迭代器，它们对应于由 path 指定目录中的条目。 这些条目会以任意顺序生成，并且不包括特殊条目 '.' 和 '..'。 如果有文件在迭代器创建之后在目录中被移除或添加，是否要包括该文件对应的条目并没有规定。

如果需要文件类型或文件属性信息，使用 scandir() 代替 listdir() 可以大大提高这部分代码的性能，因为如果操作系统在扫描目录时返回的是 os.DirEntry 对象，则该对象包含了这些信息。所有 os.DirEntry 的方法都可能执行一次系统调用，但是 is_dir() 和 is_file() 通常只在有符号链接时才执行一次系统调用。os.DirEntry.stat() 在 Unix 上始终需要一次系统调用，而在 Windows 上只在有符号链接时才需要。

path 可以是 类路径对象。如果 path 是（直接传入或通过 PathLike 接口间接传入的） bytes 类型，那么每个 os.DirEntry 的 name 和 path 属性将是 bytes 类型，其他情况下是 str 类型。

本函数也支持 指定文件描述符为参数，其中描述符必须指向目录。

引发一个 审计事件 os.scandir 并附带参数 path。

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

  • scandir.close()
  • 关闭迭代器并释放占用的资源。

当迭代器迭代完毕，或垃圾回收，或迭代过程出错时，将自动调用本方法。但仍建议显式调用它或使用 with 语句。

Added in version 3.6.

下面的例子演示了 scandir() 的简单用法，用来显示给定 path 中所有不以 '.' 开头的文件（不包括目录）。entry.is_file() 通常不会增加一次额外的系统调用:

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

备注

在基于 Unix 的系统上，scandir() 使用系统的 opendir() [https://pubs.opengroup.org/onlinepubs/009695399/functions/opendir.html] 和 readdir() [https://pubs.opengroup.org/onlinepubs/009695399/functions/readdir_r.html] 函数。 在 Windows 上，它使用 Win32 FindFirstFileW.aspx) [https://msdn.microsoft.com/en-us/library/windows/desktop/aa364418(v=vs.85).aspx] 和 FindNextFileW.aspx) [https://msdn.microsoft.com/en-us/library/windows/desktop/aa364428(v=vs.85).aspx] 函数。

Added in version 3.5.

在 3.6 版本发生变更: 增加了对 context manager 协议和 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() 解码 byte 类型的文件名。

  • 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() 解码 byte 类型的文件名。

  • inode()
  • 返回本条目的索引节点号 (inode number)。

这一结果是缓存在 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() 来获取更新信息。

Added in version 3.12.

  • stat(*, follow_symlinks=True)
  • 返回本条目对应的 stat_result 对象。本方法默认会跟踪符号链接，要获取符号链接本身的 stat，请添加 follow_symlinks=False 参数。

在 Unix 上，本方法需要一次系统调用。在 Windows 上，仅在 follow_symlinks 为 True 且该条目是一个重解析点（如符号链接或目录结点）时，才需要一次系统调用。

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

这一结果是缓存在 os.DirEntry 对象中的，且 follow_symlinks 为 True 和 False 时的缓存是分开的。请调用 os.stat() 来获取最新信息。

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

Added in version 3.5.

在 3.6 版本发生变更: 添加了对 PathLike 接口的支持。在 Windows 上添加了对 bytes 类型路径的支持。

在 3.12 版本发生变更: 统计结果的 st_ctime 属性在 Windows 上已被弃用。 文件创建时间可通过 st_birthtime 来访问，在未来 st_ctime 可能会改为返回零或元数据的修改时间，如果可用的话。

  • os.stat(path, *, dir_fd=None, follow_symlinks=True)
  • 获取文件或文件描述符的状态。在所给路径上执行等效于 stat() 系统调用的操作。path 可以是字符串类型，或（直接传入或通过 PathLike 接口间接传入的） bytes 类型，或打开的文件描述符。返回一个 stat_result 对象。

本函数默认会跟踪符号链接，要获取符号链接本身的 stat，请添加 follow_symlinks=False 参数，或使用 lstat()。

本函数支持 指定文件描述符为参数 和 不跟踪符号链接。

在 Windows 上，传入 follow_symlinks=False 将禁用所有名称代理重解析点，其中包括符号链接和目录结点。其他类型的重解析点将直接打开，比如不像链接的或系统无法跟踪的重解析点。当多个链接形成一个链时，本方法可能会返回原始链接的 stat，无法完整遍历到非链接的对象。在这种情况下，要获取最终路径的 stat，请使用 os.path.realpath() 函数尽可能地解析路径，并在解析结果上调用 lstat()。这不适用于空链接或交接点，否则会抛出异常。

示例:

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

参见

fstat() 和 lstat() 函数。

在 3.3 版本发生变更: 增加了 dir_fd 和 follow_symlinks 形参，用于指定一个文件描述符而不是路径。

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

在 3.8 版本发生变更: 在 Windows 上，本方法将跟踪系统能解析的所有重解析点，并且传入 follow_symlinks=False 会停止跟踪所有名称代理重解析点。现在，如果操作系统遇到无法跟踪的重解析点，stat 将返回原始路径的信息，就像已指定 follow_symlinks=False 一样，而不会抛出异常。

  • class os.stat_result
  • 对象的属性大致对应于 stat 结构体的成员。 它将被用作 os.stat(), os.fstat() 和 os.lstat() 的输出结果。

属性：

  • st_mode

  • 文件模式：包括文件类型和文件模式位（即权限位）。

  • st_ino

  • 与平台有关，但如果不为零，则根据 st_dev 值唯一地标识文件。通常：

  • st_dev

  • 该文件所在设备的标识符。

  • st_nlink

  • 硬链接的数量。

  • st_uid

  • 文件所有者的用户 ID。

  • st_gid

  • 文件所有者的用户组 ID。

  • st_size

  • 文件大小（以字节为单位），文件可以是常规文件或符号链接。符号链接的大小是它包含的路径的长度，不包括末尾的空字节。

时间戳：

  • st_atime

  • 最近的访问时间，以秒为单位。

  • st_mtime

  • 最近的修改时间，以秒为单位。

  • st_ctime

  • 以秒数表示的元数据最近更改的时间。

在 3.12 版本发生变更: st_ctime 在 Windows 上已被弃用。 请使用 st_birthtime 获取文件创建时间。 在未来，st_ctime 将包含最近的元数据修改时间，与其他平台一样。

  • st_atime_ns
  • 最近的访问时间，以纳秒表示，为整数。

Added in version 3.3.

  • st_mtime_ns
  • 最近的修改时间，以纳秒表示，为整数。

Added in version 3.3.

  • st_ctime_ns
  • 最近的元数据修改时间，表示为一个以纳秒为单位的整数。

Added in version 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。

Added in version 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_* 常量。

Added in version 3.5.

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

为了向下兼容，stat_result 实例还可以作为至少包含 10 个整数的元组来访问以提供 stat 结构体中最重要（且可移植）的成员，其顺序为 st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime。 某些实现还可能在末尾添加更多条目。 为了与旧版 Python 兼容，以元组形式访问 stat_result 将始终返回整数。

在 3.5 版本发生变更: 在 Windows 上，如果可用，会返回文件索引作为 st_ino 的值。

在 3.7 版本发生变更: 在 Solaris 及其衍生版本上添加了 st_fstype 成员。

在 3.8 版本发生变更: 在 Windows 上添加了 st_reparse_tag 成员。

在 3.8 版本发生变更: 在 Windows 上，st_mode 成员现在可以根据需要将特殊文件标识为 S_IFCHR、S_IFIFO 或 S_IFBLK。

在 3.12 版本发生变更: 在 Windows 上，st_ctime 已被弃用。 最终，它将包含元数据的最后修改时间，以与其他平台保持一致，但目前仍包含创建时间。 请使用 st_birthtime 来获取创建时间。

在 Windows 上，现在 st_ino 最多可为 128 比特位，具体取决于文件系统。 在之前它不会超过 64 比特位，更长的文件标识符会被强制缩减。

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

在 Windows 上增加了 st_birthtime 成员。

  • os.statvfs(path)
  • 在给定的路径上执行 statvfs() 系统调用。 返回值是一个对象，其属性描述了所给路径上的文件系统，并且与 statvfs 结构体的成员相对应，即: f_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax, f_fsid。

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

为基于 GNU/glibc 的系统还定义了额外的模块级常量。它们是 ST_NODEV （禁止访问设备专用文件），ST_NOEXEC （禁止执行程序），ST_SYNCHRONOUS （写入后立即同步），ST_MANDLOCK （允许文件系统上的强制锁定），ST_WRITE （写入文件/目录/符号链接），ST_APPEND （仅追加文件），ST_IMMUTABLE （不可变文件），ST_NOATIME （不更新访问时间），ST_NODIRATIME （不更新目录访问时间），ST_RELATIME （相对于 mtime/ctime 更新访问时间）。

本函数支持 指定文件描述符为参数。

Availability: Unix.

在 3.2 版本发生变更: 添加了 ST_RDONLY 和 ST_NOSUID 常量。

在 3.3 版本发生变更: 新增支持将 path 参数指定为打开的文件描述符。

在 3.4 版本发生变更: 添加了 ST_NODEV、ST_NOEXEC、ST_SYNCHRONOUS、ST_MANDLOCK、ST_WRITE、ST_APPEND、ST_IMMUTABLE、ST_NOATIME、ST_NODIRATIME 和 ST_RELATIME 常量。

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

在 3.7 版本发生变更: 增加了 f_fsid 属性。

  • os.supports_dir_fd
  • 一个 set 对象，指示 os 模块中的哪些函数接受一个打开的文件描述符作为 dir_fd 参数。不同平台提供的功能不同，且 Python 用于实现 dir_fd 参数的底层函数并非在 Python 支持的所有平台上都可用。考虑到一致性，支持 dir_fd 的函数始终允许指定描述符，但如果在底层不支持时调用了该函数，则会抛出异常。（在所有平台上始终支持将 dir_fd 指定为 None。）

要检查某个函数是否接受打开的文件描述符作为 dir_fd 参数，请在 supports_dir_fd 前使用 in 运算符。例如，如果 os.stat() 在当前平台上接受打开的文件描述符作为 dir_fd 参数，则此表达式的计算结果为 True:

  1. os.stat in os.supports_dir_fd

目前 dir_fd 参数仅在 Unix 平台上有效，在 Windows 上均无效。

Added in version 3.3.

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

如果当前平台上的 os.access() 支持 effective_ids=True，则此表达式的计算结果为 True:

  1. os.access in os.supports_effective_ids

目前仅 Unix 平台支持 effective_ids，Windows 不支持。

Added in version 3.3.

  • os.supports_fd
  • 一个 set 对象，指示在当前平台上 os 模块中的哪些函数接受一个打开的文件描述符作为 path 参数。不同平台提供的功能不同，且 Python 所使用到的底层函数（用于实现接受描述符作为 path）并非在 Python 支持的所有平台上都可用。

要判断某个函数是否接受打开的文件描述符作为 path 参数，请在 supports_fd 前使用 in 运算符。例如，如果 os.chdir() 在当前平台上接受打开的文件描述符作为 path 参数，则此表达式的计算结果为 True:

  1. os.chdir in os.supports_fd

Added in version 3.3.

  • os.supports_follow_symlinks
  • 一个 set 对象，指示在当前平台上 os 模块中的哪些函数的 follow_symlinks 参数可指定为 False。不同平台提供的功能不同，且 Python 用于实现 follow_symlinks 的底层函数并非在 Python 支持的所有平台上都可用。考虑到一致性，支持 follow_symlinks 的函数始终允许将其指定为 False，但如果在底层不支持时调用了该函数，则会抛出异常。（在所有平台上始终支持将 follow_symlinks 指定为 True。）

要检查某个函数的 follow_symlinks 参数是否可以指定为 False，请在 supports_follow_symlinks 前使用 in 运算符。例如，如果在当前平台上调用 os.stat() 时可以指定 follow_symlinks=False，则此表达式的计算结果为 True:

  1. os.stat in os.supports_follow_symlinks

Added in version 3.3.

  • os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)
  • 创建一个指向 src 的符号链接，名为 dst。

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

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

备注

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

当本函数由非特权账户调用时，抛出 OSError 异常。

引发一个 审计事件 os.symlink 并附带参数 src, dst, dir_fd。

Availability: Unix, Windows.

此函数在 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()
  • 强制将所有内容写入磁盘。

Availability: Unix.

Added in version 3.3.

  • os.truncate(path, length)
  • 截断 path 对应的文件，以使其最大为 length 字节。

本函数支持 指定文件描述符为参数。

引发一个 审计事件 os.truncate 并附带参数 path, length。

Availability: Unix, Windows.

Added in version 3.3.

在 3.5 版本发生变更: 添加了 Windows 支持

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

  • os.unlink(path, *, dir_fd=None)
  • 移除（删除）文件 path。该函数在语义上与 remove() 相同，unlink 是其传统的 Unix 名称。请参阅 remove() 的文档以获取更多信息。

引发一个 审计事件 os.remove 并附带参数 path, dir_fd。

在 3.3 版本发生变更: 添加了 dir_fd 参数。

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

  • os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)
  • 设置文件 path 的访问时间和修改时间。

utime() 有 times 和 ns 两个可选参数，它们指定了设置给 path 的时间，用法如下：

  • 如果指定 ns，它必须是一个 (atime_ns, mtime_ns) 形式的二元组，其中每个成员都是一个表示纳秒的整数。

  • 如果 times 不为 None，则它必须是 (atime, mtime) 形式的二元组，其中每个成员都是一个表示秒的 int 或 float。

  • 如果 times 为 None 且未指定 ns，则相当于指定 ns=(atime_ns, mtime_ns)，其中两个时间均为当前时间。

同时为 times 和 ns 指定元组会出错。

请注意你在此处设置的确切时间可能不会被后续的 stat() 调用所返回，具体取决于你的操作系统记录访问和修改时间的分辨率；请参阅 stat()。 保留准确时间的最佳方式是使用来自于将 ns 形参设为 utime() 的 os.stat() 结果对象的 st_atime_ns 和 st_mtime_ns 字段。

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

引发一个 审计事件 os.utime 并附带参数 path, times, ns, dir_fd。

在 3.3 版本发生变更: 新增支持将 path 参数指定为打开的文件描述符，以及支持 dir_fd、follow_symlinks 和 ns 参数。

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

  • os.walk(top, topdown=True, onerror=None, followlinks=False)
  • 生成目录树中的文件名，方式是按上->下或下->上顺序浏览目录树。对于以 top 为根的目录树中的每个目录（包括 top 本身），它都会生成一个三元组 (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 对 walk 的行为没有影响，因为在自下而上模式中，dirnames 中的目录是在 dirpath 本身之前生成的。

默认将忽略 scandir() 调用中的错误。如果指定了可选参数 onerror，它应该是一个函数。出错时它会被调用，参数是一个 OSError 实例。它可以报告错误然后继续遍历，或者抛出异常然后中止遍历。注意，可以从异常对象的 filename 属性中获取出错的文件名。

walk() 默认不会递归进指向目录的符号链接。可以在支持符号链接的系统上将 followlinks 设置为 True，以访问符号链接指向的目录。

备注

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

备注

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

下面的示例遍历起始目录内所有子目录，打印每个目录内的文件占用的字节数，CVS 子目录不会被遍历:

  1. import os
  2. from os.path import join, getsize
  3. for root, dirs, files in os.walk('python/Lib/email'):
  4.     print(root, "consumes", end=" ")
  5.     print(sum(getsize(join(root, name)) for name in files), end=" ")
  6.     print("bytes in", len(files), "non-directory files")
  7.     if 'CVS' in dirs:
  8.         dirs.remove('CVS')  # don't visit CVS directories

在下一个示例（shutil.rmtree() 的简单实现）中，必须使树自下而上遍历，因为 rmdir() 只允许在目录为空时删除目录:

  1. # 删除可从 "top" 指定的目录进入的所有东西，
  2. # 假定其中没有符号连接。
  3. # 注意：这很危险！举例来说，如果 top == '/'，
  4. # 它可能删除你所有的硬盘文件。
  5. import os
  6. for root, dirs, files in os.walk(top, topdown=False):
  7.     for name in files:
  8.         os.remove(os.path.join(root, name))
  9.     for name in dirs:
  10.         os.rmdir(os.path.join(root, name))
  11. os.rmdir(top)

引发一个 审计事件 os.walk 并附带参数 top, topdown, onerror, followlinks。

在 3.5 版本发生变更: 现在，本函数调用的是 os.scandir() 而不是 os.listdir()，从而减少了调用 os.stat() 的次数而变得更快。

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

  • os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)
  • 本方法的行为与 walk() 完全一样，除了它产生的是 4 元组 (dirpath, dirnames, filenames, dirfd)，并且它支持 dir_fd。

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

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

备注

由于 fwalk() 会生成文件描述符，而它们仅在下一个迭代步骤前有效，因此如果要将描述符保留更久，则应复制它们（比如使用 dup()）。

下面的示例遍历起始目录内所有子目录，打印每个目录内的文件占用的字节数，CVS 子目录不会被遍历:

  1. import os
  2. for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
  3.     print(root, "consumes", end="")
  4.     print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
  5.           end="")
  6.     print("bytes in", len(files), "non-directory files")
  7.     if 'CVS' in dirs:
  8.         dirs.remove('CVS')  # 不访问 CVS 目录

在下一个示例中，必须使树自下而上遍历，因为 rmdir() 只允许在目录为空时删除目录:

  1. # 删除可从 "top" 指定的目录进入的所有东西，
  2. # 假定其中没有符号链接。
  3. # 注意：这很危险！举例来说，如果 top == '/'，
  4. # 它会删除你所有的磁盘文件。
  5. import os
  6. for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
  7.     for name in files:
  8.         os.unlink(name, dir_fd=rootfd)
  9.     for name in dirs:
  10.         os.rmdir(name, dir_fd=rootfd)

引发一个 审计事件 os.fwalk 并附带参数 top, topdown, onerror, follow_symlinks, dir_fd。

Availability: Unix.

Added in version 3.3.

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

在 3.7 版本发生变更: 添加了对 bytes 类型路径的支持。

  • os.memfd_create(name[, flags=os.MFD_CLOEXEC])
  • 创建一个匿名文件，返回指向该文件的文件描述符。flags 必须是系统上可用的 os.MFD_* 常量之一（或将它们按位“或”组合起来）。新文件描述符默认是 不可继承的。

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

Availability: Linux >= 3.17 with glibc >= 2.27.

Added in version 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()。

Availability: Linux >= 3.17 with glibc >= 2.27

MFD_HUGE* 旗标仅从 Linux 4.14 开始可用。

Added in version 3.8.

initval 是事件计数哭喊的初始值。 该初始值必须是一个 32 位无符号整数。 请注意虽然事件计数器是一个最大值为 264-2 的无符号 64 位整数但初始值仍被限制为 32 位无符号整数。

flags 可由 EFD_CLOEXEC 、 EFD_NONBLOCK 和 EFD_SEMAPHORE 组合而成。

如果设置了 EFD_SEMAPHORE，并且事件计数器非零，那么 eventfd_read() 将返回 1 并将计数器递减 1。

如果未设置 EFD_SEMAPHORE，并且事件计数器非零，那么 eventfd_read() 返回当前的事件计数器值，并将计数器重置为零。

如果事件计数器为 0，并且未设置 EFD_NONBLOCK，那么 eventfd_read() 会阻塞。

eventfd_write() 会递增事件计数器。如果写操作会让计数器的增量大于264-2，则写入会被阻止。

示例:

  1. import os
  2.  
  3. # 取值从 '1' 开始的信号量
  4. fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
  5. try:
  6.     # 获取信号量
  7.     v = os.eventfd_read(fd)
  8.     try:
  9.         do_work()
  10.     finally:
  11.         # 释放信号量
  12.         os.eventfd_write(fd, v)
  13. finally:
  14.     os.close(fd)

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.10.

  • os.eventfd_read(fd)
  • 从一个 eventfd() 文件描述符中读取数据，并返回一个 64 位无符号整数。该函数不会校验 fd 是否为 eventfd()。

Availability: Linux >= 2.6.27

Added in version 3.10.

  • os.eventfd_write(fd, value)
  • 向一个 eventfd() 文件描述符加入数据。value 必须是一个 64 位无符号整数。本函数不会校验 fd 是否为 eventfd()。

Availability: Linux >= 2.6.27

Added in version 3.10.

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

Availability: Linux >= 2.6.27

Added in version 3.10.

Availability: Linux >= 2.6.27

Added in version 3.10.

  • os.EFD_SEMAPHORE
  • 为从 eventfd() 文件描述符进行读取提供类似信号量的语法。 在读取时内部计数器将递减一。

Availability: Linux >= 2.6.30

Added in version 3.10.

计时器文件描述符

Added in version 3.13.

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

  • os.timerfd_create(clockid, /, *, flags=0)
  • 创建并返回一个计时器文件描述符 (timerfd)。

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

文件描述符的 read() 方法被调用时可附带大小为 8 的缓冲区。 如果计时器已到期一次或多次，read() 将返回以主机端序表示的到期次数，它可通过 int.from_bytes(x, byteorder=sys.byteorder) 转换为 int。

select() 和 poll() 可被用于等待直至计时器到期并且文件描述符为可读状态。

clockid 必须是一个有效的 时钟 ID，如 time 模块中所定义的：

如果 clockid 为 time.CLOCK_REALTIME，则将使用一个可设置的系统级实时时钟。 如果系统时钟发生改变，计时器设置将需要被更新。 要在系统时钟发生改变时取消计时器，请参阅 TFD_TIMER_CANCEL_ON_SET。

如果 clockid 为 time.CLOCK_MONOTONIC，将使用一个不可设置的单调递增时钟。 即使系统时钟发生改变，计时器设置也不会受影响。

如果 clockid 为 time.CLOCK_BOOTTIME，将与 time.CLOCK_MONOTONIC 相似，不同之处在于它还包括任何系统挂起的时间。

这个文件描述符的行为可以通过指定 flags 值来改变。 可以使用以下任意变量，可以使用按位 OR (| 运算符) 来进行组合：

如果未将 TFD_NONBLOCK 设为一个旗标，read() 将会阻塞直至计时器到期。 如果它被设为旗标，则 read() 不会阻塞，但是如果自从上次对 read 的调用以来尚未有一次到期，read() 将引发 OSError 并将 errno 设为 errno.EAGAIN。

TFD_CLOEXEC 总是会由 Python 自动设置。

该文件描述符在其不再需要时必须通过 os.close() 来关闭，否则文件描述符将被泄漏。

参见

timerfd_create(2)) [https://manpages.debian.org/timerfd_create(2)] 帮助页。

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

  • os.timerfd_settime(fd, /, *, flags=flags, initial=0.0, interval=0.0)
  • 修改一个计时器文件描述符的内部计时器。 此函数将操作与 timerfd_settime_ns() 相同的间隔计时器。

fd 必须是一个有效的计时器文件描述符。

该计时器的行为可以通过指定 flags 值来改变。 可以使用以下任意变量，可以使用按位 OR (| 运算符) 来进行组合：

该计时器可通过将 initial 设为零 (0) 来禁用。 如果 initial 大于零，计时器将被启用。 如果 initial 小于零，它将引发 OSError 异常并将 errno 设为 errno.EINVAL

在默认情况下计时器将在经过 initial 秒后启动。 （如果 initial 为零，计时器将立即启动。）

但是，如果设置了 TFD_TIMER_ABSTIME 旗标，计时器将在计时器时钟 (由 timerfd_create() 中的 clockid 设置) 达到 initial 秒时启动。

计时器的间隔时间是通过 interval float 设置的。 如果 interval 为零，计时器将只在初始到期时启动一次。 如果 interval 大于零，计时器将从上一次到期后每经过 interval 秒启动一次。 如果 interval 小于零，它将引发 OSError 并将 errno 设为 errno.EINVAL

如果 TFD_TIMER_CANCEL_ON_SET 旗标与 TFD_TIMER_ABSTIME 一起被设置并且用于此计时器的时钟为 time.CLOCK_REALTIME，则当实时计时器发生不连续改变时计时器将被标记为可取消的。 对描述符的读取将被取消并设置 ECANCELED 错误。

Linux 将以 UTC 来管理系统时钟。 夏令时调整是仅通过修改时差完成的而不会导致不连续的系统时钟改变。

下列事件会导致不连续的系统时钟变化：

  • settimeofday

  • clock_settime

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

根据此函数执行之前的计时器状态，返回一个二元组 (next_expiration, interval)。

参见

timerfd_create(2)) [https://manpages.debian.org/timerfd_create(2)], timerfd_settime(2)) [https://manpages.debian.org/timerfd_settime(2)], settimeofday(2)) [https://manpages.debian.org/settimeofday(2)], clock_settime(2)) [https://manpages.debian.org/clock_settime(2)] 以及 date(1)) [https://manpages.debian.org/date(1)]。

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

  • os.timerfd_settime_ns(fd, /, *, flags=0, initial=0, interval=0)
  • 与 timerfd_settime() 类似，但使用纳秒形式的时间。 此函数将操作与 timerfd_settime() 相同的间隔计时器。

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

  • os.timerfd_gettime(fd, /)
  • 返回一个浮点数形式的二元组 (next_expiration, interval)。

next_expiration 表示距离定时器下一次启动的相对时间，无论是否设置了 TFD_TIMER_ABSTIME 旗标。

interval 表示计时器的间隔。 如果为零，该计时器将只启动一次，即在经过了 next_expiration 秒之后。

参见

timerfd_gettime(2)) [https://manpages.debian.org/timerfd_gettime(2)]

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

  • os.timerfd_gettime_ns(fd, /)
  • 与 timerfd_gettime() 类似，但返回以纳秒为单位的时间。

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

  • os.TFD_CLOEXEC
  • 一个用于 timerfd_create() 函数的旗标，如果将 TFD_CLOEXEC 设为旗标，将为新的文件描述符设置 close-on-exec 旗标。

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

  • os.TFD_TIMER_ABSTIME
  • 一个用于 timerfd_settime() 和 timerfd_settime_ns() 函数的旗标。 如果设置了此旗标，initial 将被解读为计时器时钟上的一个绝对数值（即自 Unix 纪元开始的 UTC 秒数或纳秒数）。

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

Availability: Linux >= 2.6.27 with glibc >= 2.8

Added in version 3.13.

Linux 扩展属性

Added in version 3.3.

这些函数仅在 Linux 上可用。

  • os.getxattr(path, attribute, *, follow_symlinks=True)
  • 返回 path 的扩展文件系统属性 attribute 的值。attribute 可以是 bytes 或 str （直接传入或通过 PathLike 接口间接传入）。如果是 str，则使用文件系统编码来编码字符串。

本函数支持 指定文件描述符为参数 和 不跟踪符号链接。

引发一个 审计事件 os.getxattr 并附带参数 path, attribute。

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

  • os.listxattr(path=None, *, follow_symlinks=True)
  • 返回一个列表，包含 path 的所有扩展文件系统属性。列表中的属性都表示为字符串，它们是根据文件系统编码解码出来的。如果 path 为 None，则 listxattr() 将检查当前目录。

本函数支持 指定文件描述符为参数 和 不跟踪符号链接。

引发一个 审计事件 os.listxattr 并附带参数 path。

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

  • os.removexattr(path, attribute, *, follow_symlinks=True)
  • 移除 path 中的扩展文件系统属性 attribute。 attribute 应为字节串或字符串类型（通过 PathLike 接口直接或间接得到）。 若为字符串类型，则用 filesystem encoding and error handler 进行编码。

本函数支持 指定文件描述符为参数 和 不跟踪符号链接。

引发一个 审计事件 os.removexattr 并附带参数 path, attribute。

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

  • os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)
  • 将 path 的文件系统扩展属性 attribute 设为 value。 attribute 必须是一个字节串或字符串，不含 NUL（通过 PathLike 接口直接或间接得到）。 若为字符串，将用 filesystem encoding and error handler 进行编码。 flags 可以是 XATTR_REPLACE 或 XATTR_CREATE。 如果给出 XATTR_REPLACE 而属性不存在，则会触发 ENODATA。 如果给出了 XATTR_CREATE 而属性已存在，则不会创建属性并将触发 EEXISTS。

本函数支持 指定文件描述符为参数 和 不跟踪符号链接。

备注

Linux kernel 2.6.39 以下版本的一个 bug 导致在某些文件系统上，flags 参数会被忽略。

引发一个 审计事件 os.setxattr 并附带参数 path, attribute, value, flags。

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

  • os.XATTR_SIZE_MAX
  • 一条扩展属性的值的最大大小。在当前的 Linux 上是 64 KiB。
  • os.XATTR_CREATE
  • 这是 setxattr() 的 flags 参数的可取值，它表示该操作必须创建一个属性。
  • os.XATTR_REPLACE
  • 这是 setxattr() 的 flags 参数的可取值，它表示该操作必须替换现有属性。