Struct Command 

pub struct Command { /* private fields */ }

A builder for spawning a process.

Implementations

impl Command

pub fn new<S>(program: S) -> Command

where S: AsRef<OsStr>,

Constructs a new Command for launching the program at path program, with the following default configuration:

• No arguments to the program
• Inherit the current process’s environment
• Inherit the current process’s working directory
• Inherit stdin/stdout/stderr for spawn or status, but create pipes for output

Builder methods are provided to change these defaults and otherwise configure the process.

If program is not an absolute path, the PATH will be searched in an OS-defined way.

Examples

Basic usage:

use reverie_process::Command;
let command = Command::new("sh");

pub fn program<S>(&mut self, program: S) -> &mut Command

where S: AsRef<OsStr>,

Sets the path to the program. This can be used to override what was already set in Command::new.

NOTE: This also changes argument 0 to match program.

pub fn arg0<S>(&mut self, arg0: S) -> &mut Command

where S: AsRef<OsStr>,

Explicitly sets the first argument. By default, this is the same as the program path and is what you want in most cases.

pub fn get_arg0(&self) -> &OsStr

Gets the first argument. Unless Command::arg0 was used, this returns the same string as Command::get_program.

pub fn arg<S>(&mut self, arg: S) -> &mut Command

where S: AsRef<OsStr>,

Adds an argument to pass to the program.

Only one argument can be passed per use. So instead of:

reverie_process::Command::new("sh").arg("-C /path/to/repo");

usage would be:

reverie_process::Command::new("sh")
    .arg("-C")
    .arg("/path/to/repo");

To pass multiple arguments see args.

Examples

Basic usage:

use reverie_process::Command;

let command = Command::new("ls").arg("-l").arg("-a");

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

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

Adds multiple arguments to pass to the program.

To pass a single argument see arg.

Examples

Basic usage:

use reverie_process::Command;

let command = Command::new("ls").args(&["-l", "-a"]);

pub fn get_args(&self) -> impl Iterator<Item = &OsStr>

Returns an iterator of the arguments that will be passed to the program.

This does not include the program name itself. It only includes the arguments specified with Command::arg and Command::args.

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

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

Prepends arguments to the beginning of the command. Note that arguments are prepended after arg0, but before the rest of the arguments.

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

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

Inserts or updates an environment variable mapping.

Note that environment variable names are case-insensitive (but case-preserving) on Windows, and case-sensitive on all other platforms.

Examples

Basic usage:

use reverie_process::Command;

let command = Command::new("ls").env("PATH", "/bin");

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

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

Adds or updates multiple environment variable mappings.

Examples

Basic usage:

use std::collections::HashMap;
use std::env;

use reverie_process::Command;
use reverie_process::Stdio;

let filtered_env: HashMap<String, String> = env::vars()
    .filter(|&(ref k, _)| k == "TERM" || k == "TZ" || k == "LANG" || k == "PATH")
    .collect();

let command = Command::new("printenv")
    .stdin(Stdio::null())
    .stdout(Stdio::inherit())
    .env_clear()
    .envs(&filtered_env);

pub fn env_remove<K>(&mut self, key: K) -> &mut Command

where K: AsRef<OsStr>,

Removes an environment variable mapping.

Examples

Basic usage:

use reverie_process::Command;

let command = Command::new("ls").env_remove("PATH");

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

Clears the entire environment map for the child process.

Examples

Basic usage:

use reverie_process::Command;

let command = Command::new("ls").env_clear();

pub fn current_dir<P>(&mut self, dir: P) -> &mut Command

where P: AsRef<Path>,

Sets the working directory for the child process.

Interaction with chroot

The working directory is set after the chroot is performed (if a chroot directory is specified). Thus, the path given is relative to the chroot directory. Otherwise, if no chroot directory is specified, the working directory is relative to the current working directory of the parent process at the time the child process is spawned.

Platform-specific behavior

If the program path is relative (e.g., "./script.sh"), it’s ambiguous whether it should be interpreted relative to the parent’s working directory or relative to current_dir. The behavior in this case is platform specific and unstable, and it’s recommended to use canonicalize to get an absolute program path instead.

Examples

Basic usage:

use reverie_process::Command;

let command = Command::new("ls").current_dir("/bin");

