.. module:: uos
   :synopsis: basic "operating system" services

The os module contains functions for filesystem access and urandom function.

The filesystem has / as the root directory and the available physical drives are accessible from here. They are currently:

/flash -- the internal flash filesystem

/sd -- the SD card (if it exists)

.. only:: port_pyboard

    On boot up, the current directory is ``/flash`` if no SD card is inserted,
    otherwise it is ``/sd``.

.. only:: port_wipy

    On boot up, the current directory is ``/flash``.

.. function:: chdir(path)

   Change current directory.

.. function:: getcwd()

   Get the current directory.

.. function:: listdir([dir])

   With no argument, list the current directory.  Otherwise list the given directory.

.. function:: mkdir(path)

   Create a new directory.

.. function:: remove(path)

   Remove a file.

.. function:: rmdir(path)

   Remove a directory.

.. function:: rename(old_path, new_path)

   Rename a file.

.. function:: stat(path)

   Get the status of a file or directory.

.. only:: port_unix or port_pyboard or port_esp8266

    .. function:: statvfs(path)

       Get the status of a fileystem.

       Returns a tuple with the filesystem information in the following order:

            * ``f_bsize`` -- file system block size
            * ``f_frsize`` -- fragment size
            * ``f_blocks`` -- size of fs in f_frsize units
            * ``f_bfree`` -- number of free blocks
            * ``f_bavail`` -- number of free blocks for unpriviliged users
            * ``f_files`` -- number of inodes
            * ``f_ffree`` -- number of free inodes
            * ``f_favail`` -- number of free inodes for unpriviliged users
            * ``f_flag`` -- mount flags
            * ``f_namemax`` -- maximum filename length

       Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_avail``
       and the ``f_flags`` parameter may return ``0`` as they can be unavailable
       in a port-specific implementation.

.. function:: sync()

   Sync all filesystems.

.. function:: urandom(n)

   Return a bytes object with n random bytes, generated by the hardware
   random number generator.

.. only:: port_wipy

    .. function:: mount(block_device, mount_point, \*, readonly=False)

       Mounts a block device (like an ``SD`` object) in the specified mount
       point. Example::

          os.mount(sd, '/sd')

    .. function:: unmount(path)

       Unmounts a previously mounted block device from the given path.

    .. function:: mkfs(block_device or path)

       Formats the specified path, must be either ``/flash`` or ``/sd``.
       A block device can also be passed like an ``SD`` object before
       being mounted.

    .. function:: dupterm(stream_object)

       Duplicate the terminal (the REPL) on the passed stream-like object.
       The given object must at least implement the ``.read()`` and ``.write()`` methods.

.. data:: sep

   separation character used in paths