A module for working with processes.

This module is mostly concerned with spawning and interacting with childprocesses, but it also providesabort andexit for terminating thecurrent process.

§Spawning a process

TheCommand struct is used to configure and spawn processes:

usestd::process::Command;letoutput = Command::new("echo")    .arg("Hello world")    .output()    .expect("Failed to execute command");assert_eq!(b"Hello world\n", output.stdout.as_slice());

Several methods onCommand, such asspawn oroutput, can be usedto spawn a process. In particular,output spawns the child process andwaits until the process terminates, whilespawn will return aChildthat represents the spawned child process.

§Handling I/O

Thestdout,stdin, andstderr of a child process can beconfigured by passing anStdio to the corresponding method onCommand. Once spawned, they can be accessed from theChild. Forexample, piping output from one command into another command can be donelike so:

usestd::process::{Command, Stdio};// stdout must be configured with `Stdio::piped` in order to use// `echo_child.stdout`letecho_child = Command::new("echo")    .arg("Oh no, a tpyo!")    .stdout(Stdio::piped())    .spawn()    .expect("Failed to start echo process");// Note that `echo_child` is moved here, but we won't be needing// `echo_child` anymoreletecho_out = echo_child.stdout.expect("Failed to open echo stdout");letmutsed_child = Command::new("sed")    .arg("s/tpyo/typo/")    .stdin(Stdio::from(echo_out))    .stdout(Stdio::piped())    .spawn()    .expect("Failed to start sed process");letoutput = sed_child.wait_with_output().expect("Failed to wait on sed");assert_eq!(b"Oh no, a typo!\n", output.stdout.as_slice());

Note thatChildStderr andChildStdout implementRead andChildStdin implementsWrite:

usestd::process::{Command, Stdio};usestd::io::Write;letmutchild = Command::new("/bin/cat")    .stdin(Stdio::piped())    .stdout(Stdio::piped())    .spawn()    .expect("failed to execute child");// If the child process fills its stdout buffer, it may end up// waiting until the parent reads the stdout, and not be able to// read stdin in the meantime, causing a deadlock.// Writing from another thread ensures that stdout is being read// at the same time, avoiding the problem.letmutstdin = child.stdin.take().expect("failed to get stdin");std::thread::spawn(move|| {    stdin.write_all(b"test").expect("failed to write to stdin");});letoutput = child    .wait_with_output()    .expect("failed to wait on child");assert_eq!(b"test", output.stdout.as_slice());

§Windows argument splitting

On Unix systems arguments are passed to a new process as an array of strings,but on Windows arguments are passed as a single commandline string and it isup to the child process to parse it into an array. Therefore the parent andchild processes must agree on how the commandline string is encoded.

Most programs use the standard C run-timeargv, which in practice resultsin consistent argument handling. However, some programs have their own way ofparsing the commandline string. In these cases usingarg orargs mayresult in the child process seeing a different array of arguments than theparent process intended.

Two ways of mitigating this are:

• Validate untrusted input so that only a safe subset is allowed.
• Useraw_arg to build a custom commandline. This bypasses the escapingrules used byarg so should be used with due caution.

cmd.exe and.bat files use non-standard argument parsing and are especiallyvulnerable to malicious input as they may be used to run arbitrary shellcommands. Untrusted arguments should be restricted as much as possible.For examples on handling this seeraw_arg.

§Batch file special handling

On Windows,Command uses the Windows API functionCreateProcessW tospawn new processes. An undocumented feature of this function is thatwhen given a.bat file as the application to run, it will automaticallyconvert that into runningcmd.exe /c with the batch file as the next argument.

For historical reasons Rust currently preserves this behavior when usingCommand::new, and escapes the arguments according tocmd.exe rules.Due to the complexity ofcmd.exe argument handling, it might not bepossible to safely escape some special characters, and using them will resultin an error being returned at process spawn. The set of unescapeablespecial characters might change between releases.

Also note that running batch scripts in this way may be removed in thefuture and so should not be relied upon.