Struct process_builder::ProcessBuilder

pub struct ProcessBuilder { /* private fields */ }

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

See top-level crate documentation for a usage example.

Implementations

impl ProcessBuilder

pub fn new( name: &CStr, job: &Job, options: ProcessOptions, executable: Vmo, system_vdso_vmo: Vmo, ) -> Result<ProcessBuilder, ProcessBuilderError>

Create a new ProcessBuilder that can be used to create a new process under the given job with the given name and ELF64 executable (as a VMO).

This job is only used to create the process and thus is not taken ownership of. To provide a default job handle to be passed to the new process, use ProcessBuilder::add_handles() with HandleType::DefaultJob.

The provided VMO must have the zx::Rights::EXECUTE right.

Errors

Returns Err(ProcessBuilderError::CreateProcess) if process creation fails, such as if the process using this is disallowed direct process creation rights through job policy. See top-level crate documentation for more details.

pub fn set_loader_service( &mut self, ldsvc: ClientEnd<LoaderMarker>, ) -> Result<(), ProcessBuilderError>

Sets the fuchsia.ldsvc.Loader service for the process.

The loader service is used to load dynamic libraries if the executable is a dynamically linked ELF file (i.e. if it contains a PT_INTERP header), and is required for such executables. It will only be provided to the new process in this case. Otherwise, it is unused and has no effect.

If no loader service has been provided and it is needed, process creation will fail. Note that this differs from the automatic fallback behavior of previous process creation libraries, which would clone the loader of the current process. This fallback is likely to fail in subtle and confusing ways. An appropriate loader service that has access to the libraries or interpreter must be provided.

Note that ProcessBuilder::add_handles() will automatically pass a handle with type HandleType::LdsvcLoader to this function.

If called multiple times (e.g. if a loader was initially provided through ProcessBuilder::add_handles() and you want to replace it), the new loader replaces the previous and the handle to the previous loader is dropped.

pub fn set_vdso_vmo(&mut self, vdso: Vmo)

Sets the vDSO VMO for the process.

pub fn add_arguments(&mut self, args: Vec<CString>)

Add arguments to the process’s bootstrap message. Successive calls append (not replace) arguments.

pub fn add_environment_variables(&mut self, vars: Vec<CString>)

Add environment variables to the process’s bootstrap message. Successive calls append (not replace) environment variables.

pub fn set_min_stack_size(&mut self, size: usize)

Set the minimum size of the stack for the new process, in bytes.

pub fn add_handles( &mut self, startup_handles: Vec<StartupHandle>, ) -> Result<(), ProcessBuilderError>

Add handles to the process’s bootstrap message. Successive calls append (not replace) handles.

Each process_args::StartupHandle contains a zx::Handle object accompanied by a HandleInfo object that includes the handle type and a type/context-dependent argument.

A HandleType::LdsvcLoader handle will automatically be passed along to ProcessBuilder::set_loader_service() if provided through this function.

Errors

HandleType::NamespaceDirectory handles should not be added through this function since they must be accompanied with a path. Use ProcessBuilder::add_namespace_entries() for that instead.

The following handle types cannot be added through this, as they are added automatically by the ProcessBuilder:

• HandleType::ProcessSelf
• HandleType::ThreadSelf
• HandleType::RootVmar
• HandleType::LoadedVmar
• HandleType::StackVmo
• HandleType::ExecutableVmo

pub fn add_namespace_entries( &mut self, entries: Vec<NamespaceEntry>, ) -> Result<(), ProcessBuilderError>

Add directories to the process’s namespace.

Successive calls append new namespace entries, not replace previous entries.

Each NamespaceEntry contains a client connection to a fuchsia.io.Directory FIDL service and a path to add that directory to the process’s namespace as.

Errors

Returns Err(ProcessBuilderError::InvalidArg) if the maximum number of namespace entries (2^16) was reached and the entry could not be added. This is exceedingly unlikely, and most likely if you are anywhere near this limit ProcessBuilder::build() will fail because the process’s process_args startup message is over its own length limit.

pub async fn build(self) -> Result<BuiltProcess, ProcessBuilderError>

Build the new process using the data and handles provided to the ProcessBuilder.

The return value of this function is a BuiltProcess struct which contains the new process and all the handles and data needed to start it, but the process’ initial thread is not yet started. Use BuiltProcess::start() or the zx_process_start syscall to actually start it.

Errors

There are many errors that could result during process loading and only some are listed here. See ProcessBuilderError for the various error types that can be returned.

Returns Err(ProcessBuilderError::LoaderMissing) if the ELF executable is dynamically linked (has a PT_INTERP program header) but no loader service has been provided through ProcessBuilder::set_loader_service() or ProcessBuilder::add_handles().