impl Command

fn new<S: AsRef<OsStr>>(program: S) -> Command

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 environment variable will be searched in an OS-defined way.

Platform-specific behavior

The details below describe the current behavior, but these details may change in future versions of Rust.

On Unix, the PATH searched comes from the child's environment:

• If the environment is unmodified, the child inherits the parent's PATH and that is what is searched.
• If PATH is explicitly set via env, that new value is searched.
• If env_clear or env_remove removes PATH without a replacement, execvp falls back to an OS-defined default (typically /bin:/usr/bin), not the parent's PATH. This may fail to find programs that rely on the parent's PATH.

To avoid surprises, use an absolute path or explicitly set PATH on the Command when modifying the child's environment.

On Windows, Rust resolves the executable path before spawning, rather than passing the name to CreateProcessW for resolution. When program is not an absolute path, the following locations are searched in order:

1. The child's PATH, if explicitly set via env.
2. The directory of the current executable.
3. The system directory (GetSystemDirectoryW).
4. The Windows directory (GetWindowsDirectoryW).
5. The parent process's PATH.

Note: when PATH is cleared via env_clear or env_remove on Windows, step 1 is skipped but the parent process's PATH is still searched at step 5, unlike on Unix.

For executable files, the .exe extension may be omitted. Files with other extensions must include the extension, otherwise they will not be found. Note that this behavior has some known limitations (see issue #37519).

Examples

use std::process::Command;

Command::new("sh")
    .spawn()
    .expect("sh command should start");

Caveats

Command::new is only intended to accept the path of the program. If you pass a program path along with arguments like Command::new("ls -l").spawn(), it will try to search for ls -l literally. The arguments need to be passed separately, such as via arg or args.

use std::process::Command;

Command::new("ls")
    .arg("-l") // arg passed separately
    .spawn()
    .expect("ls command should start");

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

Adds an argument to pass to the program.

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

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

usage would be:

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

To pass multiple arguments see args.

Note that the argument is not passed through a shell, but given literally to the program. This means that shell syntax like quotes, escaped characters, word splitting, glob patterns, variable substitution, etc. have no effect.

On Windows, use caution with untrusted inputs. Most applications use the standard convention for decoding arguments passed to them. These are safe to use with arg. However, some applications such as cmd.exe and .bat files use a non-standard way of decoding arguments. They are therefore vulnerable to malicious input.

In the case of cmd.exe this is especially important because a malicious argument can potentially run arbitrary shell commands.

See Windows argument splitting for more details or raw_arg for manually implementing non-standard argument encoding.

Examples

use std::process::Command;

Command::new("ls")
    .arg("-l")
    .arg("-a")
    .spawn()
    .expect("ls command should start");

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.

Note that the arguments are not passed through a shell, but given literally to the program. This means that shell syntax like quotes, escaped characters, word splitting, glob patterns, variable substitution, etc. have no effect.

On Windows, use caution with untrusted inputs. Most applications use the standard convention for decoding arguments passed to them. These are safe to use with arg. However, some applications such as cmd.exe and .bat files use a non-standard way of decoding arguments. They are therefore vulnerable to malicious input.

In the case of cmd.exe this is especially important because a malicious argument can potentially run arbitrary shell commands.

See Windows argument splitting for more details or raw_arg for manually implementing non-standard argument encoding.

Examples

use std::process::Command;

Command::new("ls")
    .args(["-l", "-a"])
    .spawn()
    .expect("ls command should start");

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

Inserts or updates an explicit environment variable mapping.

This method allows you to add an environment variable mapping to the spawned process or overwrite a previously set value. You can use Command::envs to set multiple environment variables simultaneously.

Child processes will inherit environment variables from their parent process by default. Environment variables explicitly set using Command::env take precedence over inherited variables. You can disable environment variable inheritance entirely using Command::env_clear or for a single key using Command::env_remove.

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

Examples

use std::process::Command;

Command::new("ls")
    .env("PATH", "/bin")
    .spawn()
    .expect("ls command should start");

fn envs<I, K, V>(&mut self, vars: I) -> &mut Command
where
    I: IntoIterator<Item = (K, V)>,
    K: AsRef<OsStr>,
    V: AsRef<OsStr>,

Inserts or updates multiple explicit environment variable mappings.

This method allows you to add multiple environment variable mappings to the spawned process or overwrite previously set values. You can use Command::env to set a single environment variable.

Child processes will inherit environment variables from their parent process by default. Environment variables explicitly set using Command::envs take precedence over inherited variables. You can disable environment variable inheritance entirely using Command::env_clear or for a single key using Command::env_remove.

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

Examples

use std::process::{Command, Stdio};
use std::env;
use std::collections::HashMap;

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

Command::new("printenv")
    .stdin(Stdio::null())
    .stdout(Stdio::inherit())
    .env_clear()
    .envs(&filtered_env)
    .spawn()
    .expect("printenv command should start");

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

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

This method will remove the explicit value of an environment variable set via Command::env or Command::envs. In addition, it will prevent the spawned child process from inheriting that environment variable from its parent process.

After calling Command::env_remove, the value associated with its key from Command::get_envs will be None.

To clear all explicitly set environment variables and disable all environment variable inheritance, you can use Command::env_clear.

Examples

Prevent any inherited GIT_DIR variable from changing the target of the git command, while allowing all other variables, like GIT_AUTHOR_NAME.

use std::process::Command;

Command::new("git")
    .arg("commit")
    .env_remove("GIT_DIR")
    .spawn()?;
# std::io::Result::Ok(())

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

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

This method will remove all explicitly added environment variables set via Command::env or Command::envs. In addition, it will prevent the spawned child process from inheriting any environment variable from its parent process.

After calling Command::env_clear, the iterator from Command::get_envs will be empty.

You can use Command::env_remove to clear a single mapping.

Examples

The behavior of sort is affected by LANG and LC_* environment variables. Clearing the environment makes sort's behavior independent of the parent processes' language.

use std::process::Command;

Command::new("sort")
    .arg("file.txt")
    .env_clear()
    .spawn()?;
# std::io::Result::Ok(())

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

Sets the working directory for the child process.

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

use std::process::Command;

Command::new("ls")
    .current_dir("/bin")
    .spawn()
    .expect("ls command should start");

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

Configuration for the child process's standard input (stdin) handle.

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

Examples

use std::process::{Command, Stdio};

Command::new("ls")
    .stdin(Stdio::null())
    .spawn()
    .expect("ls command should start");

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

Configuration for the child process's standard output (stdout) handle.

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

Examples

use std::process::{Command, Stdio};

Command::new("ls")
    .stdout(Stdio::null())
    .spawn()
    .expect("ls command should start");

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

Configuration for the child process's standard error (stderr) handle.

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

Examples

use std::process::{Command, Stdio};

Command::new("ls")
    .stderr(Stdio::null())
    .spawn()
    .expect("ls command should start");

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

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

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

Errors

This method returns an io::Error if the child process could not be spawned. Common reasons include:

• the program could not be found (for example, it does not exist, or, when given a bare name, it is not present in the PATH);
• the current process does not have permission to execute the program (for example, the file is not marked executable, or execution is denied by a security policy such as seccomp);
• the operating system could not create the new process because of resource exhaustion (for example, a limit on the number of processes was reached).

An error is only returned for failures that occur while the child is being spawned. Once the child has started successfully, anything that happens to it afterwards — including being terminated by a signal — is reported through its ExitStatus rather than as an error from the spawning method.

Examples

use std::process::Command;

Command::new("ls")
    .spawn()
    .expect("ls command should start");

fn output(&mut self) -> Result<Output>

Executes the command as a child process, waiting for it to finish and collecting all of its output.

By default, stdout and stderr are captured (and used to provide the resulting output). Stdin is not inherited from the parent and any attempt by the child process to read from the stdin stream will result in the stream immediately closing.

Errors

Like spawn, this method returns an io::Error if the child process could not be spawned; see spawn for the common reasons. It may also return an error if reading the child's output or waiting on the child fails.

Note that this method does not return an error if the child runs and then exits unsuccessfully, or is terminated by a signal. In those cases it still returns Ok, and the outcome is reflected in the ExitStatus stored in the returned Output.

Examples

use std::process::Command;
use std::io::{self, Write};
let output = Command::new("/bin/cat")
    .arg("file.txt")
    .output()?;

println!("status: {}", output.status);
io::stdout().write_all(&output.stdout)?;
io::stderr().write_all(&output.stderr)?;

assert!(output.status.success());
# io::Result::Ok(())

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

Executes a command as a child process, waiting for it to finish and collecting its status.

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

Errors

Like spawn, this method returns an io::Error if the child process could not be spawned; see spawn for the common reasons. It may also return an error if waiting on the child fails.

Note that this method does not return an error if the child runs and then exits unsuccessfully, or is terminated by a signal. In those cases it still returns Ok, and the outcome is reflected in the returned ExitStatus.

Examples

use std::process::Command;

let status = Command::new("/bin/cat")
    .arg("file.txt")
    .status()
    .expect("process should execute successfully");

println!("process finished with: {status}");

assert!(status.success());

fn get_program(&self) -> &OsStr

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

Examples

use std::process::Command;

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

fn get_args(&self) -> CommandArgs<'_>

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

This does not include the path to the program as the first argument; it only includes the arguments specified with Command::arg and Command::args.

Examples

use std::ffi::OsStr;
use std::process::Command;

let mut cmd = Command::new("echo");
cmd.arg("first").arg("second");
let args: Vec<&OsStr> = cmd.get_args().collect();
assert_eq!(args, &["first", "second"]);

fn get_envs(&self) -> CommandEnvs<'_>

Returns an iterator of the environment variables explicitly set for the child process.

Environment variables explicitly set using Command::env, Command::envs, and Command::env_remove can be retrieved with this method.

Note that this output does not include environment variables inherited from the parent process. To see the full list of environment variables, including those inherited from the parent process, use Command::get_resolved_envs.

Each element is a tuple key/value pair (&OsStr, Option<&OsStr>). A None value indicates its key was explicitly removed via Command::env_remove. The associated key for the None value will no longer inherit from its parent process.

An empty iterator can indicate that no explicit mappings were added or that Command::env_clear was called. After calling Command::env_clear, the child process will not inherit any environment variables from its parent process.

Examples

use std::ffi::OsStr;
use std::process::Command;

let mut cmd = Command::new("ls");
cmd.env("TERM", "dumb").env_remove("TZ");
let envs: Vec<(&OsStr, Option<&OsStr>)> = cmd.get_envs().collect();
assert_eq!(envs, &[
    (OsStr::new("TERM"), Some(OsStr::new("dumb"))),
    (OsStr::new("TZ"), None)
]);

fn get_resolved_envs(&self) -> CommandResolvedEnvs

Returns an iterator of the environment variables that will be set when the process is spawned.

This returns the environment as it would be if the command were executed at the time of calling this method. The returned environment includes:

• All inherited environment variables from the parent process (unless Command::env_clear was called)
• All environment variables explicitly set via Command::env or Command::envs
• Excluding any environment variables removed via Command::env_remove

Note that the returned environment is a snapshot at the time this method is called and will not reflect any subsequent changes to the Command or the parent process's environment. Additionally, it will not reflect changes made in a pre_exec hook (on Unix platforms).

Each element is a tuple (OsString, OsString) representing an environment variable key and value.

Examples

#![feature(command_resolved_envs)]
use std::process::Command;
use std::ffi::{OsString, OsStr};
use std::env;
use std::collections::HashMap;

let mut cmd = Command::new("ls");
cmd.env("TZ", "UTC");
unsafe { env::set_var("EDITOR", "vim"); }

let resolved: HashMap<OsString, OsString> = cmd.get_resolved_envs().collect();
assert_eq!(resolved.get(OsStr::new("TZ")), Some(&OsString::from("UTC")));
assert_eq!(resolved.get(OsStr::new("EDITOR")), Some(&OsString::from("vim")));

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.

Examples

use std::path::Path;
use std::process::Command;

let mut cmd = Command::new("ls");
assert_eq!(cmd.get_current_dir(), None);
cmd.current_dir("/bin");
assert_eq!(cmd.get_current_dir(), Some(Path::new("/bin")));

fn get_env_clear(&self) -> bool

Returns whether the environment will be cleared for the child process.

This returns true if Command::env_clear was called, and false otherwise. When true, the child process will not inherit any environment variables from its parent process.

Examples

#![feature(command_resolved_envs)]
use std::process::Command;

let mut cmd = Command::new("ls");
assert_eq!(cmd.get_env_clear(), false);

cmd.env_clear();
assert_eq!(cmd.get_env_clear(), true);