f10/sdk/lib/fdio/fd.h.md

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

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

## fdio_cwd_clone(…) {:#fdio_cwd_clone}

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

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

Clones the current working directory.

Upon success, `out_handle` contains a handle that represents the current working directory.
Internally, cloning creates a new distinct connection to the directory that can be transferred to
another process without affecting the current process's directory connection.

### Errors

  * `ZX_ERR_NOT_SUPPORTED`: The cwd cannot be represented as a `zx_handle_t`.

  * `ZX_ERR_BAD_STATE`: The cwd cannot be cloned in its current state.

  * `ZX_ERR_ACCESS_DENIED`: The cwd has insufficient rights to clone the underlying object.


## fdio_fd_clone(…) {:#fdio_fd_clone}

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

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

Clones a file descriptor.

Upon success, `out_handle` contains a handle that represents the given file descriptor.
Internally, cloning creates a new distinct connection to the backing object that can be
transferred to another process without affecting the connection associated with the `fd`. This is
more heavyweight than transferring via <code><a href="fd.h.md#fdio_fd_transfer">fdio_fd_transfer</a>()</code> but can be done in more cases. See
also <code><a href="fd.h.md#fdio_fd_transfer_or_clone">fdio_fd_transfer_or_clone</a>()</code>.

`fd` is not modified by this function.

### Errors

  * `ZX_ERR_INVALID_ARGS`: `fd` is not a valid file descriptor.

  * `ZX_ERR_NOT_SUPPORTED`: `fd` cannot be represented as a `zx_handle_t`.

  * `ZX_ERR_BAD_STATE`: `fd` cannot be cloned in its current state.

  *` ZX_ERR_ACCESS_DENIED`: `fd` has insufficient rights to clone the underlying object.


## fdio_fd_create(…) {:#fdio_fd_create}

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

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

Create a file descriptor from a `zx_handle_t`.

The `handle` must be to a channel, socket, vmo, or debuglog object. It is always consumed by this
function. FDs can be created for certain other kernel object types by <code><a href="io.h.md#fdio_handle_fd">fdio_handle_fd</a>()</code> as long
as the returned file descriptor will only be used for waiting (rather than reading/writing).

If the `zx_handle_t` is a channel, then the channel must implement the
`fuchsia.unknown/Queryable` protocol.

For more precise control over which file descriptor is allocated, consider using <code><a href="fdio.h.md#fdio_create">fdio_create</a>()</code>
and <code><a href="fdio.h.md#fdio_bind_to_fd">fdio_bind_to_fd</a>()</code>.

Upon success, `fd_out` contains a file descriptor that can be used to access `handle`.

### Errors

  * `ZX_ERR_BAD_HANDLE`: The input `handle` is invalid.

  * `ZX_ERR_ACCESS_DENIED`: Then input `handle` does not have the necessary rights.

  * `ZX_ERR_NO_MEMORY`: Memory allocation failed.

  * `ZX_ERR_NOT_SUPPORTED`: The kernel object type is not valid for an FD.


## fdio_fd_transfer(…) {:#fdio_fd_transfer}

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

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

Prepares a file descriptor for transfer to another process.

Upon return, the given file descriptor has been removed from the file descriptor table for this
process.

Upon success, `out_handle` contains a handle that represents the given file descriptor. This
handle represents the connection to the file or service that was previously represented by the
`fd`. This behavior is identical to that of fdio_get_service_handle().

A file descriptor may not always be in a state that its underlying handle can be transferred in
this way. For example, if it has been dup()-ed, there will be more than one descriptor referring
to the same handle. In these cases, callers may want to use the less-efficient <code><a href="fd.h.md#fdio_fd_clone">fdio_fd_clone</a>()</code>
to create a new connection to the same file, or <code><a href="fd.h.md#fdio_fd_transfer_or_clone">fdio_fd_transfer_or_clone</a>()</code> to automatically do
this fallback.

### Errors

  * `ZX_ERR_INVALID_ARGS`: `fd` is not a valid file descriptor.

  * `ZX_ERR_UNAVAILABLE`: `fd` is busy or has been dup'ed and therefore is referenced by multiple
    entries in the file descriptor table.

  * `ZX_ERR_NOT_SUPPORTED`: `fd` cannot be represented as a `zx_handle_t`.

  * `ZX_ERR_BAD_STATE`: `fd` cannot be transferred to another process in its
    current state.

  * `ZX_ERR_ACCESS_DENIED`: `fd` has insufficient rights to clone the underlying object.


## fdio_fd_transfer_or_clone(…) {:#fdio_fd_transfer_or_clone}

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

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

Prepares a file descriptor for transfer (as <code><a href="fd.h.md#fdio_fd_transfer">fdio_fd_transfer</a>()</code>), or falls-back to cloning (as
<code><a href="fd.h.md#fdio_fd_clone">fdio_fd_clone</a>()</code> it if the descriptor is not transferrable. FDs that have been dup()ed have
multiple file descriptors sharing the same kernel handle that prevents doing a simple transfer.

Upon return, the given file descriptor has been removed from the file descriptor table for this
process.

Upon success, `out_handle` contains a handle that represents the given file descriptor.

### Errors

  * `ZX_ERR_INVALID_ARGS`: `fd` is not a valid file descriptor.

  * `ZX_ERR_UNAVAILABLE`: `fd` is busy.

  * `ZX_ERR_NOT_SUPPORTED`: `fd` cannot be represented as a `zx_handle_t`.

  * `ZX_ERR_BAD_STATE`: `fd` cannot be transferred to another process in its current state.

  * `ZX_ERR_ACCESS_DENIED`: `fd` has insufficient rights to clone the underlying object.