std::process::Command - Rust
Description: API documentation for the Rust `Command` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, Command

# Struct std::process::Command 1.0.0 [−] [src]

    pub struct Command { /* fields omitted */ }

A process builder, providing fine-grained control over how a new process should be spawned.

A default configuration can be generated using `Command::new(program)`, where `program` gives a path to the program to be executed. Additional builder methods allow the configuration to be changed (for example, by adding arguments) prior to spawning:

    use std::process::Command;

    let output = if cfg!(target_os = "windows") {
        Command::new("cmd")
                .args(&["/C", "echo hello"])
                .output()
                .expect("failed to execute process")
    } else {
        Command::new("sh")
                .arg("-c")
                .arg("echo hello")
                .output()
                .expect("failed to execute process")
    };

    let hello = output.stdout;Run

## Methods

### `impl Command`
[src]

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

The search path to be used may be controlled by setting the `PATH` environment variable on the Command, but this has some implementation limitations on Windows (see https://github.com/rust-lang/rust/issues/37519).

# Examples

Basic usage:

    use std::process::Command;

    Command::new("sh")
            .spawn()
            .expect("sh command failed to start");Run

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

Add an argument to pass to the program.

# Examples

Basic usage:

    use std::process::Command;

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

#### `fn args<I, S>(&mut self, args: I) -> &mut Command where I: IntoIterator<Item=S>, S: AsRef<OsStr>`

Add multiple arguments to pass to the program.

# Examples

Basic usage:

    use std::process::Command;

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

#### `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 std::process::Command;

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

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

🔬 This is a nightly-only experimental API. (`command_envs` #38526)

Add or update multiple environment variable mappings.

# Examples

Basic usage: ```no_run use std::process::{Command, Stdio}; use std::env; use std::collections::HashMap;

let filtered_env : HashMap = 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 failed to start"); ```

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

Removes an environment variable mapping.

# Examples

Basic usage:

    use std::process::Command;

    Command::new("ls")
            .env_remove("PATH")
            .spawn()
            .expect("ls command failed to start");Run

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

Clears the entire environment map for the child process.

# Examples

Basic usage:

    use std::process::Command;

    Command::new("ls")
            .env_clear()
            .spawn()
            .expect("ls command failed to start");Run

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

Sets the working directory for the child process.

# Examples

Basic usage:

    use std::process::Command;

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

#### `fn stdin(&mut self, cfg: Stdio) -> &mut Command`

Configuration for the child process's stdin handle (file descriptor 0).

# Examples

Basic usage:

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

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

#### `fn stdout(&mut self, cfg: Stdio) -> &mut Command`

Configuration for the child process's stdout handle (file descriptor 1).

# Examples

Basic usage:

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

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

#### `fn stderr(&mut self, cfg: Stdio) -> &mut Command`

Configuration for the child process's stderr handle (file descriptor 2).

# Examples

Basic usage:

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

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

#### `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.

# Examples

Basic usage:

    use std::process::Command;

    Command::new("ls")
            .spawn()
            .expect("ls command failed to start");Run

#### `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, stdin, stdout and stderr are captured (and used to provide the resulting output).

# Examples

    use std::process::Command;
    let output = Command::new("/bin/cat")
                         .arg("file.txt")
                         .output()
                         .expect("failed to execute process");

    println!("status: {}", output.status);
    println!("stdout: {}", String::from_utf8_lossy(&output.stdout));
    println!("stderr: {}", String::from_utf8_lossy(&output.stderr));

    assert!(output.status.success());Run

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

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

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

# Examples

    use std::process::Command;

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

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

    assert!(status.success());Run

## Trait Implementations

### `impl Debug for Command`
[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`

Format the program and arguments of a Command for display. Any non-utf8 data is lossily converted using the utf8 replacement character.

### `impl CommandExt for Command`
[src]

#### `fn uid(&mut self, id: u32) -> &mut Command`

Sets the child process's user id. This translates to a `setuid` call in the child process. Failure in the `setuid` call will cause the spawn to fail. Read more

#### `fn gid(&mut self, id: u32) -> &mut Command`

Similar to `uid`, but sets the group id of the child process. This has the same semantics as the `uid` field. Read more

#### `fn before_exec<F>(&mut self, f: F) -> &mut Command where F: FnMut() -> Result<()> + Send + Sync + 'static`

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

#### `fn exec(&mut self) -> Error`

Performs all the required setup by this `Command`, followed by calling the `execvp` syscall. Read more

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)