在设计程序的时候偶尔会需要依靠系统指令或是其它的程序来取得一些相关的消息,或是进行一些特殊的处理,如查看系统的网卡界面,或是调用 FFmpeg 来实现影音编码的格式转换。虽然这些工作基本上都可以靠 Rust 原生程序来自行实作,或是引用其它 C/C++ 函数库,但既然有已存在的指令和可执行文件可以用,能省下许多开发时间,何不去用呢?

使用 Rust 去运行系统指令或是其它可可执行文件案,可以用标准函数库的 process 模块提供的 Command 结构体来实体化运行进程(process)的指令。Command 结构实体提供的 status 方法可以运行指令,并在运行指令之后,取得进程的 Exit Status;output 方法可以运行指令,并抓取标准输出(stdout)和标准错误(stderr)的数据,当然也一样能取得进程的 Exit Status。

例如:

use std::process::Command;

fn main() {
    let mut command = Command::new("ping");
    command.arg("-c").arg("5").arg("magiclen.org");

    let output = command.output().unwrap();

    match output.status.code() {
        Some(code) => {
            println!("Exit Status: {}", code);

            if code == 0 {
                println!("{}", String::from_utf8(output.stdout).unwrap());
            }
        }
        None => {
            println!("Process terminated.");
        }
    }
}

以上程序,会创建出运行 ping 指令的 Command 结构实体。在 Command 结构实体运行指令时,指令所创建的进程有可能在运行的过程中被中止,此时 Command 结构实体返回的 Exit Status 就会是 None。

预设情况下,若是使用 Command 结构实体的 output 方法来运行指令,原先指令输出到标准输出和标准错误的数据就会被目前的 Rust 程序抓取,所以在屏幕上并不会直接看到 ping 指令的输出数据。不过若是使用 Command 结构实体的 status 方法来运行 ping 指令,ping 指令的输出数据就可以直接在屏幕上被看到。

Command 结构实体的 stdin、stdout、stderr 方法可以设置运行指令时产生的进程之标准输入来源,以及标准输出和标准错误的目的。来源和目的可以是一个 File 结构实体,或者是其它的透过 Command 结构实体创建出来的进程之标准输入、标准输出或是标准错误,就是管线(pipeline)啦!

以下是使用 File 结构实体当作标准输出目的的例子:

use std::fs::File;
use std::process::Command;

fn main() {
    let mut command = Command::new("ping");
    command.arg("-c").arg("5").arg("magiclen.org");

    command.stdout(File::create("ping_result.txt").unwrap());

    match command.status().unwrap().code() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}

另外还有三种比较特殊的来源或目的,可以靠 process 模块提供的 Stdio 结构体来设置。Stdio 结构体的 inherit 关联函数的回传值可以使标准输入、标准输出或是标准错误就是基本的样子,也就是会直接从屏幕输入或是直接输出到屏幕的那种;piped 关联函数的回传值可以让 Rust 程序抓取进程的标准输出或是标准错误;null 关联函数的回传值可以将进程的标准输入、标准输出或是标准错误的来源或目的设置为像是 Linux 操作系统上的 /dev/null。

以下程序利用 nslookup 指令确认网域是否可以被「正解」,但不输出任何 nslookup 指令的数据:

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

fn main() {
    let mut command = Command::new("nslookup");
    command.arg("magiclen.org");

    command.stdout(Stdio::null());
    command.stderr(Stdio::null());

    match command.status().unwrap().code() {
        Some(code) => {
            if code == 0 {
                println!("This domain is available.");
            } else {
                println!("This domain is unavailable.");
            }
        }
        None => {
            println!("Process terminated.");
        }
    }
}

以下是将第一个 Command 结构实体的标准输出导到第二个 Command 结构实体的标准输入的例子:

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

