f11/sdk/lib/fdio/io.h.md

# \<lib/fdio/io.h\> in fdio

[Header source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h)

## FDIO_FLAG_USE_FOR_STDIO macro {:#FDIO_FLAG_USE_FOR_STDIO}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#19)

<pre class="devsite-disable-click-to-copy">
<span class="kwd">#define</span> <span class="lit">FDIO_FLAG_USE_FOR_STDIO</span> ((uint32_t)0x8000)
</pre>

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](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#24)

<pre class="devsite-disable-click-to-copy">
<span class="kwd">#define</span> <span class="lit">FDIO_EVT_READABLE</span> POLLIN
<span class="kwd">#define</span> <span class="lit">FDIO_EVT_WRITABLE</span> POLLOUT
<span class="kwd">#define</span> <span class="lit">FDIO_EVT_ERROR</span> POLLERR
<span class="kwd">#define</span> <span class="lit">FDIO_EVT_PEER_CLOSED</span> POLLRDHUP
<span class="kwd">#define</span> <span class="lit">FDIO_EVT_ALL</span> (POLLIN | POLLOUT | POLLERR | POLLRDHUP)
</pre>


These bit values provide the events to wait for in <code><a href="io.h.md#fdio_wait_fd">fdio_wait_fd</a>()</code>.

## fdio_get_vmo_clone(…) {:#fdio_get_vmo_clone}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#111)

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_get_vmo_clone</b>(<span class="typ">int</span> fd,
                               <span class="typ">zx_handle_t *</span> out_vmo);
</pre>

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 <code><a href="io.h.md#fdio_get_vmo_copy">fdio_get_vmo_copy</a>()</code> 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.
  * <code><a href="io.h.md#fdio_get_vmo_copy">fdio_get_vmo_copy</a>()</code>
  * <code><a href="io.h.md#fdio_get_vmo_exact">fdio_get_vmo_exact</a>()</code>
  * <code><a href="io.h.md#fdio_get_vmo_exec">fdio_get_vmo_exec</a>()</code>


## fdio_get_vmo_copy(…) {:#fdio_get_vmo_copy}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#84)

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_get_vmo_copy</b>(<span class="typ">int</span> fd,
                              <span class="typ">zx_handle_t *</span> out_vmo);
</pre>

Get a read-only VMO containing the whole contents of the file. This function creates a clone of
the underlying VMO using <code><a href="io.h.md#fdio_get_vmo_clone">fdio_get_vmo_clone</a>()</code> 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 <code><a href="io.h.md#fdio_get_vmo_clone">fdio_get_vmo_clone</a>()</code> and <code><a href="io.h.md#fdio_get_vmo_exact">fdio_get_vmo_exact</a>()</code>.

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.
  * <code><a href="io.h.md#fdio_get_vmo_clone">fdio_get_vmo_clone</a>()</code>
  * <code><a href="io.h.md#fdio_get_vmo_exact">fdio_get_vmo_exact</a>()</code>
  * <code><a href="io.h.md#fdio_get_vmo_exec">fdio_get_vmo_exec</a>()</code>


## fdio_get_vmo_exact(…) {:#fdio_get_vmo_exact}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#127)

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_get_vmo_exact</b>(<span class="typ">int</span> fd,
                               <span class="typ">zx_handle_t *</span> out_vmo);
</pre>

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.
  * <code><a href="io.h.md#fdio_get_vmo_clone">fdio_get_vmo_clone</a>()</code>
  * <code><a href="io.h.md#fdio_get_vmo_copy">fdio_get_vmo_copy</a>()</code>
  * <code><a href="io.h.md#fdio_get_vmo_exec">fdio_get_vmo_exec</a>()</code>


## fdio_get_vmo_exec(…) {:#fdio_get_vmo_exec}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#141)

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_get_vmo_exec</b>(<span class="typ">int</span> fd,
                              <span class="typ">zx_handle_t *</span> out_vmo);
</pre>

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.
  * <code><a href="io.h.md#fdio_get_vmo_clone">fdio_get_vmo_clone</a>()</code>
  * <code><a href="io.h.md#fdio_get_vmo_copy">fdio_get_vmo_copy</a>()</code>
  * <code><a href="io.h.md#fdio_get_vmo_exact">fdio_get_vmo_exact</a>()</code>


## fdio_handle_fd(…) {:#fdio_handle_fd}

[Declaration source code](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#47)

<pre class="devsite-disable-click-to-copy">
<span class="typ">int</span> <b>fdio_handle_fd</b>(<span class="typ">zx_handle_t</span> h,
                   <span class="typ">zx_signals_t</span> signals_in,
                   <span class="typ">zx_signals_t</span> signals_out,
                   <span class="typ">bool</span> shared_handle);
</pre>

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 <code><a href="fd.h.md#fdio_fd_create">fdio_fd_create</a>()</code>), 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](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#62)

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_pipe_half</b>(<span class="typ">int *</span> out_fd,
                           <span class="typ">zx_handle_t *</span> out_handle);
</pre>

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](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/sdk/lib/fdio/include/lib/fdio/io.h#33)

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_wait_fd</b>(<span class="typ">int</span> fd,
                         <span class="typ">uint32_t</span> events,
                         <span class="typ">uint32_t *</span> pending,
                         <span class="typ">zx_time_t</span> deadline);
</pre>

Waits until one or more events are pending.