:mod:`uos` -- 基本“操作系统”服务
===============================================

.. module:: uos
   :synopsis: 基本“操作系统”服务

该模块实现相应 `CPython` 模块的子集，如下所示。更多信息，请参见
|CPython文档| :mod:`python:os`.

``uos`` 模块包含文件系统访问和挂载、终端重定向和复制以及 ``uname`` 和 ``urandom`` 函数。

函数
---------

.. function:: uname()

   返回一个元组(可能是一个命名的元组)，其中包含关于底层机器和/或其操作系统的信息。tuple有五个字段，它们的顺序如下:

        * ``sysname`` --  底层系统的名称
        * ``nodename`` -- 网络名称(可以与 ``sysname`` 相同)
        * ``release`` -- 底层系统的版本
        * ``version`` -- MicroPython版本和构建日期
        * ``machine`` -- 底层硬件(如主板、CPU)的标识符。

.. function:: urandom(n)

   返回一个具有*n* 个随机字节的bytes对象。只要有可能，它就会由硬件随机数生成器生成。

文件系统访问
-----------------

.. function:: chdir(path)

   改变当前目录。

.. function:: getcwd()

   获取当前目录。

.. function:: ilistdir([dir])

   该函数返回一个迭代器，该迭代器将生成与它所列出目录中的条目相对应的3元组。无参数情况下，列出当前目录，否则列出由 *dir* 指定的目录。 

   元组的形式为 *(name, type, inode[, size])*:

    - *name* 为一个字符串（若dir为一个字节对象，则名称为字节）且为条目的名称；
    - *type* 为一个指定条目类型的整数，其中目录为0x4000，常规文件为0x8000；
    - *inode* 为一个与文件的索引节点相对应的整数，而对于没有这种概念的文件系统来说，可能为0。
    - 一些平台可能会返回一个4元组，其中包含条目的*size*。
      对于文件条目，*size* 是表示文件大小的整数，如果未知，则为-1。
      对于目录项，其含义目前尚未定义。

.. function:: listdir([dir])

   若无参数，则列出当前目录；否则将列出给定目录。

.. function:: mkdir(path)

   创建一个新目录。

.. function:: remove(path)

   删除一个文件。

.. function:: rmdir(path)

   删除一个目录。

.. function:: rename(old_path, new_path)

   重命名文件。

.. function:: stat(path)

   获取文件或目录的状态。

.. function:: statvfs(path)

   获取文件系统的状态。

   按照以下顺序返回一个具有文件系统信息的元组:

        * ``f_bsize`` -- 文件系统块大小
        * ``f_frsize`` -- 碎片大小
        * ``f_blocks`` -- f_frsize单元中fs的大小
        * ``f_bfree`` -- 空闲块的数量
        * ``f_bavail`` -- 非特权用户的免费块数
        * ``f_files`` -- 索引节点的数量
        * ``f_ffree`` -- 空闲索引节点的数量
        * ``f_favail`` -- 非特权用户的免费空闲索引节点的数量
        * ``f_flag`` -- 挂载标志
        * ``f_namemax`` -- 最大文件名长度

   与索引节点相关的参数： ``f_files`` 、 ``f_ffree`` 、 ``f_avail`` 、 ``f_flags`` 参数可能会返回0，因为它们在特定于端口的实现中不可用。

.. function:: sync()

   同步所有文件系统。

终端重定向和复制
------------------------------------

.. function:: dupterm(stream_object, index=0)

   在给定的 `stream` 类对象上复制或切换MicroPython终端(REPL)。*stream_object* 参数必须是一个本机流对象，
   或者派生自 ``uio.IOBase`` 并实现 ``readinto()`` 和 ``write()`` 方法。流应该处于非阻塞模式，
   如果没有数据可供读取，``readinto()`` 应该返回 ``None`` 。

   调用此函数后，将在此流上重复所有终端输出，并将流上可用的任何输入传递到终端输入。

   *index*参数应该是一个非负整数，并指定设置哪个复制插槽。
   给定的端口可以实现多个插槽(插槽0总是可用的)，在这种情况下，终端输入和输出在所有设置的插槽上重复。

   如果 ``None`` 作为 *stream_object* 传递，则在 *index* 提供的插槽上取消复制。

   该函数返回给定插槽中的前一个类似流的对象。

