python操作系统接口错误_os --- 多种操作系统接口 — Python 3.10.0a2 文档

文件描述符操作¶

这些函数对文件描述符所引用的 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 复制 count 字节，从偏移量 offset_src 开始读取，到文件描述符 dst，从偏移量 offset_dst 开始写入。如果 offset_src 为 None，则 src 将从当前位置开始读取；offset_dst 同理。src 和 dst 指向的文件必须处于相同的文件系统，否则将会抛出一个 errno 被设为 errno.EXDEV 的 OSError 。

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

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

Availability: Linux kernel >= 4.5 或 glibc >= 2.27。

3.8 新版功能.

os.device_encoding(fd)¶

如果连接到终端，则返回一个与 fd 关联的设备描述字符，否则返回 None。

On Unix, if the Python UTF-8 Mode is enabled, return

'UTF-8' rather than the device encoding.

在 3.10 版更改:On Unix, the function now implements the Python UTF-8 Mode.

os.dup(fd)¶

返回一个文件描述符 fd 的副本。该文件描述符的副本是 不可继承的。

在 Windows 中，当复制一个标准流(0: stdin, 1: stdout, 2: stderr)时，新的文件描述符是 可继承的。

在 3.4 版更改:新的文件描述符现在是不可继承的。

os.dup2(fd, fd2, inheritable=True)¶

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

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

可用性: Unix。

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。

可用性: Unix。

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

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

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

可用性: Unix, Windows。

在 3.5 版更改:添加了 Windows 支持

os.get_blocking(fd)¶

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

可用性: Unix。

3.5 新版功能.

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。

可用性: Unix。

3.3 新版功能.

os.F_LOCK¶

os.F_TLOCK¶

os.F_ULOCK¶

os.F_TEST¶

标志位，用于指定 lockf() 进行哪一种操作。

可用性: Unix。

3.3 新版功能.

os.lseek(fd, pos, how)¶

将文件描述符 fd 的当前位置设置为 pos，位置的计算方式 how 如下：设置为 SEEK_SET 或 0 表示从文件开头计算，设置为 SEEK_CUR 或 1 表示从文件当前位置计算，设置为 SEEK_END 或 2 表示文件末尾计算。返回新指针位置，这个位置是从文件开头计算的，单位是字节。

os.SEEK_SET¶

os.SEEK_CUR¶

os.SEEK_END¶

lseek() 函数的参数，它们的值分别为 0、1 和 2。

3.3 新版功能:某些操作系统可能支持其他值，例如 os.SEEK_HOLE 或 os.SEEK_DATA。

os.open(path, flags, mode=511, *, 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)。

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

