python / 3.7.2rc1 / all / library-os.html

os —其他 os 接口

源代码: Lib/os.py


该模块提供了使用依赖于 os 的Function的便携式方法。如果只想读取或写入文件,请参见open();如果要操纵路径,请参见os.path模块;如果要读取命令行中所有文件的所有行,请参见fileinput模块。有关创建临时文件和目录的信息,请参见tempfile模块;有关高级文件和目录的处理的信息,请参见shutil模块。

有关这些Function的可用性的注意事项:

  • Python 的所有依赖于 os 的内置模块的设计都是这样,只要有相同的Function可用,它就使用相同的接口。例如,函数os.stat(path)以相同格式(恰好起源于 POSIX 接口)返回有关* path *的统计信息。

  • 特定于 os 的 extensions 也可以passos模块获得,但是使用 extensions 当然会威胁到可移植性。

  • 如果返回路径或文件名,则所有接受路径或文件名的函数都将接受字节对象和字符串对象,并导致相同类型的对象。

  • 在 VxWorks 上,不支持 os.fork,os.execv 和 os.spawn * p *。

Note

在无效或不可访问的文件名和路径或具有正确类型但 os 不接受的其他参数的情况下,此模块中的所有函数均引发OSError(或其子类)。

  • exception os. error

    • 内置OSErrorexception 的别名。
  • os. name

    • 导入的 os 相关模块的名称。当前已注册以下名称:'posix''nt''java'

See also

sys.platform具有更好的粒度。 os.uname()提供与系统有关的版本信息。

platform模块提供对系统身份的详细检查。

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

在 Python 中,文件名,命令行参数和环境变量使用字符串类型表示。在某些系统上,有必要在将这些字符串与字节之间进行解码之前,将它们传递给 os。 Python 使用文件系统编码来执行此转换(请参见sys.getfilesystemencoding())。

在版本 3.1 中进行了更改:在某些系统上,使用文件系统编码的转换可能会失败。在这种情况下,Python 使用surrogateescape 编码错误处理程序,这意味着无法解码的字节在解码时会被 Unicode 字符 U DCxx 替换,并且在编码时会再次转换为原始字节。

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

Process Parameters

这些Function和数据项提供信息并在当前进程和用户上运行。

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

Availability: Unix.

  • os. environ
    • 表示字符串环境的mapping对象。例如,environ['HOME']是主目录的路径名(在某些平台上),等效于 C 中的getenv("HOME")

首次导入os模块时(通常在 Python 启动期间作为处理site.py的一部分)捕获此 Map。此时间之后对环境所做的更改不会反映在os.environ中,除非直接pass修改os.environ进行更改。

如果平台支持putenv()Function,则此 Map 可用于修改环境以及查询环境。修改 Map 后,将自动调用putenv()

在 Unix 上,键和值使用sys.getfilesystemencoding()'surrogateescape'错误处理程序。如果您想使用其他编码,请使用environb

Note

直接调用putenv()不会更改os.environ,因此最好修改os.environ

Note

在某些平台上,包括 FreeBSD 和 Mac OS X,设置environ可能会导致内存泄漏。有关putenv()的信息,请参阅系统文档。

如果未提供putenv(),则可以将此 Map 的修改后的副本传递到适当的进程创建函数,以使子进程使用修改后的环境。

如果平台支持unsetenv()Function,则可以删除此 Map 中的项目以取消设置环境变量。当从os.environ中删除一个项目,并且调用pop()clear()方法之一时,将自动调用unsetenv()

environb仅在supports_bytes_environTrue时可用。

3.2 版中的新Function。

  • os. chdir(* path *)

  • os. fchdir(* fd *)

  • os. getcwd ( )

  • os. fsencode(* filename *)

    • 使用'surrogateescape'错误处理程序或 Windows 上的'strict'path-like 文件名编码为文件系统编码;返回bytes不变。

fsdecode()是反向Function。

3.2 版中的新Function。

在版本 3.6 中更改:添加了支持以接受实现os.PathLike接口的对象。

  • os. fsdecode(* filename *)
    • 使用'surrogateescape'错误处理程序或 Windows 上的'strict'从文件系统编码中解码path-like 文件名;返回str不变。

fsencode()是反向Function。

3.2 版中的新Function。

在版本 3.6 中更改:添加了支持以接受实现os.PathLike接口的对象。

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

如果传递了strbytes,则返回的值不变。否则,只要是strbytes对象,就调用fspath()并返回其值。在所有其他情况下,TypeError被引发。

3.6 版的新Function。

3.6 版的新Function。

  • 抽象方法 __fspath__()
    • 返回对象的文件系统路径表示形式。

该方法应仅返回strbytes对象,首选项为str

  • os. getenv(* key default = None *)
    • 如果环境变量* key 存在,则返回它的值;如果不存在,则返回 default *。 * key default *,结果为 str。

在 Unix 上,键和值使用sys.getfilesystemencoding()'surrogateescape'错误处理程序解码。如果您想使用其他编码,请使用os.getenvb()

Availability:大多数版本的 Unix,Windows。

  • os. getenvb(* key default = None *)
    • 如果环境变量* key 存在,则返回它的值;如果不存在,则返回 default *。 * key default *和结果为字节。

getenvb()仅在supports_bytes_environTrue时可用。

Availability:大多数 Unix 版本。

3.2 版中的新Function。

  • os. get_exec_path(* env = None *)
    • 返回启动进程时将搜索与 Shell 程序类似的命名可执行文件的目录列表。 * env (指定时)应为环境变量字典以在其中查找 PATH。默认情况下,当 env *为None时,将使用environ

3.2 版中的新Function。

  • os. getegid ( )
    • 返回当前进程的有效组 ID。这对应于当前进程中正在执行的文件上的“ set id”位。

Availability: Unix.

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

Availability: Unix.

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

Availability: Unix.

  • os. getgrouplist(* user group *)
    • 返回* user 所属的组 ID 的列表。如果 group 不在列表中,则将其包括在内;通常, group 被指定为 user *的密码 Logging 的 group ID 字段。

Availability: Unix.

版本 3.3 中的新Function。

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

Availability: Unix.

Note

在 Mac OS X 上,getgroups()行为与其他 Unix 平台有所不同。如果 Python 解释程序的部署目标是10.5或更早版本,则getgroups()返回与当前用户进程关联的有效组 ID 的列表;否则,此列表限于系统定义的条目数,通常为 16,并且可以pass适当地特权对setgroups()的调用进行修改。如果构建的部署目标大于10.5,则getgroups()返回与该进程的有效用户标识关联的用户的当前组访问列表;组访问列表可能会在该过程的整个生命周期内发生变化,不受setgroups()调用的影响,并且其长度不限于 16.可以使用sysconfig.get_config_var()获得部署目标值MACOSX_DEPLOYMENT_TARGET

  • os. getlogin ( )
    • 返回在该过程的控制终端上登录的用户的名称。在大多数情况下,使用getpass.getuser()更为有用,因为后者检查环境变量 LOGNAME USERNAME以确定用户是谁,然后回退到pwd.getpwuid(os.getuid())[0]以获取当前实际用户 ID 的登录名。

Availability:Unix,Windows。

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

Availability: Unix.

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

Availability: Unix.

  • os. getpid ( )
    • 返回当前进程 ID。
  • os. getppid ( )
    • 返回父进程的 ID。退出父进程后,在 Unix 上,返回的 id 是 init 进程(1)中的一个,在 Windows 上,它仍然是相同的 id,它可能已被另一个进程重用。

Availability:Unix,Windows。

在版本 3.2 中进行了更改:添加了对 Windows 的支持。

  • os. getpriority(* which who *)
    • 获取程序调度优先级。值* that PRIO_PROCESSPRIO_PGRPPRIO_USER之一,并且 who 相对于 which *(PRIO_PROCESS的进程标识符,PRIO_PGRP的进程组标识符和PRIO_USER的用户 ID)进行解释。 * who *的零值分别表示呼叫过程,呼叫过程的过程组或呼叫过程的真实用户 ID。

Availability: Unix.

版本 3.3 中的新Function。

Availability: Unix.

版本 3.3 中的新Function。

  • os. getresuid ( )
    • 返回一个 Tuples(ruid,euid,suid),表示当前进程的真实,有效和已保存的用户 ID。

Availability: Unix.

3.2 版中的新Function。

  • os. getresgid ( )
    • 返回一个 Tuples(rgid,egid,sgid),表示当前进程的真实,有效和已保存的组 ID。

Availability: Unix.

3.2 版中的新Function。

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

Availability: Unix.

  • os. initgroups(* username gid *)
    • 调用系统 initgroups()初始化包含指定用户名是成员的所有组以及指定组 ID 的组访问列表。

Availability: Unix.

3.2 版中的新Function。

  • os. putenv(* key value *)
    • 将名为* key 的环境变量设置为字符串 value *。对环境的此类更改会影响以os.system()popen()fork()execv()开头的子流程。

Availability:大多数版本的 Unix,Windows。

Note

在某些平台上,包括 FreeBSD 和 Mac OS X,设置environ可能会导致内存泄漏。请参阅系统文档以获取 putenv。

如果支持putenv(),则对os.environ中项目的分配将自动转换为对putenv()的相应调用;但是,对putenv()的调用不会更新os.environ,因此实际上最好分配给os.environ的项。

用参数keyvalue引发auditing event os.putenv

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

Availability: Unix.

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

Availability: Unix.

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

Availability: Unix.

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

Availability: Unix.

Note

在 Mac OS X 上,* groups *的长度不得超过系统定义的有效组 ID 的最大数量,通常为 16.有关getgroups()的信息,可能无法pass调用 setgroups()返回相同的组列表,请参见getgroups()的文档。 。

  • os. setpgrp ( )
    • 根据实现的版本(如有),调用系统调用setpgrp()setpgrp(0, 0)。有关语义,请参见 Unix 手册。

Availability: Unix.

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

Availability: Unix.

  • os. setpriority(哪个优先级)
    • 设置节目安排优先级。值* that PRIO_PROCESSPRIO_PGRPPRIO_USER之一,并且 who 相对于 which *(PRIO_PROCESS的进程标识符,PRIO_PGRP的进程组标识符和PRIO_USER的用户 ID)进行解释。 * who *的零值分别表示呼叫过程,呼叫过程的过程组或呼叫过程的真实用户 ID。 * priority *是介于-20 到 19 之间的值。默认优先级为 0;默认值为 0.较低的优先级会导致更有利的调度。

Availability: Unix.

版本 3.3 中的新Function。

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

Availability: Unix.

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

Availability: Unix.

3.2 版中的新Function。

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

Availability: Unix.

3.2 版中的新Function。

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

Availability: Unix.

  • os. getsid(* pid *)
    • 拨打系统电话getsid()。有关语义,请参见 Unix 手册。

Availability: Unix.

  • os. setsid ( )
    • 拨打系统电话setsid()。有关语义,请参见 Unix 手册。

Availability: Unix.

  • os. setuid(* uid *)
    • 设置当前进程的用户标识。

Availability: Unix.

  • os. strerror(* code *)

    • 返回与* code *中的错误代码相对应的错误消息。在给定未知错误号的情况下,strerror()返回NULL的平台上,引发ValueError
  • os. supports_bytes_environ

    • True(如果环境的本机 OS 类型是字节)(例如 Windows 上的False)。

3.2 版中的新Function。

  • os. umask(* mask *)

    • 设置当前的数字 umask 并返回上一个 umask。
  • os. uname ( )

    • 返回标识当前 os 的信息。返回值是具有五个属性的对象:
  • sysname-os 名称

  • nodename-网络上的计算机名称(实现定义)

  • release-os 版本

  • version-os 版本

  • machine-硬件标识符

为了向后兼容,该对象也是可迭代的,其行为类似于包含五个数组,依次包含sysnamenodenamereleaseversionmachine

某些系统将nodename截断为 8 个字符或开头的部分;获取主机名的更好方法是socket.gethostname()甚至socket.gethostbyaddr(socket.gethostname())

Availability:Unix 的最新版本。

在版本 3.3 中更改:返回类型从 Tuples 更改为具有命名属性的类似 Tuples 的对象。

  • os. unsetenv(* key *)

如果支持unsetenv(),则删除os.environ中的项目会自动转换为对unsetenv()的相应调用;但是,对unsetenv()的调用不会更新os.environ,因此实际上最好删除os.environ的项。

用参数key引发auditing event os.unsetenv

Availability:大多数 Unix 版本。

文件对象的创建

这些函数创建新的file objects。 (有关打开文件 Descriptors 的信息,另请参见open()。)

  • os. fdopen(* fd *, *args * kwargs *)
    • 返回连接到文件 Descriptors* fd *的打开文件对象。这是open()内置函数的别名,并接受相同的参数。唯一的区别是fdopen()的第一个参数必须始终为整数。

文件 Descriptors 操作

这些Function对使用文件 Descriptors 引用的 I/O 流起作用。

文件 Descriptors 是与当前进程已打开的文件相对应的小整数。例如,标准 Importing 通常是文件 Descriptors0,标准输出是 1,标准错误是 2.然后,进程打开的其他文件将被分配 3、4、5,依此类推。名称“文件 Descriptors”具有欺骗性;在 Unix 平台上,套接字和管道也由文件 Descriptors 引用。