fn main() {
    let mut command1 = Command::new("ping");
    command1.arg("-c").arg("5").arg("magiclen.org");

    let mut command2 = Command::new("grep");
    command2.arg("ttl");

    command1.stdout(Stdio::piped());

    command2.stdin(command1.spawn().unwrap().stdout.unwrap());

    let output = command2.output().unwrap();

    match output.status.code() {
        Some(code) => {
            println!("Exit Status: {}", code);

            if code == 0 {
                println!("{}", String::from_utf8(output.stdout).unwrap());
            }
        }
        None => {
            println!("Process terminated.");
        }
    }
}

以上程序中,有使用到 Command 结构实体的 spawn 方法,这个方法类似 status 和 output 方法,可以运行指令并产生进程,但它不会等待并返回结果,取而代之的是返回一个代表新进程的 Child 结构实体。在预设情况(即不使用 Command 结构实体的 stdin、stdout 或 stderr 方法来设置进程的输入来源和输出目的)下,使用 spawn 运行指令,会等同于将来源或目的设置为 Stdio::inherit()。

笔者觉得 Rust 标准函数库提供的 Command 结构体之 API 容易让人混乱,不太容易阅读,撰写起来冗长也很容易出错。再加上要产生一个 Command 结构实体实在很麻烦,几乎不能够用一进程式叙述来解决,所有指令的参数一定要分开提供,实在是难以阅读及维护。还有就是虽然进程的输出可以轻易地存成 Vec<u8>,但输入却不能够直接从 Vec<u8> 来提供,更别说是直接把任意有实作 Read 特性的对象当作进程的数据输入来源了。

Execute

「Execute」是笔者开发的套件,用来扩展 Command 结构体的 API,使它更容易使用。

Crates.io

Cargo.toml

execute = "*"

宏的使用

execute 这个 crate 提供了 command 和 command_args 这两个方便的宏,可以用来快速产生 Command 结构实体。

command!

command 宏可以直接传入一个指令字符串,不需将程序名称和参数分开。这个指令字符串,会在程序编译阶段被解析,不用担心会对运行阶段的性能造成影响。使用起来就像是在终端机打指令一样,非常容易阅读和维护。

fn main() {
    let mut command = execute::command!("ping -c 5 magiclen.org");

    match command.status().unwrap().code() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}
command_args!

command_args 宏可以直接传入一个程序路径和多个分开的参数。程序路径和每个参数可以是不同的类型。

fn main() {
    let mut command = execute::command_args!("ping", "-c", "5", "magiclen.org");

    match command.status().unwrap().code() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}

command 和 shell 函数

execute 这个 crate 也提供了 command 和 shell 这两个方便的函数,可以用来快速产生 Command 结构实体。

command

command 函数可以直接传入一个指令字符串,不需将程序名称和参数分开。这个指令字符串,会在程序运行阶段被解析,所以可以用程序来组成指令,不过因为会对运行阶段的性能造成影响,不是很建议使用这样的方式来产生 Command 结构实体。

fn main() {
    let mut command = execute::command("ping -c 5 magiclen.org");

    match command.status().unwrap().code() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}
shell

shell 函数可以直接传入一个指令字符串,不需将程序名称和参数分开。这个指令字符串,并不会被 Rust 程序解析,而是会透过操作系统环境预设的 shell 解释器来解析并运行。

fn main() {
    let mut command = execute::shell("ping -c 5 magiclen.org");

    match command.status().unwrap().code() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}

在 Linux 操作系统下,甚至可以直接使用 | 来进行管线处理。

fn main() {
    let mut command = execute::shell("ping -c 5 magiclen.org | grep ttl");

    match command.status().unwrap().code() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}

不过如果很在乎程序运行性能的话,也是不建议用 shell 函数来产生 Command 结构实体。

Execute 特性的使用

execute 这个 crate 提供的 Execute 特性,可以扩充 Command 结构实体,使其拥有多个以 execute 为名称前缀的方法。

验证程序

由于 Command 结构体是用来产生一个进程来运行某个指令,也就是某个外部的程序。也就是说,这个程序可能不存在于当前的运行环境中,或者当前的运行环境中找到的这个程序,并不是我们的 Rust 程序所要的。因此,我们通常会需要在程序运行阶段,开始正式做事情前,先去验证这个外部程序,避免工作失败。

