Struct Command 

pub struct Command { /* private fields */ }

A builder for a process to spawn, like std::process::Command.

The methods that spawn the process take the runtime to spawn it on. Configure the command as with std: its arguments, environment, working directory and the standard streams of the process. A command from Command::new starts with the environment and working directory of this process.

as_std gives the std command inside, for its getters of the program, the arguments, the environment and the working directory. as_std_mut gives it for the extension traits of the platform, such as std’s CommandExt on unix.

What happens to the process when its Child is dropped is set on this builder, not on the std command. kill_on_drop and reap_on_drop set it, and get_kill_on_drop and get_reap_on_drop read it.

A command can run more than once. A standard stream that was not configured gets the default of the method that runs the command, afresh on each run. spawn and status inherit it from this process. output connects the standard input to nothing and the other two streams to pipes, which it reads to their ends.

spawn, status and output start the process when they are called, before any future is polled, and it runs from then on. The futures of status and output only wait for it. If the spawn fails, spawn returns the error, and the other two resolve to it.

Example

Runs a command and checks its exit status. Its output goes to this process’s own:

use zruntime::{LocalRuntime, process::Command};

let runtime = LocalRuntime::new()?;

let status = runtime.block_on(Command::new("true").status(&runtime))?;

assert!(status.success());

Implementations

impl Command

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

where S: AsRef<OsStr>,

Creates a command that runs program.

The command has no arguments, inherits the environment and working directory of this process, and has no standard streams configured. If program has no path in it, it is looked up on the PATH, as for std’s Command::new.

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

where S: AsRef<OsStr>,

Adds an argument to pass to the program.

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

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

Adds arguments to pass to the program.

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

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

Sets an environment variable of the process.

On Windows, names of environment variables are case-insensitive but case-preserving. On other platforms, they are case-sensitive.

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

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

Sets environment variables of the process.

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

where K: AsRef<OsStr>,

Removes an environment variable from the environment of the process, whether it is inherited from this process or was set on the command.

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

Clears the environment of the process, so that it inherits none of this process’s variables.

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

where P: AsRef<Path>,

Sets the working directory of the process.

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

where T: Into<Stdio>,

Configures what the standard input of the process is connected to.

With Stdio::piped(), the child’s stdin is the pipe to the process.

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

where T: Into<Stdio>,

Configures what the standard output of the process is connected to.

With Stdio::piped(), the child’s stdout is the pipe from the process.

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

where T: Into<Stdio>,

Configures what the standard error of the process is connected to.

With Stdio::piped(), the child’s stderr is the pipe from the process.

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

Sets whether the process is killed when its Child is dropped.

The default is false: dropping the Child leaves the process running. See the module documentation. The status of a killed process is collected like that of any other dropped process, unless reap_on_drop is off.

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

Sets whether the status of the process is collected when its Child is dropped while the process is still running.

The default is true. On unix, a process that exits with nobody to collect its status stays a zombie and keeps its process ID. With this on, dropping a running Child hands the process to a thread of a pool for waits for children. The thread waits for the process to exit and collects its status, and is held until then. Turning this off spares the thread but leaves the zombie: see the module documentation.

This does nothing on Windows, where an exited process leaves nothing to collect.

pub fn get_kill_on_drop(&self) -> bool

Whether the process is killed when its Child is dropped.

The default is false. kill_on_drop sets it.

pub fn get_reap_on_drop(&self) -> bool

Whether the status of the process is collected when its Child is dropped while the process is still running.

The default is true. reap_on_drop sets it. It makes no difference on Windows, where an exited process leaves nothing to collect.

pub fn as_std(&self) -> &Command

The std command inside this one, to read the program, the arguments, the environment and the working directory.

The std command knows nothing about what happens when the Child is dropped. Read that with get_kill_on_drop and get_reap_on_drop.

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

The std command inside this one, to configure with what only it has.

That is the std extension traits for the platform, such as uid, pre_exec and process_group on unix, or creation_flags on Windows.

Do not configure the standard streams through it. This builder does not know about a stream set there, so the method that runs the command overrides it with its default. Use stdin, stdout and stderr instead.

pub fn spawn<M>(&mut self, runtime: &Runtime<M>) -> Result<Child<M>>

where M: Mode,

Spawns the process on runtime and returns its Child.

The process is running when this returns. A standard stream that the command was not told about is inherited from this process. A stream set to Stdio::piped() is the matching pipe field of the Child. On unix, runtime watches the pipes. On Windows, they run on a thread of the pool of unblock().

Errors

Fails if the process cannot be spawned, for the reasons given by std’s spawn, for example a program that does not exist or may not run.

Also fails if runtime cannot start watching the pipes, or the descriptor for the exit of the process if the runtime watches for the exit. The poller of the system may refuse to watch any of them. On Apple’s platforms and the BSDs, the system may also refuse to create that descriptor, for example if the process is out of descriptors, because there is no other way to wait there. The process is then killed and its status is collected, so it is not left running with nobody holding it.

pub fn status<M>( &mut self, runtime: &Runtime<M>, ) -> impl Future<Output = Result<ExitStatus>> + use<M>

where M: Mode,

Spawns the process on runtime, waits for it to exit and resolves to its exit status.

A standard stream that the command was not told about is inherited from this process, as for spawn. The pipe to the standard input, if the command asked for one, is closed before the wait, as Child::status does. A pipe from the process that nothing reads may fill and keep the process from ever exiting. Use output for a process whose output you want.

The process is spawned by this call, before the future is polled, and runs whether or not the future is polled. Dropping the future gives up the wait and drops the child. The process keeps running unless the command set kill_on_drop.

Errors

The future resolves to the error if the spawn fails, for the reasons given for spawn, or if the wait fails, for the reasons given for Child::status.

pub fn output<M>( &mut self, runtime: &Runtime<M>, ) -> impl Future<Output = Result<Output>> + use<M>

where M: Mode,

Spawns the process on runtime and resolves to its output and exit status once it exits.

The output holds what the process wrote to its standard output and its standard error. A standard stream that the command was not told about is connected to nothing for the standard input, and to a pipe for each of the standard output and error, which are read to their ends. A stream that the command was told about is as it was told, and a stream that is not piped is not captured: the output holds nothing of it. See Child::output for how the pipes are read.

The process is spawned by this call, before the future is polled, and runs whether or not the future is polled. Dropping the future gives up the wait and drops the child. The process keeps running unless the command set kill_on_drop.

Errors

The future resolves to the error if the spawn fails, for the reasons given for spawn, or if reading the pipes or the wait fails, for the reasons given for Child::output.

Trait Implementations

impl Debug for Command

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Command> for Command

Wraps a std command.

The standard streams configured on command count as not configured, so the method that runs the command overrides them with its defaults. As with Command::new, the process is not killed when its Child is dropped, and its status is collected where the platform needs that.

fn from(command: Command) -> Self

Converts to this type from the input type.