文件系统安装
-------------------

某些端口提供虚拟文件系统（VFS），并能够在此VFS中挂载多个“实际”文件系统。
文件系统对象可以安装在VFS的根目录下，也可以安装在根目录下的子目录中。
这样可以动态灵活地配置Python程序可以看到的文件系统。
具有此功能的端口提供 :func:`mount` 和 :func:`umount` 函数，以及由VFS类表示的各种文件系统实现。

.. function:: mount(fsobj, mount_point, \*, readonly)

    将文件系统对象 *fsobj* 挂载在VFS中 *mount_point* 字符串给出的位置。
    *fsobj* 可以是一个具有 ``mount()`` 方法的VFS对象，也可以是一个块设备。
    如果是块设备，则自动检测文件系统类型(如果没有识别出文件系统，则会引发异常)。
    *mount_point* 可以是 ``'/'`` 以便将 *fsobj* 挂载在根目录下，
    或者是 ``'/<name>'`` 可以将其挂载在根目录下的子目录中。

    如果 *readonly* 是 ``True``，那么文件系统是只读安装的。

    在挂载过程中，在文件系统对象上调用 ``mount()`` 方法。

    如果 *mount_point* 已经挂载将引发 ``OSError(EPERM)`` 。

.. function:: umount(mount_point)

    卸载文件系统。*mount_point* 可以是命名挂载位置的字符串，也可以是以前挂载的文件系统对象。
    在卸载过程中，在文件系统对象上调用 ``umount()`` 方法。

    如果没有找到 *mount_point* ，将引发 ``OSError(EINVAL)``。

.. class:: VfsFat(block_dev)

    创建一个使用FAT文件系统格式的文件系统对象。FAT文件系统的存储由 *block_dev* 提供。
    这个构造函数创建的对象可以使用 :func:`mount` 来挂载。

    .. staticmethod:: mkfs(block_dev)

        在 *block_dev* 上构建一个FAT文件系统。

块设备
-------------

块设备是实现块协议的对象，该对象是下面的 :class:`AbstractBlockDev` 类描述的一组方法。
此类的具体实现通常允许访问硬件(如闪存)的类似内存的功能。
一个特定的文件系统驱动程序可以使用一个块设备来存储其文件系统的数据。

.. class:: AbstractBlockDev(...)

    构造一个块设备对象。构造函数的参数依赖于特定的块设备。

    .. method:: readblocks(block_num, buf)

        从索引 *block_num* 给出的块开始，将块从设备读入 *buf* (字节数组)。
        读取的块数由 *buf* 的长度给出，它是块大小的倍数。

    .. method:: writeblocks(block_num, buf)

        从索引 *block_num* 给出的块开始，从 *buf* (字节数组)向设备写入块。
        要写入的块的数量由 *buf* 的长度给出，它是块大小的倍数。

    .. method:: ioctl(op, arg)

        控制块设备并查询其参数。要执行的操作由 *op* 给出，它是以下整数之一:

          - 1 -- 初始化设备( *arg* 未使用)
          - 2 -- 关闭设备( *arg* 未使用)
          - 3 -- 同步设备( *arg* 未使用)
          - 4 -- 获取块数的计数，应该返回一个整数( *arg* 未使用)
          - 5 -- 获取一个块中的字节数，应该返回一个整数，或者 ``None`` ，在这种情况下使用默认值512 ( *arg* 未使用)

举例来说，下面的类将实现一个块设备，它使用 ``bytearray``::

    class RAMBlockDev:
        def __init__(self, block_size, num_blocks):
            self.block_size = block_size
            self.data = bytearray(block_size * num_blocks)

        def readblocks(self, block_num, buf):
            for i in range(len(buf)):
                buf[i] = self.data[block_num * self.block_size + i]

        def writeblocks(self, block_num, buf):
            for i in range(len(buf)):
                self.data[block_num * self.block_size + i] = buf[i]

        def ioctl(self, op, arg):
            if op == 4: # get number of blocks
                return len(self.data) // self.block_size
            if op == 5: # get block size
                return self.block_size

它的使用方法如下::

    import uos

    bdev = RAMBlockDev(512, 50)
    uos.VfsFat.mkfs(bdev)
    vfs = uos.VfsFat(bdev)
    uos.mount(vfs, '/ramdisk')