fuchsia.process

Added: 7

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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
info LaunchInfo

Response

NameType
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

NameType
info LaunchInfo

Response

NameType
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.

Added: 9

Request

NameType
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

NameType
name string:2048

Response

NameType
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.

FieldTypeDescriptionDefault
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.

FieldTypeDescriptionDefault
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.

FieldTypeDescriptionDefault
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.

FieldTypeDescriptionDefault
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 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<channel>

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

NameValueTypeDescription
MAX_RESOLVE_NAME_SIZE 2048 uint32

The maximum size for a name used by Resolver.