Struct subprocess::Popen

pub struct Popen {
    pub stdin: Option<File>,
    pub stdout: Option<File>,
    pub stderr: Option<File>,
    // some fields omitted
}

Interface to a running subprocess.

Popen is the parent's interface to a created subprocess. The child process is started in the constructor, so owning a Popen value indicates that the specified program has been successfully launched. To prevent accumulation of zombie processes, the child is waited upon when a Popen goes out of scope, which can be prevented using the detach method.

Depending on how the subprocess was configured, its input, output, and error streams can be connected to the parent and available as stdin, stdout, and stderr public fields. If you need to read the output and errors into memory (or provide input as a memory slice), use the communicate family of methods, which guarantee deadlock-free communication with the subprocess.

Popen instances can be obtained with the create method, or using the [popen] method of the Exec class. Subprocesses can be connected into pipes, most easily achieved using using Exec.

Fields

stdin: Option<File>

If stdin was specified as Redirection::Pipe, this will contain a writeble File connected to the standard input of the child process.

stdout: Option<File>

If stdout was specified as Redirection::Pipe, this will contain a readable File connected to the standard output of the child process.

stderr: Option<File>

If stderr was specified as Redirection::Pipe, this will contain a readable File connected to the standard error of the child process.

Methods

impl Popen

pub fn create(argv: &[impl AsRef<OsStr>], config: PopenConfig) -> Result<Popen>

Execute an external program in a new process.

argv is a slice containing the program followed by its arguments, such as &["ps", "x"]. config specifies details how to create and interface to the process.

For example, this launches the cargo update command:

Popen::create(&["cargo", "update"], PopenConfig::default())?;

Errors

If the external program cannot be executed for any reason, an error is returned. The most typical reason for execution to fail is that the program is missing on the PATH, but other errors are also possible. Note that this is distinct from the program running and then exiting with a failure code - this can be detected by calling the wait method to obtain its exit status.

pub fn detach(&mut self)

Mark the process as detached.

This method has no effect on the OS level, it simply tells Popen not to wait for the subprocess to finish when going out of scope. If the child process has already finished, or if it is guaranteed to finish before Popen goes out of scope, calling detach has no effect.

pub fn pid(&self) -> Option<u32>

Return the PID of the subprocess, if it is known to be still running.

Note that this method won't actually check whether the child process is still running, it will only return the information last set using one of create, wait, wait_timeout, or poll. For a newly created Popen, pid() always returns Some.

pub fn exit_status(&self) -> Option<ExitStatus>

Return the exit status of the subprocess, if it is known to have finished.

Note that this method won't actually check whether the child process has finished, it only returns the previously available information. To check or wait for the process to finish, call wait, wait_timeout, or poll.

pub fn communicate_start(&mut self, input_data: Option<Vec<u8>>) -> Communicator

Prepare to communicate with the subprocess.

Communicating refers to providing the given input_data to the subprocess's standard input, while simultaneously reading from its standard output and error streams.

This method does not start the actual communication, it just sets it up and returns a Communicator handle. Call the read method on the returned handle to communicate.

Compared to communicate() and communicate_bytes(), the Communicator provides more control, such as timeout, read size limit, and the ability to retrieve captured output in case of read error.

pub fn communicate_bytes(
    &mut self,
    input_data: Option<&[u8]>
) -> Result<(Option<Vec<u8>>, Option<Vec<u8>>)>

Feed the subprocess with input data and capture its output.

This will write the provided input_data to the subprocess's standard input, and simultaneously read its standard output and error. The output and error contents are returned as a pair of Option<Vec<u8>>. The None options correspond to streams not specified as Redirection::Pipe when creating the subprocess.

The communication is deadlock-free, which is achieved by reading and writing in parallel using poll() on Unix and threads on Windows.

Note that this method does not wait for the subprocess to finish, only to close its output/error streams. It is rare but possible for the program to continue running after having closed the streams, in which case Popen::Drop will wait for it to finish. If such a wait is undesirable, it can be prevented by waiting explicitly using wait(), by detaching the process using detach(), or by terminating it with terminate().

For additional control over communication, such as timeout and size limit, call communicate_start().

Panics

If input_data is provided and stdin was not redirected to a pipe. Also, if input_data is not provided and stdin was redirected to a pipe.

Errors

• Err(::std::io::Error) if a system call fails

pub fn communicate(
    &mut self,
    input_data: Option<&str>
) -> Result<(Option<String>, Option<String>)>

Feed the subprocess with data and capture its output as string.

This is a convenience method equivalent to communicate_bytes, but with input as &str and output as String. Invalid UTF-8 sequences, if found, are replaced with the the U+FFFD Unicode replacement character.

Panics

The same as with communicate_bytes.

Errors

• Err(::std::io::Error) if a system call fails

pub fn poll(&mut self) -> Option<ExitStatus>

Check whether the process is still running, without blocking or errors.

This checks whether the process is still running and if it is still running, None is returned, otherwise Some(exit_status). This method is guaranteed not to block and is exactly equivalent to wait_timeout(Duration::new(0, 0)).unwrap_or(None).

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

Wait for the process to finish, and return its exit status.

If the process has already finished, it will exit immediately, returning the exit status. Calling wait after that will return the cached exit status without executing any system calls.

Errors

Returns an Err if a system call fails in an unpredicted way. This should not happen in normal usage.

pub fn wait_timeout(&mut self, dur: Duration) -> Result<Option<ExitStatus>>

Wait for the process to finish, timing out after the specified duration.

This function behaves like wait(), except that the caller will be blocked for roughly no longer than dur. It returns Ok(None) if the timeout is known to have elapsed.

On Unix-like systems, timeout is implemented by calling waitpid(..., WNOHANG) in a loop with adaptive sleep intervals between iterations.

pub fn terminate(&mut self) -> Result<()>

Terminate the subprocess.

On Unix-like systems, this sends the SIGTERM signal to the child process, which can be caught by the child in order to perform cleanup before exiting. On Windows, it is equivalent to kill().

pub fn kill(&mut self) -> Result<()>

Kill the subprocess.

On Unix-like systems, this sends the SIGKILL signal to the child process, which cannot be caught.

On Windows, it invokes TerminateProcess on the process handle with equivalent semantics.

Trait Implementations

impl Debug for Popen

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

Formats the value using the given formatter.

impl Drop for Popen

fn drop(&mut self)

Executes the destructor for this type.

impl PopenExt for Popen

fn send_signal(&self, signal: i32) -> Result<()>

Send the specified signal to the child process.