PROTOCOLS
Launcher
Defined in fuchsia.process/launcher.fidl
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<vector<uint8>>
|
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<vector<uint8>>
|
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<HandleInfo>
|
AddNames
Adds the given names to the namespace for the process.
The paths in the namespace must be non-overlapping. See https://fuchsia.dev/fuchsia-src/concepts/process/namespaces for details.
Calling this method multiple times concatenates the names.
Request
Name | Type |
---|---|
names |
vector<NameInfo>
|
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 |
LaunchInfo
|
Response
Name | Type |
---|---|
status |
zx/Status
|
data |
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 |
LaunchInfo
|
Response
Name | Type |
---|---|
status |
zx/Status
|
process |
handle<process>?
|
SetOptions
Sets the options with which the process is created.
Calling this method multiple times will overwrite the current options.
Request
Name | Type |
---|---|
options |
uint32
|
Resolver
Defined in fuchsia.process/resolver.fidl
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 |
zx/Status
|
executable |
handle<vmo>?
|
ldsvc |
fuchsia.ldsvc/Loader?
|
STRUCTS
HandleInfo resource
Defined in fuchsia.process/launcher.fidl
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<handle>
|
The handle to use for this process argument. |
No default |
id |
uint32
|
Process argument identifier. See <zircon/processargs.h> for definitions of well-known process arguments. |
No default |
LaunchInfo resource
Defined in fuchsia.process/launcher.fidl
The information needed to launch a process.
Field | Type | Description | Default |
---|---|---|---|
executable |
handle<vmo>
|
The executable to run in the process. |
No default |
job |
handle<job>
|
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
Defined in fuchsia.process/launcher.fidl
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 |
fuchsia.io/Path
|
Path at which to install the associated directory. Must be an absolute path (i.e., start with '/'). |
No default |
directory |
fuchsia.io/Directory
|
The associated directory. |
No default |
ProcessStartData resource
Defined in fuchsia.process/launcher.fidl
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<process>
|
The process that was created. |
No default |
root_vmar |
handle<vmar>
|
The vmar object that was created when the process was created. See https://fuchsia.dev/fuchsia-src/reference/syscalls/process_create.md. |
No default |
thread |
handle<thread>
|
The initial thread for the process. Should be passed to |
No default |
entry |
uint64
|
The address of the initial entry point in the process. Should be passed to |
No default |
stack |
uint64
|
The stack pointer value for the initial thread of the process. Should be passed to |
No default |
bootstrap |
handle<channel>
|
The bootstrap channel to pass to the process on startup. Should be passed to |
No default |
vdso_base |
uint64
|
The base address of the vDSO to pass to the process on startup. Should be passed to |
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 |
2048
|
uint32 |
The maximum size for a name used by |