fuchsia.sys

PROTOCOLS

ComponentController

Defined in fuchsia.sys/component_controller.fidl

An interface for controlling components.

Closing this interface implicitly kills the controlled component unless the Detach method has been called.

If the component exits, this interface will be closed.

Typically obtained via Launcher.CreateComponent.

Kill

Terminates the component.

This ComponentController connection is closed when the component has terminated.

Request

NameType

Detach

Decouples the lifetime of the component from this controller.

After calling Detach, the component will not be implicitly killed when this interface is closed.

Request

NameType

OnTerminated

DEPRECATED: Use OnTerminated instead of Wait(). 3: Wait() Event that is triggered when the component is terminated.

This event provides the return code of the process and reason for its termination. The return_code is only valid if the termination reason is EXITED. If the termination reason is not EXITED, the return code is guaranteed not to be 0.

Response

NameType
return_code int64
termination_reason TerminationReason

OnDirectoryReady

Event that is triggered when the component's output directory is mounted.

This event will not be triggered for every component, only those that serve a directory over their PA_DIRECTORY_REQUEST handle.

Response

NameType

Environment

Defined in fuchsia.sys/environment.fidl

An interface for managing a set of applications.

Applications run inside environments, which provide ambient services and support for their lifecycle.

CreateNestedEnvironment

Creates a new environment nested inside this environment.

When applications are created inside the nested environment using the environment's Launcher, the environment requests the environment services from host_directory before passing those services to the newly created application in its StartupInfo.

The controller can be used to control the lifecycle of the created environment. Note that by default the environment will be killed automatically when the EnvironmentController's interface is closed. You can use EnvironmentController.Detach to disable this behavior.

label defines the new environment's label/name. It must be unique within the parent environment (though not globally) and is used for isolating separate environments. It can also be used for diagnostic purposes. The label will be truncated if it is longer than kLabelMaxLength.

additional_services, which may be empty, contains a list of services that the environment provides, which are hosted by additional_services.host_directory. If options.inherit_parent_services is false, host_directory must provide a Loader service if it wishes to allow new components to be loaded in the new environment.

options provides additional options, see EnvironmentOptions for details.

Request

NameType
environment request<Environment>
controller request<EnvironmentController>
label string
additional_services ServiceList?
options EnvironmentOptions

GetLauncher

Gets the Launcher associated with this environment.

Applications created using this application launcher will be given the environment services provided by this environment's host_directory.

Request

NameType
launcher request<Launcher>

GetServices

Gets a superset of services provided by this environment's host_directory.

Request

NameType
services request<ServiceProvider>

GetDirectory

Gets a superset of services provided by this environment's host_directory.

Request

NameType
directory_request handle<channel>

EnvironmentController

Defined in fuchsia.sys/environment_controller.fidl

An interface for controlling an environment.

Closing this interface implicitly kills the controlled environment unless the Detach method has been called.

If the environment is destroyed, this interface will be closed.

Typically obtained via Environment.CreateNestedEnvironment.

Kill

Terminates the environment.

When an Environment is terminated, all applications launched in the environment (and in all transitively nested environments) are also killed.

Request

NameType

Response

NameType

Detach

Decouples the lifetime of the environment from this controller.

After calling Detach, the environment will not be implicitly killed when this interface is closed.

Request

NameType

OnCreated

Event that is triggered when the environment is created.

Response

NameType

JobProvider

Defined in fuchsia.sys/job_provider.fidl

An interface for providing a job handle. Instances of this interface are created in the context of an already-identified realm, so there is no need to explicitly identify the realm below.

GetJob

Gets the root job associated with the realm.

Request

NameType

Response

NameType
job handle<job>

Launcher

Defined in fuchsia.sys/launcher.fidl

An interface for creating component instances.

Typically obtained via Environment.GetLauncher.

CreateComponent

Creates a new instance of the component described by launch_info.

The component instance is created in the Environment associated with this Launcher. When creating the component, the environment requests the environment services for this component from its EnvironmentHost.

The controller can be used to control the lifecycle of the created component instance. If an ComponentController's interface is requested, the component instance is killed when the interface is closed.

Request

NameType
launch_info LaunchInfo
controller request<ComponentController>?

Loader

Defined in fuchsia.sys/loader.fidl

An interface for loading from packages.

LoadUrl

LoadUrl a package by url.

Request

NameType
url string[2083]

Response

NameType
package Package?

Runner

Defined in fuchsia.sys/runner.fidl

An interface for running components.

Typically exposed by components that provide execution environments for particular classes of programs. For example, the Dart virtual machine exposes this interface to run Dart programs.

StartComponent

Execute the given component.

Upon startup, the component is to be given the information in startup_info, but the mechanism by which the component receives that information is up to the component runner.

The controller interface request typically originates from the Launcher.CreateComponent message that caused this component to be started.

Request

NameType
package Package
startup_info StartupInfo
controller request<ComponentController>?

ServiceProvider

Defined in fuchsia.sys/service_provider.fidl

An interface through which a client may request services from a host. Instances of this interface are created within the context of an already-identified client and host pair, so there is no need to explicitly identify the client or host in the methods below.