execute_check_exit_status_code 方法可以运行指令并且验证进程回传的 Exit Status 是不是我们预期的。

例如:

use execute::{command, Execute};

fn main() {
    if command!("ping -c 1 127.0.0.1").execute_check_exit_status_code(0).is_err() {
        println!("Is your `ping` correct?");
        return;
    }

    let mut command = execute::shell("ping -c 5 magiclen.org | grep ttl");

    match command.status().unwrap().code() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}
运行程序并仅取得 Exit Status
use execute::{command, Execute};

fn main() {
    match command!("ping -c 5 magiclen.org").execute().unwrap() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}
运行程序并让进程输出
输出到屏幕
use execute::{command, Execute};

fn main() {
    let output = command!("ping -c 5 magiclen.org").execute_output().unwrap();

    match output.status.code() {
        Some(code) => {
            println!("Exit Status: {}", code);
        }
        None => {
            println!("Process terminated.");
        }
    }
}
输出到内存(抓取)
use std::process::Stdio;

use execute::{command, Execute};

fn main() {
    let mut command = command!("ping -c 5 magiclen.org");

    command.stdout(Stdio::piped());
    command.stderr(Stdio::null());

    let output = command.execute_output().unwrap();

    match output.status.code() {
        Some(code) => {
            println!("Exit Status: {}", code);
            
            if code == 0 {
                println!("{}", String::from_utf8(output.stdout).unwrap());
            }
        }
        None => {
            println!("Process terminated.");
        }
    }
}
运行程序并输入数据到进程
输入内存中的数据
use std::process::Stdio;

use execute::{command, Execute};

fn main() {
    let mut command = command!("bc");

    command.stdout(Stdio::piped());

    let output = command.execute_input_output("2^99\n").unwrap();

    println!("Answer: {}", String::from_utf8(output.stdout).unwrap().trim_end());
}
输入 Reader 中的数据
use std::fs::File;
use std::process::Stdio;

use execute::{command, Execute};

fn main() {
    let mut command = command!("cat");

    command.stdout(Stdio::piped());

    let mut file = File::open("Cargo.toml").unwrap();

    let output = command.execute_input_reader_output(&mut file).unwrap();

    println!("{}", String::from_utf8(output.stdout).unwrap());
}

以上程序只是为了举例而举例,实际上要用文件作为标准输入的话可以直接将 File 结构实体传给 Command 结构实体的 stdin 方法。

在预设的情况下,读取 Reader 使用的缓冲空间大小为 256 个字节。如果想要更改缓冲空间大小,就要使用以 _reader2 或是 _reader_output2 为名称结尾的方法,并明确定义要使用的大小。

例如,将缓冲空间大小改为 4096 个字节:

use std::fs::File;
use std::process::Stdio;

use execute::generic_array::typenum::U4096;
use execute::{command, Execute};

fn main() {
    let mut command = command!("cat");

    command.stdout(Stdio::piped());

    let mut file = File::open("Cargo.toml").unwrap();

    let output = command.execute_input_reader_output2::<U4096>(&mut file).unwrap();

    println!("{}", String::from_utf8(output.stdout).unwrap());
}
运行多个 Command 结构实体,将它们的标准输入和标准输出透过管线来引导

以 execute_multiple 为名称前缀的方法可以运行多个 Command 结构实体,并将它们的标准输入和标准输出依序连接在一起。

use std::process::Stdio;

use execute::{command, Execute};

fn main() {
    let mut command1 = command!("echo 'HELLO WORLD'");
    let mut command2 = command!("cut -d ' ' -f 1");
    let mut command3 = command!("tr A-Z a-z");

    command3.stdout(Stdio::piped());

    let output = command1.execute_multiple_output(&mut [&mut command2, &mut command3]).unwrap();

    assert_eq!(b"hello\n", output.stdout.as_slice());
}