std​::io​::process

Structs

Process
ProcessConfig
ProcessOutput

Enums

ProcessExit
StdioContainer
[src]

Struct std::io::process::Process

pub struct Process {
    stdin: Option<PipeStream>,
    stdout: Option<PipeStream>,
    stderr: Option<PipeStream>,
    extra_io: ~[Option<PipeStream>],
    // some fields omitted
}

Representation of a running or exited child process.

This structure is used to create, run, and manage child processes. A process is configured with the ProcessConfig struct which contains specific options for dictating how the child is spawned.

Example

use std::io::Process;

let mut child = match Process::new("/bin/cat", [~"file.txt"]) {
    Ok(child) => child,
    Err(e) => fail!("failed to execute child: {}", e),
};

let contents = child.stdout.get_mut_ref().read_to_end();
assert!(child.wait().success());

Fields

stdin

Handle to the child's stdin, if the stdin field of this process's ProcessConfig was CreatePipe. By default, this handle is Some.

stdout

Handle to the child's stdout, if the stdout field of this process's ProcessConfig was CreatePipe. By default, this handle is Some.

stderr

Handle to the child's stderr, if the stderr field of this process's ProcessConfig was CreatePipe. By default, this handle is Some.

extra_io

Extra I/O handles as configured by the original ProcessConfig when this process was created. This is by default empty.

Methods

impl Process

fn new(prog: &str, args: &[~str]) -> IoResult<Process>

Creates a new process for the specified program/arguments, using otherwise default configuration.

By default, new processes have their stdin/stdout/stderr handles created as pipes the can be manipulated through the respective fields of the returned Process.

Example

use std::io::Process;

let mut process = match Process::new("sh", &[~"c", ~"echo hello"]) {
    Ok(p) => p,
    Err(e) => fail!("failed to execute process: {}", e),
};

let output = process.stdout.get_mut_ref().read_to_end();

fn output(prog: &str, args: &[~str]) -> IoResult<ProcessOutput>

Executes the specified program with arguments, waiting for it to finish and collecting all of its output.

Example

use std::io::Process;
use std::str;

let output = match Process::output("cat", [~"foo.txt"]) {
    Ok(output) => output,
    Err(e) => fail!("failed to execute process: {}", e),
};

println!("status: {}", output.status);
println!("stdout: {}", str::from_utf8_lossy(output.output));
println!("stderr: {}", str::from_utf8_lossy(output.error));

fn status(prog: &str, args: &[~str]) -> IoResult<ProcessExit>

Executes a child process and collects its exit status. This will block waiting for the child to exit.

Example

use std::io::Process;

let status = match Process::status("ls", []) {
    Ok(status) => status,
    Err(e) => fail!("failed to execute process: {}", e),
};

println!("process exited with: {}", status);

fn configure(config: ProcessConfig) -> IoResult<Process>

Creates a new process with the specified configuration.

fn kill(id: pid_t, signal: int) -> IoResult<()>

Sends signal to another process in the system identified by id.

Note that windows doesn't quite have the same model as unix, so some unix signals are mapped to windows signals. Notably, unix termination signals (SIGTERM/SIGKILL/SIGINT) are translated to TerminateProcess.

Additionally, a signal number of 0 can check for existence of the target process. Note, though, that on some platforms signals will continue to be successfully delivered if the child has exited, but not yet been reaped.

fn id(&self) -> pid_t

Returns the process id of this child process

fn signal(&mut self, signal: int) -> IoResult<()>

Sends the specified signal to the child process, returning whether the signal could be delivered or not.

Note that signal 0 is interpreted as a poll to check whether the child process is still alive or not. If an error is returned, then the child process has exited.

On some unix platforms signals will continue to be received after a child has exited but not yet been reaped. In order to report the status of signal delivery correctly, unix implementations may invoke waitpid() with WNOHANG in order to reap the child as necessary.

Errors

If the signal delivery fails, the corresponding error is returned.

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

Sends a signal to this child requesting that it exits. This is equivalent to sending a SIGTERM on unix platforms.

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

Sends a signal to this child forcing it to exit. This is equivalent to sending a SIGKILL on unix platforms.

fn wait(&mut self) -> ProcessExit

Wait for the child to exit completely, returning the status that it exited with. This function will continue to have the same return value after it has been called at least once.

The stdin handle to the child process will be closed before waiting.

fn wait_with_output(&mut self) -> ProcessOutput

Simultaneously wait for the child to exit and collect all remaining output on the stdout/stderr handles, returning a ProcessOutput instance.

The stdin handle to the child is closed before waiting.

Trait Implementations

impl Drop for Process

fn drop(&mut self)

The drop method, called when the value goes out of scope.