以下常量是 open() 函数 flags 参数的选项。可以用按位或运算符 | 将它们组合使用。部分常量并非在所有平台上都可用。有关其可用性和用法的说明，请参阅 MSDN (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_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 模块。

可用性: 某些 Unix。

在 3.4 版更改:新的文件描述符不再可继承。

os.pipe()¶

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

可用性: Unix, Windows。

在 3.4 版更改:新的文件描述符不再可继承。

os.pipe2(flags)¶

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

可用性: 某些 Unix。

3.3 新版功能.

os.posix_fallocate(fd, offset, len)¶

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

可用性: Unix。

3.3 新版功能.

os.posix_fadvise(fd, offset, len, advice)¶

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 个字节，而保持文件偏移量不变。

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

可用性: Unix。

3.3 新版功能.

os.preadv(fd, buffers, offset, flags=0)¶

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

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

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

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

可用性：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.pwrite(fd, str, offset)¶

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

返回实际写入的字节数。

可用性: Unix。

3.3 新版功能.

os.pwritev(fd, buffers, offset, flags=0)¶

将缓冲区 buffers 的内容写入文件描述符 fd 的偏移位置 offset 处，保持文件偏移量不变。缓冲区 buffers 必须是由 字节类对象 组成的序列。缓冲区以数组顺序处理。先写入第一个缓冲区的全部内容，再写入第二个缓冲区，照此继续。

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

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

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

可用性：Linux 2.6.30 或更高版本，FreeBSD 6.0 或更高版本，OpenBSD 2.7 或更高版本，AIX 7.1 或更高版本。使用标志位需要 Linux 4.7 或更高版本。

3.7 新版功能.

os.RWF_DSYNC¶

Provide a per-write equivalent of the O_DSYNC os.open() flag.

This flag effect applies only to the data range written by the system call.

可用性：Linux 4.7 或更高版本。

3.7 新版功能.

os.RWF_SYNC¶

Provide a per-write equivalent of the O_SYNC os.open() flag.

This flag effect applies only to the data range written by the system call.

可用性：Linux 4.7 或更高版本。

3.7 新版功能.

os.RWF_APPEND¶

Provide a per-write equivalent of the O_APPEND os.open()

flag. This flag is meaningful only for os.pwritev(), and its

effect applies only to the data range written by the system call. The

offset argument does not affect the write operation; the data is always

appended to the end of the file. However, if the offset argument is

-1, the current file offset is updated.

Availability: Linux 4.16 and newer.

3.10 新版功能.

os.read(fd, n)¶

从文件描述符 fd 中读取至多 n 个字节。

返回所读取字节的字节串 (bytestring)。如果到达了 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 的位置。

第二种函数用法可以在 Mac OS X 和 FreeBSD 上使用，其中，headers 和 trailers 是任意的缓冲区序列，它们分别在写入 in_fd 的数据前、后被写入。返回值与第一种用法相同。

在 Mac OS X 和 FreeBSD 上，将 count 设为 0 表示持续复制直到 in_fd 的结尾。

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

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

可用性: Unix。

3.3 新版功能.

在 3.9 版更改:out 和 in 参数被重命名为 out_fd 和 in_fd。

os.set_blocking(fd, blocking)¶

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

可用性: Unix。

3.5 新版功能.

os.SF_NODISKIO¶

os.SF_MNOWAIT¶

os.SF_SYNC¶

sendfile() 函数的参数(假设当前实现支持这些参数)。

可用性: Unix。

3.3 新版功能.

os.splice(src, dst, count, offset_src=None, offset_dst=None)¶

Transfer count bytes from file descriptor src, starting from offset

offset_src, to file descriptor dst, starting from offset offset_dst.

At least one of the file descriptors must refer to a pipe. If offset_src

is None, then src is read from the current position; respectively for

offset_dst. The offset associated to the file descriptor that refers to a

pipe must be None. The files pointed by src and dst must reside in

the same filesystem, otherwise an OSError is raised with

errno set to errno.EXDEV.

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

Upon successful completion, returns the number of bytes spliced to or from

the pipe. A return value of 0 means end of input. If src refers to a

pipe, then this means that there was no data to transfer, and it would not

make sense to block because there are no writers connected to the write end

of the pipe.

Availability: Linux kernel >= 2.6.17 and glibc >= 2.5

3.10 新版功能.

os.SPLICE_F_MOVE¶

os.SPLICE_F_NONBLOCK¶

os.SPLICE_F_MORE¶

3.10 新版功能.

os.readv(fd, buffers)¶

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

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

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

可用性: Unix。

3.3 新版功能.

os.tcgetpgrp(fd)¶

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

可用性: Unix。

os.tcsetpgrp(fd, pg)¶

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

可用性: Unix。

os.ttyname(fd)¶

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

可用性: Unix。

os.write(fd, str)¶

将 str 中的字节串 (bytestring) 写入文件描述符 fd。

返回实际写入的字节数。

注解

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

在 3.5 版更改:如果系统调用被中断，但信号处理程序没有触发异常，此函数现在会重试系统调用，而不是触发 InterruptedError 异常 (原因详见 PEP 475)。

os.writev(fd, buffers)¶

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

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

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

可用性: Unix。

3.3 新版功能.

查询终端的尺寸¶

3.3 新版功能.

os.get_terminal_size(fd=STDOUT_FILENO)¶

返回终端窗口的尺寸，格式为 (columns, lines)，它是类型为 terminal_size 的元组。

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

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

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

可用性: Unix, Windows。

classos.terminal_size¶

元组的子类，存储终端窗口尺寸 (columns, lines)。

columns¶

终端窗口的宽度，单位为字符。

lines¶

终端窗口的高度，单位为字符。

文件描述符的继承¶

3.4 新版功能.

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

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

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

os.get_inheritable(fd)¶

获取指定文件描述符的“可继承”标志位(为布尔值)。

os.set_inheritable(fd, inheritable)¶

设置指定文件描述符的“可继承”标志位。

os.get_handle_inheritable(handle)¶

获取指定句柄的“可继承”标志位(为布尔值)。

可用性: Windows。

os.set_handle_inheritable(handle, inheritable)¶

设置指定句柄的“可继承”标志位。

可用性: Windows。