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

Modules§

  • Utilities for loading ELF files into an existing address space.
  • Parses ELF files per the ELF specification in ulib/musl/include/elf.h

Structs§

Enums§

Functions§

  • Calculate the size of the initial stack to allocate for the dynamic linker, based on the given process_args 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.