pub fn stdin<T>(&mut self, cfg: T) -> &mut Command

where T: Into<Stdio>,

Sets configuration for the child process’s standard input (stdin) handle.

Defaults to Stdio::inherit when used with spawn or status, and defaults to Stdio::piped when used with output.

Examples

Basic usage:

use reverie_process::Command;
use reverie_process::Stdio;

let command = Command::new("ls").stdin(Stdio::null());

pub fn stdout<T>(&mut self, cfg: T) -> &mut Command

where T: Into<Stdio>,

Sets configuration for the child process’s standard output (stdout) handle.

Defaults to Stdio::inherit when used with spawn or status, and defaults to Stdio::piped when used with output.

Examples

Basic usage:

use reverie_process::Command;
use reverie_process::Stdio;

let command = Command::new("ls").stdout(Stdio::null());

pub fn stderr<T>(&mut self, cfg: T) -> &mut Command

where T: Into<Stdio>,

Sets configuration for the child process’s standard error (stderr) handle.

Defaults to Stdio::inherit when used with spawn or status, and defaults to Stdio::piped when used with output.

Examples

Basic usage:

use reverie_process::Command;
use reverie_process::Stdio;

let command = Command::new("ls").stderr(Stdio::null());

pub fn take_prepared_stdio(&mut self) -> Result<PreparedStdio, Error>

Consumes and prepares this command’s standard stream configurations.

All three configurations are replaced with Stdio::inherit, including when preparation fails. The returned plan owns the materialized child and parent descriptors without registering them with an async runtime.

This handles only stdio. It does not apply PTY, container, or pre_exec setup, or replace the caller’s existing domain checks. A fork-based launcher must perform its common child setup before installing the prepared streams, so explicit streams override PTY descriptors.

pub fn chroot<P>(&mut self, chroot: P) -> &mut Command

where P: AsRef<Path>,

Changes the root directory of the calling process to the specified path. This directory will be inherited by all child processes of the calling process.

Note that changing the root directory may cause the program to not be found. As such, the program path should be relative to this directory.

pub fn unshare(&mut self, namespace: Namespace) -> &mut Command

Unshares parts of the process execution context that are normally shared with the parent process. This is useful for executing the child process in a new namespace.

pub fn pid(&mut self, pid: Pid) -> &mut Command

Asks for process ID pid for the child, through clone3’s set_tid (Linux 5.5 and later), in the PID namespace this process creates its children in (normally its own). Without it the kernel picks the next free ID, so a caller that starts the same program twice can give it the same ID both times only this way.

Command::spawn then fails with the kernel’s error in the Context::Clone context (a spawn without a requested ID reports a failed clone in Context::Unknown, as before): EPERM without CAP_SYS_ADMIN or CAP_CHECKPOINT_RESTORE over that namespace, EEXIST when a task, process group or session holds pid, EINVAL when pid is not in 1..pid_max, E2BIG on Linux 5.3 and 5.4, and ENOSYS where clone3 is unavailable (before Linux 5.3, or refused by a seccomp filter).

A command that also unshares a namespace is refused with EINVAL before anything is created: with a new PID namespace the requested ID would name a PID inside it, and the other namespaces are not supported with a requested ID yet. The child starts as after fork, on a copy of the calling thread’s stack.

pub fn get_pid(&self) -> Option<Pid>

The process ID asked for with Command::pid, if any.

pub unsafe fn pre_exec<F>(&mut self, f: F) -> &mut Command

where F: FnMut() -> Result<(), Errno> + Send + Sync + 'static,

Schedules a closure to be run just before the exec function is invoked.

The closure is allowed to return an I/O error whose OS error code will be communicated back to the parent and returned as an error from when the spawn was requested.

Multiple closures can be registered and they will be called in order of their registration. If a closure returns Err then no further closures will be called and the spawn operation will immediately return with a failure.

Safety

This closure will be run in the context of the child process after a fork. This primarily means that any modifications made to memory on behalf of this closure will not be visible to the parent process. This is often a very constrained environment where normal operations like malloc or acquiring a mutex are not guaranteed to work (due to other threads perhaps still running when the fork was run).

This also means that all resources such as file descriptors and memory-mapped regions got duplicated. It is your responsibility to make sure that the closure does not violate library invariants by making invalid use of these duplicates.