必要时,可以使用fileno()方法获取与file object关联的文件 Descriptors。请注意,直接使用文件 Descriptors 将忽略文件对象方法,而忽略诸如数据内部缓冲之类的方面。

  • os. close(* fd *)
    • 关闭文件 Descriptors* fd *。

Note

此函数用于低级 I/O,并且必须应用于os.open()pipe()返回的文件 Descriptors。要关闭内置函数open()popen()fdopen()返回的“文件对象”,请使用其close()方法。

  • os. closerange(* fd_low fd_high *)
    • 关闭所有文件 Descriptors,从* 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 *)
    • 从偏移量* offset_src 开始,从文件 Descriptors src 复制 count 个字节,从偏移量 offset_dst 开始,复制到文件 Descriptors dst 。如果 offset_src 为 None,则从当前位置读取 src 。分别用于 offset_dst *。 * src dst *指向的文件必须位于同一文件系统中,否则引发OSErrorerrno设置为errno.EXDEV

完成此复制无需将数据从内核传输到用户空间然后再传输回内核的额外费用。此外,某些文件系统可以实现额外的优化。复制就像两个文件都以二进制文件打开一样。

返回值是复制的字节数。这可能小于请求的数量。

Availability:Linux 内核> = 4.5 或 glibc> = 2.27.

3.8 版的新Function。

  • os. device_encoding(* fd *)

    • 返回一个字符串,该字符串描述与* fd *关联的设备(如果已连接至终端)的编码;否则返回None
  • os. dup(* fd *)

    • 返回文件 Descriptors* fd *的副本。新文件 Descriptors 为non-inheritable

在 Windows 上,当复制标准流(0:stdin,1:stdout,2:stderr)时,新文件 Descriptors 为inheritable

在版本 3.4 中进行了更改:现在不可继承新文件 Descriptors。

  • os. dup2(* fd fd2 inheritable = True *)
    • 将文件 Descriptors* fd 复制到 fd2 ,如有必要,先关闭后者。返回 fd2 。默认情况下,新文件 Descriptors 为inheritable;如果 inheritable *为False,则新文件 Descriptors 为不可继承。

在版本 3.4 中进行了更改:添加可选的* inheritable *参数。

在 3.7 版中进行了更改:成功返回* fd2 *。以前,None总是返回。

  • os. fchmod(* fd mode *)
    • 将* fd 给定的文件模式更改为数字 mode 。请参阅chmod()的文档,以获取 mode *的可能值。从 Python 3.3 开始,这等效于os.chmod(fd, mode)

用参数pathmodedir_fd引发auditing event os.chmod

Availability: Unix.

  • os. fchown(* fd uid gid *)
    • 将* fd 给定的文件的所有者和组 ID 更改为数字 uid gid *。要使其中一个 ID 保持不变,请将其设置为-1.参见chown()。从 Python 3.3 开始,这等效于os.chown(fd, uid, gid)

用参数pathuidgiddir_fd引发auditing event os.chown

Availability: Unix.

  • os. fdatasync(* fd *)
    • 强制使用 filedescriptor * fd *将文件写入磁盘。不强制更新元数据。

Availability: Unix.

Note

此Function在 MacOS 上不可用。

  • os. fpathconf(* fd name *)
    • 返回与打开的文件有关的系统配置信息。 * name 指定要检索的配置值;它可以是一个字符串,它是定义的系统值的名称;这些名称在许多标准(POSIX.1,Unix 95,Unix 98 等)中指定。一些平台还定义了其他名称。主机 os 已知的名称在pathconf_names字典中给出。对于未包含在该 Map 中的配置变量,也可接受为 name *传递整数。

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

从 Python 3.3 开始,这等效于os.pathconf(fd, name)

Availability: Unix.

  • os. fstat(* fd *)
    • 获取文件 Descriptors* fd *的状态。返回一个stat_result对象。

从 Python 3.3 开始,这等效于os.stat(fd)

See also

stat()Function。

  • os. fstatvfs(* fd *)
    • 返回有关包含与文件 Descriptors* fd *关联的文件的文件系统的信息,例如statvfs()。从 Python 3.3 开始,这等效于os.statvfs(fd)

Availability: Unix.

  • os. fsync(* fd *)
    • 强制使用 filedescriptor * fd *将文件写入磁盘。在 Unix 上,这将调用本地fsync()函数;在 Windows 上,MS _commit()Function。

如果您从缓冲的 Python file object * f 开始,请首先执行f.flush(),然后执行os.fsync(f.fileno()),以确保与 f *关联的所有内部缓冲区都写入磁盘。

Availability:Unix,Windows。

  • os. ftruncate(* fd length *)
    • 截断与文件 Descriptors* fd 对应的文件,以使其最大为 length *个字节。从 Python 3.3 开始,这等效于os.truncate(fd, length)

用参数fdlength引发auditing event os.truncate

Availability:Unix,Windows。

在版本 3.5 中进行了更改:添加了对 Windows 的支持

  • os. get_blocking(* fd *)
    • 获取文件 Descriptors 的阻止模式:如果设置了O_NONBLOCK标志,则返回False;如果该标志被清除,则返回True

另请参见set_blocking()socket.socket.setblocking()

Availability: Unix.

3.5 版中的新Function。

  • os. isatty(* fd *)

    • 如果文件 Descriptors* fd *已打开并连接到 tty(-like)设备,则返回True,否则返回False
  • os. lockf(* fd cmd len *)

    • 在打开的文件 Descriptors 上应用,测试或删除 POSIX 锁。 * fd *是一个打开的文件 Descriptors。 * cmd *指定要使用的命令-F_LOCKF_TLOCKF_ULOCKF_TEST之一。 * len *指定要锁定的文件部分。

用参数fdcmdlen引发auditing event os.lockf

Availability: Unix.

版本 3.3 中的新Function。

  • os. F_LOCK
  • os. F_TLOCK
  • os. F_ULOCK
  • os. F_TEST
    • 用于指定lockf()将要采取的操作的标志。

Availability: Unix.

版本 3.3 中的新Function。

  • os. lseek(* fd pos how *)

    • 将文件 Descriptors* fd *的当前位置设置为 position * pos ,由 how *修改:SEEK_SET0以设置相对于文件开头的位置; SEEK_CUR1相对于当前位置进行设置; SEEK_END2相对于文件末尾进行设置。从头开始以字节为单位返回新的光标位置。
  • os. SEEK_SET

  • os. SEEK_CUR

  • os. SEEK_END

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

版本 3.3 中的新增Function:某些 os 可能支持其他值,例如os.SEEK_HOLEos.SEEK_DATA

  • os. open(* path flags mode = 0o777 **,* dir_fd = None *)
    • 打开文件* path 并根据 flags 设置各种标志,并根据* mode 设置其模式。当计算 mode *时,当前的 umask 值首先被屏蔽掉。返回新打开文件的文件 Descriptors。新文件 Descriptors 为non-inheritable

有关标志和模式值的说明,请参见 C 运行时文档。标志常量(例如O_RDONLYO_WRONLY)在os模块中定义。特别是在 Windows 上,需要添加O_BINARY才能以二进制模式打开文件。

此函数可以pass* dir_fd *参数支持相对于目录 Descriptors 的路径

用参数pathmodeflags引发auditing event open

在版本 3.4 中进行了更改:现在不可继承新文件 Descriptors。

Note

此Function适用于低级 I/O。为了正常使用,请使用内置函数open(),该函数会返回带有read()write()方法(还有更多)的file object。要将文件 Descriptors 包装在文件对象中,请使用fdopen()

版本 3.3 中的新Function:* dir_fd *参数。

在版本 3.5 中进行了更改:如果系统调用被break并且 signal 处理程序没有引发异常,则该函数现在重试系统调用,而不是引发InterruptedError异常(有关原理,请参见 PEP 475)。

在版本 3.6 中更改:接受path-like object

以下常量是open()函数的* flags 参数的选项。可以使用按位或运算符|组合它们。其中一些Function并非在所有平台上都可用。有关其可用性和使用的说明,请参阅 Unix 上的 open(2) *手册页或 Windows 上的the 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_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

    • 上面的常量是 extensions,如果 C 库未定义它们则不存在。

在版本 3.4 中进行了更改:在支持它的系统上添加O_PATH。添加O_TMPFILE,仅在 Linux Kernel 3.11 或更高版本上可用。

  • os. openpty ( )
    • 打开一个新的伪终端对。分别为 pty 和 tty 返回Pair文件 Descriptors(master, slave)。新的文件 Descriptors 为non-inheritable。对于(稍微)更可移植的方法,请使用pty模块。

Availability:某些 Unix 风格。

在版本 3.4 中更改:现在不可继承新的文件 Descriptors。

  • os. pipe ( )
    • 创建一个管道。返回Pair分别可用于读取和写入的文件 Descriptors(r, w)。新文件 Descriptors 为non-inheritable

Availability:Unix,Windows。

在版本 3.4 中更改:现在不可继承新的文件 Descriptors。

  • os. pipe2(* flags *)
    • 创建一个具有* flags *原子设置的管道。 * flags *可以pass对以下一个或多个值进行“或”运算来构造:O_NONBLOCKO_CLOEXEC。返回Pair分别可用于读取和写入的文件 Descriptors(r, w)

Availability:某些 Unix 风格。

版本 3.3 中的新Function。

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

Availability: Unix.

版本 3.3 中的新Function。

Availability: Unix.

版本 3.3 中的新Function。

  • 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()建议中使用的标志,用于指定可能使用的访问模式。

Availability: Unix.

版本 3.3 中的新Function。

  • os. pread(* fd n offset *)
    • 在* offset 的位置从文件 Descriptors fd 读取最多 n *个字节,而文件偏移量保持不变。

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

Availability: Unix.

版本 3.3 中的新Function。

  • os. preadv(* fd buffers offset flags = 0 *)
    • 从文件 Descriptors* fd offset *的位置读取到可变的bytes-like objects * buffers *中,使文件偏移保持不变。将数据传输到每个缓冲区中,直到已满为止,然后移到序列中的下一个缓冲区以保留其余数据。

flags 参数包含零个或多个以下标志的按位或:

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

os 可以设置可以使用的缓冲区数的限制(sysconf()'SC_IOV_MAX')。

结合os.readv()os.pread()的Function。

Availability:Linux 2.6.30 和更高版本,FreeBSD 6.0 和更高版本,OpenBSD 2.7 和更高版本。使用标志需要 Linux 4.6 或更高版本。

3.7 版中的新Function。

  • os. RWF_NOWAIT
    • 不要 await 无法立即获得的数据。如果指定了此标志,则系统调用必须从后备存储器中读取数据或 await 锁定时将立即返回。

如果成功读取了某些数据,它将返回读取的字节数。如果未读取任何字节,它将返回-1并将 errno 设置为errno.EAGAIN

Availability:Linux 4.14 及更高版本。

3.7 版中的新Function。

  • os. RWF_HIPRI
    • 高优先级读/写。允许基于块的文件系统使用设备的轮询,这可以降低延迟,但可能会使用其他资源。

当前,在 Linux 上,此Function仅在使用O_DIRECT标志打开的文件 Descriptors 上可用。

Availability:Linux 4.6 及更高版本。

3.7 版中的新Function。

  • os. pwrite(* fd str offset *)
    • 将* str 中的字节串写入 offset 位置的文件 Descriptors fd *中,使文件偏移保持不变。

返回实际写入的字节数。

Availability: Unix.

版本 3.3 中的新Function。

  • os. pwritev(* fd buffers offset flags = 0 *)
    • 将* buffers 内容以偏移量 offset 写入文件 Descriptors fd *,使文件偏移量保持不变。 * buffers *必须是bytes-like objects的序列。缓冲区以数组 Sequences 处理。在 continue 第二个缓冲区之前,先写入第一个缓冲区的全部内容,依此类推。

flags 参数包含零个或多个以下标志的按位或:

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

os 可以设置可以使用的缓冲区数的限制(sysconf()'SC_IOV_MAX')。

结合os.writev()os.pwrite()的Function。

Availability:Linux 2.6.30 和更高版本,FreeBSD 6.0 和更高版本,OpenBSD 2.7 和更高版本。使用标志需要 Linux 4.7 或更高版本。

3.7 版中的新Function。

  • os. RWF_DSYNC
    • 提供与O_DSYNC open(2)标志等效的每次写入。此标志作用仅适用于系统调用写入的数据范围。

Availability:Linux 4.7 及更高版本。

3.7 版中的新Function。

  • os. RWF_SYNC
    • 提供与O_SYNC open(2)标志等效的每次写入。此标志作用仅适用于系统调用写入的数据范围。

Availability:Linux 4.7 及更高版本。

3.7 版中的新Function。

  • os. read(* fd n *)
    • 从文件 Descriptors* fd 读取最多 n *个字节。

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

Note

此函数用于低级 I/O,并且必须应用于os.open()pipe()返回的文件 Descriptors。要读取内置函数open()popen()fdopen()sys.stdin返回的“文件对象”,请使用其read()readline()方法。

在版本 3.5 中进行了更改:如果系统调用被break并且 signal 处理程序没有引发异常,则该函数现在重试系统调用,而不是引发InterruptedError异常(有关原理,请参见 PEP 475)。

  • os. sendfile(* out in offset count *)

  • os. sendfile(* out in offset count *,[* headers *,] [* trailers *,] * flags = 0 *)

    • 从* offset 开始,将 count 个字节从文件 Descriptors in 复制到文件 Descriptors out *。返回发送的字节数。达到 EOF 后,返回 0.

