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_bytes or communicate 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

fn create<S: AsRef<OsStr>>(argv: &[S], 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.

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.

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.

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.

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

Feed and capture the piped data of the subprocess.

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. This is currently ensured using threads (only when interaction with more than one stream is needed), and may be converted to poll() in the future.

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() must be used to ensure that it has actually finished.

Panics

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

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

Feed and capture the piped data of the subprocess as strings.

This is a convenience method equivalent to communicate_bytes, but with input as &str and output as String.

Panics

The same as with communicate_bytes

Errors

• Err(::std::io::Error) if a system call fails
• Err(PopenError::Utf8Error) if the output of the process is not valid UTF-8 and therefore cannot be represented as a String.

Panics

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

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).

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.

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.

fn terminate(&mut self) -> IoResult<()>

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

fn kill(&mut self) -> IoResult<()>

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 PopenExt for Popen

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

Send the specified signal to the child process.

impl Debug for Popen

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

Formats the value using the given formatter.

impl Drop for Popen

fn drop(&mut self)

A method called when the value goes out of scope.