Struct Job 

#[non_exhaustive]
pub struct Job {
    pub stdin: Option<File>,
    pub stdout: Option<File>,
    pub stderr: Option<File>,
    pub stdin_data: InputData,
    pub check_success: bool,
    pub processes: Vec<Process>,
}

Interface to a started process or pipeline.

Created by [Exec::start] or [Pipeline::start].

When dropped, waits for all processes to finish unless detached.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

stdin: Option<File>

Write end of the first process’s stdin pipe, if stdin was Pipe.

stdout: Option<File>

Read end of the last process’s stdout pipe, if stdout was Pipe.

stderr: Option<File>

Read end of the shared stderr pipe, if stderr was Pipe.

stdin_data: InputData

Data to feed to the first process’s stdin, set by [Exec::stdin] or [Pipeline::stdin].

check_success: bool

Whether to return an error on non-zero exit status.

processes: Vec<Process>

Started processes, in pipeline order.

Implementations

impl Job

pub fn communicate(&mut self) -> Result<Communicator>

Creates a Communicator from the pipe ends.

The communicator takes ownership of stdin, stdout, and stderr, leaving them as None. Only streams that were redirected to a pipe will be available to the communicator.

pub fn terminate(&self) -> Result<()>

Terminates all processes in the pipeline.

Delegates to Process::terminate() on each process, which sends SIGTERM on Unix and calls TerminateProcess on Windows. Already reaped processes are silently skipped.

pub fn wait(&self) -> Result<ExitStatus>

Waits for all processes to finish and returns the last process’s exit status.

If no processes have been started (empty pipeline), returns a successful exit status.

Unlike join, this does not consume self, does not close the pipe ends, and ignores check_success.

pub fn pid(&self) -> u32

Returns the PID of the last process in the pipeline.

For a single command started with [Exec::start], this is the PID of that command. For a pipeline, this is the PID of the last command.

Panics

Panics if no processes have been started because this was created by an empty Pipeline.

pub fn pids(&self) -> Vec<u32>

Returns the PIDs of all processes in the pipeline, in pipeline order.

If the job was started by a single process, this will return its pid. It will be empty for a job started by an empty pipeline.

pub fn kill(&self) -> Result<()>

Kill all processes in the pipeline.

Delegates to Process::kill() on each process, which sends SIGKILL on Unix and calls TerminateProcess on Windows. Already reaped processes are silently skipped.

pub fn detach(&self)

Detach all processes in the pipeline.

After detaching, the processes will not be waited for in drop.

pub fn poll(&self) -> Option<ExitStatus>

Poll all processes for completion without blocking.

Returns Some(exit_status) of the last process if all processes have finished, or None if any process is still running. If no processes have been started (empty pipeline), returns Some with a successful exit status.

pub fn wait_timeout(&self, timeout: Duration) -> Result<Option<ExitStatus>>

Like wait, but with a timeout.

Returns Ok(None) if the processes don’t finish within the given duration.

pub fn join(self) -> Result<ExitStatus>

Closes the pipe ends, waits for all processes to finish, and returns the exit status of the last process.

If input or output was redirected to pipe, this close input and drain the output as needed.

pub fn join_timeout(self, timeout: Duration) -> Result<ExitStatus>

Like join, but with a timeout.

Returns an error of kind ErrorKind::TimedOut if the processes don’t finish within the given duration.

pub fn capture(self) -> Result<Capture>

Captures the output and waits for the process(es) to finish.

Only streams that were redirected to a pipe will produce data; non-piped streams will result in empty bytes in Capture.

pub fn capture_timeout(self, timeout: Duration) -> Result<Capture>

Like capture, but with a timeout.

Returns an error of kind ErrorKind::TimedOut if the processes don’t finish within the given duration.

Trait Implementations

impl Debug for Job

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl JobExt for Job

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

Send the specified signal to all processes in the pipeline.

fn send_signal_group(&self, signal: i32) -> Result<()>

Send the specified signal to the process group of the first process.