所有定义sendfile()的平台都支持第一个Function符号。

在 Linux 上,如果将* offset 设置为None,则从 in 的当前位置读取字节,并更新 in *的位置。

第二种情况可以在 Mac OS X 和 FreeBSD 上使用,其中* headers trailers 是在写入来自 in *的数据之前和之后写入的任意缓冲区序列。返回的结果与第一种情况相同。

在 Mac OS X 和 FreeBSD 上,* count 的值 0 指定发送直到到达 in *的末尾。

所有平台都将套接字作为* out *文件 Descriptors 支持,某些平台还允许其他类型(例如常规文件,管道)。

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

Availability: Unix.

Note

有关sendfile()的高级包装,请参见socket.socket.sendfile()

版本 3.3 中的新Function。

  • os. set_blocking(* fd blocking *)
    • 设置指定文件 Descriptors 的阻止模式。如果阻止为False,则设置O_NONBLOCK标志,否则清除该标志。

另请参见get_blocking()socket.socket.setblocking()

Availability: Unix.

3.5 版中的新Function。

  • os. SF_NODISKIO
  • os. SF_MNOWAIT
  • os. SF_SYNC
    • sendfile()函数的参数(如果实现支持)。

Availability: Unix.

版本 3.3 中的新Function。

  • os. readv(* fd buffers *)
    • 从文件 Descriptors* fd *读取到多个可变的bytes-like objects * buffers *中。将数据传输到每个缓冲区中,直到已满为止,然后移到序列中的下一个缓冲区以保留其余数据。

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

os 可以设置可以使用的缓冲区数的限制(sysconf()'SC_IOV_MAX')。

Availability: Unix.

版本 3.3 中的新Function。

  • os. tcgetpgrp(* fd *)
    • 返回与* fd *(由os.open()返回的打开文件 Descriptors)给定的终端关联的进程组。

Availability: Unix.

  • os. tcsetpgrp(* fd pg *)
    • 将与* fd (由os.open()返回的打开文件 Descriptors)给定的终端相关联的进程组设置为 pg *。

Availability: Unix.

  • os. ttyname(* fd *)
    • 返回一个字符串,该字符串指定与文件 Descriptors* fd 关联的终端设备。如果 fd *没有与终端设备关联,则会引发异常。

Availability: Unix.

  • os. write(* fd str *)
    • 将* str 中的字节串写入文件 Descriptors fd *中。

返回实际写入的字节数。

Note

此函数用于低级 I/O,并且必须应用于os.open()pipe()返回的文件 Descriptors。要编写由内置函数open()popen()fdopen()sys.stdoutsys.stderr返回的“文件对象”,请使用其write()方法。

在版本 3.5 中进行了更改:如果系统调用被break并且 signal 处理程序没有引发异常,则该函数现在重试系统调用,而不是引发InterruptedError异常(有关原理,请参见 PEP 475)。

  • os. writev(* fd buffers *)
    • 将* buffers 的内容写入文件 Descriptors fd *中。 * buffers *必须是bytes-like objects的序列。缓冲区以数组 Sequences 处理。在 continue 第二个缓冲区之前,先写入第一个缓冲区的全部内容,依此类推。

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

os 可以设置可以使用的缓冲区数的限制(sysconf()'SC_IOV_MAX')。

Availability: Unix.

版本 3.3 中的新Function。

查询终端的大小

版本 3.3 中的新Function。

  • os. get_terminal_size(* fd = STDOUT_FILENO *)
    • 返回终端窗口的大小为(columns, lines),类型为terminal_size的 Tuples。

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

如果文件 Descriptors 未连接到终端,则会引发OSError

shutil.get_terminal_size()是通常应使用的高级Function,os.get_terminal_size是低级实现。

Availability:Unix,Windows。

  • 类别 os. terminal_size

    • Tuples 的子类,具有终端窗口大小的(columns, lines)
  • columns

    • 终端窗口的宽度,以字符为单位。
  • lines

    • 终端窗口的高度(以字符为单位)。

文件 Descriptors 的继承

3.4 版的新Function。

文件 Descriptors 具有“可继承”标志,该标志指示文件 Descriptors 是否可以由子进程继承。从 Python 3.4 开始,默认情况下,由 Python 创建的文件 Descriptors 是不可继承的。

在 UNIX 上,执行新程序时在子进程中关闭了不可继承的文件 Descriptors,其他文件 Descriptors 被继承。

在 Windows 上,不可继承的句柄和文件 Descriptors 在子进程中关闭,但始终继承的标准流(文件 Descriptors0、1 和 2:stdin,stdout 和 stderr)除外。使用spawn*函数,所有可继承的句柄和所有可继承的文件 Descriptors 都被继承。使用subprocess模块,将关闭标准流以外的所有文件 Descriptors,并且仅当* close_fds *参数为False时才能继承可继承的句柄。

  • os. get_inheritable(* fd *)

    • 获取指定文件 Descriptors 的“可继承”标志(一个布尔值)。
  • os. set_inheritable(* fd inheritable *)

    • 设置指定文件 Descriptors 的“可继承”标志。
  • os. get_handle_inheritable(* handle *)

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

Availability: Windows.

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

Availability: Windows.

文件和目录

在某些 Unix 平台上,其中许多Function支持以下一项或多项Function:

  • 指定文件 Descriptors: 通常,在os模块中提供给函数的* path 参数必须是指定文件路径的字符串。但是,某些函数现在可以替换地为其 path *参数接受一个打开的文件 Descriptors。然后,该函数将对 Descriptors 所引用的文件进行操作。 (对于 POSIX 系统,Python 将调用以f为前缀的函数的变体(例如,调用fchdir而不是chdir)。)

您可以使用os.supports_fd检查* path *是否可以指定为平台上特定Function的文件 Descriptors。如果此Function不可用,则使用它将引发NotImplementedError

