Struct Wrap 

pub struct Wrap<'a> { /* private fields */ }

Main class of spawn process and execute functions.

Implementations

impl<'a> Wrap<'a>

Core implementation

pub fn new() -> Self

Create a new instance with default.

pub fn new_program<S: AsRef<OsStr>>(program: S) -> Self

Create a new instance with program to execute.

pub fn program<S: AsRef<OsStr>>(&mut self, program: S) -> &mut Self

Set command to execute

pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Self

Adds an argument to pass to the program.

Only one argument can be passed per use.

pub fn args<I, S>(&mut self, args: I) -> &mut Self

where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

Adds multiple arguments to pass to the program.

To pass a single argument see Self::arg().

pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Self

Set

pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Self

where K: AsRef<OsStr>, V: AsRef<OsStr>,

Inserts or updates an explicit environment variable mapping.

pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Self

where I: IntoIterator<Item = (K, V)>, K: AsRef<OsStr>, V: AsRef<OsStr>,

Inserts or updates multiple explicit environment variable mappings.

pub fn env_remove<K: AsRef<OsStr>>(&mut self, key: K) -> &mut Self

Removes an explicitly set environment variable and prevents inheriting it from a parent process.

pub fn env_clear(&mut self) -> &mut Self

Clears all explicitly set environment variables and prevents inheriting any parent process environment variables.

pub fn spawn(&mut self) -> Result<Child, Error>

Executes the callbacks and program in a child process, returning a handle to it.

This instance of Wrap will not be consumed, but it’s queue of callback functions will be empty.

pub fn status(&mut self) -> Result<ExitStatus, Error>

Executes the command and callback functions in a child process, waiting for it to finish and collecting its status.

By default, stdin, stdout and stderr are inherited from the parent.

pub fn callback<F>(&mut self, cb: F) -> &mut Self

where F: FnOnce() -> isize + Send + 'static,

Add a callback to run in the child before execute the program.

This function can be called multiple times, all functions will be called after clone(2) and environment setup, in the same order as they were added. The return value of last function can be retrieved from ExitStatus if no program is executed.

Notes and Safety

This closure will be run in the context of the child process after a clone(2). This primarily means that any modifications made to memory on behalf of this closure will not be visible to the parent process.

This method will not cause memory corruption, but it will be risky when interact with thread-related components. For example, it’s possible to create a deadlock using std::sync::Mutex. Because clone(2) clone whole process, they do not share any modified memory area. Child process is not thread, and should not be threat like thread.

And it’s possible to disrupt file descriptors and other environment configuration.

Use pipe(2) or other IPC method to communicate with child process.

For further details on this topic, please refer to the Rust Std Lib Document, related GitHub issue of nix library, GitHub issue of rust and the equivalent documentation for any targeted platform, especially the requirements around async-signal-safety.

pub fn unshare(&mut self, typ: NamespaceType) -> &mut Self

Set new namespace(7) for child process.

use nswrap::Wrap;
use nswrap::config;
let mut wrap = Wrap::new();
wrap.callback(|| {print!("Cool!");return 5})
    .unshare(config::NamespaceType::User);
wrap.spawn().unwrap().wait().unwrap();

pub fn nsenter(&mut self, typ: NamespaceType, pidfd: RawFd) -> &mut Self

Reassociate child process with a namespace.

The order in which this method is called will affect the result.

pub fn abi_fs(self) -> Self

Add some mount points and file path that application usually needs.

This will require a mount namespace.

The Linux ABI includes both syscalls and several special file paths. Applications expecting a Linux environment will very likely expect these file paths to be set up correctly. Please refer to Linux parts of OCI Runtime Specification for more information.

pub fn uid_map( &mut self, host_id: u32, container_id: u32, size: u32, ) -> &mut Self

Sets user id mappings for new process.

Each call to this function will add an item in /proc/{pid}/uid_map.

pub fn gid_map( &mut self, host_id: u32, container_id: u32, size: u32, ) -> &mut Self

Sets group id mappings for new process.

Each call to this function will add an item in /proc/{pid}/gid_map.

pub fn id_map_preset(&mut self, set: IdMapPreset) -> &mut Self

Use some preset to set id mapping in container.

pub fn sandbox_mnt(&mut self, opt: bool) -> &mut Self

Simulate brwrap’s behaviour, use a tmpfs as root dir inside namespace.

This is required if a user what to use Wrap for mountpoint management

Trait Implementations

impl<'a> Default for Wrap<'a>

fn default() -> Wrap<'a>

Returns the “default value” for a type.