Struct std::process::Command

1.0.0 · source ·

pub struct Command { /* private fields */ }

Expand description

进程生成器，提供对如何生成新进程的细粒度控制。

可以使用 Command::new(program) 生成默认配置，其中 program 提供了要执行的程序的路径。

其他生成器方法允许在生成之前更改配置 (例如，通过添加参数) ：

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

Command 可以重用以生成多个进程。构建器方法无需立即使进程 spawn 即可更改命令。

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

Run

同样，您可以在生成进程之后调用构建器方法，然后使用修改后的设置 spawn 新建一个进程。

use std::process::Command;

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

// 在程序的当前目录中执行 `ls`。
list_dir.status().expect("process failed to execute");

println!();

// 更改 `ls` 以在根目录中执行。
list_dir.current_dir("/");

// 然后再次在根目录中执行 `ls`。
list_dir.status().expect("process failed to execute");

Run

Implementations§

source §

impl Command

source

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

使用以下默认配置创建一个新的 Command，以在路径 program 处启动该程序：

程序无参数
继承当前进程的环境
继承当前进程的工作目录
为 spawn 或 status 继承 stdin/stdout/stderr，但为 output 创建管道

提供了生成器方法来更改这些默认值，并以其他方式配置该进程。

如果 program 不是绝对路径，则将以 OS 定义的方式搜索 PATH。

可以通过在 Command 上设置 PATH 环境变量来控制要使用的搜索路径，但这在 Windows 上有一些实现上的限制 (请参见 issue #37519)。

Examples

基本用法：

use std::process::Command;

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

Run

source

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

添加参数以传递给程序。

每次使用只能传递一个参数。因此，而不是：

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

Run

用法是：

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

Run

要传递多个参数，请参见 args。

注意，该参数不是通过 shell 传递的，而是按字面意义提供给程序的。这意味着 shell 语法，例如引号，转义字符，单词拆分，全局模式，替换等。

没有效果。

Examples

基本用法：

use std::process::Command;

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

Run

source

pub fn args<I, S>(&mut self, args: I) -> &mut Commandwhere I: IntoIterator<Item = S>, S: AsRef<OsStr>,

添加多个参数以传递给程序。

要传递单个参数，请参见 arg。

请注意，该参数不是通过 shell 传递的，而是按字面意义提供给程序的。这意味着 shell 语法，例如引号，转义字符，单词拆分，全局模式，替换等。

没有效果。

Examples

基本用法：

use std::process::Command;

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

Run

source

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

插入或更新显式环境变量映射。

此方法允许您将环境变量映射添加到生成的进程或覆盖先前设置的值。您可以使用 Command::envs 同时设置多个环境变量。

默认情况下，子进程将从其父进程继承环境变量。使用 Command::env 显式设置的环境变量优先于继承的变量。您可以使用 Command::env_clear 完全禁用环境变量继承，或者使用 Command::env_remove 禁用单个键。

请注意，环境变量名称在 Windows 上不区分大小写 (但保留大小写)，在所有其他平台上区分大小写。

Examples

基本用法：

use std::process::Command;

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

Run

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>,

插入或更新多个显式环境变量映射。

此方法允许您将多个环境变量映射添加到生成的进程或覆盖以前设置的值。您可以使用 Command::env 设置单个环境变量。

默认情况下，子进程将从其父进程继承环境变量。使用 Command::envs 显式设置的环境变量优先于继承的变量。您可以使用 Command::env_clear 完全禁用环境变量继承，或者使用 Command::env_remove 禁用单个键。

请注意，环境变量名称在 Windows 上不区分大小写 (但保留大小写)，在所有其他平台上区分大小写。

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

Run

source

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

删除显式设置的环境变量并防止从父进程继承它。

此方法将删除通过 Command::env 或 Command::envs 设置的环境变量的显式值。此外，它将阻止派生的子进程从其父进程继承该环境变量。

调用 Command::env_remove 后，与 Command::get_envs 中的键关联的值将是 None。

要清除所有显式设置的环境变量并禁用所有环境变量继承，可以使用 Command::env_clear。

Examples

基本用法：

use std::process::Command;

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

Run

source

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

清除所有显式设置的环境变量并防止继承任何父进程环境变量。

此方法将删除通过 Command::env 或 Command::envs 设置的所有明确添加的环境变量。此外，它将阻止派生的子进程从其父进程继承任何环境变量。

调用 Command::env_remove 后，Command::get_envs 的迭代器将为空。

您可以使用 Command::env_remove 清除单个映射。

Examples

基本用法：

use std::process::Command;

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

Run

source

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

设置子进程的工作目录。

特定于平台的行为

如果程序路径是相对路径 (例如 "./script.sh")，则是相对于父级工作目录还是相对于 current_dir 来解释路径。这种情况下的行为是特定于平台且不稳定的，建议使用 canonicalize 来获取绝对程序路径。

Examples

基本用法：

use std::process::Command;

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

Run

source

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

子进程的标准输入 (stdin) 句柄的配置。

与 spawn 或 status 一起使用时，默认为 inherit，与 output 一起使用时，默认为 piped。

Examples

基本用法：

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

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

Run

source

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

子进程的标准输出 (stdout) 句柄的配置。

与 spawn 或 status 一起使用时，默认为 inherit，与 output 一起使用时，默认为 piped。

Examples

基本用法：

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

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

Run

source

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

子进程的标准错误 (stderr) 句柄的配置。

与 spawn 或 status 一起使用时，默认为 inherit，与 output 一起使用时，默认为 piped。

Examples

基本用法：

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

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

Run

source

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

将命令作为子进程执行，并返回其句柄。

默认情况下，stdin、stdout 和 stderr 都是从父级继承的。

Examples

基本用法：

use std::process::Command;

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

Run

source

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

将命令作为子进程执行，等待其完成并收集所有输出。

默认情况下，将捕获 stdout 和 stderr (并用于提供结果输出)。 Stdin 不是从父级继承的，子进程尝试从 stdin 流中进行读取的任何尝试都将导致该流立即关闭。

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

Run

source

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

将命令作为子进程执行，等待其完成并收集其状态。

默认情况下，stdin、stdout 和 stderr 都是从父级继承的。

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

Run

1.57.0 · source

pub fn get_program(&self) -> &OsStr

返回给 Command::new 的程序的路径。

Examples

use std::process::Command;

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

Run

1.57.0 · source

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

返回将传递给程序的参数的迭代器。

这不包括程序的路径作为第一个参数；它仅包含 Command::arg 和 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"]);

Run

1.57.0 · source

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

返回为子进程显式设置的环境变量的迭代器。

可以使用此方法检索使用 Command::env、Command::envs 和 Command::env_remove 显式设置的环境变量。

请注意，此输出不包括从父进程继承的环境变量。

每个元素都是一个元组 key/value 对 (&OsStr, Option<&OsStr>). None 值表示其密钥已通过 Command::env_remove 明确删除。 None 值的关联键将不再从其父进程继承。

空迭代器可以指示未添加显式映射或调用了 Command::env_clear。调用 Command::env_clear 后，子进程不会继承父进程的任何环境变量。

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

Run

1.57.0 · source

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

返回子进程的工作目录。

如果不更改工作目录，则返回 None。

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

Run