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 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
[src]
pub fn create<S: AsRef<OsStr>>(argv: &[S], config: PopenConfig) -> Result<Popen>
[src]
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)
[src]
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>
[src]
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>
[src]
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_bytes(
&mut self,
input_data: Option<&[u8]>
) -> IoResult<(Option<Vec<u8>>, Option<Vec<u8>>)>
[src]
&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.
pub fn communicate(
&mut self,
input_data: Option<&str>
) -> Result<(Option<String>, Option<String>)>
[src]
&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 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.
pub fn poll(&mut self) -> Option<ExitStatus>
[src]
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>
[src]
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>>
[src]
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) -> IoResult<()>
[src]
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) -> IoResult<()>
[src]
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
[src]
fn fmt(&self, __arg_0: &mut Formatter) -> Result
[src]
Formats the value using the given formatter. Read more