如果该函数还支持* dir_fd follow_symlinks 参数,则在提供 path *作为文件 Descriptors 时指定其中一个是错误的。

  • 相对于目录 Descriptors 的路径: 如果* dir_fd 不是None,则它应该是引用目录的文件 Descriptors,并且要操作的路径应该是相对的;路径将相对于该目录。如果路径是绝对路径,则 dir_fd *将被忽略。 (对于 POSIX 系统,Python 将使用at后缀调用该函数的变体,并且可能以f作为前缀(例如,调用faccessat而不是access)。

您可以使用os.supports_dir_fd检查平台上的特定Function是否支持* dir_fd *。如果不可用,使用它将引发NotImplementedError

  • 不要跟随符号链接: 如果* follow_symlinks *是False,并且要操作的路径的最后一个元素是符号链接,则该函数将在符号链接本身而不是链接所指向的文件上操作。 (对于 POSIX 系统,Python 将调用该函数的l...变体.)
  • 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_OKW_OKX_OK中的一个或多个以进行包含性测试权限。如果允许访问,则返回True,如果不允许则返回False。有关更多信息,请参见 Unix 手册页 access(2) *。

此Function可以支持指定相对于目录 Descriptors 的路径不遵循符号链接

如果* effective_ids True,则access()将使用有效的 uid/gid 而非实际的 uid/gid 执行访问检查。您的平台可能不支持 effective_ids *;您可以使用os.supports_effective_ids检查它是否可用。如果不可用,使用它将引发NotImplementedError

Note

使用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()

Note

即使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 *。

此Function可以支持指定文件 Descriptors。Descriptors 必须引用打开的目录,而不是打开的文件。

此函数可以引发OSError和子类,例如FileNotFoundErrorPermissionErrorNotADirectoryError

用参数path引发auditing event os.chdir

3.3 版的新增Function:在某些平台上增加了对将* path *指定为文件 Descriptors 的支持。

在版本 3.6 中更改:接受path-like object

此Function可以支持不遵循符号链接

用参数pathflags引发auditing event os.chflags

Availability: Unix.

3.3 版的新Function:* follow_symlinks *参数。

在版本 3.6 中更改:接受path-like object

此Function可以支持指定文件 Descriptors相对于目录 Descriptors 的路径不遵循符号链接

Note

尽管 Windows 支持chmod(),但是您只能使用它设置文件的只读标志(passstat.S_IWRITEstat.S_IREAD常量或相应的整数值)。所有其他位均被忽略。

用参数pathmodedir_fd引发auditing event os.chmod

3.3 版中的新增Function:添加了对将* path 指定为打开文件 Descriptors 以及 dir_fd follow_symlinks *参数的支持。

在版本 3.6 中更改:接受path-like object

  • os. chown(* path uid gid **,* dir_fd = None follow_symlinks = True *)
    • 将* path 的所有者和组标识更改为数字 uid gid *。要使其中一个 ID 保持不变,请将其设置为-1.

此Function可以支持指定文件 Descriptors相对于目录 Descriptors 的路径不遵循符号链接

有关接受除数字 ID 之外的名称的更高级Function,请参见shutil.chown()

用参数pathuidgiddir_fd引发auditing event os.chown

Availability: Unix.

3.3 版中的新增Function:添加了对将* path 指定为打开文件 Descriptors 以及 dir_fd follow_symlinks *参数的支持。

在版本 3.6 中更改:支持path-like object

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

Availability: Unix.

在版本 3.6 中更改:接受path-like object

  • os. fchdir(* fd *)
    • 将当前工作目录更改为文件 Descriptors* fd *表示的目录。Descriptors 必须引用打开的目录,而不是打开的文件。从 Python 3.3 开始,这等效于os.chdir(fd)

用参数path引发auditing event os.chdir

Availability: Unix.

  • os. getcwd ( )

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

    • 返回一个代表当前工作目录的字节串。

在版本 3.8 中更改:该函数现在在 Windows 上使用 UTF-8 编码,而不是在 ANSI 代码页上:原理请参见 PEP 529。 Windows 不再弃用该Function。

  • os. lchflags(* path flags *)
    • 将* path 的标志设置为数字 flags *,例如chflags(),但不要跟随符号链接。从 Python 3.3 开始,这等效于os.chflags(path, flags, follow_symlinks=False)

用参数pathflags引发auditing event os.chflags

Availability: Unix.

在版本 3.6 中更改:接受path-like object

  • os. lchmod(* path mode *)
    • 将* path 的模式更改为数字 mode 。如果 path 是符号链接,则这会影响符号链接而不是目标。请参阅chmod()的文档,以获取 mode *的可能值。从 Python 3.3 开始,这等效于os.chmod(path, mode, follow_symlinks=False)

用参数pathmodedir_fd引发auditing event os.chmod

Availability: Unix.

在版本 3.6 中更改:接受path-like object

  • os. lchown(* path uid gid *)
    • 将* path 的所有者和组标识更改为数字 uid gid *。此Function将不遵循符号链接。从 Python 3.3 开始,这等效于os.chown(path, uid, gid, follow_symlinks=False)

用参数pathuidgiddir_fd引发auditing event os.chown

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 *来提供相对于目录 Descriptors 的路径不遵循符号链接

用参数srcdstsrc_dir_fddst_dir_fd引发auditing event os.link

Availability:Unix,Windows。

在版本 3.2 中更改:添加了 Windows 支持。

3.3 版的新增Function:添加了* src_dir_fd dst_dir_fd follow_symlinks *参数。

在版本 3.6 中更改:接受_和* dst *的path-like object

  • os. listdir(* path ='.'*)
    • 返回一个列表,其中包含* path *给出的目录中条目的名称。该列表以任意 Sequences 排列,并且不包含特殊条目'.''..',即使它们存在于目录中也是如此。
  • path 可能是path-like object。如果 path *为bytes类型(直接或passPathLike接口间接),则返回的文件名也将为bytes类型;在所有其他情况下,它们的类型将为str

此Function还可以支持指定文件 Descriptors;文件 Descriptors 必须引用目录。

用参数path引发auditing event os.listdir

Note

要将str文件名编码为bytes,请使用fsencode()

See also

scandir()函数返回目录条目以及文件属性信息,从而为许多常见用例提供了更好的性能。

在版本 3.2 中更改:* path *参数变为可选。

版本 3.3 中的新增Function:添加了对将* path *指定为打开文件 Descriptors 的支持。

在版本 3.6 中更改:接受path-like object

  • os. lstat(* path **,* dir_fd = None *)
    • 在给定路径上执行等效于lstat()系统调用。与stat()相似,但不遵循符号链接。返回一个stat_result对象。

在不支持符号链接的平台上,这是stat()的别名。

从 Python 3.3 开始,这等效于os.stat(path, dir_fd=dir_fd, follow_symlinks=False)

此Function还可以支持相对于目录 Descriptors 的路径

See also

stat()Function。

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

在版本 3.3 中进行了更改:添加了* dir_fd *参数。

在版本 3.6 中更改:接受_和* dst *的path-like object

在版本 3.8 中进行了更改:在 Windows 上,现在打开表示另一个路径(名称代理)的重新分析点,包括符号链接和目录连接。os 针对stat()解析其他种类的重新解析点。

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

如果目录已经存在,则引发FileExistsError

在某些系统上,* mode 被忽略。使用它时,当前的 umask 值将首先被屏蔽掉。如果设置了除最后 9 个之外的其他位(即 mode *的八进制表示形式的最后 3 位),则它们的含义取决于平台。在某些平台上,它们将被忽略,您应该显式调用chmod()进行设置。

此Function还可以支持相对于目录 Descriptors 的路径

也可以创建临时目录。请参见tempfile模块的tempfile.mkdtemp()Function。

用参数pathmodedir_fd引发auditing event os.mkdir

版本 3.3 中的新Function:* dir_fd *参数。

在版本 3.6 中更改:接受path-like object

  • os. makedirs(* name mode = 0o777 exist_ok = False *)
    • 递归目录创建Function。类似于mkdir(),但是使所有中间级目录都包含叶子目录。
  • mode *参数传递给mkdir()以创建叶子目录;有关其解释的信息,请参见mkdir()说明。要设置任何新创建的父目录的文件许可权位,可以在调用makedirs()之前设置 umask。现有父目录的文件权限位不会更改。

如果* exist_ok *为False(默认值),则在目标目录已存在的情况下引发FileExistsError

Note

如果要创建的路径元素包含pardir(例如,在 UNIX 系统上为“ ..”),则makedirs()将变得混乱。

此函数正确处理 UNC 路径。

用参数pathmodedir_fd引发auditing event os.mkdir

版本 3.2 中的新Function:* exist_ok *参数。

在版本 3.4.1 中进行了更改:在 Python 3.4.1 之前,如果* exist_ok True并且目录存在,则如果 mode *与现有目录的模式不匹配,则makedirs()仍会引发错误。由于无法安全实现此行为,因此在 Python 3.4.1 中将其删除。参见bpo-21082

在版本 3.6 中更改:接受path-like object

在版本 3.7 中更改:* mode *参数不再影响新创建的中间级目录的文件许可权位。

  • os. mkfifo(* path mode = 0o666 **,* dir_fd = None *)
    • 使用数字模式* mode 创建名为 path *的 FIFO(命名管道)。当前的 umask 值首先从该模式中屏蔽掉。

此Function还可以支持相对于目录 Descriptors 的路径

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

Availability: Unix.

版本 3.3 中的新Function:* dir_fd *参数。

在版本 3.6 中更改:接受path-like object

  • os. mknod(* path mode = 0o600 device = 0 **,* dir_fd = None *)
    • 创建一个名为* path *的文件系统节点(文件,设备专用文件或命名管道)。 * mode 指定使用权限和要创建的节点类型,将它们与stat.S_IFREGstat.S_IFCHRstat.S_IFBLKstat.S_IFIFO(这些常量在stat中可用)之一组合(按位或)。对于stat.S_IFCHRstat.S_IFBLK device *定义新创建的设备专用文件(可能使用os.makedev()),否则将被忽略。

此Function还可以支持相对于目录 Descriptors 的路径

Availability: Unix.

版本 3.3 中的新Function:* dir_fd *参数。

在版本 3.6 中更改:接受path-like object

  • os. major(* device *)

    • 从原始设备号(通常是statst_devst_rdev字段)中提取设备主 Numbers。
  • os. minor(* device *)

    • 从原始设备号(通常是statst_devst_rdev字段)中提取设备次设备号。
  • os. makedev(主要次要)

    • 从主要和次要设备号组成一个原始设备号。
  • os. pathconf(* path name *)

    • 返回与命名文件有关的系统配置信息。 * name 指定要检索的配置值;它可以是一个字符串,它是定义的系统值的名称;这些名称在许多标准(POSIX.1,Unix 95,Unix 98 等)中指定。一些平台还定义了其他名称。主机 os 已知的名称在pathconf_names字典中给出。对于未包含在该 Map 中的配置变量,也可接受为 name *传递整数。

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

此Function可以支持指定文件 Descriptors

Availability: Unix.

在版本 3.6 中更改:接受path-like object

  • os. pathconf_names
    • pathconf()fpathconf()接受的字典 Map 名称到主机 os 为此名称定义的整数值。这可用于确定系统已知的名称集。

Availability: Unix.

  • os. readlink(* path **,* dir_fd = None *)
    • 返回表示符号链接指向的路径的字符串。结果可以是绝对路径名,也可以是相对路径名。如果是相对的,则可以使用os.path.join(os.path.dirname(path), result)转换为绝对路径名。

如果* path 是字符串对象(直接或passPathLike接口间接),则结果也将是字符串对象,并且该调用可能会引发 UnicodeDecodeError。如果 path *是字节对象(直接或间接),则结果将是字节对象。

此Function还可以支持相对于目录 Descriptors 的路径

try解析可能包含链接的路径时,请使用realpath()正确处理递归和平台差异。

Availability:Unix,Windows。

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

版本 3.3 中的新Function:* dir_fd *参数。

在版本 3.6 中更改:在 Unix 上接受path-like object

在版本 3.8 中更改:在 Windows 上接受path-like object和字节对象。

在版本 3.8 中进行了更改:添加了对目录连接的支持,并更改为返回替换路径(通常包含\\?\前缀),而不是先前返回的可选“打印名称”字段。

  • os. remove(* path **,* dir_fd = None *)

此Function可以支持相对于目录 Descriptors 的路径

在 Windows 上,try删除正在使用的文件会引发异常。在 Unix 上,目录条目已删除,但是分配给文件的存储空间不再可用,直到不再使用原始文件为止。

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

用参数pathdir_fd引发auditing event os.remove

版本 3.3 中的新Function:* dir_fd *参数。

在版本 3.6 中更改:接受path-like object

  • os. removedirs(* name *)
    • 递归删除目录。像rmdir()一样工作,不同之处在于,如果成功删除了叶目录,则removedirs()会try依次删除* path *中提到的每个父目录,直到引发错误为止(该错误会被忽略,因为它通常意味着父目录不为空)。例如,os.removedirs('foo/bar/baz')将首先删除目录'foo/bar/baz',然后删除'foo/bar''foo'(如果它们为空)。如果无法成功删除叶目录,则引发OSError

用参数pathdir_fd引发auditing event os.remove

在版本 3.6 中更改:接受path-like object

  • os. rename(* src dst **,* src_dir_fd = None dst_dir_fd = None *)
    • 将文件或目录* src 重命名为 dst 。如果存在 dst *,则在许多情况下,该操作将失败并带有OSError子类:

在 Windows 上,如果* dst *存在,则始终引发FileExistsError

在 Unix 上,如果* src 是文件,而 dst 是目录,反之亦然,则分别引发IsADirectoryErrorNotADirectoryError。如果两个都是目录并且 dst 为空,则 dst 将被静默替换。如果 dst 是非空目录,则会引发OSError。如果两个都是文件,则 dst 会在用户许可的情况下被静默替换。如果 src dst *在不同的文件系统上,则该操作在某些 Unix 风格上可能会失败。如果成功,重命名将是原子操作(这是 POSIX 要求)。

该函数可以支持指定* src_dir_fd 和/或 dst_dir_fd *来提供相对于目录 Descriptors 的路径

如果要跨平台覆盖目标,请使用replace()

用参数srcdstsrc_dir_fddst_dir_fd引发auditing event os.rename

版本 3.3 中的新增Function:* src_dir_fd dst_dir_fd *参数。

在版本 3.6 中更改:接受_和* dst *的path-like object

  • os. renames(* old new *)
    • 递归目录或文件重命名Function。像rename()一样工作,除了首先try创建使新路径名良好所需的任何中间目录。重命名后,将使用removedirs()删除对应于旧名称最右边路径段的目录。

Note

如果您缺少删除叶子目录或文件所需的权限,则使用新的目录结构时此Function可能会失败。

用参数srcdstsrc_dir_fddst_dir_fd引发auditing event os.rename

在版本 3.6 中更改:接受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 *来提供相对于目录 Descriptors 的路径

用参数srcdstsrc_dir_fddst_dir_fd引发auditing event os.rename

版本 3.3 中的新Function。

在版本 3.6 中更改:接受_和* dst *的path-like object

  • os. rmdir(* path **,* dir_fd = None *)

此Function可以支持相对于目录 Descriptors 的路径

用参数pathdir_fd引发auditing event os.rmdir

版本 3.3 中的新Function:* dir_fd *参数。

在版本 3.6 中更改:接受path-like object

  • os. scandir(* path ='.'*)
    • 返回与_path *给出的目录中的条目相对应的os.DirEntry个对象的迭代器。条目以任意 Sequences 产生,并且不包括特殊条目'.''..'

使用scandir()而不是listdir()可以大大提高还需要文件类型或文件属性信息的代码的性能,因为如果 os 在扫描目录时提供了os.DirEntry对象,则它们会公开此信息。所有os.DirEntry方法都可以执行系统调用,但是is_dir()is_file()通常只需要系统调用即可进行符号链接; os.DirEntry.stat()在 Unix 上始终需要系统调用,但在 Windows 上仅需要一个用于符号链接的系统调用。

  • path 可能是path-like object。如果 path *的类型为bytes(直接或passPathLike接口间接),则每个os.DirEntrynamepath属性的类型将为bytes;在所有其他情况下,它们的类型将为str

此Function还可以支持指定文件 Descriptors;文件 Descriptors 必须引用目录。

用参数path引发auditing event os.scandir

scandir()迭代器支持context manager协议,并具有以下方法:

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

当迭代器用尽或垃圾回收时,或在迭代过程中发生错误时,将自动调用此方法。但是,建议显式调用它或使用with语句。

3.6 版的新Function。

以下示例显示了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)

Note

在基于 Unix 的系统上,scandir()使用系统的opendir()readdir()函数。在 Windows 上,它使用 Win32 FindFirstFileWFindNextFileW函数。

3.5 版中的新Function。

3.6 版的新Function:添加了对context manager协议和close()方法的支持。如果scandir()迭代器未耗尽也未明确关闭,则ResourceWarning将在其析构函数中发出。

该函数接受path-like object

在版本 3.7 中更改:在 Unix 上增加了对file descriptors的支持。

  • 类别 os. DirEntry
    • scandir()产生的对象,用于显示目录条目的文件路径和其他文件属性。

scandir()将在不进行其他系统调用的情况下提供尽可能多的此类信息。进行stat()lstat()系统调用时,os.DirEntry对象将缓存结果。

os.DirEntry实例不打算存储在长期存在的数据结构中;如果您知道文件元数据已更改,或者自调用scandir()以来已经过了很长时间,请调用os.stat(entry.path)以获取最新信息。

因为os.DirEntry方法可以进行 os 调用,所以它们也可以引发OSError。如果您需要对错误进行非常细粒度的控制,则可以在调用os.DirEntry方法之一并适当处理时捕获OSError

为了直接用作path-like objectos.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 *参数是file descriptor,则path属性与name属性相同。

如果scandir() * path *参数的类型为bytes,则path属性为bytes,否则为str。使用fsdecode()解码字节文件名。

  • 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(不包含以下符号链接);否则,返回True。如果该条目是任何其他类型的文件或不再存在,则返回False

结果被缓存在os.DirEntry对象上,并带有* follow_symlinks * TrueFalse的单独缓存。连同os.stat()一起呼叫os.stat()以获取最新信息。

在第一个未缓存的调用中,大多数情况下不需要系统调用。具体来说,对于非符号链接,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(不包含以下符号链接);否则,返回True。如果该条目是目录或其他非文件条目,或者不再存在,则返回False

结果被缓存在os.DirEntry对象上。根据is_dir()进行缓存,进行系统调用并引发异常。

结果被缓存在os.DirEntry对象上。致电os.path.islink()以获取最新信息。

在第一个未缓存的调用中,大多数情况下不需要系统调用。特别是,Windows 或 Unix 都不需要系统调用,除非某些 Unix 文件系统(例如网络文件系统)返回dirent.d_type == DT_UNKNOWN

此方法可以引发OSError,例如PermissionError,但是FileNotFoundError被捕获而不被引发。

  • stat(** follow_symlinks = True *)
    • 返回此条目的stat_result对象。默认情况下,此方法遵循符号链接。要设置符号链接,请添加follow_symlinks=False参数。

在 Unix 上,此方法始终需要系统调用。在 Windows 上,仅当* follow_symlinks *为True并且该条目是重新解析点(例如,符号链接或目录结点)时,才需要系统调用。

在 Windows 上,stat_resultst_inost_devst_nlink属性始终设置为零。调用os.stat()以获取这些属性。

结果被缓存在os.DirEntry对象上,并为* follow_symlinks * TrueFalse单独缓存。致电os.stat()以获取最新信息。

注意,os.DirEntrypathlib.Path的几个属性和方法之间存在很好的对应关系。特别地,name属性与is_dir()is_file()is_symlink()stat()方法具有相同的含义。

3.5 版中的新Function。

在 3.6 版中进行了更改:添加了对PathLike界面的支持。在 Windows 上增加了对bytes路径的支持。

  • os. stat(* path **,* dir_fd = None follow_symlinks = True *)
    • 获取文件或文件 Descriptors 的状态。在给定路径上执行等效于stat()系统调用。 * path *可以直接或passPathLike接口间接指定为字符串或字节,也可以指定为打开文件 Descriptors。返回一个stat_result对象。

此Function通常遵循符号链接。要设置符号链接,请添加参数follow_symlinks=False或使用lstat()

此Function可以支持指定文件 Descriptors不遵循符号链接

在 Windows 上,传递follow_symlinks=False将禁用所有名称代理重新解析点,其中包括符号链接和目录结点。与链接不相似或 os 无法遵循的其他类型的重新分析点将直接打开。当遵循多个链接的链时,这可能会导致返回原始链接,而不是阻止完全遍历的非链接。在这种情况下,要获取finally路径的统计结果,请使用os.path.realpath()函数尽可能地解析路径名称,并在结果上调用lstat()。这不适用于悬挂的符号链接或连接点,这会引发通常的异常。

