f10n/sdk/lib/fdio/spawn.h.md

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

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

## FDIO_SPAWN_ERR_MSG_MAX_LENGTH macro {:#FDIO_SPAWN_ERR_MSG_MAX_LENGTH}

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

<pre class="devsite-disable-click-to-copy">
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_ERR_MSG_MAX_LENGTH</span> ((size_t)1024u)
</pre>

The maximum size for error messages from <code><a href="spawn.h.md#fdio_spawn_etc">fdio_spawn_etc</a>()</code> including the null terminator.

## Spawn action command macros {:#FDIO_SPAWN_ACTION_CLONE_FD}

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

<pre class="devsite-disable-click-to-copy">
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_ACTION_CLONE_FD</span> ((uint32_t)0x0001u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_ACTION_TRANSFER_FD</span> ((uint32_t)0x0002u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_ACTION_ADD_NS_ENTRY</span> ((uint32_t)0x0003u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_ACTION_ADD_HANDLE</span> ((uint32_t)0x0004u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_ACTION_SET_NAME</span> ((uint32_t)0x0005u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_ACTION_CLONE_DIR</span> ((uint32_t)0x0006u)
</pre>


The <code><a href="spawn.h.md#fdio_spawn_etc">fdio_spawn_etc</a>()</code> function allows the running process to control the file descriptor table
in the process being spawned. These values are put into the `action` field of
`fdio_spawn_action_t` to indicate which action is requested and which of the union subfields to
use.


### FDIO_SPAWN_ACTION_CLONE_FD

Duplicate a descriptor `local_fd` into `target_fd` in the spawned process. Uses the `fd` entry in
the `fdio_spawn_action_t` union.


### FDIO_SPAWN_ACTION_TRANSFER_FD

Transfer local descriptor `local_fd` into `target_fd` in the spawned process.

This action will fail if `local_fd` is not a valid `local_fd`, if `local_fd` has been duplicated,
if `local_fd` is being used in an io operation, or if `local_fd` does not support this operation.

From the point of view of the calling process, the `local_fd` will appear to have been closed,
regardless of whether the `fdio_spawn_etc` call succeeds.

Uses the `fd` entry in the `fdio_spawn_action_t` union.


### FDIO_SPAWN_ACTION_ADD_NS_ENTRY

Add the given entry to the namespace of the spawned process.

If `FDIO_SPAWN_CLONE_NAMESPACE` is specified via `flags`, the namespace entry is added to the
cloned namespace from the calling process.

The namespace entries are added in the order they appear in the action list. If
`FDIO_SPAWN_CLONE_NAMESPACE` is specified via `flags`, the entries from the calling process are
added before any entries specified with `FDIO_SPAWN_ACTION_ADD_NS_ENTRY`.

The spawned process decides how to process and interpret the namespace entries. Typically, the
spawned process with disregard duplicate entries (i.e., the first entry for a given name wins)
and will ignore nested entries (e.g., `/foo/bar` when `/foo` has already been added to the
namespace).

To override or replace an entry in the namespace of the calling process, use
`fdio_ns_export_root` to export the namespace table of the calling process and construct the
namespace for the spawned process explicitly using `FDIO_SPAWN_ACTION_ADD_NS_ENTRY`.

The given handle will be closed regardless of whether the `fdio_spawn_etc` call succeeds.

Uses the `ns` entry in the `fdio_spawn_action_t` union.


### FDIO_SPAWN_ACTION_ADD_HANDLE

Add the given handle to the process arguments of the spawned process.

The given handle will be closed regardless of whether the `fdio_spawn_etc` call succeeds.

Uses the `h` entry in the `fdio_spawn_action_t` union.


### FDIO_SPAWN_ACTION_SET_NAME

Sets the name of the spawned process to the given name.

Overrides the default of use the first argument to name the process.

Uses the `name` entry in the `fdio_spawn_action_t` union.


### FDIO_SPAWN_ACTION_CLONE_DIR

Shares the given directory by installing it into the namespace of spawned process.

Uses the `dir` entry in the `fdio_spawn_action_t` union

## Spawn flag macros {:#FDIO_SPAWN_CLONE_JOB}

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

<pre class="devsite-disable-click-to-copy">
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_CLONE_JOB</span> ((uint32_t)0x0001u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_DEFAULT_LDSVC</span> ((uint32_t)0x0002u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_CLONE_NAMESPACE</span> ((uint32_t)0x0004u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_CLONE_STDIO</span> ((uint32_t)0x0008u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_CLONE_ENVIRON</span> ((uint32_t)0x0010u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_CLONE_UTC_CLOCK</span> ((uint32_t)0x0020u)
<span class="kwd">#define</span> <span class="lit">FDIO_SPAWN_CLONE_ALL</span> ((uint32_t)0xFFFFu)
</pre>


The <code><a href="spawn.h.md#fdio_spawn">fdio_spawn</a>()</code> and <code><a href="spawn.h.md#fdio_spawn_etc">fdio_spawn_etc</a>()</code> functions allow some or all of the environment of the
running process to be shared with the process being spawned. These macros define bits that can
be combined in the `flags` parameter.


### FDIO_SPAWN_CLONE_JOB

Provides the spawned process with the job in which the process was created.

The spawned process receives the job using the `PA_JOB_DEFAULT` process argument.


### FDIO_SPAWN_DEFAULT_LDSVC

Provides the spawned process with the shared library loader resolved via fuchsia.process.Resolver
(if resolved), or that which is used by this process.

The shared library loader is passed as `PA_LDSVC_LOADER`.


### FDIO_SPAWN_CLONE_NAMESPACE

Clones the filesystem namespace into the spawned process.


### FDIO_SPAWN_CLONE_STDIO

Clones file descriptors 0, 1, and 2 into the spawned process.

Skips any of these file descriptors that are closed without generating an error.


### FDIO_SPAWN_CLONE_ENVIRON

Clones the environment into the spawned process.


### FDIO_SPAWN_CLONE_UTC_CLOCK

Clones the process-global UTC clock into the spawned process.


### FDIO_SPAWN_CLONE_ALL

Clones all of the above into the spawned process.

## fdio_spawn_action struct {:#fdio_spawn_action}

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

<pre class="devsite-disable-click-to-copy">
<span class="kwd">struct</span> <span class="typ">fdio_spawn_action</span> {
    <span class="typ">uint32_t</span> action;
    <span class="typ">GlobalNamespace::fdio_spawn_action::</span> ;
};
</pre>

### action

The action to take.

See `FDIO_SPAWN_ACTION_*` above. If `action` is invalid, the action will be ignored (rather
than generate an error).

## fdio_spawn(…) {:#fdio_spawn}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_spawn</b>(<span class="typ">zx_handle_t</span> job,
                       <span class="typ">uint32_t</span> flags,
                       <span class="typ">const char *</span> path,
                       <span class="typ">const char *const *</span> argv,
                       <span class="typ">zx_handle_t *</span> process_out);
</pre>

Spawn a process in the given job.

The program for the process is loaded from the given `path` and passed `argv`. The aspects of
this process' environment indicated by `flags` are shared with the process. If the target program
begins with `#!resolve ` then the binary is resolved by url via `fuchsia.process.Resolver`.

The `argv` array must be terminated with a null pointer.

If `job` is `ZX_HANDLE_INVALID`, then the process is spawned in `zx_job_default()`. Does not take
ownership of `job`.

Upon success, `process_out` will be a handle to the process.

### Errors

  * `ZX_ERR_NOT_FOUND`: `path` cannot be opened.

  * `ZX_ERR_BAD_HANDLE`: `path` cannot be opened as an executable VMO.

  * `ZX_ERR_PEER_CLOSED`: Cannot connect to `fuchsia.process.Launcher`.

Returns the result of <code><a href="spawn.h.md#fdio_spawn_vmo">fdio_spawn_vmo</a>()</code> in all other cases.


## fdio_spawn_etc(…) {:#fdio_spawn_etc}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_spawn_etc</b>(<span class="typ">zx_handle_t</span> job,
                           <span class="typ">uint32_t</span> flags,
                           <span class="typ">const char *</span> path,
                           <span class="typ">const char *const *</span> argv,
                           <span class="typ">const char *const *</span> environ,
                           <span class="typ">size_t</span> action_count,
                           <span class="typ">const fdio_spawn_action_t *</span> actions,
                           <span class="typ">zx_handle_t *</span> process_out,
                           <span class="typ">char[1024]</span> err_msg_out);
</pre>

Spawn a process in the given job.

The binary for the process is loaded from the given `path` and passed `argv`. The aspects of this
process' environment indicated by `clone` are shared with the process.

The spawned process is also given `environ` as its environment and the given `actions` are
applied when creating the process.

The `argv` array must be terminated with a null pointer.

If non-null, the `environ` array must be terminated with a null pointer.

If non-null, the `err_msg_out` buffer must have space for `FDIO_SPAWN_ERR_MSG_MAX_LENGTH` bytes.

If both `FDIO_SPAWN_CLONE_ENVIRON` and `environ` are specified, then the spawned process is given
`environ` as its environment. If both `FDIO_SPAWN_CLONE_STDIO` and `actions` that target any of
fds 0, 1, and 2 are specified, then the actions that target those fds will control their
semantics in the spawned process.

If `job` is `ZX_HANDLE_INVALID`, then the process is spawned in `zx_job_default()`. Does not take
ownership of `job`.

Upon success, `process_out` will be a handle to the process. Upon failure, if `err_msg_out` is
not null, an error message will be we written to `err_msg_out`, including a null terminator.

### Errors

  * `ZX_ERR_NOT_FOUND`: `path` cannot be opened.

  * `ZX_ERR_BAD_HANDLE`: `path` cannot be opened as an executable VMO.

  * `ZX_ERR_PEER_CLOSED`: Cannot connect to `fuchsia.process.Launcher`.

Returns the result of <code><a href="spawn.h.md#fdio_spawn_vmo">fdio_spawn_vmo</a>()</code> in all other cases.


## fdio_spawn_vmo(…) {:#fdio_spawn_vmo}

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

<pre class="devsite-disable-click-to-copy">
<span class="typ">zx_status_t</span> <b>fdio_spawn_vmo</b>(<span class="typ">zx_handle_t</span> job,
                           <span class="typ">uint32_t</span> flags,
                           <span class="typ">zx_handle_t</span> executable_vmo,
                           <span class="typ">const char *const *</span> argv,
                           <span class="typ">const char *const *</span> environ,
                           <span class="typ">size_t</span> action_count,
                           <span class="typ">const fdio_spawn_action_t *</span> actions,
                           <span class="typ">zx_handle_t *</span> process_out,
                           <span class="typ">char[1024]</span> err_msg_out);
</pre>

Spawn a process using the given executable in the given job.

See <code><a href="spawn.h.md#fdio_spawn_etc">fdio_spawn_etc</a>()</code> for details. Rather than loading the binary for the process from a path,
this function receives the binary as the contents of a vmo.

Always consumes `executable_vmo`.

### Errors

  * `ZX_ERR_INVALID_ARGS`: any supplied action is invalid, or the process name is unset.

  * `ZX_ERR_IO_INVALID`: the recursion limit is hit resolving the executable name.

  * `ZX_ERR_BAD_HANDLE`: `executable_vmo` is not a valid handle.

  * `ZX_ERR_WRONG_TYPE`: `executable_vmo` is not a VMO handle.

  * `ZX_ERR_ACCESS_DENIED`: `executable_vmo` is not readable.

  * `ZX_ERR_OUT_OF_RANGE`: `executable_vmo` is smaller than the resolver prefix.

  * `ZX_ERR_PEER_CLOSED`: Cannot connect to `fuchsia.process.Launcher`.

  * `ZX_ERR_INTERNAL`: A dependency needed to launch the process was unavailable. Most commonly
    this indicates a failure attempting to resolve a `#!resolve ` line using
    `fuchsia.process.Resolver`.

May return other errors.