When this closure is run, aspects such as the stdio file descriptors and working directory have successfully been changed, so output to these locations may not appear where intended.

pub unsafe fn terminal_execve( &mut self, entry: unsafe extern "C" fn(*const i8, *const *const i8, *const *const i8) -> !, ) -> &mut Command

Select a trusted terminal entry for the final original execve.

The supplied entry receives the same prepared program, argv and envp used by ordinary spawn. No PATH search, script fallback or vector rewrite is performed on this path. A relative program is refused.

Safety

The caller qualifies the actual entry, child setup, inherited filter and gate mapping. The entry must allocate and free nothing, preserve all supplied vector bytes, issue the actual original target exec and terminate through the surviving gate on every returned kernel error. No replacement helper image or success-return path is permitted.

pub fn get_program(&self) -> &OsStr

Returns the path to the program that was given to Command::new.

Examples

use reverie_process::Command;

let cmd = Command::new("echo");
assert_eq!(cmd.get_program(), "echo");

pub fn get_current_dir(&self) -> Option<&Path>

Returns the working directory for the child process.

This returns None if the working directory will not be changed.

pub fn get_envs(&self) -> impl Iterator<Item = (&OsStr, Option<&OsStr>)>

Returns an iterator of the environment variables that will be set when the process is spawned. Note that this does not include any environment variables inherited from the parent process.

pub fn get_captured_envs(&self) -> BTreeMap<OsString, OsString>

Returns a mapping of all environment variables that the new child process will inherit.

pub fn get_env<K>(&self, env: K) -> Option<Cow<'_, OsStr>>

where K: AsRef<OsStr>,

Gets an environment variable. If the child process is to inherit this environment variable from the current process, then this returns the current process’s environment variable unless it is to be overridden.

pub fn map_uid(&mut self, inside_uid: u32, outside_uid: u32) -> &mut Command

Maps one user ID to another.

Implies Namespace::USER.

Example

This is can be used to gain CAP_SYS_ADMIN privileges in the user namespace by mapping the root user inside the container to the current user outside of the container.

use reverie_process::Command;

let command = Command::new("ls").map_uid(1, unsafe { libc::getuid() });

Implementation

This modifies /proc/{pid}/uid_map where {pid} is the PID of the child process. See user_namespaces(7) for more details.

pub fn map_uid_range( &mut self, starting_inside_uid: u32, starting_outside_uid: u32, count: u32, ) -> &mut Command

Maps potentially many user IDs inside the new user namespace to user IDs outside of the user namespace.

Implies Namespace::USER.

Implementation

This modifies /proc/{pid}/uid_map where {pid} is the PID of the child process. See user_namespaces(7) for more details.

pub fn map_root(&mut self) -> &mut Command

Convience function for mapping root (inside the container) to the current user ID (outside the container). This is useful for gaining new capabilities inside the container, such as being able to mount file systems.

Implies Namespace::USER.

This is the same as:

use reverie_process::Command;

let command = Command::new("ls")
    .map_uid(0, unsafe { libc::geteuid() })
    .map_gid(0, unsafe { libc::getegid() });

pub fn map_gid(&mut self, inside_gid: u32, outside_gid: u32) -> &mut Command

Maps one group ID to another.

Implies Namespace::USER.

Implementation

This modifies /proc/{pid}/gid_map where {pid} is the PID of the child process. See user_namespaces(7) for more details.

pub fn map_gid_range( &mut self, starting_inside_gid: u32, starting_outside_gid: u32, count: u32, ) -> &mut Command

Maps potentially many group IDs inside the new user namespace to group IDs outside of the user namespace.

Implies Namespace::USER.

Implementation

This modifies /proc/{pid}/gid_map where {pid} is the PID of the child process. See user_namespaces(7) for more details.

pub fn hostname<S>(&mut self, hostname: S) -> &mut Command

where S: Into<OsString>,

Sets the hostname of the container.

Implies Namespace::UTS, which requires CAP_SYS_ADMIN.

use reverie_process::Command;

let command = Command::new("cat")
    .arg("/proc/sys/kernel/hostname")
    .map_root()
    .hostname("foobar.local");

pub fn domainname<S>(&mut self, domainname: S) -> &mut Command

