Struct subprocess::Popen
[−]
[src]
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 running subprocess. The
child process is started in the constructor, so owning Popen
means that the program has been successfully executed. To prevent
accumulation of zombie processes, the child is automatically
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. To simply
read the output and errors into memory (and optionally provide
input the same way), 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
[src]
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 simply runs cargo update
:
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>>)>
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>)>
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 failsErr(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
[src]
fn send_signal(&self, signal: i32) -> IoResult<()>
Send the specified signal to the child process. Read more