os – 基本的“操作系统”服务¶
This module implements a subset of the corresponding CPython module,
as described below. For more information, refer to the original
CPython documentation: os。
os 模块包含用于文件系统访问和挂载、终端重定向和复制以及 uname 和 urandom 函数的功能。
通用函数¶
- os.uname()¶
返回一个元组（可能是一个命名元组），其中包含关于底层机器和/或其操作系统的信息。元组按照以下顺序有五个字段，每个字段都是一个字符串：
sysname– 底层系统的名称nodename– 网络名称（可以与sysname相同）release– 底层系统的版本version– MicroPython 版本和构建日期machine– 底层硬件的标识符（例如板子、CPU）
- os.urandom(n)¶
返回一个包含 n 个随机字节的字节对象。尽可能使用硬件随机数生成器生成。
文件系统访问¶
- os.chdir(path)¶
更改当前目录。
- os.getcwd()¶
获取当前目录。
- os.ilistdir([dir])¶
此函数返回一个迭代器，然后产生与其正在列出的目录中的条目对应的元组。如果没有参数，则列出当前目录，否则列出由*dir*给定的目录。
元组的形式为 (name, type, inode[, size]):
name*是一个字符串（如果 *dir 是一个字节对象，则是字节）并且是条目的名称;
type 是一个整数，指定条目的类型，对于目录为0×4000，对于常规文件为0×8000;
inode 是文件的inode对应的整数，对于没有此概念的文件系统可能为0。
一些平台可能返回包含条目的*size*的4元组。对于文件条目，*size*是一个表示文件大小的整数，如果大小未知则为-1。对于目录条目，其含义目前未定义。
- os.listdir([dir])¶
如果没有参数，则列出当前目录。否则列出给定目录。
- os.mkdir(path)¶
创建一个新的目录。
- os.remove(path)¶
删除一个文件。
- os.rmdir(path)¶
删除一个目录。
- os.rename(old_path, new_path)¶
重命名一个文件。
- os.stat(path)¶
获取文件或目录的状态。
- os.statvfs(path)¶
获取系统文件的状态。
返回一个元组，其中包含以下顺序的文件系统信息：
f_bsize– 文件系统块大小f_frsize– 片段大小f_blocks– 以f_frsize为单位的fs大小f_bfree– 空闲块数f_bavail– 非特权用户使用的空闲块数f_files– inode 数量f_ffree– 空闲 inode 数量f_favail– 非特权用户的可用空闲 inode 数量f_flag– 挂载标志f_namemax– 最大文件名长度
与 inode 相关的参数：
f_files、f_ffree、f_avail和f_flags参数可能返回0，因为它们可能在移植版本特定的实现中不可用。
- os.sync()¶
同步所有文件系统。
终端重定向和复制¶
- os.dupterm(stream_object, index=0, /)¶
复制或切换给定的 stream 类对象上的 MicroPython 终端（REPL）。stream_object 参数必须是本机流对象，或派生自
io.IOBase并实现readinto()和write()方法。流应处于非阻塞模式，如果没有数据可用于读取，则readinto()应返回None。调用此函数后，所有终端输出都会在此流上重复，任何可用于流上的输入都会传递到终端输入。
index 参数应为非负整数，并指定设置的复制槽。给定移植版本可能实现多个槽（槽 0 总是可用），在这种情况下，终端输入和输出会复制到所有设置的槽上。
如果将
None作为 stream_object 传递，则在给定的 index 槽上取消复制。函数返回给定槽中的以前的类似流对象。
文件系统挂载¶
某些移植版本提供了虚拟文件系统（VFS）以及在此VFS内挂载多个“真实”文件系统的能力。文件系统对象可以挂载在VFS的根目录，也可以挂载在根目录下的子目录中。这样可以动态和灵活地配置Python程序所见的文件系统。具有此功能的移植版本提供了 mount() 和 umount() 函数，以及可能由VFS类表示的各种文件系统实现。
- os.mount(fsobj, mount_point, *, readonly)¶
在VFS中由 mount_point 字符串指定的位置挂载文件系统对象 fsobj。fsobj 可以是具有
mount()方法的VFS对象，也可以是块设备。如果它是块设备，则文件系统类型将自动检测（如果未识别出文件系统，则会引发异常）。mount_point 可以是'/'，以将 fsobj 挂载到根目录，也可以是'/<name>'，以将其挂载到根目录下的子目录中。如果 readonly 为
True，则文件系统将以只读模式挂载。在挂载过程中，将在文件系统对象上调用
mount()方法。如果 mount_point 已经挂载，则会引发
OSError(EPERM)。
- os.umount(mount_point)¶
卸载文件系统。mount_point 可以是命名挂载位置的字符串，也可以是先前挂载的文件系统对象。在卸载过程中，将在文件系统对象上调用
umount()方法。如果未找到 mount_point，则会引发
OSError(EINVAL)。
- class os.VfsFat(block_dev)¶
创建一个使用FAT文件系统格式的文件系统对象。 block_dev 提供FAT文件系统的存储。使用此构造函数创建的对象可以使用
mount()挂载。- static mkfs(block_dev)¶
在 block_dev 上构建FAT文件系统。
- class os.VfsLfs1(block_dev, readsize=32, progsize=32, lookahead=32)¶
创建一个使用 littlefs v1 filesystem format 的文件系统对象。由 block_dev 提供littlefs文件系统的存储，block_dev 必须支持 extended interface。使用此构造函数创建的对象可以使用
mount()挂载。有关更多信息，请参阅 使用文件系统。
- static mkfs(block_dev, readsize=32, progsize=32, lookahead=32)¶
在 block_dev 上构建Lfs1文件系统。
备注
有关littlefs v1在某些情况下失败的报告，请参阅 littlefs问题347。
- class os.VfsLfs2(block_dev, readsize=32, progsize=32, lookahead=32, mtime=True)¶
创建一个使用 littlefs v2 filesystem format 的文件系统对象。由 block_dev 提供littlefs文件系统的存储，block_dev 必须支持 extended interface。使用此构造函数创建的对象可以使用
mount()挂载。mtime 参数启用了文件的修改时间戳，使用littlefs属性存储。此选项可以在每次挂载时以不同方式禁用或启用，如果启用了 mtime，时间戳将仅在需要时添加或更新，否则时间戳将保持不变。没有时间戳的littlefs v2文件系统将在不重新格式化的情况下工作，并且一旦对现有文件进行写入，时间戳将被透明地添加到这些文件中。当启用 mtime 时，对于没有时间戳的文件，
os.stat将返回0作为时间戳。有关更多信息，请参阅 使用文件系统。
- static mkfs(block_dev, readsize=32, progsize=32, lookahead=32)¶
在 block_dev 上构建Lfs2文件系统。
备注
有关littlefs v2在某些情况下失败的报告，请参阅 littlefs issue 295。
块设备¶
块设备是实现块协议的对象。这使得设备可以支持MicroPython文件系统。物理硬件由用户定义的类表示。AbstractBlockDev 类是这样一个类设计的模块：MicroPython实际上并没有提供这个类，但实际的块设备类必须实现下面描述的方法。
此类的具体实现通常允许访问硬件的内存类功能（例如闪存）。块设备可以格式化为任何支持的文件系统，并使用 os 方法挂载。
有关使用下面描述的两种块协议变体的块设备示例实现，请参阅 使用文件系统。
简单和扩展接口¶
readblocks 和 writeblocks 方法有两种兼容的签名（见下文），以支持各种用例。给定的块设备可以实现一种形式或另一种形式，或同时实现两种形式。第二种形式（带有偏移参数）称为“扩展接口”。
某些文件系统（例如littlefs）需要对写操作进行更多的控制，例如在不拆除的情况下写入子块区域，可能需要块设备支持扩展接口。
- class os.AbstractBlockDev(...)¶
构造一个块设备对象。构造函数的参数取决于特定的块设备。
- readblocks(block_num, buf)¶
- readblocks(block_num, buf, offset)
第一种形式读取对齐的块的倍数。从由索引 block_num 给出的块开始，从设备读取 buf （字节数组）中的块。要读取的块数由 buf 的长度给出，这将是块大小的倍数。
第二种形式允许在块内的任意位置读取，并且任意长度。从块索引 block_num 开始，从该块的 offset 字节偏移处，从设备读取 buf*（字节数组）中的字节。要读取的字节数由 *buf 的长度给出。
- writeblocks(block_num, buf)¶
- writeblocks(block_num, buf, offset)
第一种形式写入对齐的块的倍数，并要求要写入的块首先通过此方法擦除（如果需要）。从由索引 block_num 给出的块开始，将 buf*（字节数组）中的块写入设备。要写入的块数由 *buf 的长度给出，这将是块大小的倍数。
第二种形式允许在块内的任意位置写入，并且任意长度。只应更改要写入的字节，此方法的调用者必须确保相关块通过先前的
ioctl调用擦除。从块索引 block_num 开始，从该块的 offset 字节偏移处，将 buf*（字节数组）中的字节写入设备。要写入的字节数由 *buf 的长度给出。请注意，如果制定了偏移参数，则实现绝不能隐式擦除快，即使偏移为零也是如此。
- ioctl(op, arg)¶
控制块设备并查询其参数。要执行的操作由 op 给出，它是以下整数之一：
1 – 初始化设备（arg 未使用）
2 – 关闭设备（arg 未使用）
3 – 同步设备（arg 未使用）
4 – 获取块数的计数，应返回整数（arg 未使用）
5 – 获取块中的字节数，应返回整数，或者
None，在这种情况下，将使用512的默认值（arg 未使用）6 – 擦除一个块，arg 是要擦除的块号
至少必须拦截
ioctl(4, ...)；对于littlefs，还必须拦截ioctl(6, ...)。其他操作的需要取决于硬件。在任何调用
writeblocks(block, ...)之前，littlefs都会发出ioctl(6, block)。这使得设备驱动程序可以在写入之前擦除块（如果硬件需要）。或者，驱动程序可以拦截ioctl(6, block)并返回0（成功）。在这种情况下，驱动程序负责检测擦除的需要。除非另有说明，否则
ioctl(op, arg)可以返回None。因此，实现可以忽略未使用的op值。拦截op时，操作4和5的返回值如上所述。其他操作应在成功时返回0，在失败时返回非零值，返回值为OSError错误代码。