f7/sdk/fidl/fuchsia.process/README.md

<link rel="stylesheet" href="../style.css" />

[TOC]
# fuchsia.process

<p><b>Added:7</b></p>

## **PROTOCOLS**

## Launcher {#Launcher}
*Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=117)*
<p>A low-level interface for launching processes.</p>
<p>This interface is used for manually assembling a process. The caller supplies
all the capabilities for the newly created process.</p>
<p>That create processes typically use <code>fdio_spawn</code> or <code>fdio_spawn_etc</code> rather
than using this interface directly. The <code>fdio_spawn</code> and <code>fdio_spawn_etc</code>
functions are implemented using this interface.</p>
<p>Debuggers and other clients that need to create processes in a suspended
state often use this interface directly. These clients use the
<code>CreateWithoutStarting</code> method to create the process without actually
starting it.</p>

### AddArgs {#Launcher.AddArgs}

<p>Adds the given arguments to the command-line for the process.</p>
<p>Calling this method multiple times concatenates the arguments.</p>

#### Request {#Launcher.AddArgs_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>args</code></td>
            <td>
                <code>vector&lt;vector&lt;uint8&gt;&gt;</code>
            </td>
        </tr>
</table>


### AddEnvirons {#Launcher.AddEnvirons}

<p>Adds the given variables to the environment variables for the process.</p>
<p>Calling this method multiple times concatenates the variables.</p>

#### Request {#Launcher.AddEnvirons_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>environ</code></td>
            <td>
                <code>vector&lt;vector&lt;uint8&gt;&gt;</code>
            </td>
        </tr>
</table>


### AddHandles {#Launcher.AddHandles}

<p>Adds the given handles to the startup handles for the process.</p>
<p>Calling this method multiple times concatenates the handles.</p>

#### Request {#Launcher.AddHandles_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>handles</code></td>
            <td>
                <code>vector&lt;<a class='link' href='#HandleInfo'>HandleInfo</a>&gt;</code>
            </td>
        </tr>
</table>


### AddNames {#Launcher.AddNames}

<p>Adds the given names to the namespace for the process.</p>
<p>The paths in the namespace must be non-overlapping. See
<a href="https://fuchsia.dev/fuchsia-src/concepts/process/namespaces">https://fuchsia.dev/fuchsia-src/concepts/process/namespaces</a> for details.</p>
<p>Calling this method multiple times concatenates the names.</p>

#### Request {#Launcher.AddNames_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>names</code></td>
            <td>
                <code>vector&lt;<a class='link' href='#NameInfo'>NameInfo</a>&gt;</code>
            </td>
        </tr>
</table>


### CreateWithoutStarting {#Launcher.CreateWithoutStarting}

<p>Creates the process described by <code>info</code> but does not start it.</p>
<p>After processing this message, the <code>Launcher</code> is reset to its initial
state and is ready to launch another process.</p>
<p>The caller is responsible for calling <code>zx_process_start</code> using the data
in <code>ProcessStartData</code> to actually start the process.</p>
<p><code>data</code> is present if, and only if, <code>status</code> is <code>ZX_OK</code>.</p>

#### Request {#Launcher.CreateWithoutStarting_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>info</code></td>
            <td>
                <code><a class='link' href='#LaunchInfo'>LaunchInfo</a></code>
            </td>
        </tr>
</table>


#### Response {#Launcher.CreateWithoutStarting_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>status</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>data</code></td>
            <td>
                <code><a class='link' href='#ProcessStartData'>ProcessStartData</a>?</code>
            </td>
        </tr>
</table>

### Launch {#Launcher.Launch}

<p>Creates and starts the process described by <code>info</code>.</p>
<p>After processing this message, the <code>Launcher</code> is reset to its initial
state and is ready to launch another process.</p>
<p><code>process</code> is present if, and only if, <code>status</code> is <code>ZX_OK</code>.</p>

#### Request {#Launcher.Launch_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>info</code></td>
            <td>
                <code><a class='link' href='#LaunchInfo'>LaunchInfo</a></code>
            </td>
        </tr>
</table>


#### Response {#Launcher.Launch_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>status</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>process</code></td>
            <td>
                <code>handle&lt;process&gt;?</code>
            </td>
        </tr>
</table>

## Resolver {#Resolver}
*Defined in [fuchsia.process/resolver.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/resolver.fidl;l=28)*
<p>An interface for resolving names to executables and library loaders.</p>
<p>An executable itself is often not sufficient to create a working process
because many executables also load shared libraries. On Fuchsia, there is no
global pool of shared libraries. Instead, every process has an associated
<code>fuchsia.ldsvc.Loader</code>, which provides access to a private pool of shared
libraries appropriate for that process.</p>
<p>This interface provides a protocol for resolving a name into both the
<code>zx.handle:VMO</code> for the executable and the <code>fuchsia.ldsvc.Loader</code> for its
associated shared libraries.</p>
<p>This interface is rarely used directly. Instead, <code>fdio_spawn</code> and
<code>fdio_spawn_etc</code> use this interface internally when they try to run a file
with a <code>#!resolve</code> directive.</p>

### Resolve {#Resolver.Resolve}

<p>Resolves the given <code>name</code> to an <code>executable</code> and an shared library
loader.</p>
<p>If present, the <code>executable</code> is suitable for use as the <code>executable</code>
property of <code>LaunchInfo</code> -- in particular, it will have <code>ZX_RIGHT_EXECUTE</code>.
If present, the <code>ldsvc</code> is suitable for use as the <code>PA_LDSVC_LOADER</code>
handle when launching the process.</p>
<p>For example, the resolver might locate the given <code>name</code> inside a package
and return the executable binary from the package as well as a shared
library loader scoped to that package.</p>

#### Request {#Resolver.Resolve_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>name</code></td>
            <td>
                <code>string[2048]</code>
            </td>
        </tr>
</table>


#### Response {#Resolver.Resolve_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>status</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>executable</code></td>
            <td>
                <code>handle&lt;vmo&gt;?</code>
            </td>
        </tr>
        <tr>
            <td><code>ldsvc</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ldsvc/'>fuchsia.ldsvc</a>/<a class='link' href='../fuchsia.ldsvc/#Loader'>Loader</a>?</code>
            </td>
        </tr>
</table>


## **STRUCTS**

### HandleInfo [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#HandleInfo data-text="HandleInfo"}
*Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=17)*
<p>Information about a handle provided to a process at startup.</p>
<p>Processes are given a set of initial handles as part of the bootstrapping
sequence. Some of these handles are associated with zx.procarg identifiers
that designate their intended use by the new process.</p>
<p>This structure represents one such handle and its associated zx.procarg
identifier.</p>

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="HandleInfo.handle">
            <td><code>handle</code></td>
            <td>
                <code>handle&lt;handle&gt;</code>
            </td>
            <td><p>The handle to use for this process argument.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="HandleInfo.id">
            <td><code>id</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#procarg'>procarg</a></code>
            </td>
            <td><p>Process argument identifier.</p>
<p>See &lt;zircon/processargs.h&gt; for definitions of well-known process
arguments.</p>
</td>
            <td>No default</td>
        </tr>
</table>

### LaunchInfo [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#LaunchInfo data-text="LaunchInfo"}
*Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=46)*
<p>The information needed to launch a process.</p>

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="LaunchInfo.executable">
            <td><code>executable</code></td>
            <td>
                <code>handle&lt;vmo&gt;</code>
            </td>
            <td><p>The executable to run in the process.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="LaunchInfo.job">
            <td><code>job</code></td>
            <td>
                <code>handle&lt;job&gt;</code>
            </td>
            <td><p>The job in which to create the process.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="LaunchInfo.name">
            <td><code>name</code></td>
            <td>
                <code>string[32]</code>
            </td>
            <td><p>The name to assign to the created process.</p>
</td>
            <td>No default</td>
        </tr>
</table>

