Struct process_builder::ProcessBuilder
source · pub struct ProcessBuilder { /* private fields */ }Expand description
The main builder type for this crate. Collects inputs and creates a new process.
See top-level crate documentation for a usage example.
Implementations§
source§impl ProcessBuilder
impl ProcessBuilder
sourcepub fn new(
name: &CStr,
job: &Job,
options: ProcessOptions,
executable: Vmo,
system_vdso_vmo: Vmo
) -> Result<ProcessBuilder, ProcessBuilderError>
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.
sourcepub fn set_loader_service(
&mut self,
ldsvc: ClientEnd<LoaderMarker>
) -> Result<(), ProcessBuilderError>
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.
sourcepub fn set_vdso_vmo(&mut self, vdso: Vmo)
pub fn set_vdso_vmo(&mut self, vdso: Vmo)
Sets the vDSO VMO for the process.
sourcepub fn add_arguments(&mut self, args: Vec<CString>)
pub fn add_arguments(&mut self, args: Vec<CString>)
Add arguments to the process’s bootstrap message. Successive calls append (not replace) arguments.
sourcepub fn add_environment_variables(&mut self, vars: Vec<CString>)
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.
sourcepub fn set_min_stack_size(&mut self, size: usize)
pub fn set_min_stack_size(&mut self, size: usize)
Set the minimum size of the stack for the new process, in bytes.
sourcepub fn add_handles(
&mut self,
startup_handles: Vec<StartupHandle>
) -> Result<(), ProcessBuilderError>
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:
sourcepub fn add_namespace_entries(
&mut self,
entries: Vec<NamespaceEntry>
) -> Result<(), ProcessBuilderError>
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.
sourcepub async fn build(self) -> Result<BuiltProcess, ProcessBuilderError>
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().