Example:

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

See also

fstat()lstat()Function。

3.3 版的新增Function:添加了* dir_fd follow_symlinks *参数,指定了文件 Descriptors 而不是路径。

在版本 3.6 中更改:接受path-like object

在版本 3.8 中进行了更改:在 Windows 上,现在遵循 os 可以解析的所有重新解析点,并且传递follow_symlinks=False会禁用所有名称代理重新解析点。如果 os 达到了无法遵循的重新解析点,则* stat *现在将返回原始路径的信息,就像已指定follow_symlinks=False一样,而不是引发错误。

Attributes:

  • st_mode

    • 文件模式:文件类型和文件模式位(权限)。
  • st_ino

    • 与平台有关,但如果不为零,则以给定值st_dev唯一地标识文件。通常:
  • Unix 上的索引节点号,

  • Windows 上的file index

  • st_dev

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

    • 文件所有者的用户标识。
  • st_gid

    • 文件所有者的组标识符。
  • st_size

    • 文件大小(以字节为单位)(如果是常规文件或符号链接)。符号链接的大小是它包含的路径名的长度,没有终止的空字节。

Timestamps:

  • st_atime

    • 最近一次访问的时间,以秒为单位。
  • st_mtime

    • 最近一次内容修改的时间,以秒为单位。
  • st_ctime

    • Platform dependent:
  • Unix 上最近的元数据更改时间,

  • 在 Windows 上创建的时间,以秒为单位。

  • st_atime_ns

    • 最近访问的时间,以纳秒为单位表示为整数。
  • st_mtime_ns

    • 最近一次内容修改的时间,以纳秒为单位表示。
  • st_ctime_ns

    • Platform dependent:
  • Unix 上最近的元数据更改时间,

  • 在 Windows 上创建的时间,以纳秒为单位表示为整数。

Note

st_atimest_mtimest_ctime属性的确切含义和分辨率取决于 os 和文件系统。例如,在使用 FAT 或 FAT32 文件系统的 Windows 系统上,st_mtime具有 2 秒的分辨率,而st_atime仅具有 1 天的分辨率。有关详细信息,请参见您的 os 文档。

类似地,尽管st_atime_nsst_mtime_nsst_ctime_ns始终以纳秒表示,但是许多系统并不提供纳秒精度。在确实提供纳秒精度的系统上,用于存储st_atimest_mtimest_ctime的浮点对象不能保留所有精度,因此将有些不精确。如果需要确切的时间戳,则应始终使用st_atime_nsst_mtime_nsst_ctime_ns

在某些 Unix 系统(例如 Linux)上,以下属性也可能可用:

  • st_blocks

    • 为文件分配的 512 字节块数。当文件有孔时,它可能小于st_size/512.
  • st_blksize

    • “首选”块大小可实现有效的文件系统 I/O。以较小的块写入文件可能会导致读取-修改-重写效率低下。
  • st_rdev

    • 设备类型(如果是 inode 设备)。
  • st_flags

    • 用户定义的文件标志。

在其他 Unix 系统(例如 FreeBSD)上,以下属性可能可用(但只有在 root try使用它们时才可以填写):

  • st_gen

    • 文件生成号。
  • st_birthtime

    • 文件创建时间。

在 Solaris 及其衍生产品上,以下属性也可能可用:

  • st_fstype
    • 唯一标识包含文件的文件系统类型的字符串。

在 Mac OS 系统上,以下属性也可能可用:

  • st_rsize

    • 文件的实际大小。
  • st_creator

    • 文件的创建者。
  • st_type

    • File type.

在 Windows 系统上,以下属性也可用:

  • st_file_attributes

    • Windows 文件属性:GetFileInformationByHandle()返回的BY_HANDLE_FILE_INFORMATION结构的dwFileAttributes成员。请参见stat模块中的FILE_ATTRIBUTE_*常量。
  • st_reparse_tag

    • st_file_attributes设置为FILE_ATTRIBUTE_REPARSE_POINT时,此字段包含用于标识重新解析点类型的标签。请参见stat模块中的IO_REPARSE_TAG_*常量。

标准模块stat定义了对从stat结构中提取信息有用的函数和常量。 (在 Windows 上,某些项目填充有伪值.)

为了向后兼容,还可以访问至少_1 个整数的stat_result实例,以st_inost_devst_nlinkst_uidst_gidst_sizest_atime的 Sequences 提供stat结构的最重要(且可移植)的成员。 ,st_mtimest_ctime。某些实现可能在末尾添加更多项。为了与旧版本的 Python 兼容,将stat_result作为 Tuples 访问总是返回整数。

版本 3.3 中的新Function:添加了st_atime_nsst_mtime_nsst_ctime_ns成员。

3.5 版的新Function:在 Windows 上添加了st_file_attributes成员。

在版本 3.5 中进行了更改:Windows 现在在可用时将文件索引返回为st_ino

3.7 版中的新增Function:在 Solaris /衍生产品中添加了st_fstype成员。

3.8 版的新Function:在 Windows 上添加了st_reparse_tag成员。

在 3.8 版中进行了更改:在 Windows 上,st_mode成员现在可以根据需要将特殊文件标识为S_IFCHRS_IFIFOS_IFBLK

  • os. statvfs(* path *)
    • 在给定路径上执行statvfs()系统调用。返回值是一个对象,其属性描述给定路径上的文件系统,并与statvfs结构的成员相对应,即f_bsizef_frsizef_blocksf_bfreef_bavailf_filesf_ffreef_favailf_flagf_namemaxf_fsid

f_flag属性的位标志定义了两个模块级常量:如果设置了ST_RDONLY,则文件系统以只读方式安装;如果设置了ST_NOSUID,则禁用或不支持 setuid/setgid 位的语义。

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

此Function可以支持指定文件 Descriptors

Availability: Unix.

在版本 3.2 中更改:添加了ST_RDONLYST_NOSUID常量。

版本 3.3 中的新增Function:添加了对将* path *指定为打开文件 Descriptors 的支持。

在版本 3.4 中更改:添加了ST_NODEVST_NOEXECST_SYNCHRONOUSST_MANDLOCKST_WRITEST_APPENDST_IMMUTABLEST_NOATIMEST_NODIRATIMEST_RELATIME常量。

在版本 3.6 中更改:接受path-like object

3.7 版的新Function:添加了f_fsid

  • os. supports_dir_fd
    • 一个set对象,指示os模块中的哪些Function接受其* dir_fd 参数的打开文件 Descriptors。不同的平台提供不同的Function,并且 Python 用于实现 dir_fd 参数的基础Function并非在 Python 支持的所有平台上都可用。为了保持一致性,可能支持 dir_fd *的函数始终允许指定参数,但是如果在本地不可用时使用了该Function,则会抛出异常。 (在所有平台上始终支持为 dir_fd *指定None.)

若要检查特定函数的* dir_fd 参数是否接受打开的文件 Descriptors,请在supports_dir_fd上使用in运算符。例如,如果os.stat()在本地平台上接受 dir_fd *的打开文件 Descriptors,则此表达式的值为True

os.stat in os.supports_dir_fd

当前* dir_fd *参数仅在 Unix 平台上有效;它们都无法在 Windows 上运行。

版本 3.3 中的新Function。

  • os. supports_effective_ids
    • 一个set对象,指示os.access()是否允许在本地平台上为其_valid_ids 参数指定True。 (在所有平台上始终支持为False指定 effective_ids.)如果本地平台支持,则集合将包含os.access();否则它将为空。

如果os.access()在本地平台上支持effective_ids=True,则此表达式的值为True

os.access in os.supports_effective_ids

当前* effective_ids *仅在 Unix 平台上受支持;在 Windows 上不起作用。

版本 3.3 中的新Function。

  • os. supports_fd
    • 一个set对象,指示os模块中的哪些Function允许将其* path 参数指定为本地平台上的打开文件 Descriptors。不同的平台提供不同的Function,Python 使用的底层Function接受打开的文件 Descriptors,因为 path *参数并非在 Python 支持的所有平台上都可用。

要确定某个特定函数是否允许为其* path 参数指定打开文件 Descriptors,请使用supports_fd上的in运算符。例如,如果os.chdir()在本地平台上接受 path *的打开文件 Descriptors,则此表达式的值为True

os.chdir in os.supports_fd

版本 3.3 中的新Function。

若要检查特定函数的* follow_symlinks *参数是否接受False,请对supports_follow_symlinks使用in运算符。例如,如果在本地平台上调用os.stat()时可以指定follow_symlinks=False,则此表达式的值为True

os.stat in os.supports_follow_symlinks

版本 3.3 中的新Function。

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

在 Windows 上,符号链接表示文件或目录,并且不会动态变形为目标。如果存在目标,则将创建符号链接的类型以进行匹配。否则,如果* target_is_directory True,则符号链接将被创建为目录,否则,文件符号链接将被创建(默认)。在非 Windows 平台上, target_is_directory *被忽略。

此Function可以支持相对于目录 Descriptors 的路径

Note

在 Windows 10 的较新版本上,如果启用了开发人员模式,则非特权帐户可以创建符号链接。如果开发人员模式不可用/未启用,则需要* SeCreateSymbolicLinkPrivilege *特权,或者必须以 Management 员身份运行该过程。

当非特权用户调用该函数时,将引发OSError

用参数srcdstdir_fd引发auditing event os.symlink

Availability:Unix,Windows。

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

3.3 版中的新增Function:添加了* dir_fd 参数,现在允许在非 Windows 平台上使用 target_is_directory *。

在版本 3.6 中更改:接受_和* dst *的path-like object

在版本 3.8 中进行了更改:在具有开发人员模式的 Windows 上添加了对未提升符号链接的支持。

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

Availability: Unix.

版本 3.3 中的新Function。

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

此Function可以支持指定文件 Descriptors

用参数pathlength引发auditing event os.truncate

Availability:Unix,Windows。

版本 3.3 中的新Function。

在版本 3.5 中进行了更改:添加了对 Windows 的支持

在版本 3.6 中更改:接受path-like object

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

用参数pathdir_fd引发auditing event os.remove

版本 3.3 中的新Function:* 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)形式的 2Tuples,其中每个成员都是一个表示纳秒的 int。

  • 如果* times *不是None,则它必须是(atime, mtime)形式的 2Tuples,其中每个成员都是表示秒的 int 或 float。

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

同时为* time ns *指定 Tuples 是错误的。

请注意,根据 os 记录访问和修改时间的分辨率,后续的stat()调用可能不会返回您在此处设置的确切时间。参见stat()。保留精确时间的最佳方法是使用os.stat()结果对象中的* st_atime_ns st_mtime_ns 字段,并使用 uns 的 ns *参数。

此Function可以支持指定文件 Descriptors相对于目录 Descriptors 的路径不遵循符号链接

用参数pathtimesnsdir_fd引发auditing event os.utime

3.3 版的新增Function:添加了对将* path 指定为打开文件 Descriptors 以及 dir_fd follow_symlinks ns *参数的支持。

在版本 3.6 中更改:接受path-like object

  • os. walk(* top topdown = True onerror = None followlinks = False *)
    • pass自上而下或自下而上浏览目录树来生成目录树中的文件名。对于以目录* top 为根的树中的每个目录(包括 top *本身),它会生成一个三 Tuples(dirpath, dirnames, filenames)
  • dirpath *是一个字符串,是目录的路径。 * dirnames dirpath *中子目录名称的列表(不包括'.''..')。 * filenames dirpath 中非目录文件名称的列表。请注意,列表中的名称不包含路径成分。要获取 dirpath 中文件或目录的完整路径(以 top *开头),请执行os.path.join(dirpath, name)

如果可选参数* topdown True或未指定,则将在其任何子目录的三 Tuples 之前生成目录的三 Tuples(目录是自上而下生成的)。如果 topdown False,则在其所有子目录的三 Tuples 之后生成目录的三 Tuples(目录是自下而上生成的)。不管 topdown *的值如何,在生成目录及其子目录的 Tuples 之前,都将检索子目录的列表。

当* topdown True时,调用者可以就地修改 dirnames 列表(也许使用del或切片分配),而walk()将仅递归到其名称保留在 dirnames 中的子目录中;这可用于修剪搜索,强加特定的访问 Sequences,甚至在调用方再次恢复walk()之前,甚至通知walk()有关呼叫者创建或重命名的目录。当 topdown False时修改 dirnames 对步行的行为没有影响,因为在自下而上模式下, dirnames 中的目录是在生成 dirpath *本身之前生成的。

默认情况下,来自scandir()调用的错误将被忽略。如果指定了可选参数* onerror *,则它应该是一个函数。它将使用一个参数OSError实例进行调用。它可以报告错误以 continue 进行遍历,或者引发异常以中止遍历。请注意,文件名可用作异常对象的filename属性。

默认情况下,walk()不会进入解析为目录的符号链接。在支持链接的系统上,将* followlinks *设置为True以访问符号链接指向的目录。

Note

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

Note

如果传递相对路径名,请不要在恢复walk()之间更改当前的工作目录。 walk()从不更改当前目录,并假定其调用者也没有。

此示例显示起始目录下每个目录中非目录文件占用的字节数,除了它不在任何 CVS 子目录下显示:

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

