os —- 多种操作系统接口

`os` —- 多种操作系统接口

源代码： Lib/os.py [https://github.com/python/cpython/tree/3.13/Lib/os.py]

本模块提供了一种使用与操作系统相关的功能的便捷式途径。如果你只是想读写一个文件，请参阅 open()，如果你想操作文件路径，请参阅 os.path 模块，如果你想读取通过命令行给出的所有文件中的所有行，请参阅 fileinput 模块。为了创建临时文件和目录，请参阅 tempfile 模块，对于高级文件和目录处理，请参阅 shutil 模块。

关于这些函数的适用性的说明：

Python中所有依赖于操作系统的内置模块的设计都是这样，只要不同的操作系统某一相同的功能可用，它就使用相同的接口。例如，函数 os.stat(path) 以相同的格式返回关于 path 的状态信息（该格式源于 POSIX 接口）。
特定于某一操作系统的扩展通过操作 os 模块也是可用的，但是使用它们当然是对可移植性的一种威胁。
所有接受路径或文件名的函数都同时支持字节串和字符串对象，并在返回路径或文件名时使用相应类型的对象作为结果。
在 VxWorks 系统上，os.popen, os.fork, os.execv 和 os.spawnp 都未支持。
在 WebAssembly 平台、Android 和 iOS 上，os 模块的很大一部分都不可用或具有不同的行为。与进程相关联的 API (例如 fork(), execve()) 和资源 (例如 nice()) 都不可用。其他诸如 getuid() 和 getpid() 等则为模拟或空盒。 WebAssembly 平台还缺少对信号 (例如 kill(), wait()) 的支持。

备注

如果使用无效或无法访问的文件名与路径，或者其他类型正确但操作系统不接受的参数，此模块的所有函数都抛出 OSError （或者它的子类）。

exception os.error
内建的 OSError 异常的一个别名。

os.name
导入的依赖特定操作系统的模块的名称。以下名称目前已注册: 'posix', 'nt', 'java'.

参见

sys.platform 具有更细的粒度。 os.uname() 将给出基于不同系统的版本信息。

platform 模块对系统的标识有更详细的检查。

文件名，命令行参数，以及环境变量。

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

filesystem encoding and error handler 是在 Python 启动时通过 PyConfig_Read() 函数来配置的：请参阅 PyConfig 的 filesystem_encoding 和 filesystem_errors 等成员。

在 3.1 版本发生变更: 在某些系统上，使用文件系统编码格式进行转换可能会失败。在这种情况下，Python 会使用 surrogateescape 编码错误处理器，这意味着不可解码的字节在解码时会被 Unicode 字符 U+DCxx 替换，并且这些字节在编码时又会再次被转换为原始字节。

文件系统编码器必须保证能成功解码所有 128 以内的字节。如果不能保证，API 函数可能触发 UnicodeError 。

另请参见 locale encoding。

Python UTF-8 模式

Added in version 3.7: 有关更多详细信息，请参阅 PEP 540 [https://peps.python.org/pep-0540/] 。

Python UTF-8 模式会忽略 locale encoding 并强制使用 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 编码格式。但是，它们默认仍将使用 strict 错误处理器因此试图在文本模式下打开二进制文件可能会引发异常而不是产生无意义的数据。

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

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

如果没有设置 PYTHONUTF8 环境变量，那么解释器默认使用当前的地区设置，除非当前地区识别为基于 ASCII 的传统地区（如 PYTHONCOERCECLOCALE 所述），并且 locale coercion 被禁用或失败。在这种传统地区，除非显式指明不要如此，解释器将默认启用 UTF-8 模式。

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

另请参阅在 Windows 中的 UTF-8 模式和 filesystem encoding and error handler。

参见

PEP 686 [https://peps.python.org/pep-0686/]
Python 3.15 将把 Python UTF-8 模式设为默认值。

进程参数

这些函数和数据项提供了操作当前进程和用户的信息。

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

Availability: Unix, not WASI.

os.environ
一个 mapping 对象，其中键值是代表进程环境的字符串。例如，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 [https://peps.python.org/pep-0584/] 的合并 (|) 和更新 (|=) 运算符。

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

environb 仅在 supports_bytes_environ 为 True 时可用。

Added in version 3.2.

在 3.9 版本发生变更: 已更新并支持了 PEP 584 [https://peps.python.org/pep-0584/] 的合并 (|) 和更新 (|=) 运算符。

os.chdir(path)
os.fchdir(fd)
os.getcwd()
以上函数请参阅文件和目录。

os.fsencode(filename)
将类似路径形式的 filename 编码为 filesystem encoding and error handler；原样返回 bytes。

fsdecode() 是此函数的逆向函数。

Added in version 3.2.

在 3.6 版本发生变更: 增加对实现了 os.PathLike 接口的对象的支持。

os.fsdecode(filename)
根据 filesystem encoding and error handler 来解码类似路径形式的 filename；原样返回 str。

fsencode() 是此函数的逆向函数。

Added in version 3.2.

在 3.6 版本发生变更: 增加对实现了 os.PathLike 接口的对象的支持。

os.fspath(path)
返回路径的文件系统表示。

如果传入的是 str 或 bytes 类型的字符串，将原样返回。否则 __fspath__() 将被调用，如果得到的是一个 str 或 bytes 类型的对象，那就返回这个值。其他所有情况则会抛出 TypeError 异常。

Added in version 3.6.

class os.PathLike
某些对象用于表示文件系统中的路径（如 pathlib.PurePath 对象），本类是这些对象的抽象基类。

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

Availability: Unix, Windows.

os.getenvb(key, default=None)
如果环境变量 key 存在则将其值作为字节串返回，如果不存在则返回 default。 key 必须为字节串。请注意由于 getenvb() 使用了 os.environb，因此 getenvb() 的映射同样也会在导入时被捕获，并且该函数可能无法反映未来的环境变化。

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

Availability: Unix.

Added in version 3.2.

os.get_exec_path(env=None)
返回将用于搜索可执行文件的目录列表，与在外壳程序中启动一个进程时相似。指定的 env 应为用于搜索 PATH 的环境变量字典。默认情况下，当 env 为 None 时，将会使用 environ 。

Added in version 3.2.

os.getegid()
返回当前进程的有效组ID。对应当前进程执行文件的 "set id" 位。

Availability: Unix, not WASI.

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

Availability: Unix, not WASI.

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

Availability: Unix.

该函数在 WASI 上为空代码段，请参阅 WebAssembly 平台了解详情。

os.getgrouplist(user, group, /)
返回 user 所属的组 ID 列表。如果 group 不在该列表中，它将被包括在内；通常，group 将会被指定为来自 user 的密码记录文件的组 ID 字段，因为在其他情况下该组 ID 有可能会被略去。

Availability: Unix, not WASI.

Added in version 3.3.

os.getgroups()
返回当前进程关联的附加组ID列表

Availability: Unix, not 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 的登录名。

Availability: Unix, Windows, not WASI.

os.getpgid(pid)
根据进程id pid 返回进程的组 ID 列表。如果 pid 为 0，则返回当前进程的进程组 ID 列表

Availability: Unix, not WASI.

os.getpgrp()
返回当时进程组的ID

Availability: Unix, not WASI.

os.getpid()
返回当前进程ID

该函数在 WASI 上为空代码段，请参阅 WebAssembly 平台了解详情。

os.getppid()
返回父进程ID。当父进程已经结束，在Unix中返回的ID是初始进程(1)中的一个，在Windows中仍然是同一个进程ID，该进程ID有可能已经被进行进程所占用。

Availability: 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 为 0 时（分别）表示调用的进程，调用进程的进程组或调用进程所属的真实用户 ID。

Availability: Unix, not WASI.

Added in version 3.3.

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

Availability: Unix, not WASI.

Added in version 3.3.

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

Availability: macOS

Added in version 3.12.

os.getresuid()
返回一个由 (ruid, euid, suid) 所组成的元组，分别表示当前进程的真实用户ID，有效用户ID和暂存用户ID。

Availability: Unix, not WASI.

Added in version 3.2.

os.getresgid()
返回一个由 (rgid, egid, sgid) 所组成的元组，分别表示当前进程的真实组ID，有效组ID和暂存组ID。

Availability: Unix, not WASI.

Added in version 3.2.

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

Availability: Unix.

该函数在 WASI 上为空代码段，请参阅 WebAssembly 平台了解详情。

os.initgroups(username, gid, /)
调用系统 initgroups()，使用指定用户所在的所有值来初始化组访问列表，包括指定的组ID。

Availability: Unix, not WASI, not Android.

Added in version 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() 的系统文档。

引发一个审计事件 os.putenv 并附带参数 key, value。

在 3.9 版本发生变更: 该函数现在总是可用。

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

Availability: Unix, not WASI, not Android.

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

Availability: Unix, not WASI, not Android.

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

Availability: Unix, not WASI, not Android.

os.setgroups(groups, /)
将 group 参数值设置为与当进程相关联的附加组ID列表。group 参数必须为一个序列，每个元素应为每个组的数字ID。该操作通常只适用于超级用户。

Availability: Unix, not WASI.

备注

在 macOS 中，groups 的长度不能超过系统定义的最大有效组 ID 数量，通常为 16。对于未返回与调用 setgroups() 产生的相同组列表的情况，请参阅 getgroups() 的文档。

os.setns(fd, nstype=0)
将当前线程与 Linux 命名空间重新关联。详情参见 setns(2)) [https://manpages.debian.org/setns(2)] 和 namespaces(7)) [https://manpages.debian.org/namespaces(7)] 手册页面。

如果 fd 是指向一个 procpid/ns/ 链接，setns() 会将调用线程与该链接所关联的命名空间重新关联起来，并且 nstype 可以设为某个 CLONE_NEW* 常量以便对操作施加约束 (0 表示没有任何约束)。

自 Linux 5.8 起，fd 可以是通过 pidfd_open() 获取的 PID 文件描述符。在这种情况下，setns() 会将调用线程重新关联到与 fd 引用的线程相同的一个或多个命名空间。位掩码 nstype 通常会结合一个或多个 CLONE_NEW* 常量，例如 setns(fd, os.CLONE_NEWUTS | os.CLONE_NEWPID)，其施加的任何约束限制仍然保留，调用者在未指定的命名空间中的成员资格保持不变。

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

此示例将线程与 init 进程的网络命名空间进行了重新关联:

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

Availability: Linux >= 3.0 with glibc >= 2.14.

Added in version 3.12.

参见

unshare() 函数。

os.setpgrp()
在系统调用 setpgrp() 和 setpgrp(0, 0) 中择一调用，具体取决于何种实现版本可用（如果任一实现存在的话）。请参阅 Unix 手册以了解语义。

Availability: Unix, not WASI.

os.setpgid(pid, pgrp, /)
使用系统调用 setpgid() 将 pid 对应进程的组 ID 设置为 pgrp。请参阅 Unix 手册以了解语义。

Availability: Unix, not 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；较小的优先级数值会更优先被调度。

Availability: Unix, not WASI.

Added in version 3.3.

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

Availability: Unix, not WASI, not Android.

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

Availability: Unix, not WASI, not Android.

Added in version 3.2.

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

Availability: Unix, not WASI, not Android.

Added in version 3.2.

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

Availability: Unix, not WASI, not Android.

os.getsid(pid, /)
调用系统调用 getsid()。其语义请参见 Unix 手册。

Availability: Unix, not WASI.

os.setsid()
调用系统调用 setsid()。其语义请参见 Unix 手册。

Availability: Unix, not WASI.

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

Availability: Unix, not WASI, not Android.

os.strerror(code, /)
根据 code 中的错误码返回错误消息。如果 strerror() 返回 NULL ，说明给出的是未知错误码，则会引发 ValueError。

os.supports_bytes_environ
如果操作系统上原生环境类型是字节型则为 True (例如在 Windows 上为 False)。

Added in version 3.2.

os.umask(mask, /)
设定当前数值掩码并返回之前的掩码。

该函数在 WASI 上为空代码段，请参阅 WebAssembly 平台了解详情。

os.uname()
返回当前操作系统的识别信息。返回值是一个有5个属性的对象：
- 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 上获取面向用户的操作系统名称和版本。

Availability: Unix.

在 3.3 版本发生变更: 返回结果的类型由元组变成一个类似元组的对象，同时具有命名的属性。

os.unsetenv(key, /)
取消设置（删除）名为 key 的环境变量。变量名的改变会影响由 os.system()，popen()，fork() 和 execv() 触发的子进程。

删除 os.environ 中的项目会自动转化为对 unsetenv() 的相应调用；然而，对 unsetenv() 的调用并不更新 os.environ ，所以实际上最好是删除 os.environ 的项目。

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

在 3.9 版本发生变更: 该函数现在总是可用，并且在 Windows 上也可用。

os.unshare(flags)
拆分进程执行上下文的部分内容，并将其移入新创建的命名空间中。请参阅 unshare(2)) [https://manpages.debian.org/unshare(2)] 手册页了解详情。 flags 参数是一个位掩码，它组合了零个或多个 CLONE_* 常量，用于指定执行上下文中的哪些部分应从现有关联中解除共享并移动到新的命名空间。如果 flags 参数为 0，则不会对调用方进程的执行上下文进行任何更改。

Availability: Linux >= 2.6.16.

Added in version 3.12.

参见

setns() 函数。

unshare() 函数的旗标，如果实现支持。访问 Linux 手册中的 unshare(2)) [https://manpages.debian.org/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

创建文件对象

这些函数创建新的 file objects 。（参见 open() 以获取打开文件描述符的相关信息。）

os.fdopen(fd, args, *kwargs)
返回打开文件描述符 fd 对应文件的对象。类似内建 open() 函数，二者接受同样的参数。不同之处在于 fdopen() 第一个参数应该为整数。

文件描述符操作

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

文件描述符是一些小的整数，对应于当前进程所打开的文件。例如，标准输入的文件描述符通常是0，标准输出是1，标准错误是2。之后被进程打开的文件的文件描述符会被依次指定为3，4，5等。“文件描述符”这个词有点误导性，在 Unix 平台中套接字和管道也被文件描述符所引用。

当需要时，可以用 fileno() 可以获得 file object 所对应的文件描述符。需要注意的是，直接使用文件描述符会绕过文件对象的方法，会忽略如数据内部缓冲等情况。

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 自偏移量 offset_src 起的位置拷贝 count 个字节到文件描述符 dst 自偏移量 offset_dst 起的位置。如果 offset_src 为 None，则从当前位置读取 src；相应地 offset_dst 也是如此。

在早于 5.3 版的 Linux 内核中，src 和 dst 指向的文件必须位于相同的文件系统中，否则会引发 OSError 并将 errno 设为 errno.EXDEV。

执行这种拷贝无需付出将数据从内核传输到用户空间再返回内核的额外耗费。此外，某些文件系统还可以实现进一步的优化，例如使用引用链接（即两个或多个共享指向相同写入时复制磁盘块的指针的 inode；支持的文件系统包括 btrfs 和 XFS）和服务器端拷贝（对于 NFS）。

此函数在两个文件描述符之间拷贝字节数据。文本选项，如编码格式和行结束符等将被忽略。

返回值是复制的字节的数目。这可能低于需求的数目。

备注

在 Linux 上，os.copy_file_range() 不应被用于从特殊的文件系统如 procfs 和 sysfs 复制特定范围的伪文件。因为已知的 Linux 内核问题它将总是不复制任何字节并返回 0 就像文件是空的一样。

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

Added in version 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）时，新的文件描述符是可继承的。

Availability: not WASI.

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

os.dup2(fd, fd2, inheritable=True)
把文件描述符 fd 复制为 fd2，必要时先关闭后者。返回 fd2。新的文件描述符默认是可继承的，除非在 inheritable 为 False 时，是不可继承的。

Availability: not WASI.

在 3.4 版本发生变更: 添加可选参数 inheritable。

在 3.7 版本发生变更: 成功时返回 fd2，以过去的版本中，总是返回 None。

os.fchmod(fd, mode)
将 fd 指定文件的权限状态修改为 mode。可以参考 chmod() 中列出 mode 的可用值。从Python 3.3开始，这相当于 os.chmod(fd, mode)。

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

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

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

Availability: Unix.

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

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

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

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

Availability: Unix.

os.fsync(fd)
强制将文件描述符 fd 指向的文件写入磁盘。在 Unix 上，这将调用原生 fsync() 函数；在 Windows 上，则是 MS _commit() 函数。

如果要写入的是缓冲区内的 Python 文件对象 f，请先执行 f.flush()，然后执行 os.fsync(f.fileno())，以确保与 f 关联的所有内部缓冲区都写入磁盘。

Availability: Unix, Windows.

os.ftruncate(fd, length, /)
截断文件描述符 fd 指向的文件，以使其最大为 length 字节。从 Python 3.3 开始，它等效于 os.truncate(fd, length)。

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

Availability: Unix, Windows.

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

os.get_blocking(fd, /)
获取文件描述符的阻塞模式：如果设置了 O_NONBLOCK 标志位，返回 False，如果该标志位被清除，返回 True。

参见 set_blocking() 和 socket.socket.setblocking()。

Availability: Unix, Windows.

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

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

Added in version 3.5.

在 3.12 版本发生变更: 增加了在Windows上对于管道的支持。

os.grantpt(fd, /)
允许访问与文件描述符 fd 所指向的主伪终端设备相关联的从伪终端设备。文件描述符 fd 在失败时不会被关闭。

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

Availability: Unix, not WASI.

Added in version 3.13.

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

os.lockf(fd, cmd, len, /)
在打开的文件描述符上，使用、测试或删除 POSIX 锁。fd 是一个打开的文件描述符。cmd 指定要进行的操作，它们是 F_LOCK、F_TLOCK、F_ULOCK 或 F_TEST 中的一个。len 指定哪部分文件需要锁定。

引发一个审计事件 os.lockf 并附带参数 fd, cmd, len。

Availability: Unix.

Added in version 3.3.

os.F_LOCK
os.F_TLOCK
os.F_ULOCK
os.F_TEST
标志位，用于指定 lockf() 进行哪一种操作。

Availability: Unix.

Added in version 3.3.

os.login_tty(fd, /)
准备 tty 设置 fd 为新登录会话的文件描述符。设置调用方进程为会话主进程；设置该 tty 为主控 tty，调用方进程使用其 stdin, stdout 和 stderr；关闭 fd。

Availability: Unix, not WASI.

Added in version 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() 方法的形参，用于调整文件位置指示器。
- SEEK_SET
- 相对于文件的开头调整文件位置。
- SEEK_CUR
- 相对于当前文件位置调整文件位置。
- SEEK_END
- 相对于文件的末尾调整文件位置。

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

os.SEEK_HOLE
os.SEEK_DATA
传给 lseek() 函数和文件型对象上 seek() 方法的形参，用于查找文件数据和稀疏分配的文件中的空洞。
- SEEK_DATA
- 相对于查找位置调整到下一个包含数据的位置的文件偏移量。
- SEEK_HOLE
- 相对于查找位置调整到下一个包含空洞的位置的文件偏移量。空洞被定义为零值的序列。

备注

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

Availability: Linux >= 3.1, macOS, Unix

Added in version 3.3.

os.open(path, flags, mode=0o777, *, dir_fd=None)
打开文件 path，根据 flags 设置各种标志位，并根据 mode 设置其权限状态。当计算 mode 时，会首先根据当前 umask 值将部分权限去除。本方法返回新文件的描述符。新的文件描述符是不可继承的。

有关 flag 和 mode 取值的说明，请参见 C 运行时文档。标志位常量（如 O_RDONLY 和 O_WRONLY）在 os 模块中定义。特别地，在 Windows 上需要添加 O_BINARY 才能以二进制模式打开文件。

本函数带有 dir_fd 参数，支持基于目录描述符的相对路径。

引发一个审计事件 open 并附带参数 path, mode, flags。

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

备注

本函数适用于底层的 I/O。常规用途请使用内置函数 open()，该函数的 read() 和 write() 方法（及其他方法）会返回文件对象。要将文件描述符包装在文件对象中，请使用 fdopen()。

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

在 3.5 版本发生变更: 如果系统调用被中断，但信号处理程序没有触发异常，此函数现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475 [https://peps.python.org/pep-0475/])。

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

以下常量是 open() 函数 flags 参数的选项。可以用按位或运算符 | 将它们组合使用。部分常量并非在所有平台上都可用。有关其可用性和用法的说明，请参阅 open(2)) [https://manpages.debian.org/open(2)] 手册（Unix 上）或 MSDN [https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx] （Windows 上）。

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。新的文件描述符是不可继承的。对于（稍微）轻量一些的方法，请使用 pty 模块。

Availability: Unix, not WASI.

在 3.4 版本发生变更: 新的文件描述符不再可继承。

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

Availability: Unix, Windows.

在 3.4 版本发生变更: 新的文件描述符不再可继承。

os.pipe2(flags, /)
创建带有 flags 标志位的管道。可通过对以下一个或多个值进行“或”运算来构造这些 flags：O_NONBLOCK、O_CLOEXEC。返回一对分别用于读取和写入的文件描述符 (r, w)。

Availability: Unix, not WASI.

Added in version 3.3.

os.posix_fallocate(fd, offset, len, /)
确保为 fd 指向的文件分配了足够的磁盘空间，该空间从偏移量 offset 开始，到 len 字节为止。

Availability: Unix.

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

Availability: Unix.

Added in version 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 参数的标志位，指定可能使用的访问模式。

Availability: Unix.

Added in version 3.3.

os.pread(fd, n, offset, /)
从文件描述符 fd 所指向文件的偏移位置 offset 开始，读取至多 n 个字节，而保持文件偏移量不变。

返回所读取字节的字节串 (bytestring)。如果到达了 fd 指向的文件末尾，则返回空字节对象。

Availability: Unix.

Added in version 3.3.

os.posix_openpt(oflag, /)
打开并返回一个代表主要伪终端设备的文件描述符。

调用 C 标准库函数 posix_openpt()。 oflag 参数用于设置文件状态旗标和文件访问模式，如你所用系统的 posix_openpt() 帮助页中所指明的那样。

返回的文件描述符是非不可继承的。如果所在系统上 O_CLOEXEC 值是可用的，它将被添加到 oflag。

Availability: Unix, not WASI.

Added in version 3.13.

os.preadv(fd, buffers, offset, flags=0, /)
从文件描述符 fd 所指向文件的偏移位置 offset 开始，将数据读取至可变字节类对象缓冲区 buffers 中，保持文件偏移量不变。将数据依次存放到每个缓冲区中，填满一个后继续存放到序列中的下一个缓冲区，来保存其余数据。

flags 参数可以由零个或多个标志位进行按位或运算来得到：

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

操作系统可能对允许使用的缓冲区数量有限制（使用 sysconf() 获取 'SC_IOV_MAX' 值）。

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

Availability: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

使用旗标需要 Linux >= 4.6。

Added in version 3.7.

os.RWF_NOWAIT
不要等待无法立即获得的数据。如果指定了此标志，那么当需要从后备存储器中读取数据，或等待文件锁时，系统调用将立即返回。

如果成功读取了数据，将返回读取的字节数。如果未读取到数据，将返回 -1 并将 errno 设为 errno.EAGAIN。

Availability: Linux >= 4.14.

Added in version 3.7.

os.RWF_HIPRI
高优先级读/写。允许基于块的文件系统对设备进行轮询，这样可以降低延迟，但可能会占用更多资源。

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

Availability: Linux >= 4.6.

Added in version 3.7.

os.ptsname(fd, /)
返回与文件描述符 fd 所指向的主伪终端设备相关联的从伪终端设备。文件描述符 fd 在失败时不会被关闭。

如果可重入 C 标准库函数 ptsname_r() 可用则调用它；在其他情况下，则调用 C 标准库函数 ptsname()，该函数不保证线程安全。

Availability: Unix, not WASI.

Added in version 3.13.

os.pwrite(fd, str, offset, /)
将 str 中的字节串 (bytestring) 写入文件描述符 fd 的偏移位置 offset 处，保持文件偏移量不变。

返回实际写入的字节数。

Availability: Unix.

Added in version 3.3.

os.pwritev(fd, buffers, offset, flags=0, /)
将 buffers 内容写入文件描述符 fd 的偏移位置 offset 处，保持文件偏移位置不变。 buffers 必须是由字节型对象组成的序列。缓冲区以数组顺序处理。先写入第一个缓冲区的全部内容再写入第二个，依此类推。

flags 参数可以由零个或多个标志位进行按位或运算来得到：

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

操作系统可能对允许使用的缓冲区数量有限制（使用 sysconf() 获取 'SC_IOV_MAX' 值）。

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

Availability: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.

使用旗标需要 Linux >= 4.6。

Added in version 3.7.

os.RWF_DSYNC
提供预写功能，等效于带 O_DSYNC 标志的 os.open() 。本标志只作用于通过系统调用写入的数据。

Availability: Linux >= 4.7.

Added in version 3.7.

os.RWF_SYNC
提供预写功能，等效于带 O_SYNC 标志的 os.open() 。本标志只作用于通过系统调用写入的数据。

Availability: Linux >= 4.7.

Added in version 3.7.

os.RWF_APPEND
提供预写功能，等效于带 O_APPEND 标志的 os.open() 。本标志只对 os.pwritev() 有意义，只作用于通过系统调用写入的数据。参数 offset 对写入操作无效；数据总是会添加到文件的末尾。但如果 offset 参数为 -1，则会刷新当前文件的 offset 。

Availability: Linux >= 4.16.

Added in version 3.10.

os.read(fd, n, /)
从文件描述符 fd 中读取至多 n 个字节。

返回所读取字节的字节串 (bytestring)。如果到达了 fd 指向的文件末尾，则返回空字节对象。

备注

该功能适用于低级 I/O 操作，必须用于 os.open() 或 pipe() 返回的文件描述符。若要读取由内建函数 open()、popen()、fdopen() 或 sys.stdin 返回的 "文件对象"，则应使用其相应的 read() 或 readline() 方法。

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 上，传入 0 值作为 count 将指定持续发送直至到达 in_fd 的末尾。

所有平台都支持将套接字作为 out_fd 文件描述符，有些平台也支持其他类型（如常规文件或管道）。

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

Availability: Unix, not WASI.

备注

有关 sendfile() 的高级封装，参见 socket.socket.sendfile()。

Added in version 3.3.

在 3.9 版本发生变更: out 和 in 参数被重命名为 out_fd 和 in_fd。

os.SF_NODISKIO
os.SF_MNOWAIT
os.SF_SYNC
sendfile() 函数的参数（假设当前实现支持这些参数）。

Availability: Unix, not WASI.

Added in version 3.3.

os.SF_NOCACHE
传给 sendfile() 函数的形参，如果具体实现支持的话。数据不会缓存在虚拟内存中并将随即被释放。

Availability: Unix, not WASI.

Added in version 3.11.

os.set_blocking(fd, blocking, /)
设置指定文件描述符的阻塞模式：如果 blocking 为 False，则为该描述符设置 O_NONBLOCK 标志位，反之则清除该标志位。

参见 get_blocking() 和 socket.socket.setblocking()。

Availability: Unix, Windows.

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

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

Added in version 3.5.

在 3.12 版本发生变更: 增加了在Windows上对于管道的支持。

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

此复制的完成没有额外的从内核到用户空间再回到内核的数据转移花费。另外，一些文件系统可能实现额外的优化。完成复制就如同打开两个二进制文件一样。

调用成功后，返回拼接到管道的字节数或从管道拼接出来的字节数。返回值为 0 意味着输入结束。如果 src 指向一个管道，则意味着没有数据需要传输，而且由于没有写入程序连到管道的写入端，所以将不会阻塞。

Availability: Linux >= 2.6.17 with glibc >= 2.5

Added in version 3.10.

os.SPLICE_F_MOVE
os.SPLICE_F_NONBLOCK
os.SPLICE_F_MORE

Added in version 3.10.

os.readv(fd, buffers, /)
从文件描述符 fd 将数据读取至多个可变的字节类对象缓冲区 buffers 中。将数据依次存放到每个缓冲区中，填满一个后继续存放到序列中的下一个缓冲区，来保存其余数据。

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

操作系统可能对允许使用的缓冲区数量有限制（使用 sysconf() 获取 'SC_IOV_MAX' 值）。

Availability: Unix.

Added in version 3.3.

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

Availability: Unix, not WASI.

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

Availability: Unix, not WASI.

os.ttyname(fd, /)
返回一个字符串，该字符串表示与文件描述符 fd 关联的终端。如果 fd 没有与终端关联，则抛出异常。

Availability: Unix.

os.unlockpt(fd, /)
解锁与文件描述符 fd 所指向的主伪终端设备相关联的从伪终端设备。文件描述符 fd 在失败时不会被关闭。

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

Availability: Unix, not WASI.

Added in version 3.13.

os.write(fd, str, /)
将 str 中的字节串 (bytestring) 写入文件描述符 fd。

返回实际写入的字节数。

备注

该功能适用于低级 I/O 操作，必须用于 os.open() 或 pipe() 返回的文件描述符。若要写入由内建函数 open()、popen()、fdopen()、sys.stdout 或 sys.stderr 返回的 "文件对象"，则应使用其相应的 write() 方法。

os.writev(fd, buffers, /)
将缓冲区 buffers 的内容写入文件描述符 fd。缓冲区 buffers 必须是由字节类对象组成的序列。缓冲区以数组顺序处理。先写入第一个缓冲区的全部内容，再写入第二个缓冲区，照此继续。

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

操作系统可能对允许使用的缓冲区数量有限制（使用 sysconf() 获取 'SC_IOV_MAX' 值）。

Availability: Unix.

Added in version 3.3.

查询终端的尺寸

Added in version 3.3.

os.get_terminal_size(fd=STDOUT_FILENO, /)
返回终端窗口的尺寸，格式为 (columns, lines)，它是类型为 terminal_size 的元组。

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

如果文件描述符未连接到终端，则抛出 OSError 异常。

shutil.get_terminal_size() 是供常规使用的高阶函数，os.get_terminal_size 是其底层的实现。

Availability: Unix, Windows.

class os.terminal_size
元组的子类，存储终端窗口尺寸 (columns, lines)。
- columns
- 终端窗口的宽度，单位为字符。
- lines
- 终端窗口的高度，单位为字符。

os --- 多种操作系统接口

os —- 多种操作系统接口

文件名，命令行参数，以及环境变量。

Python UTF-8 模式

进程参数

创建文件对象

文件描述符操作

查询终端的尺寸

`os` —- 多种操作系统接口