This interface is deprecated. Services should be published as directory entries instead, just like files.

ConnectToService

Asks the host to provide the service identified by service_name through the channel endpoint supplied by the caller. If the host is not willing or able to provide the requested service, it should close the channel.

Request

NameType
service_name string
channel handle<channel>

STRUCTS

EnvironmentOptions

Defined in fuchsia.sys/environment.fidl

NameTypeDescriptionDefault
inherit_parent_services bool True if this environment should inherit services provided by the parent environment. No default
allow_parent_runners bool True if components in this environment can share a runner provided by the parent environment. If false, a new runner will be started in this environment for components. No default
kill_on_oom bool True if this environment should be killed first in out of memory situations by setting the `ZX_PROP_JOB_KILL_ON_OOM` property on this environment's job. No default
delete_storage_on_death bool True if "persistent" storage requested by components in this environment should not actually be persistent, and instead be deleted when this environment is killed. No default

FlatNamespace

Defined in fuchsia.sys/flat_namespace.fidl

NameTypeDescriptionDefault
paths vector<string> The mount point for each of the directories below. For example, ["/pkg", "/svc"]. No default
directories vector<channel> The directories mounted at each path in the namespace. No default

FileDescriptor

Defined in fuchsia.sys/launcher.fidl

An FDIO file descriptor.

NameTypeDescriptionDefault
type0 int32 The FDIO types of the handle (e.g., `FA_FDIO_REMOTE`). No default
type1 int32 No default
type2 int32 No default
handle0 handle<handle>? The handles for the file descriptor (e.g., a channel). No default
handle1 handle<handle>? No default
handle2 handle<handle>? No default

LaunchInfo

Defined in fuchsia.sys/launcher.fidl

Information used to create an instance of a component and obtain services from it.

NameTypeDescriptionDefault
url string[2083] The location from which to retrieve this component. This field will probably be replaced with a stronger notion of identity, such as an unforgeable token. This field is included in this iteration to ease the transition from the previous component interfaces. No default
arguments vector<string>? The arguments to be provided to the component. No default
out FileDescriptor? The file descriptor to use for stdout. If null, the component will use the default stdout for the environment. No default
err FileDescriptor? The file descriptor to use for stderr. If null, the component will use the default stderr for the environment. No default
directory_request handle<channel>? The interface request for a Directory that is passed through to the component and arrives in the component as its `directory_request` interface request. No default
flat_namespace FlatNamespace? A custom namespace that can be appended to the namespace generated by appmgr and provided to this component. Adding a mount point at standard paths like 'pkg' or 'svc' will be ignored. HACK(alhaad): Adding mount points for deprecated default directories like '/data' will override the default. No default
additional_services ServiceList? A list of services to be added to this component's svc namespace. These services are in addition to those coming from Environment. No default

ServiceList

Defined in fuchsia.sys/launcher.fidl

NameTypeDescriptionDefault
names vector<string> A list of services that can be requested from `provider`. No default
provider ServiceProvider? A service provider to get the services listed in `names` from. No default
host_directory handle<channel>? A channel to the directory hosting the services in `names`. No default

StartupInfo

Defined in fuchsia.sys/runner.fidl

Information given to components at startup.

For ELF binaries, this information is provided in the initialization message given to libc by fuchsia.process.Launcher.

NameTypeDescriptionDefault
launch_info LaunchInfo The launch info for the component to start. No default
flat_namespace FlatNamespace The namespace in which to run the component. No default
program_metadata vector<ProgramMetadata>? Key string value string map of the component's program metadata, obtained from its component manifest. No default

ProgramMetadata

Defined in fuchsia.sys/runner.fidl

Program information about a component.

NameTypeDescriptionDefault
key string Key for program metadata pair. E.g. "binary" for an ELF binary component, or "data" for a flutter/dart component. No default
value string Value for program metadata pair. E.g. "bin/app" for a "binary" key, or "data/foo" for a flutter/dart component. No default

Package

Defined in fuchsia.sys/runner.fidl

A binary representation of a component.

Typically provided to Runner.StartComponent when starting a component.

NameTypeDescriptionDefault
data fuchsia.mem/Buffer? A read-only binary representation of the component. For example, if the component is intended to run in the Dart virtual machine, this data might contain a dartx package. No default
directory handle<channel>? A directory containing the contents of the package. For example, if the component is stored in pkgfs, this directory will be the pkgfs directory containing the package. No default
resolved_url string[2083] Resolved URL of the component. This is the url specified in `startup_info` after following redirects and resolving relative paths. No default

ENUMS

TerminationReason

Type: uint32

Defined in fuchsia.sys/component_controller.fidl

NameValueDescription
UNKNOWN 0
EXITED 1
URL_INVALID 2
PACKAGE_NOT_FOUND 3
INTERNAL_ERROR 4
PROCESS_CREATION_ERROR 5
RUNNER_FAILED 6
RUNNER_TERMINATED 7
UNSUPPORTED 8

CONSTANTS

NameValueType
kLabelMaxLength 32 uint32
MAX_URL_LENGTH 2083 uint16