在下一个示例(shutil.rmtree()的简单实现)中,使树自下而上是必不可少的,rmdir()不允许在目录为空之前删除目录:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))

在版本 3.5 中进行了更改:此函数现在调用os.scandir()而不是os.listdir(),pass减少对os.stat()的调用次数使其变得更快。

在版本 3.6 中更改:接受path-like object

  • os. fwalk(* top ='.' topdown = True onerror = None **,* follow_symlinks = False dir_fd = None *)
    • 它的行为与walk()完全相同,除了它产生一个四 Tuples(dirpath, dirnames, filenames, dirfd),并且支持dir_fd
  • dirpath dirnames filenames walk()输出相同,并且 dirfd 是引用目录 dirpath *的文件 Descriptors。

此Function始终支持相对于目录 Descriptors 的路径不遵循符号链接。但是请注意,与其他函数不同,* follow_symlinks *的fwalk()默认值为False

Note

由于fwalk()会产生文件 Descriptors,因此它们仅在下一个迭代步骤之前有效,因此,如果要保留更长的时间,则应复制它们(例如,使用dup())。

此示例显示起始目录下每个目录中非目录文件占用的字节数,除了它不在任何 CVS 子目录下显示:

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    print(root, "consumes", end="")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end="")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS directories

在下一个示例中,使树自下而上是必不可少的:rmdir()不允许在目录为空之前删除目录:

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

Availability: Unix.

版本 3.3 中的新Function。

在版本 3.6 中更改:接受path-like object

在 3.7 版中进行了更改:添加了对bytes路径的支持。

  • os. memfd_create(* name * [,* flags = os.MFD_CLOEXEC *])
    • 创建一个匿名文件并返回引用该文件的文件 Descriptors。 * flags *必须是系统上可用的os.MFD_*常量之一(或它们的按位 ORed 组合)。默认情况下,新文件 Descriptors 为non-inheritable
  • name *中提供的名称用作文件名,并将显示为目录/proc/self/fd/中相应符号链接的目标。显示的名称始终以memfd:为前缀,并且仅用于调试目的。名称不会影响文件 Descriptors 的行为,因此,多个文件可以具有相同的名称,而不会产生任何副作用。

Availability:Linux 3.17 或更高版本以及 glibc 2.27 或更高版本。

3.8 版的新Function。

  • 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

Availability:Linux 3.17 或更高版本以及 glibc 2.27 或更高版本。 MFD_HUGE*标志仅从 Linux 4.14 开始可用。

3.8 版的新Function。

Linux 扩展属性

版本 3.3 中的新Function。

这些Function仅在 Linux 上可用。

  • os. getxattr(* path attribute **,* follow_symlinks = True *)
    • 返回* path 的扩展文件系统属性 attribute *的值。 * attribute *可以是字节或 str(直接或passPathLike接口间接)。如果为 str,则使用文件系统编码进行编码。

此Function可以支持指定文件 Descriptors不遵循符号链接

用参数pathattribute引发auditing event os.getxattr

在版本 3.6 中更改:接受path-like object作为* path attribute *。

  • os. listxattr(* path = None **,* follow_symlinks = True *)
    • 返回* path 上扩展文件系统属性的列表。列表中的属性表示为使用文件系统编码解码的字符串。如果 path *为None,则listxattr()将检查当前目录。

此Function可以支持指定文件 Descriptors不遵循符号链接

用参数path引发auditing event os.listxattr

在版本 3.6 中更改:接受path-like object

  • os. removexattr(* path attribute **,* follow_symlinks = True *)
    • 从* path 移除扩展文件系统属性 attribute *。 * attribute *应该是字节或 str(直接或passPathLike接口间接)。如果是字符串,则使用文件系统编码进行编码。

此Function可以支持指定文件 Descriptors不遵循符号链接

用参数pathattribute引发auditing event os.removexattr

在版本 3.6 中更改:接受path-like object作为* path attribute *。

  • os. setxattr(* path attribute value flags = 0 **,* follow_symlinks = True *)
    • 将* path 上的扩展文件系统属性 attribute 设置为 value *。 * attribute *必须是没有嵌入式 NUL 的字节或 str(直接或passPathLike接口间接)。如果为 str,则使用文件系统编码进行编码。 标志可以是XATTR_REPLACEXATTR_CREATE。如果给定XATTR_REPLACE并且该属性不存在,则将引发EEXISTS。如果给定XATTR_CREATE并且该属性已经存在,则不会创建该属性,并且会引发ENODATA

此Function可以支持指定文件 Descriptors不遵循符号链接

Note

Linux 内核版本低于 2.6.39 的错误导致某些文件系统上的 flags 参数被忽略。

用参数pathattributevalueflags引发auditing event os.setxattr

在版本 3.6 中更改:接受path-like object作为* path attribute *。

  • os. XATTR_SIZE_MAX

    • 扩展属性值的最大大小。当前,这是 Linux 上的 64 KiB。
  • os. XATTR_CREATE

    • 这是setxattr()中的 flags 参数的可能值。它指示该操作必须创建一个属性。
  • os. XATTR_REPLACE

    • 这是setxattr()中的 flags 参数的可能值。它指示该操作必须替换现有属性。

Process Management

这些Function可用于创建和 Management 过程。

各种exec*函数获取加载到进程中的新程序的参数列表。在每种情况下,这些参数中的第一个作为其自己的名称而不是作为用户可能在命令行上键入的参数传递给新程序。对于 C 程序员,这是传递给程序main()argv[0]。例如,os.execv('/bin/echo', ['foo', 'bar'])将仅在标准输出上打印barfoo似乎将被忽略。

  • os. abort ( )

    • 生成一个SIGABRTsignal 到当前进程。在 Unix 上,默认行为是产生核心转储。在 Windows 上,该过程立即返回退出代码3。请注意,调用此函数将不会调用passsignal.signal()SIGABRT注册的 Pythonsignal 处理程序。
  • os. add_dll_directory(* path *)

    • 将路径添加到 DLL 搜索路径。

解决导入的扩展模块的依赖项(模块本身pass sys.path 解析)以及ctypes时,将使用此搜索路径。

pass在返回的对象上调用 close() 或在with语句中使用它来删除目录。

有关如何加载 DLL 的更多信息,请参见Microsoft documentation

用参数path引发auditing event os.add_dll_directory

Availability: Windows.

3.8 版中的新增Function:早期版本的 CPython 将使用当前进程的默认行为来解析 DLL。这导致不一致,例如仅有时搜索 PATH或当前工作目录,并且 OS Function(例如AddDllDirectory)无效。

在 3.8 中,DLL 的两种主要加载方式现在显式覆盖了整个进程的行为,以确保一致性。有关更新库的信息,请参见porting notes

  • os. execl(* path arg0 arg1 ... *)
  • os. execle(* path arg0 arg1 ... env *)
  • os. execlp(* file arg0 arg1 ... *)
  • os. execlpe(* file arg0 arg1 ... env *)
  • os. execv(* path args *)
  • os. execve(* path args env *)
  • os. execvp(* file args *)
  • os. execvpe(* file args env *)
    • 这些Function都执行一个新程序,以替换当前进程。他们不回来。在 Unix 上,新的可执行文件已加载到当前进程中,并且将具有与调用方相同的进程 ID。错误将被报告为OSError个 exception。

当前过程将立即替换。打开文件对象和 Descriptors 不会刷新,因此,如果这些打开文件上有缓冲数据,则应在调用exec*函数之前使用sys.stdout.flush()os.fsync()刷新它们。

exec*函数的“ l”和“ v”变体在命令行参数的传递方式上有所不同。如果在编写代码时参数数量固定,则“ l”变体可能是最容易使用的;各个参数只是成为execl*()函数的附加参数。当参数的数量可变时,“ v”变体很好,参数以列表或 Tuples 的形式作为* args *参数传递。在这两种情况下,子进程的参数都应以正在运行的命令的名称开头,但这不是强制性的。

在末尾(execlp()execlpe()execvp()execvpe())附近包含“ p”的变体将使用 PATH环境变量来定位程序* file *。当替换环境时(使用exec*e变体中的一种,在下一段中讨论),新环境将用作 PATH变量的源。其他变体execl()execle()execv()execve()不会使用 PATH变量来定位可执行文件; * path *必须包含适当的绝对或相对路径。

对于execle()execlpe()execve()execvpe()(请注意,所有这些都以“ e”结尾),* env *参数必须是用于定义新进程的环境变量的 Map(使用这些变量代替当前变量)过程的环境);函数execl()execlp()execv()execvp()都使新进程继承当前进程的环境。

对于某些平台上的execve(),也可以将* path *指定为打开文件 Descriptors。您的平台可能不支持此Function;您可以使用os.supports_fd检查它是否可用。如果不可用,使用它将引发NotImplementedError

用参数pathargsenv引发auditing event os.exec

Availability:Unix,Windows。

版本 3.3 中的新增Function:添加了对将* path *指定为execve()的打开文件 Descriptors 的支持。

在版本 3.6 中更改:接受path-like object

  • os. _exit(* n *)
    • 退出状态为* n *的进程,而不调用清理处理程序,刷新 stdio 缓冲区等。

Note

退出的标准方式是sys.exit(n)_exit()通常只应在fork()之后的子进程中使用。

定义了以下退出代码,并且可以与_exit()一起使用,尽管它们不是必需的。这些通常用于用 Python 编写的系统程序,例如邮件服务器的外部命令传递程序。

Note

其中有些可能并非在所有 Unix 平台上都可用,因为存在一些差异。这些常量是在基础平台定义的地方定义的。

  • os. EX_OK
    • 退出代码,表示未发生任何错误。

Availability: Unix.

  • os. EX_USAGE
    • 退出代码,表示该命令使用不正确,例如,给出了错误数量的参数时。

Availability: Unix.

  • os. EX_DATAERR
    • 退出代码,表示 Importing 数据不正确。

Availability: Unix.

  • os. EX_NOINPUT
    • 退出代码,表示 Importing 文件不存在或不可读。

Availability: Unix.

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

Availability: Unix.

  • os. EX_NOHOST
    • 退出代码,意味着指定的主机不存在。

Availability: Unix.

  • os. EX_UNAVAILABLE
    • 退出代码,表示所需的服务不可用。

Availability: Unix.

  • os. EX_SOFTWARE
    • 退出代码,表示检测到内部软件错误。

Availability: Unix.

  • os. EX_OSERR
    • 退出代码,表示检测到 os 错误,例如无法分叉或创建管道。

Availability: Unix.

  • os. EX_OSFILE
    • 退出代码,表示某些系统文件不存在,无法打开或发生其他错误。

Availability: Unix.

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

Availability: Unix.

  • os. EX_IOERR
    • 退出代码,表示对某些文件执行 I/O 时发生错误。

Availability: Unix.

  • os. EX_TEMPFAIL
    • 退出代码,表示发生了暂时的故障。这表示可能并非 true 错误的内容,例如在重试操作期间无法构建的网络连接。

Availability: Unix.

  • os. EX_PROTOCOL
    • 退出代码,表示协议交换是非法,无效或无法理解的。

Availability: Unix.

  • os. EX_NOPERM
    • 退出代码,表示没有足够的权限执行该操作(但不适用于文件系统问题)。

Availability: Unix.

  • os. EX_CONFIG
    • 退出代码,表示发生某种配置错误。

Availability: Unix.

  • os. EX_NOTFOUND
    • 退出代码,其含义类似于“未找到条目”。

Availability: Unix.

  • os. fork ( )
    • 分叉子进程。在子级中返回0,在父级中返回子级的进程 ID。如果发生错误,将引发OSError

请注意,从线程使用fork()时,包括 FreeBSD <= 6.3 和 Cygwin 在内的某些平台存在已知问题。

引发不带参数的auditing event os.fork

在 3.8 版中进行了更改:不再支持在子解释器中调用fork()(引发RuntimeError)。

Warning

有关将 SSL 模块与 fork()结合使用的应用程序,请参见ssl

Availability: Unix.

  • os. forkpty ( )
    • 使用新的伪终端作为子进程的控制终端,分叉子进程。返回Pair(pid, fd),其中* pid 在子代中是0,新子代的进程 ID 在父代中,而 fd *是伪终端的主端的文件 Descriptors。对于更便携的方法,请使用pty模块。如果发生错误,将引发OSError

引发不带参数的auditing event os.forkpty

在 3.8 版中进行了更改:不再支持在子解释器中调用forkpty()(引发RuntimeError)。

Availability:某些 Unix 风格。

  • os. kill(* pid sig *)
    • 发送 signal* sig 到进程 pid *。主机平台上可用的特定 signal 的常量在signal模块中定义。

Windows:signal.CTRL_C_EVENTsignal.CTRL_BREAK_EVENTsignal 是特殊 signal,只能发送到共享公共控制台窗口的控制台进程,例如某些子进程。 * sig 的任何其他值将导致该进程被 TerminateProcess API 无条件终止,并且退出代码将设置为 sig *。 Windows 版本的kill()还需要杀死进程句柄。

另请参见signal.pthread_kill()

用参数pidsig引发auditing event os.kill

版本 3.2 中的新Function:Windows 支持。

  • os. killpg(* pgid sig *)
    • 将 signal* sig 发送到进程组 pgid *。

用参数pgidsig引发auditing event os.killpg

