fuchsia.sys

Deprecation

The Components v1 framework, which serves uses these protocols, has been removed from the Fuchsia platform in https://fxrev.dev/874963 and https://fxrev.dev/874960.

Use Component Framework v2 and its APIs in fuchsia.component.* instead.

Removed: 14 Added: 7

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.

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

<EMPTY>

Kill

Terminates the component.

This ComponentController connection is closed when the component has terminated.

Request

<EMPTY>

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

<EMPTY>

OnTerminated

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

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 server_end<Environment>
controller server_end<EnvironmentController>
label string
additional_services ServiceList?
options EnvironmentOptions

GetDirectory

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

Request

NameType
directory_request server_end<fuchsia.io/Directory>

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 server_end<Launcher>

GetServices

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

Request

NameType
services server_end<ServiceProvider>

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.

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

<EMPTY>

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

<EMPTY>

Response

<EMPTY>

OnCreated

Event that is triggered when the environment is created.

Response

<EMPTY>

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

<EMPTY>

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 server_end<ComponentController>?

Loader

Defined in fuchsia.sys/loader.fidl

An interface for loading from packages.

LoadUrl

Load a package by url. The returned package's data VMO handle will not have ZX_RIGHT_EXECUTE, but the directory field, if present, will have both the READABLE and EXECUTABLE rights.

Request

NameType
url component_url

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 server_end<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

FieldTypeDescriptionDefault
inherit_parent_services bool

True if this environment should inherit services provided by the parent environment.

No default
use_parent_runners bool

True if components in this environment will 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

FileDescriptor resource

Defined in fuchsia.sys/launcher.fidl

An FDIO file descriptor.

FieldTypeDescriptionDefault
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

FlatNamespace resource

Defined in fuchsia.sys/flat_namespace.fidl

FieldTypeDescriptionDefault
paths vector<string>

The mount point for each of the directories below.

For example, ["/pkg", "/svc"].

No default
directories vector<fuchsia.io/Directory>
Added: 10
No default

LaunchInfo resource

Defined in fuchsia.sys/launcher.fidl

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

FieldTypeDescriptionDefault
url component_url

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 server_end<fuchsia.io/Directory>?
Added: 10
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

Package resource

Defined in fuchsia.sys/runner.fidl

A binary representation of a component.

Typically provided to Runner.StartComponent when starting a component.

FieldTypeDescriptionDefault
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 fuchsia.io/Directory?
Added: 10
No default
resolved_url component_url

Resolved URL of the component. This is the url specified in startup_info after following redirects and resolving relative paths.

No default

ProgramMetadata

Defined in fuchsia.sys/runner.fidl

Program information about a component.

FieldTypeDescriptionDefault
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

ServiceList resource

Defined in fuchsia.sys/launcher.fidl

FieldTypeDescriptionDefault
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 fuchsia.io/Directory?
Added: 10
No default

StartupInfo resource

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.

FieldTypeDescriptionDefault
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

ENUMS

TerminationReason strict

Type: uint32

Defined in fuchsia.sys/component_controller.fidl

NameValueDescription
0

The channel closed without giving a termination reason.

1

Component ran and exited with a given return_code.

2

The given URL given to launch was invalid.

3

The requested package could not be found.

4

An internal error happened during the launch process.

5

Process creation failed.

6

A Runner failed to start.

7

A Runner terminated while attempting to run a component.

8

Attempted to use an unsupported feature.

9

Attempted to create a component in a realm which is shutting down.

10

Insufficient privilege to start the component.

CONSTANTS

NameValueTypeDescription
MAX_URL_LENGTH 2083 uint16
kLabelMaxLength 32 uint32

Maximum length for an environment label.

ALIASES

NameValueDescription
component_url string[MAX_URL_LENGTH]

A URL used to retrieve, launch, and load a component from a specified network location, or to identify a component when connecting to it.