where S: Into<OsString>,

Sets the domain name of the container.

Implies Namespace::UTS, which requires CAP_SYS_ADMIN.

Example

use reverie_process::Command;

let command = Command::new("cat")
    .arg("/proc/sys/kernel/domainname")
    .map_root()
    .domainname("foobar");

pub fn get_hostname(&self) -> Option<&OsStr>

Gets the hostname of the container.

pub fn get_domainname(&self) -> Option<&OsStr>

Gets the domainname of the container.

pub fn mount(&mut self, mount: Mount) -> &mut Command

Adds a file system to be mounted. Note that these are mounted in the same order as given.

Implies Namespace::MOUNT. Note that Namespace::USER should also have been set and map_uid should have been called in order to gain the privileges required to mount.

pub fn mounts<I>(&mut self, mounts: I) -> &mut Command

where I: IntoIterator<Item = Mount>,

Adds multiple mounts.

pub fn local_networking_only(&mut self) -> &mut Command

Sets up the container to have local networking only. This will prevent any network communication to the outside world.

Implies Namespace::NETWORK and Namespace::MOUNT.

This also causes a fresh /sys to be mounted to avoid seeing the host network interfaces in /sys/class/net.

pub fn seccomp(&mut self, filter: Filter) -> &mut Command

Sets the seccomp filter. The filter is loaded immediately before execve and after all pre_exec callbacks have been executed. Thus, you will still be able to call filtered syscalls from pre_exec callbacks.

pub fn seccomp_notify(&mut self) -> &mut Command

Indicates that we want to listen for seccomp events using seccomp_unotify(2).

If this is set, the seccomp listener file descriptor will be accessible via the Child.

pub fn pty(&mut self, child: PtyChild) -> &mut Command

Sets the controlling pseudoterminal for the child process).

In the child process, this has the effect of:

1. Creating a new session (with setsid()).
2. Using an ioctl to set the controlling terminal.
3. Setting this file descriptor as the stdio streams.

NOTE: Since this modifies the stdio streams, calling this will reset Self::stdin, Self::stdout, and Self::stderr back to Stdio::inherit().

pub fn find_program(&self) -> Result<PathBuf, Error>

Finds the path to the program.

impl Command

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

Executes the command, waiting for it to finish and collecting its exit status.

pub async fn output(&mut self) -> Result<Output, Error>

Executes the command, waiting for it to finish while collecting its stdout and stderr into buffers.

impl Command

pub fn turn_off_leak_check(&mut self) -> &mut Command

Turns off a sanitizer build’s leak check in the environment this command gives its program, keeping every other sanitizer setting: [with_leak_check_off] of ASAN_OPTIONS and LSAN_OPTIONS, and of UBSAN_OPTIONS when that is set. A command this was already applied to is left as it is.

impl Command

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

Executes the command as a child process, returning a handle to it.

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

pub fn spawn_with<F>(&mut self, onfail: F) -> Result<Child, Error>

where F: FnMut(Error) -> i32,

Spawn the child with helper functions. The onfail callback runs in the child process if an error occurs during execution of the process. The wait function can be used to wait for the child to fully start up and to transform it into another type.

impl Command

pub fn from_std_lossy(cmd: &Command) -> Command

Converts std::process::Command into Command. Note that this is a very basic and lossy conversion.

This only preserves the

• program path,
• arguments,
• environment variables,
• and working directory.

Caveats

Since std::process::Command is rather opaque and doesn’t provide access to all fields, this will not preserve:

• stdio handles,
• env_clear,
• any pre_exec callbacks,
• arg0 (if not the same as program),
• uid, gid, or groups.

pub fn try_into_std(self) -> Result<Command, Error>

Converts this command to std::process::Command.

This fails if the command contains container configuration that cannot be represented by std::process::Command, rather than silently discarding that configuration. This includes namespaces, mounts, seccomp filters, pseudoterminals, CPU affinity, and a requested process ID.

pub fn into_std_lossy(self) -> Command

Converts this command to std::process::Command, refusing to discard any container configuration.

This compatibility shim preserves the former return type for callers whose commands are representable. It panics instead of silently losing unsupported configuration. New callers should use Self::try_into_std to handle that refusal explicitly.