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

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

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

## fdio_flat_namespace struct {:#fdio_flat_namespace}

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

<pre class="devsite-disable-click-to-copy">
<span class="kwd">struct</span> <span class="typ">fdio_flat_namespace</span> {
    <span class="typ">size_t</span> count;
    <span class="typ">zx_handle_t *</span> handle;
    <span class="typ">uint32_t *</span> type;
    <span class="typ">const char *const *</span> path;
};
</pre>

Contains parallel arrays of handles, path names, and types.

### count

The number of elements in the other arrays of this struct.

### handle

handle[i] is the zx_handle_t representing that element in the namespace.

### type

type[i] is a handle info entry as defined in zircon/processargs.h by PA_HND.

### path

path[i] is the user-readable name of that element (e.g., "/bin").

## fdio_ns_bind(…) {:#fdio_ns_bind}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_bind</b>(<span class="typ">fdio_ns_t *</span> ns,
                         <span class="typ">const char *</span> path,
                         <span class="typ">zx_handle_t</span> h);
</pre>

Create a new directory within a namespace, bound to the directory-protocol-compatible handle h

The path must be an absolute path like "/x/y/z". It is relative to the root
of the namespace.

Ownership of `h` is transferred to `ns`: it is closed on error.

### Errors

  * `ZX_ERR_BAD_STATE`: Namespace is already in use and immutable.

  * `ZX_ERR_ALREADY_EXISTS`: There is already a mounted directory there.

  * `ZX_ERR_NOT_SUPPORTED`: `path` would shadow a mounted directory.

  * `ZX_ERR_INVALID_ARGS`: `path` is null or is not an absolute path.

  * `ZX_ERR_BAD_PATH`: `path` is not a valid path.


## fdio_ns_bind_fd(…) {:#fdio_ns_bind_fd}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_bind_fd</b>(<span class="typ">fdio_ns_t *</span> ns,
                            <span class="typ">const char *</span> path,
                            <span class="typ">int</span> fd);
</pre>

Create a new directory within a namespace, bound to the
directory referenced by the file descriptor fd.
The path must be an absolute path like "/x/y/z".  It is relative to the root
of the namespace.

`fd` is borrowed by this function, but is not closed on success or error.
Closing the fd after success does not affect namespace.

