Struct tracing::stdlib::process::Command

1.0.0 · source ·
pub struct Command {
    inner: Command,
}
Expand description

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;

Command can be reused to spawn multiple processes. The builder methods change the command without needing to immediately spawn the process.

use std::process::Command;

let mut echo_hello = Command::new("sh");
echo_hello.arg("-c")
          .arg("echo hello");
let hello_1 = echo_hello.output().expect("failed to execute process");
let hello_2 = echo_hello.output().expect("failed to execute process");

Similarly, you can call builder methods after spawning a process and then spawn a new process with the modified settings.

use std::process::Command;

let mut list_dir = Command::new("ls");

// Execute `ls` in the current directory of the program.
list_dir.status().expect("process failed to execute");

println!();

// Change `ls` to execute in the root directory.
list_dir.current_dir("/");

// And then execute `ls` again but in the root directory.
list_dir.status().expect("process failed to execute");

Fields§

§inner: Command

Implementations§

source§

impl Command

source

pub fn new<S>(program: S) -> Commandwhere 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.

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 issue #37519).

Examples

Basic usage:

use std::process::Command;

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

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

Adds an argument to pass to the program.

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

.arg("-C /path/to/repo")

usage would be:

.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, substitution, etc. have no effect.

Examples

Basic usage:

use std::process::Command;

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

pub fn args<I, S>(&mut self, args: I) -> &mut Commandwhere 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, substitution, etc. have no effect.

Examples

Basic usage:

use std::process::Command;

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

pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Commandwhere 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");
1.19.0 · source

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

Adds or updates multiple environment variable mappings.

Examples

Basic usage:

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 failed to start");
source

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

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");
source

pub 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");
source

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

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

Basic usage:

use std::process::Command;

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

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

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

Basic usage:

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

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

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

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

Basic usage:

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

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

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

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

Basic usage:

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

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

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.

Examples

Basic usage:

use std::process::Command;

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

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

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.

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

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

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

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

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.

Examples
use std::process::Command;

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

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

assert!(status.success());
1.57.0 · source

pub 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");
1.57.0 · source

pub 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"]);
1.57.0 · source

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

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

Each element is a tuple (&OsStr, Option<&OsStr>), where the first value is the key, and the second is the value, which is None if the environment variable is to be explicitly removed.

This only includes environment variables explicitly set with Command::env, Command::envs, and Command::env_remove. It does not include environment variables that will be inherited by the child 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)
]);
1.57.0 · source

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.

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")));

Trait Implementations§

source§

impl CommandExt for Command

source§

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.
source§

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.
source§

fn groups(&mut self, groups: &[u32]) -> &mut Command

🔬This is a nightly-only experimental API. (setgroups #90747)
Sets the supplementary group IDs for the calling process. Translates to a setgroups call in the child process.
source§

unsafe fn pre_exec<F>(&mut self, f: F) -> &mut Commandwhere F: FnMut() -> Result<(), Error> + Send + Sync + 'static,

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

fn exec(&mut self) -> Error

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

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

Set executable argument Read more
source§

fn process_group(&mut self, pgroup: i32) -> &mut Command

Sets the process group ID (PGID) of the child process. Equivalent to a setpgid call in the child process, but may be more efficient. Read more
1.15.0 · source§

fn before_exec<F>(&mut self, f: F) -> &mut Commandwhere F: FnMut() -> Result<(), Error> + Send + Sync + 'static,

👎Deprecated since 1.37.0: should be unsafe, use <code>pre_exec</code> instead
Schedules a closure to be run just before the exec function is invoked. Read more
source§

impl CommandExt for Command

source§

fn create_pidfd(&mut self, val: bool) -> &mut Command

🔬This is a nightly-only experimental API. (linux_pidfd #82971)
Sets whether a PidFd should be created for the Child spawned by this Command. By default, no pidfd will be created. Read more
source§

impl Debug for Command

source§

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

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

The default format approximates a shell invocation of the program along with its arguments. It does not include most of the other command properties. The output is not guaranteed to work (e.g. due to lack of shell-escaping or differences in path resolution) On some platforms you can use the alternate syntax to show more fields.

Note that the debug implementation is platform-specific.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more