<lib/fdio/io.h> in fdio

Header source code

FDIO_FLAG_USE_FOR_STDIO macro {:#FDIO_FLAG_USE_FOR_STDIO}

Declaration source code

Flag on handle args in processargs instructing that this fd should be dup'd to 0/1/2 and be used for all of stdio.

Wait events {:#FDIO_EVT_READABLE}

Declaration source code

These bit values provide the events to wait for in fdio_wait_fd().

fdio_get_vmo_clone(…) {:#fdio_get_vmo_clone}

Declaration source code

Gets VMO containing a read-only child of the underlying VMO representing the file.

Not all file descriptors represent normal files, and no filesystem is required to provide the contents of the file as a VMO. Therefore, callers should be prepared for this function to fail. Callers that can tolerate the performance and memory implications of an eager copy of the entire contents of the file can use fdio_get_vmo_copy() which includes automatic fallback.

On success, the returned VMO will have at least the semantics of the ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE flag for the zx_vmo_create_child() system call. This leaves unspecified whether the returned VMO will reflect subsequent changes in the underlying file or not. The size of the VMO will not reflect changes to the underlying file. These semantics match the POSIX mmap() MAP_PRIVATE flag.

Users requiring a guaranteed snapshot of the file should use fdio_get_vmo_exact() and then use zx_vmo_create_child() with ZX_VMO_CHILD_SNAPSHOT to create a snapshot. However, clients should be prepared for this to fail in common cases, both because the filesystem is not required to supply an exact VMO, and because creating a snapshot has additional restrictions (most commonly that the VMO must not be attached to the paging system).

See also:

  • [zxio_vmo_get_clone()] which implements the backend of this function.
  • fdio_get_vmo_copy()
  • fdio_get_vmo_exact()
  • fdio_get_vmo_exec()

fdio_get_vmo_copy(…) {:#fdio_get_vmo_copy}

Declaration source code

Get a read-only VMO containing the whole contents of the file. This function creates a clone of the underlying VMO using fdio_get_vmo_clone() when possible, falling back to eagerly reading the contents into a freshly-created VMO. Copying the file data can have significant memory and performance implications for large files so this function must be used carefully, but having this fallback avoids the many error cases of fdio_get_vmo_clone() and fdio_get_vmo_exact().

When cloning is successful, the cloned VMO will have at least the semantics of the ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE flag for the zx_vmo_create_child() system call. This leaves unspecified whether the returned VMO will reflect subsequent changes in the underlying file or not. When the eager-reading fallback happens, the returned VMO will be a non-atomic snapshot of the file when it was read. The size of the VMO will not reflect changes to the underlying file. As a result, users should not make assumptions about the semantics of the returned VMO with respect to file content changes.

See also:

  • [zxio_vmo_get_copy()] which implements the backend of this function.
  • fdio_get_vmo_clone()
  • fdio_get_vmo_exact()
  • fdio_get_vmo_exec()

fdio_get_vmo_exact(…) {:#fdio_get_vmo_exact}

Declaration source code

Get a read-only handle to the exact VMO used by the file system server to represent the file. This VMO will track size and content changes to the file.

Not all file descriptors represent normal files, and no filesystem is required to provide the contents of the file as a VMO. Therefore, callers should be prepared for this function to fail. Callers that can tolerate the performance and memory implications of an eager copy of the entire contents of the file can use fdio_get_vmo_copy() which includes automatic fallback.

See also:

  • [zxio_vmo_get_clone()] which implements the backend of this function.
  • fdio_get_vmo_clone()
  • fdio_get_vmo_copy()
  • fdio_get_vmo_exec()

fdio_get_vmo_exec(…) {:#fdio_get_vmo_exec}

Declaration source code

Get a VMO containing a read-only executable child of the underlying VMO. This function will fail rather than copying the contents if it cannot be cloned.

This function is identical to fdio_get_vmo_clone() except it adds executable rights. See that function for more information.

See also:

  • [zxio_vmo_get_exec()] which implements the backend of this function.
  • fdio_get_vmo_clone()
  • fdio_get_vmo_copy()
  • fdio_get_vmo_exact()

fdio_handle_fd(…) {:#fdio_handle_fd}

Declaration source code

Create a file descriptor that works with wait APIs (epoll, select, etc.) from a handle and expected signals (signals_in/signals_out correspond to POLLIN/POLLOUT events respectively).

Unlike a file (see fdio_fd_create()), the returned handle can only be used for waiting and closing. However, the input handle can be any waitable kernel object, such as an event.

The shared_handle flag indicates if ownership of the handle should be transferred to the FD. When true, the caller is expected to manage the lifetime of the handle (it must outlive the usage of the FD). When false, the handle will be closed when the returned descriptor is closed.

On success, returns the created file descriptor. On failure, returns -1 and sets errno.

fdio_pipe_half(…) {:#fdio_pipe_half}

Declaration source code

Creates a pipe. The first argument returns the file descriptor representing the pipe, and the second argument returns the handle of the socket used to communicate with the pipe.

Unlike the POSIX pipe() function which returns two file descriptors, this function returns one end of the pipe as a file descriptor for use in the current process with fdio, and the other end of the pipe as a kernel handle for transferring to another process.

Errors

  • ZX_ERR_NO_MEMORY: Failed due to a lack of memory.

  • ZX_ERR_NO_RESOURCES: Failed to bind to the file descriptor.

fdio_wait_fd(…) {:#fdio_wait_fd}

Declaration source code

Waits until one or more events are pending.