Availability: Unix.

  • os. nice(增量)
    • 将* increment *添加到进程的“ niceness”中。返回新的美好。

Availability: Unix.

  • os. plock(* op *)
    • 将程序段锁定到内存中。 * op *(在<sys/lock.h>中定义)的值确定哪些段被锁定。

Availability: Unix.

  • os. popen(* cmd mode ='r' buffering = -1 *)
    • 打开到命令* cmd 或来自命令 cmd 的管道。返回值是连接到管道的打开文件对象,可以根据 mode *是'r'(默认值)还是'w'进行读取或写入。 * buffering *参数的含义与内置open()函数的相应参数的含义相同。返回的文件对象读取或写入文本字符串,而不是字节。

如果子进程成功退出,则close方法返回None;如果发生错误,则返回子进程的返回码。在 POSIX 系统上,如果返回码为正,则表示该进程的返回值左移一个字节。如果返回码为负,则过程由返回码的取反值给出的 signal 终止。 (例如,如果子进程被终止,则返回值可能是- signal.SIGKILL.)在 Windows 系统上,该返回值包含子进程的带符号整数返回码。

这是使用subprocess.Popen实现的;有关更强大的方法来 Management 子流程和与子流程进行通信,请参见该类的文档。

  • os. posix_spawn(* path argv env **,* file_actions = None setpgroup = None resetids = False setsid = False setsigmask =(), * setsigdef =(),* scheduler = None *)
    • 包装posix_spawn() C 库 API 以便从 Python 使用。

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

仅位置参数* path args env *与execve()相似。

  • path 参数是可执行文件的路径. path *应该包含目录。使用posix_spawnp()传递不带目录的可执行文件。

  • file_actions *参数可以是 Tuples 序列,描述在 C 库实现的fork()exec()步骤之间的子进程中要对特定文件 Descriptors 执行的操作。每个 Tuples 中的第一项必须是下面列出的描述剩余 Tuples 元素的三个类型指示符之一:

  • os. POSIX_SPAWN_OPEN
    • (os.POSIX_SPAWN_OPEN,* fd path flags mode *)

执行os.dup2(os.open(path, flags, mode), fd)

  • os. POSIX_SPAWN_CLOSE
    • (os.POSIX_SPAWN_CLOSE,* fd *)

执行os.close(fd)

  • os. POSIX_SPAWN_DUP2
    • (os.POSIX_SPAWN_DUP2,* fd new_fd *)

执行os.dup2(fd, new_fd)

这些 Tuples 对应于用于准备posix_spawn()调用本身的 C 库posix_spawn_file_actions_addopen()posix_spawn_file_actions_addclose()posix_spawn_file_actions_adddup2() API 调用。

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

如果* resetids *参数为True,它将把子级的有效 UID 和 GID 重置为父进程的实际 UID 和 GID。如果参数为False,则子级保留父级的有效 UID 和 GID。无论哪种情况,如果在可执行文件上启用了“设置用户 ID”和“设置组 ID”权限位,它们的效果将覆盖有效 UID 和 GID 的设置。此参数对应于 C 库POSIX_SPAWN_RESETIDS标志。

如果* setsid *参数为True,它将为 posix_spawn 创建一个新的会话 ID。 * setsid *需要POSIX_SPAWN_SETSIDPOSIX_SPAWN_SETSID_NP标志。否则,将引发NotImplementedError

  • setsigmask *参数会将 signal 掩码设置为指定的 signal 集。如果未使用该参数,则子级将继承父级的 signal 掩码。此参数对应于 C 库POSIX_SPAWN_SETSIGMASK标志。

  • sigdef *参数将重置指定集中所有 signal 的配置。此参数对应于 C 库POSIX_SPAWN_SETSIGDEF标志。

  • scheduler *参数必须是一个包含(可选)调度程序策略的 Tuples,并带有调度程序参数的sched_param实例。调度程序策略中的None值表示未提供该值。此参数是 C 库POSIX_SPAWN_SETSCHEDPARAMPOSIX_SPAWN_SETSCHEDULER标志的组合。

用参数pathargvenv引发auditing event os.posix_spawn

3.8 版的新Function。

Availability: Unix.

  • os. posix_spawnp(* path argv env **,* file_actions = None setpgroup = None resetids = False setsid = False setsigmask =(), * setsigdef =(),* scheduler = None *)
    • 包装posix_spawnp() C 库 API 以便从 Python 使用。

posix_spawn()相似,除了系统在 PATH环境变量指定的目录列表中搜索* executable *文件(与execvp(3)相同)。

用参数pathargvenv引发auditing event os.posix_spawn

3.8 版的新Function。

Availability:请参阅posix_spawn()文档。

  • os. register_at_fork(** before = None after_in_parent = None after_in_child = None *)

    • 注册使用os.fork()或类似的流程克隆 API 派生新的子流程时要执行的可调用对象。参数是可选的,并且仅关键字。每个指定一个不同的呼叫点。
    • before *是在派生子进程之前调用的函数。
    • after_in_parent *是在分叉子进程之后从父进程调用的函数。
    • after_in_child *是从子进程中调用的函数。

仅当期望控制权返回到 Python 解释器时才进行这些调用。典型的subprocess启动将不会触发它们,因为孩子不会重新 Importing 解释器。

在派生之前注册要执行的Function按相反的注册 Sequences 调用。分叉后注册执行的Function(在父级或子级中)按注册 Sequences 调用。

请注意,除非第三方 C 代码显式调用PyOS_BeforeFork()PyOS_AfterFork_Parent()PyOS_AfterFork_Child(),否则第三方 C 代码进行的fork()调用可能不会调用这些函数。

无法取消注册Function。

Availability: Unix.

3.7 版中的新Function。

  • os. spawnl(* mode path ... *)
  • os. spawnle(* mode path ... env *)
  • os. spawnlp(* mode file ... *)
  • os. spawnlpe(* mode file ... env *)
  • os. spawnv(* mode path args *)
  • os. spawnve(* mode path args env *)
  • os. spawnvp(* mode file args *)
  • os. spawnvpe(* mode file args env *)
    • 在新进程中执行程序* path *。

(请注意,subprocess模块提供了更强大的工具来生成新进程并检索其结果;使用该模块优于使用这些Function。尤其是检查用子流程模块替换旧Function部分。)

如果* mode P_NOWAIT,则此函数返回新进程的进程 ID;否则,返回 0.如果 mode P_WAIT,则返回正常退出的进程的退出代码,或-signal,其中 signal *是杀死进程的 signal。在 Windows 上,进程 ID 实际上是进程句柄,因此可以与waitpid()函数一起使用。

请注意,在 VxWorks 上,新进程被终止后,此函数不会返回-signal。相反,它将引发 OSError 异常。

spawn*函数的“ l”和“ v”变体在命令行参数的传递方式上有所不同。如果在编写代码时参数数量固定,则“ l”变体可能是最容易使用的;各个参数只是成为spawnl*()函数的附加参数。当参数的数量可变时,“ v”变体很好,参数以列表或 Tuples 的形式作为* args *参数传递。无论哪种情况,子进程的参数都必须以正在运行的命令的名称开头。

在末尾(spawnlp()spawnlpe()spawnvp()spawnvpe())附近包含第二个“ p”的变体将使用 PATH环境变量来定位程序* file *。当替换环境时(使用spawn*e变体中的一种,在下一段中讨论),新环境将用作 PATH变量的源。其他变体spawnl()spawnle()spawnv()spawnve()不会使用 PATH变量来定位可执行文件; * path *必须包含适当的绝对或相对路径。

对于spawnle()spawnlpe()spawnve()spawnvpe()(请注意,所有这些都以“ e”结尾),* env 参数必须是用于定义新进程的环境变量的 Map(使用它们代替当前变量)过程的环境);函数spawnl()spawnlp()spawnv()spawnvp()都使新进程继承当前进程的环境。请注意, env *词典中的键和值必须是字符串;无效的键或值将导致函数失败,返回值为127

例如,以下对spawnlp()spawnvpe()的调用是等效的:

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

用参数modepathargsenv引发auditing event os.spawn

Availability:Unix,Windows。 spawnlp()spawnlpe()spawnvp()spawnvpe()在 Windows 上不可用。 spawnle()spawnve()在 Windows 上不是线程安全的;我们建议您改用subprocess模块。

在版本 3.6 中更改:接受path-like object

  • os. P_NOWAIT
  • os. P_NOWAITO
    • spawn*系列函数的* mode *参数的可能值。如果给出了这些值中的任何一个,则spawn*()函数将在创建新进程后立即返回,并将进程 ID 作为返回值。

Availability:Unix,Windows。

  • os. P_WAIT
    • spawn*系列函数的* mode 参数的可能值。如果将其指定为 mode *,则spawn*()函数将在新进程运行完成之前不返回,并且将返回运行成功的进程的退出代码,或者-signal(如果有 signal 终止了该进程)。

Availability:Unix,Windows。

  • os. P_DETACH
  • os. P_OVERLAY
    • spawn*系列函数的* mode *参数的可能值。它们比上面列出的那些便携式性差。 P_DETACHP_NOWAIT类似,但是新过程与调用过程的控制台分离。如果使用P_OVERLAY,将替换当前进程; spawn*函数不会返回。

Availability: Windows.

  • os. startfile(* path * [,* operation *])
    • 使用其关联的应用程序启动文件。

如果未指定* operation *或'open',则类似于在 Windows 资源 Management 器中双击文件,或从交互式命令 Shell 将文件名作为 start 命令的参数来提供:使用任何命令打开文件应用程序(如果有)与其 extensions 相关联。

当给出另一个* operation *时,它必须是一个“命令动词”,它指定应该对文件执行的操作。 Microsoft 记录的常用动词是'print''edit'(将在文件上使用)以及'explore''find'(将在目录上使用)。

关联的应用程序启动后,startfile()返回。没有选择 await 应用程序关闭的选项,也没有办法检索应用程序的退出状态。 * path *参数是相对于当前目录的。如果要使用绝对路径,请确保第一个字符不是斜杠('/');基本的 Win32 ShellExecute()函数不能正常工作。使用os.path.normpath()函数来确保路径已正确地为 Win32 编码。

为了减少解释器的启动开销,直到第一次调用 Win32 ShellExecute()函数时,才会解析该函数。如果无法解析该Function,将引发NotImplementedError

用参数pathoperation引发auditing event os.startfile

Availability: Windows.

  • os. system(* command *)
    • 在子 Shell 程序中执行命令(字符串)。这是pass调用标准 C 函数system()实现的,并且具有相同的限制。对sys.stdin等的更改不会反映在已执行命令的环境中。如果* command *生成任何输出,它将被发送到解释器标准输出流。

在 Unix 上,返回值是以wait()指定的格式编码的进程的退出状态。请注意,POSIX 没有指定 C system()函数的返回值的含义,因此 Python 函数的返回值与系统有关。

在 Windows 上,返回值是运行* command *后系统 Shell 程序返回的值。该 Shell 程序由 Windows 环境变量 COMSPEC给出:它通常是 cmd.exe ,它返回命令运行的退出状态。在使用非本机 Shell 的系统上,请查阅您的 Shell 文档。

subprocess模块提供了更强大的Function来生成新流程并检索其结果;使用该模块优于使用此Function。有关一些有用的食谱,请参见subprocess文档中的用子流程模块替换旧Function部分。

用参数command引发auditing event os.system

Availability:Unix,Windows。

  • os. times ( )

    • 返回当前的全局处理时间。返回值是具有五个属性的对象:
  • user-用户时间

  • system-系统时间

  • children_user-所有子进程的用户时间

  • children_system-所有子进程的系统时间

  • elapsed-从过去的固定点过去的实时时间

为了向后兼容,该对象的行为也类似于包含usersystemchildren_userchildren_systemelapsed的五 Tuples。

请参阅 Unix 手册页* times(2) times(3) *手册页(在 Unix 上)或GetProcessTimes MSDN(在 Windows 上)。在 Windows 上,仅usersystem是已知的。其他属性为零。

Availability:Unix,Windows。

在版本 3.3 中更改:返回类型从 Tuples 更改为具有命名属性的类似 Tuples 的对象。

  • os. wait ( )
    • await 子进程完成,并返回一个包含其 pid 和退出状态指示的 Tuples:一个 16 位数字,其低字节是杀死该进程的 signal 号,而其高字节是退出状态(如果 signal 数字为零);如果生成了核心文件,则设置低字节的高位。

Availability: Unix.

  • os. waitid(* idtype id options *)
    • await 一个或多个子进程完成。 * idtype *可以是P_PIDP_PGIDP_ALL。 * id *指定要 await 的 pid。 * options *是pass对WEXITEDWSTOPPEDWCONTINUED中的一个或多个进行“或”运算而构造的,并且可以与WNOHANGWNOWAIT进行“或”运算。返回值是一个对象,表示siginfo_t结构中包含的数据,即:如果指定了WNOHANG并且没有子级处于 await 状态,则si_pidsi_uidsi_signosi_statussi_codeNone

Availability: Unix.

版本 3.3 中的新Function。

  • os. P_PID
  • os. P_PGID
  • os. P_ALL
    • 这些是waitid()中* idtype 的可能值。它们影响 id *的解释方式。

Availability: Unix.

版本 3.3 中的新Function。

  • os. WEXITED
  • os. WSTOPPED
  • os. WNOWAIT
    • 可以在waitid()的* options *中使用的标志,用于指定要 await 的子 signal。

