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

Return a handle that does communication with the subprocess feeding it with input data and capturing its output.

This method does not start the actual communication, it just sets it up; call read on the returned handle to communicate.

Compared to communicate() and communicate_bytes(), this method provides more control over the communication, such as timeout and allocation limits.

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

Feed the subprocess with data and capture its output.

This will send the input_data to the subprocess, read its output and error, and return them as a pair of Option<Vec<u8>>. The corresponding options will be None if the respective stream was not specified as Redirection::Pipe.

The communication is guaranteed to be deadlock-free. On Unix-like systems this is ensured using poll() and on Windows using threads behind the scenes.

Note that this method will not wait for the program to finish, only to close its output stream(s). The program may continue running afterwards, and wait() can be used to ensure that it has actually finished.

For additional control over communication, such as timeouts and size limits, 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.

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.