Crate process_builder

source ·
Expand description

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()?;

Re-exports

pub use self::elf_load::ElfLoadError;
pub use self::elf_parse::ElfParseError;

Modules

Utilities for loading ELF files into an existing address space.
Parses ELF files. For documentation on the format, see the ELF specification or /usr/include/elf.h

Structs

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().
A bootstrap message following the processargs protocol.
Contents of a bootstrap message, following the processargs protocol. Used as an input to Message::build().
A container for a single namespace entry, containing a path and a directory handle. Used as an input to ProcessBuilder::add_namespace_entries().
The main builder type for this crate. Collects inputs and creates a new process.
A container for a single startup handle, containing a handle and metadata. Used as an input to ProcessBuilder::add_handles().

Enums

Error type returned by ProcessBuilder methods.
Possible errors that can occur during processargs startup message construction

Functions

Calculate the size of the initial stack to allocate for the dynamic linker, based on the given processargs message contents.
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.
Load the dynamic linker/loader specified in the PT_INTERP header via the fuchsia.ldsvc.Loader handle.