Crate process_builder

Native process creation and program loading library.

Restrictions

Most Fuchsia processes are not able to use this library.

This library uses the zx_process_create syscall to create a new process in a job. Use of that syscall requires that the job of the process using the syscall (not the job that the process is being created in) be allowed to create processes. In concrete terms, the process using this library must be in a job whose ZX_POL_NEW_PROCESS job policy is ZX_POL_ACTION_ALLOW.

Most processes on Fuchsia run in jobs where this job policy is set to DENY and thus will not be able to use this library. Those processes should instead use the fuchsia.process.Launcher FIDL service, which is itself implemented using this library. [fdio::spawn()], [fdio::spawn_vmo()], and [fdio::spawn_etc()] provide simple interfaces to this service.

Example

let process_name = CString::new("my_process")?;
let job = /* job to create new process in */;
let executable = /* VMO with execute rights containing ELF executable */;
let pkg_directory = /* fidl::endpoints::ClientEnd for fuchsia.io.Directory */;
let out_directory = /* server end of zx::Channel */;
let other_handle = /* some arbitrary zx::Handle */;

let builder = ProcessBuilder::new(&process_name, &job, executable)?;
builder.add_arguments(vec![process_name, CString::new("arg0")?]);
builder.add_environment_variables(vec![CString::new("VAR=VALUE")?]);
builder.add_namespace_entries(vec![NamespaceEntry{
    path: CString::new("/pkg")?,
    directory: package_directory,
}])?;
builder.add_handles(vec![
    StartupHandle{
        handle: out_directory.into_handle(),
        info: HandleInfo::new(HandleType::DirectoryRequest, 0),
    },
    StartupHandle{
        handle: other_handle,
        info: HandleInfo::new(HandleType::User0, 1),
    },
])?;

let built_process: BuiltProcess = builder.build()?;
let process: zx::Process = builder.start()?;

Modules

elf_load

Utilities for loading ELF files into an existing address space.

elf_parse

Parses ELF files per the ELF specification in ulib/musl/include/elf.h

Structs

BuiltProcess

A container for a fully built but not yet started (as in, its initial thread is not yet running) process, with all related handles and metadata. Output of ProcessBuilder::build().

Message

A bootstrap message following the processargs protocol.

MessageContents

Contents of a bootstrap message, following the processargs protocol. Used as an input to Message::build().

NamespaceEntry

A container for a single namespace entry, containing a path and a directory handle. Used as an input to ProcessBuilder::add_namespace_entries().

ProcessBuilder

The main builder type for this crate. Collects inputs and creates a new process.

StartupHandle

A container for a single startup handle, containing a handle and metadata. Used as an input to ProcessBuilder::add_handles().

Enums

ProcessBuilderError

Error type returned by ProcessBuilder methods.

ProcessargsError

Possible errors that can occur during processargs startup message construction

Functions

calculate_initial_linker_stack_size

Calculate the size of the initial stack to allocate for the dynamic linker, based on the given process_args message contents.

compute_initial_stack_pointer

Given the base and size of the stack block, compute the appropriate initial SP value for an initial thread according to the C calling convention for the machine.

get_dynamic_linker

Load the dynamic linker/loader specified in the PT_INTERP header via the fuchsia.ldsvc.Loader handle.