### Errors

  * `ZX_ERR_BAD_STATE: Namespace is already in use and immutable or `fd` cannot be cloned in its
    current state.

  * `ZX_ERR_ALREADY_EXISTS: There is already a mounted directory there.

  * `ZX_ERR_NOT_SUPPORTED: `path` would shadow a mounted directory or `fd` cannot
    be represented as a handle.

  * `ZX_ERR_INVALID_ARGS: `path` is null or is not an absolute path or `fd` is not
    a valid file descriptor.

  * `ZX_ERR_BAD_PATH: `path` is not a valid path.

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


## fdio_ns_bind_local(…) {:#fdio_ns_bind_local}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_bind_local</b>(<span class="typ">fdio_ns_t *</span> ns,
                               <span class="typ">const char *</span> path,
                               <span class="typ">fdio_open_local_func_t</span> on_open,
                               <span class="typ">void *</span> context);
</pre>

Create a new local entry within a namespace.

Opening the path will run the given `on_open` with the given `context` to
populate the file. The callback must set the zxio operations table, and can
set an internal state inside the provided storage.

The path must be an absolute path like "/x/y/z". It is relative to the root
of the namespace.

### Errors

  * `ZX_ERR_BAD_STATE`: Namespace is already in use and immutable.

  * `ZX_ERR_ALREADY_EXISTS`: There is already a mounted directory there.

  * `ZX_ERR_NOT_SUPPORTED`: `path` would shadow a mounted directory.

  * `ZX_ERR_INVALID_ARGS`: `path` is null or is not an absolute path.

  * `ZX_ERR_BAD_PATH`: `path` is not a valid path.


## fdio_ns_chdir(…) {:#fdio_ns_chdir}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_chdir</b>(<span class="typ">fdio_ns_t *</span> ns);
</pre>

Changes the current directory to "/" in the provided namespace.


## fdio_ns_connect(…) {:#fdio_ns_connect}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_connect</b>(<span class="typ">fdio_ns_t *</span> ns,
                            <span class="typ">const char *</span> path,
                            <span class="typ">uint32_t</span> flags,
                            <span class="typ">zx_handle_t</span> request);
</pre>

Attempt to connect to a service through the namespace. The handle is always consumed.  It will be
closed on error or passed to the remote service on success. The path must be an absolute path
starting with "/".


## fdio_ns_create(…) {:#fdio_ns_create}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_create</b>(<span class="typ">fdio_ns_t **</span> out);
</pre>

Create a new, empty namespace


## fdio_ns_destroy(…) {:#fdio_ns_destroy}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_destroy</b>(<span class="typ">fdio_ns_t *</span> ns);
</pre>

Destroy and deallocate a namespace.

If the namespace is in-use, it will be destroyed once it is no longer referenced.

This function always returns `ZX_OK`.


## fdio_ns_export(…) {:#fdio_ns_export}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_export</b>(<span class="typ">fdio_ns_t *</span> ns,
                           <span class="typ">fdio_flat_namespace_t **</span> out);
</pre>

On success the caller takes ownership of a fdio_flat_namespace_t containing a flat representation
of the exported namespace (the one provided in 'ns' or the active root namespace, respectively.)
The handles are CLONEs of the handles in the namespace and also belong to the caller.

The whole data structure can be released with fdio_ns_free_flat_ns().


## fdio_ns_export_root(…) {:#fdio_ns_export_root}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_export_root</b>(<span class="typ">fdio_flat_namespace_t **</span> out);
</pre>


## fdio_ns_free_flat_ns(…) {:#fdio_ns_free_flat_ns}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">void</span> <b>fdio_ns_free_flat_ns</b>(<span class="typ">fdio_flat_namespace_t *</span> ns);
</pre>

Frees a flat namespace.

Closes all handles contained within `ns`.


## fdio_ns_get_installed(…) {:#fdio_ns_get_installed}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_get_installed</b>(<span class="typ">fdio_ns_t **</span> ns);
</pre>

Retrieve the fdio "global" namespace (if any).


## fdio_ns_is_bound(…) {:#fdio_ns_is_bound}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">bool</span> <b>fdio_ns_is_bound</b>(<span class="typ">fdio_ns_t *</span> ns,
                      <span class="typ">const char *</span> path);
</pre>

Whether `path` is bound to a remote directory in `ns`.


## fdio_ns_open(…) {:#fdio_ns_open}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_open</b>(<span class="typ">fdio_ns_t *</span> ns,
                         <span class="typ">const char *</span> path,
                         <span class="typ">uint32_t</span> flags,
                         <span class="typ">zx_handle_t</span> request);
</pre>

Opens an object at `path` relative to the root of `ns` with `flags` asynchronously.

`path` is looked up in `ns`. If found, the object at `path` is opened, passing `request` to the
remote party.

Upon success, `request` is handed off to the remote party. The operation completes
asynchronously, which means a ZX_OK result does not ensure that the requested service actually
exists.

`path` must be absolute.

`flags` is a `fuchsia.io/OpenFlags`.

`request` must be a channel and it is always consumed by this function.

### Errors

  * `ZX_ERR_INVALID_ARGS`: `path` is invalid.

  * `ZX_ERR_NOT_FOUND`: A prefix of `path` cannot be found in `ns`.


## fdio_ns_opendir(…) {:#fdio_ns_opendir}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">int</span> <b>fdio_ns_opendir</b>(<span class="typ">fdio_ns_t *</span> ns);
</pre>

Opens the root directory of the namespace as a file descriptor


## fdio_ns_service_connect(…) {:#fdio_ns_service_connect}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_service_connect</b>(<span class="typ">fdio_ns_t *</span> ns,
                                    <span class="typ">const char *</span> path,
                                    <span class="typ">zx_handle_t</span> request);
</pre>

Connects to a service at `path` relative to the root of `ns` asynchronously.

`path` is looked up in `ns`. If found, the object at `path` is opened, passing `request` to the
remote party.

Upon success, `request` is handed off to the remote party. The operation completes
asynchronously, which means a ZX_OK result does not ensure that the requested service actually
exists.

`path` must be absolute.

`request` must be a channel and it is always consumed by this function.

### Errors

  * `ZX_ERR_INVALID_ARGS`: `path` is invalid.

  * `ZX_ERR_NOT_FOUND`: A prefix of `path` cannot be found in `ns`.


## fdio_ns_unbind(…) {:#fdio_ns_unbind}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_ns_unbind</b>(<span class="typ">fdio_ns_t *</span> ns,
                           <span class="typ">const char *</span> path);
</pre>

Unbinds `path` from a namespace, closing the handle within `ns` that corresponds to that path
when all references to the node go out of scope.

### Errors

  * `ZX_ERR_NOT_FOUND: `path` is not a remote.

  * `ZX_ERR_NOT_SUPPORTED: `path` is the root of the namespace.

  * `ZX_ERR_INVALID_ARGS: `path` is null or not an absolute path.

  * `ZX_ERR_BAD_PATH: `path` is not a valid path.