Availability: Unix.

版本 3.3 中的新Function。

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

Availability: Unix.

版本 3.3 中的新Function。

  • os. waitpid(* pid options *)
    • 此函数的详细信息在 Unix 和 Windows 上有所不同。

在 Unix 上:await 进程 ID * pid 给出的子进程完成,并返回一个包含其进程 ID 和退出状态指示的 Tuples(编码为wait())。调用的语义受整数 options *的值影响,对于正常操作,该值应为0

如果* pid 大于0,则waitpid()请求该特定进程的状态信息。如果 pid 0,则请求是针对当前进程的进程组中任何子进程的状态。如果 pid -1,则该请求与当前进程的任何子进程有关。如果 pid 小于-1,则请求状态组-pid中的任何进程的状态( pid *的绝对值)。

当系统调用返回-1 时,将用 errno 的值引发OSError

在 Windows 上:await 进程句柄* pid 给定的进程完成,然后返回包含 pid 的 Tuples,其退出状态向左移 8 位(这种移位使跨平台使用该函数更加容易)。小于或等于0 pid 在 Windows 上没有特殊含义,并引发异常。整数 options *的值无效。 * pid *可以引用其 ID 已知的任何进程,不一定是子进程。用P_NOWAIT调用的spawn*函数返回合适的进程句柄。

在版本 3.5 中进行了更改:如果系统调用被break并且 signal 处理程序没有引发异常,则该函数现在重试系统调用,而不是引发InterruptedError异常(有关原理,请参见 PEP 475)。

  • os. wait3(* options *)
    • waitpid()相似,不同之处在于未给出任何进程 ID 参数,并返回一个包含子进程 ID,退出状态指示和资源使用信息的 3 元素 Tuples。请参考resourcegetrusage()有关资源使用信息的详细信息。 option 参数与提供给waitpid()wait4()的参数相同。

Availability: Unix.

  • os. wait4(* pid options *)
    • waitpid()相似,除了包含 3 个元素的 Tuples 之外,该 Tuples 包含子进程的 ID,退出状态指示和资源使用信息。请参考resourcegetrusage()有关资源使用信息的详细信息。 wait4()的参数与提供给waitpid()的参数相同。

Availability: Unix.

  • os. WNOHANG
    • 如果没有立即可用的子进程状态,则waitpid()可以立即返回的选项。在这种情况下,该函数返回(0, 0)

Availability: Unix.

  • os. WCONTINUED
    • 如果子进程自上次报告其状态以来已从作业控制停止 continue 进行,则此选项将导致报告这些子进程。

Availability:某些 Unix 系统。

  • os. WUNTRACED
    • 如果已停止子进程,但是自停止以来尚未报告其当前状态,则此选项将导致报告子进程。

Availability: Unix.

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

  • os. WCOREDUMP(状态)
    • 如果为该进程生成了核心转储,则返回True,否则返回False

仅当WIFSIGNALED()为 true 时,才应使用此Function。

Availability: Unix.

  • os. WIFCONTINUED(状态)
    • 如果pass交付SIGCONT恢复了被停止的孩子,则返回True(如果从作业控制停止处 continue 进行该过程),否则返回False

请参阅WCONTINUED选项。

Availability: Unix.

  • os. WIFSTOPPED(状态)
    • 如果进程由于传递 signal 而停止,则返回True,否则返回False

如果使用WUNTRACED选项完成了waitpid()调用或正在跟踪进程,则WIFSTOPPED()仅返回True(请参阅* ptrace(2) *)。

Availability: Unix.

  • os. WIFSIGNALED(状态)
    • 如果进程被 signal 终止,则返回True,否则返回False

Availability: Unix.

  • os. WIFEXITED(状态)
    • 如果退出的进程正常终止,则返回True,即pass调用exit()_exit()或从main()返回;否则返回False

Availability: Unix.

  • os. WEXITSTATUS(状态)
    • 返回进程退出状态。

仅当WIFEXITED()为 true 时,才应使用此Function。

Availability: Unix.

  • os. WSTOPSIG(状态)
    • 返回导致进程停止的 signal。

仅当WIFSTOPPED()为 true 时,才应使用此Function。

Availability: Unix.

  • os. WTERMSIG(状态)
    • 返回导致进程终止的 signal 编号。

仅当WIFSIGNALED()为 true 时,才应使用此Function。

Availability: Unix.

与调度程序的接口

这些Function控制 os 如何为进程分配 CPU 时间。它们仅在某些 Unix 平台上可用。有关更多详细信息,请查阅 Unix 联机帮助页。

版本 3.3 中的新Function。

如果 os 支持以下调度策略,则将公开它们。

  • os. SCHED_OTHER

    • 默认的调度策略。
  • os. SCHED_BATCH

    • CPU 密集型进程的调度策略,该策略试图保留计算机其余部分的交互性。
  • os. SCHED_IDLE

    • 优先级极低的后台任务的调度策略。
  • os. SCHED_SPORADIC

    • 零星服务器程序的调度策略。
  • os. SCHED_FIFO

    • 先进先出调度策略。
  • os. SCHED_RR

    • 循环调度策略。
  • os. SCHED_RESET_ON_FORK

    • 该标志可以与其他任何调度策略进行“或”运算。当设置了该标志的进程派生时,其子级的调度策略和优先级将重置为默认值。
    • class * os. sched_param(* sched_priority *)

目前,只有一个可能的参数:

  • sched_priority

    • 调度策略的调度优先级。
  • os. sched_get_priority_min(* policy *)

    • 获取* policy *的最小优先级值。 * policy *是上述调度策略常量之一。
  • os. sched_get_priority_max(* policy *)

    • 获取* policy *的最大优先级值。 * policy *是上述调度策略常量之一。
  • os. sched_setscheduler(* pid policy param *)

    • 使用 PID * pid *设置进程的调度策略。 * pid *为 0 表示调用过程。 * policy *是上述调度策略常量之一。 * param *是sched_param实例。
  • os. sched_getscheduler(* pid *)

    • 返回带有 PID * pid *的进程的调度策略。 * pid *为 0 表示调用过程。结果是上面的调度策略常量之一。
  • os. sched_setparam(* pid param *)

    • 使用 PID * pid *设置过程的调度参数。 * pid *为 0 表示调用过程。 * param *是sched_param实例。
  • os. sched_getparam(* pid *)

    • 使用 PID * pid *返回该调度参数作为该进程的sched_param实例。 * pid *为 0 表示调用过程。
  • os. sched_rr_get_interval(* pid *)

    • 使用 PID * pid *返回以秒为单位的循环量子。 * pid *为 0 表示调用过程。
  • os. sched_yield ( )

    • 自愿放弃 CPU。
  • os. sched_setaffinity(* pid mask *)

    • 将具有 PID * pid *的进程(或当前进程,如果为零)限制为一组 CPU。 * mask *是整数的可迭代数,表示应将进程限制在其中的一组 CPU。
  • os. sched_getaffinity(* pid *)

    • 将限制使用 PID * pid *(或当前进程,如果为零)的进程返回给 CPU 组。

其他系统信息

  • os. confstr(* name *)
    • 返回字符串值的系统配置值。 * name 指定要检索的配置值;它可以是一个字符串,它是定义的系统值的名称;这些名称在许多标准(POSIX,Unix 95,Unix 98 等)中指定。一些平台还定义了其他名称。主机 os 已知的名称作为confstr_names字典的键给出。对于未包含在该 Map 中的配置变量,也可接受为 name *传递整数。

如果未定义* name *指定的配置值,则返回None

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

Availability: Unix.

  • os. confstr_names
    • confstr()接受的字典 Map 名称到主机 os 为此名称定义的整数值。这可用于确定系统已知的名称集。

Availability: Unix.

  • os. cpu_count ( )
    • 返回系统中的 CPU 数量。如果不确定,则返回None

该数目不等于当前进程可以使用的 CPU 数目。可用的 CPU 数量可以passlen(os.sched_getaffinity(0))获得

3.4 版的新Function。

  • os. getloadavg ( )
    • 返回过去 1、5 和 15 分钟内系统运行队列中的平均进程数,如果无法获得平均负载,则返回OSError

Availability: Unix.

  • os. sysconf(* name *)
    • 返回整数值的系统配置值。如果未定义* name 指定的配置值,则返回-1。关于confstr() name *参数的 Comments 也适用于此;提供有关已知名称信息的字典由sysconf_names给出。

Availability: Unix.

  • os. sysconf_names
    • sysconf()接受的字典 Map 名称到主机 os 为此名称定义的整数值。这可用于确定系统已知的名称集。

Availability: Unix.

以下数据值用于支持路径操纵操作。这些是为所有平台定义的。

os.path模块中定义了对路径名的更高级操作。

  • os. curdir
    • os 用来引用当前目录的常量字符串。对于 Windows 和 POSIX,这是'.'。也可以passos.path获得。
  • os. pardir
    • os 用来引用父目录的常量字符串。对于 Windows 和 POSIX,这是'..'。也可以passos.path获得。
  • os. sep
    • os 用来分隔路径名组件的字符。对于 POSIX,这是'/',对于 Windows 是'\\'请注意,仅了解这一点还不足以解析或连接路径名(使用os.path.split()os.path.join()),但是有时它很有用。也可以passos.path获得。
  • os. altsep
    • os 用来分隔路径名组件的替代字符;如果仅存在一个分隔符,则为None。在sep是反斜杠的 Windows 系统上,它设置为'/'。也可以passos.path获得。
  • os. extsep
    • 将基本文件名与 extensions 分开的字符;例如os.py中的'.'。也可以passos.path获得。
  • os. pathsep

    • os 通常用于分隔搜索路径组件(如 PATH)的字符,例如 POSIX 的':'或 Windows 的';'。也可以passos.path获得。
  • os. defpath

    • 如果环境没有'PATH'键,则exec*p*spawn*p*使用的默认搜索路径。也可以passos.path获得。
  • os. linesep

    • 在当前平台上用于分隔(或终止)行的字符串。对于 POSIX,这可以是单个字符,例如'\n';对于 Windows,可以是多个字符,例如'\r\n'。编写以文本模式打开的文件时(默认),请勿使用* os.linesep *作为行终止符;在所有平台上都使用一个'\n'代替。
  • os. devnull

    • 空设备的文件路径。例如:'/dev/null'用于 POSIX,'nul'用于 Windows。也可以passos.path获得。
  • os. RTLD_LAZY

  • os. RTLD_NOW

  • os. RTLD_GLOBAL

  • os. RTLD_LOCAL

  • os. RTLD_NODELETE

  • os. RTLD_NOLOAD

  • os. RTLD_DEEPBIND

版本 3.3 中的新Function。

Random numbers

  • os. getrandom(* size flags = 0 *)
    • 最多获取* size *个随机字节。该函数返回的字节数少于请求的字节数。

这些字节可用于为用户空间随机数生成器提供种子或用于加密目的。

getrandom()依赖于从设备驱动程序和其他环境噪声源收集的熵。不必要地读取大量数据将对/dev/random/dev/urandom设备的其他用户造成负面影响。

flags 参数是一个位掩码,可以包含零个或多个以下值“或”在一起:os.GRND_RANDOMGRND_NONBLOCK

另请参见Linux getrandom()手册页

Availability:Linux 3.17 及更高版本。

3.6 版的新Function。

  • os. urandom(* size *)
    • 返回适合加密使用的* size *个随机字节的字符串。

该函数从特定于 os 的随机性源返回随机字节。尽管返回的数据的确切质量取决于 os 的实现,但是对于加密应用程序而言,返回的数据应该足够不可预测。

在 Linux 上,如果getrandom() syscall 可用,则以阻塞模式使用它:阻塞直到初始化系统 urandom 熵池(内核收集 128 位熵)。原理请参见 PEP 524。在 Linux 上,可以使用getrandom()函数以非阻塞模式(使用GRND_NONBLOCK标志)获取随机字节,或者可以轮询直到初始化系统 urandom 熵池为止。

在类 Unix 系统上,从/dev/urandom设备读取随机字节。如果/dev/urandom设备不可用或不可读,则会引发NotImplementedError异常。

在 Windows 上,它将使用CryptGenRandom()

See also

secrets模块提供更高级别的Function。有关平台所提供的随机数生成器的易于使用的界面,请参阅random.SystemRandom

在版本 3.6.0 中更改:在 Linux 上,getrandom()现在用于阻止模式以提高安全性。

在版本 3.5.2 中进行了更改:在 Linux 上,如果getrandom() syscall 阻止(尚未初始化 urandom 熵池),请退回阅读/dev/urandom

在版本 3.5 中进行了更改:在 Linux 3.17 和更高版本上,现在可以使用getrandom() syscall。在 OpenBSD 5.6 和更高版本上,现在使用 C getentropy()函数。这些Function避免使用内部文件 Descriptors。

  • os. GRND_NONBLOCK
    • 默认情况下,从/dev/random读取时,如果没有可用的随机字节,则getrandom()阻塞;从/dev/urandom读取时,如果尚未初始化熵池,则阻塞。

如果设置了GRND_NONBLOCK标志,则getrandom()在这些情况下不会阻塞,而是立即引发BlockingIOError

3.6 版的新Function。

  • os. GRND_RANDOM
    • 如果设置了此位,那么将从/dev/random池而不是/dev/urandom池中抽取随机字节。

3.6 版的新Function。