Process spawning.

Struct Process

pub struct Process {
    /// The unique id of the process (this should never be negative).
    priv pid: pid_t,
    /**
     * A handle to the process - on unix this will always be NULL, but on
     * windows it will be a HANDLE to the process, which will prevent the
     * pid being re-used until the handle is closed.
     */
    priv handle: *(),
    /// Some(fd), or None when stdin is being redirected from a fd not created by Process::new.
    priv input: Option<c_int>,
    /// Some(file), or None when stdout is being redirected to a fd not created by Process::new.
    priv output: Option<*libc::FILE>,
    /// Some(file), or None when stderr is being redirected to a fd not created by Process::new.
    priv error: Option<*libc::FILE>,
    /// None until finish() is called.
    priv exit_code: Option<int>,
}

A value representing a child process.

The lifetime of this value is linked to the lifetime of the actual process - the Process destructor calls self.finish() which waits for the process to terminate.

Struct ProcessOptions

pub struct ProcessOptions<'self> {
    /**
     * If this is None then the new process will have the same initial
     * environment as the parent process.
     *
     * If this is Some(vec-of-names-and-values) then the new process will
     * have an environment containing the given named values only.
     */
    env: Option<&'self [(~str, ~str)]>,
    /**
     * If this is None then the new process will use the same initial working
     * directory as the parent process.
     *
     * If this is Some(path) then the new process will use the given path
     * for its initial working directory.
     */
    dir: Option<&'self Path>,
    /**
     * If this is None then a new pipe will be created for the new process's
     * input and Process.input() will provide a Writer to write to this pipe.
     *
     * If this is Some(file-descriptor) then the new process will read its input
     * from the given file descriptor, Process.input_redirected() will return
     * true, and Process.input() will fail.
     */
    in_fd: Option<c_int>,
    /**
     * If this is None then a new pipe will be created for the new progam's
     * output and Process.output() will provide a Reader to read from this pipe.
     *
     * If this is Some(file-descriptor) then the new process will write its output
     * to the given file descriptor, Process.output_redirected() will return
     * true, and Process.output() will fail.
     */
    out_fd: Option<c_int>,
    /**
     * If this is None then a new pipe will be created for the new progam's
     * error stream and Process.error() will provide a Reader to read from this pipe.
     *
     * If this is Some(file-descriptor) then the new process will write its error output
     * to the given file descriptor, Process.error_redirected() will return true, and
     * and Process.error() will fail.
     */
    err_fd: Option<c_int>,
}

Options that can be given when starting a Process.

Struct ProcessOutput

pub struct ProcessOutput {
    /// The status (exit code) of the process.
    status: int,
    /// The data that the process wrote to stdout.
    output: ~[u8],
    /// The data that the process wrote to stderr.
    error: ~[u8],
}

The output of a finished process.

Implementation for ProcessOptions<'self> where <'self>

Method new

fn new<'a>() -> ProcessOptions<'a>

Return a ProcessOptions that has None in every field.

Implementation for Process

Method new

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

Spawns a new Process.

Arguments

  • prog - The path to an executable.
  • args - Vector of arguments to pass to the child process.
  • options - Options to configure the environment of the process, the working directory and the standard IO streams.

Method get_id

fn get_id(&self) -> pid_t

Returns the unique id of the process

Method input_redirected

fn input_redirected(&self) -> bool

Returns whether this process is reading its stdin from an existing file descriptor rather than a pipe that was created specifically for this process.

If this method returns true then self.input() will fail.

Method output_redirected

fn output_redirected(&self) -> bool

Returns whether this process is writing its stdout to an existing file descriptor rather than a pipe that was created specifically for this process.

If this method returns true then self.output() will fail.

Method error_redirected

fn error_redirected(&self) -> bool

Returns whether this process is writing its stderr to an existing file descriptor rather than a pipe that was created specifically for this process.

If this method returns true then self.error() will fail.

Method input

fn input(&mut self) -> @io::Writer

Returns an io::Writer that can be used to write to this Process's stdin.

Fails if this Process's stdin was redirected to an existing file descriptor.

Method output

fn output(&mut self) -> @io::Reader

Returns an io::Reader that can be used to read from this Process's stdout.

Fails if this Process's stdout was redirected to an existing file descriptor.

Method error

fn error(&mut self) -> @io::Reader

Returns an io::Reader that can be used to read from this Process's stderr.

Fails if this Process's stderr was redirected to an existing file descriptor.

Method close_input

fn close_input(&mut self)

Closes the handle to the child process's stdin.

If this process is reading its stdin from an existing file descriptor, then this method does nothing.

Method finish

fn finish(&mut self) -> int

Closes the handle to stdin, waits for the child process to terminate, and returns the exit code.

If the child has already been finished then the exit code is returned.

Method finish_with_output

fn finish_with_output(&mut self) -> ProcessOutput

Closes the handle to stdin, waits for the child process to terminate, and reads and returns all remaining output of stdout and stderr, along with the exit code.

If the child has already been finished then the exit code and any remaining unread output of stdout and stderr will be returned.

This method will fail if the child process's stdout or stderr streams were redirected to existing file descriptors.

Method destroy

fn destroy(&mut self)

Terminates the process, giving it a chance to clean itself up if this is supported by the operating system.

On Posix OSs SIGTERM will be sent to the process. On Win32 TerminateProcess(..) will be called.

Method force_destroy

fn force_destroy(&mut self)

Terminates the process as soon as possible without giving it a chance to clean itself up.

On Posix OSs SIGKILL will be sent to the process. On Win32 TerminateProcess(..) will be called.

Implementation of Drop for Process

Method drop

fn drop(&self)

Function process_output

fn process_output(prog: &str, args: &[~str]) -> ProcessOutput

Spawns a process, records all its output, and waits for it to terminate.

Arguments

Return value

The process's stdout/stderr output and exit code.

Function process_status

fn process_status(prog: &str, args: &[~str]) -> int

Spawns a process and waits for it to terminate. The process will inherit the current stdin/stdout/stderr file descriptors.

Arguments

Return value

The process's exit code