The core Fuchsia method for talking about files and other I/O primitives are FIDL protocols over Zircon channels. But since most applications are written against Unix integer file descriptors (“FD”s), Fuchsia provides the FDIO library to adapt the core protocols to POSIX-like file descriptors.
To see how FDIO fits into the overall I/O stack, see life of an open.
The main functions to convert between channels and file descriptors are:
These other variants also create handles from file descriptors. A “transfer” means that the source file descriptor is closed and ownership transferred to the
out_handle (this is identical to [fdio_get_service_handle()]. However, if a file descriptor has been
dup()ed and there are more than one descriptor representing the kernel handle, it can not be simply closed. In these cases, the file descriptor can be “cloned” meaning that the original file descriptor is not modified. The output handle is a new handle that the caller owns.
Internally, FDIO uses the opaque
fdio_t type to refer to a file descriptor. These can be separately created and bound to channels and FDs:
The fdio library is built on top of the zxio library. These functions provide integration between fdio and zxio.
Clients can use watch for changes in a given directory. This does not watch for changes in subdirectories of the given directory.
Most standard Fuchsia files are represented by an underlying virtual memory object (VMO). FDIO provides access to the kernel handle for this VMO when low-level operations are required.
These functions (which all have the same signature) convert a FDIO file handle to a kernel handle to a VMO. They differ by the handling of error conditions and the type of VMO provided. Since not all FDIO file handles represent normal files and filesystems are not obligated to provide a VMO representation of a file, callers should consider what behavior they want in such cases.
These functions provide ways to open files or connect to services in directories. To open or connect, a client will create a channel and send the handle to the server end of that channel (the
request parameters) to the service for the directory (identified here either by handle file descriptor, or by name bound in the current process' installed namespace).
There are also variants that automatically create the channel and register the client end as a file descriptor in the current process.
A namespace represents an application‘s view of a filesystem. The application’s view into the rest of the system is constructed by binding services (such as a directory in a filesystem) to names in the namespace (such as “/data”). Typically applications only interact with their installed but other namespaces can be constructed and destroyed if desired.
An application can bind or unbind names in a namespace:
Namespaces support basic filesystem-like operations. These functions are used as the basis for higher-level functions in FDIO like the directory functions:
Namespaces can be converted into parallel arrays of path/handle/type. This flat namespace structure is typically used to communicate a namespace between processes:
The fdio library provides process spawning functions that allow some or all of the current process' environment to be shared. The spawned executable can be identified either by a
path in the current process' installed namespace or by a VMO containing the binary.
These interfaces exist to allow integration of FDIO file descriptors with handle-centric message loops. If used incorrectly they can corrupt the internal FDIO state.
This function assists in creating POSIX-style pipes that will be shared with other processes: