Added: 7 ## **PROTOCOLS** ## Launcher *Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=113)* A low-level interface for launching processes. This interface is used for manually assembling a process. The caller supplies all the capabilities for the newly created process. That create processes typically use `fdio_spawn` or `fdio_spawn_etc` rather than using this interface directly. The `fdio_spawn` and `fdio_spawn_etc` functions are implemented using this interface. Debuggers and other clients that need to create processes in a suspended state often use this interface directly. These clients use the `CreateWithoutStarting` method to create the process without actually starting it.
### AddArgs Adds the given arguments to the command-line for the process. Calling this method multiple times concatenates the arguments. #### Request | Name | Type | |---|---| | `args` | `vector>` | ### AddEnvirons Adds the given variables to the environment variables for the process. Calling this method multiple times concatenates the variables. #### Request | Name | Type | |---|---| | `environ` | `vector>` | ### AddHandles Adds the given handles to the startup handles for the process. Calling this method multiple times concatenates the handles. #### Request | Name | Type | |---|---| | `handles` | `vector` | ### AddNames Adds the given names to the namespace for the process. The paths in the namespace must be non-overlapping. See for details. Calling this method multiple times concatenates the names. #### Request | Name | Type | |---|---| | `names` | `vector` | ### CreateWithoutStarting Creates the process described by `info` but does not start it. After processing this message, the `Launcher` is reset to its initial state and is ready to launch another process. The caller is responsible for calling `zx_process_start` using the data in `ProcessStartData` to actually start the process. `data` is present if, and only if, `status` is `ZX_OK`. #### Request | Name | Type | |---|---| | `info` | `https://fuchsia.dev/reference/fidl/fuchsia.process#LaunchInfo` | #### Response | Name | Type | |---|---| | `status` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Result` | | `data` | `https://fuchsia.dev/reference/fidl/fuchsia.process#ProcessStartData?` | ### Launch Creates and starts the process described by `info`. After processing this message, the `Launcher` is reset to its initial state and is ready to launch another process. `process` is present if, and only if, `status` is `ZX_OK`. #### Request | Name | Type | |---|---| | `info` | `https://fuchsia.dev/reference/fidl/fuchsia.process#LaunchInfo` | #### Response | Name | Type | |---|---| | `status` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Result` | | `process` | `handle?` | ### SetOptions Sets the options with which the process is created. Calling this method multiple times will overwrite the current options. Added: 9 #### Request | Name | Type | |---|---| | `options` | `uint32` | ## Resolver *Defined in [fuchsia.process/resolver.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/resolver.fidl;l=31)* An interface for resolving names to executables and library loaders. 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 `fuchsia.ldsvc.Loader`, which provides access to a private pool of shared libraries appropriate for that process. This interface provides a protocol for resolving a name into both the `zx.Handle:VMO` for the executable and the `fuchsia.ldsvc.Loader` for its associated shared libraries. This interface is rarely used directly. Instead, `fdio_spawn` and `fdio_spawn_etc` use this interface internally when they try to run a file with a `#!resolve` directive. **DEPRECATED**
### Resolve Resolves the given `name` to an `executable` and an shared library loader. If present, the `executable` is suitable for use as the `executable` property of `LaunchInfo` -- in particular, it will have `ZX_RIGHT_EXECUTE`. If present, the `ldsvc` is suitable for use as the `PA_LDSVC_LOADER` handle when launching the process. For example, the resolver might locate the given `name` inside a package and return the executable binary from the package as well as a shared library loader scoped to that package. #### Request | Name | Type | |---|---| | `name` | `string:2048` | #### Response | Name | Type | |---|---| | `status` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Result` | | `executable` | `handle?` | | `ldsvc` | `client_end:https://fuchsia.dev/reference/fuchsia.ldsvc//https://fuchsia.dev/reference/fuchsia.ldsvc#Loader?` | ## **STRUCTS** ### HandleInfo [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=16)* Information about a handle provided to a process at startup. Processes are given a set of initial handles as part of the bootstrapping sequence. Some of these handles are associated with process argument identifiers that designate their intended use by the new process. This structure represents one such handle and its associated identifier.
| Field | Type | Description | Default | |---|---|---|---| | `handle` | `handle` | The handle to use for this process argument. | No default | | `id` | `uint32` | Process argument identifier. See \ for definitions of well-known process arguments. | No default | ### LaunchInfo [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=45)* The information needed to launch a process.
| Field | Type | Description | Default | |---|---|---|---| | `executable` | `handle` | The executable to run in the process. | No default | | `job` | `handle` | The job in which to create the process. | No default | | `name` | `string:32` | The name to assign to the created process. | No default | ### NameInfo [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=34)* A namespace entry provided to a process at startup. 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. This structure represents one such handle and its associated namespace path.
| Field | Type | Description | Default | |---|---|---|---| | `path` | `https://fuchsia.dev/reference/fuchsia.io//https://fuchsia.dev/reference/fuchsia.io#Path` | Path at which to install the associated directory. Must be an absolute path (i.e., start with '/'). | No default | | `directory` | `client_end:https://fuchsia.dev/reference/fuchsia.io//https://fuchsia.dev/reference/fuchsia.io#Directory` | The associated directory. | No default | ### ProcessStartData [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource) *Defined in [fuchsia.process/launcher.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/launcher.fidl;l=59)* The information required to start a process. To start the process, call `zx_process_start` with the arguments provided.
| Field | Type | Description | Default | |---|---|---|---| | `process` | `handle` | The process that was created. | No default | | `root_vmar` | `handle` | The vmar object that was created when the process was created. See . | No default | | `thread` | `handle` | The initial thread for the process. Should be passed to `zx_process_start` when starting the process. | No default | | `entry` | `uint64` | The address of the initial entry point in the process. Should be passed to `zx_process_start` when starting the process. | No default | | `stack` | `uint64` | The stack pointer value for the initial thread of the process. Should be passed to `zx_process_start` when starting the process. | No default | | `bootstrap` | `handle` | The bootstrap channel to pass to the process on startup. Should be passed to `zx_process_start` when starting the process. | No default | | `vdso_base` | `uint64` | The base address of the vDSO to pass to the process on startup. Should be passed to `zx_process_start` when starting the process. | No default | | `base` | `uint64` | The base load address of the ELF file loaded. Most often used by debuggers or other tools that inspect the process. | No default | ## **CONSTANTS** | Name | Value | Type | Description | |---|---|---|---| | [MAX_RESOLVE_NAME_SIZE](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.process/resolver.fidl;l=10) | `2048` | `uint32` | The maximum size for a name used by `Resolver`. |