### NameInfo [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#NameInfo data-text="NameInfo"}
*Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=35)*
<p>A namespace entry provided to a process at startup.</p>
<p>Processes are given a set of initial handles as part of the bootstrapping
sequence. Some of these handles are associated with paths that designate
their intended use by the new process as namespace entries.</p>
<p>This structure represents one such handle and its associated namespace path.</p>

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="NameInfo.path">
            <td><code>path</code></td>
            <td>
                <code>string[4096]</code>
            </td>
            <td><p>Path at which to install the associated directory.</p>
<p>Must be an absolute path (i.e., start with '/').</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="NameInfo.directory">
            <td><code>directory</code></td>
            <td>
                <code><a class='link' href='../fuchsia.io/'>fuchsia.io</a>/<a class='link' href='../fuchsia.io/#Directory'>Directory</a></code>
            </td>
            <td><p>The associated directory.</p>
</td>
            <td>No default</td>
        </tr>
</table>

### ProcessStartData [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ProcessStartData data-text="ProcessStartData"}
*Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=60)*
<p>The information required to start a process.</p>
<p>To start the process, call <code>zx_process_start</code> with the arguments provided.</p>

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="ProcessStartData.process">
            <td><code>process</code></td>
            <td>
                <code>handle&lt;process&gt;</code>
            </td>
            <td><p>The process that was created.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ProcessStartData.root_vmar">
            <td><code>root_vmar</code></td>
            <td>
                <code>handle&lt;vmar&gt;</code>
            </td>
            <td><p>The vmar object that was created when the process was created.</p>
<p>See <a href="https://fuchsia.dev/fuchsia-src/reference/syscalls/process_create.md">https://fuchsia.dev/fuchsia-src/reference/syscalls/process_create.md</a>.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ProcessStartData.thread">
            <td><code>thread</code></td>
            <td>
                <code>handle&lt;thread&gt;</code>
            </td>
            <td><p>The initial thread for the process.</p>
<p>Should be passed to <code>zx_process_start</code> when starting the process.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ProcessStartData.entry">
            <td><code>entry</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#vaddr'>vaddr</a></code>
            </td>
            <td><p>The address of the initial entry point in the process.</p>
<p>Should be passed to <code>zx_process_start</code> when starting the process.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ProcessStartData.stack">
            <td><code>stack</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#vaddr'>vaddr</a></code>
            </td>
            <td><p>The stack pointer value for the initial thread of the process.</p>
<p>Should be passed to <code>zx_process_start</code> when starting the process.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ProcessStartData.bootstrap">
            <td><code>bootstrap</code></td>
            <td>
                <code>handle&lt;channel&gt;</code>
            </td>
            <td><p>The bootstrap channel to pass to the process on startup.</p>
<p>Should be passed to <code>zx_process_start</code> when starting the process.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ProcessStartData.vdso_base">
            <td><code>vdso_base</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#vaddr'>vaddr</a></code>
            </td>
            <td><p>The base address of the vDSO to pass to the process on startup.</p>
<p>Should be passed to <code>zx_process_start</code> when starting the process.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ProcessStartData.base">
            <td><code>base</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#vaddr'>vaddr</a></code>
            </td>
            <td><p>The base load address of the ELF file loaded.</p>
<p>Most often used by debuggers or other tools that inspect the process.</p>
</td>
            <td>No default</td>
        </tr>
</table>






## **CONSTANTS**

<table>
    <tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
        <tr id="MAX">
            <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=101">MAX</a></td>
                <td>
                    <code>4294967295</code>
                </td>
                <td><code>uint32</code></td>
            <td></td>
        </tr>
        <tr id="MAX_RESOLVE_NAME_SIZE">
            <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/resolver.fidl;l=10">MAX_RESOLVE_NAME_SIZE</a></td>
                <td>
                    <code>2048</code>
                </td>
                <td><code>uint32</code></td>
            <td><p>The maximum size for a name used by <code>Resolver</code>.</p>
</td>
        </tr>
</table>