[−][src]Struct subprocess::Popen
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
[src]
pub fn create(argv: &[impl AsRef<OsStr>], 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_start(&mut self, input_data: Option<Vec<u8>>) -> Communicator
[src]
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>>)>
[src]
&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>)>
[src]
&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>
[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) -> Result<()>
[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) -> Result<()>
[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
Auto Trait Implementations
impl RefUnwindSafe for Popen
impl Send for Popen
impl !Sync for Popen
impl Unpin for Popen
impl UnwindSafe for Popen
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,