Struct Child

pub struct Child { /* private fields */ }

Representation of a running or exited child process.

This structure is used to represent and manage child processes. A child process is created via the Command struct, which configures the spawning process and can itself be constructed using a builder-style interface.

Warnings

Calling wait is necessary for the OS to release resources. A process that terminated but has not been waited on is still around as a “zombie”. Leaving too many zombies around may exhaust global resources.

This library does not automatically wait on child processes (not even if the Child is dropped), it is up to the application developer to do so. As a consequence, dropping Child handles without waiting on them first is not recommended in long-running applications.

Examples

use CreateProcessW::Command;

let mut child = Command::new("notepad.exe")
    .spawn()
    .expect("failed to execute child");

let status = child.wait().expect("failed to wait on child");

assert!(status.success());

Implementations

impl Child

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

Forces the child process to exit. If the child has already exited, a [KillFailed][Error::KillFailed] error is returned.

This function is used to unconditionally cause a process to exit and stops execution of all threads within the process and requests cancellation of all pending I/O. The terminated process cannot exit until all pending I/O has been completed and canceled. When a process terminates, its kernel object is not destroyed until all processes that have open handles to the process have released those handles.

Equivalent to the TerminateProcess function. Note that the value passed as the uExitCode is always 0 at the moment.

Examples

use CreateProcessW::Command;

let mut command = Command::new("notepad.exe");

if let Ok(mut child) = command.spawn() {
    child.kill().expect("notepad wasn't running");
} else {
    println!("notepad didn't start");
}

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

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

If the function fail, it return a [GetExitCodeFailed][Error::GetExitCodeFailed] error.

This is equivalent to calling the WaitForSingleObject][wait-for-single-object] and the [CloseHandle` functions.

Examples

use CreateProcessW::Command;

let mut command = Command::new("notepad.exe");

if let Ok(mut child) = command.spawn() {
    child.wait().expect("command wasn't running");
    println!("Child has finished its execution!");
} else {
    println!("notepad didn't start");
}

pub fn try_wait(&self) -> Result<Option<ExitStatus>, Error>

Attempts to collect the exit status of the child if it has already exited.

This function will not block the calling thread and will only check to see if the child process has exited or not.

If the child has exited, then Ok(Some(status)) is returned. If the exit status is not available at this time then Ok(None) is returned. If an error occurs, then that error is returned.

Equivalent to the [GetExitCodeProcess][get-exit-code-process] function.

Note that this function will call CloseHandle if the child has exited. If the function fail, a [GetExitCodeProcess][Error::GetExitCodeFailed] error is returned.

Examples

use CreateProcessW::Command;

let mut child = Command::new("notepad.exe").spawn().unwrap();

match child.try_wait() {
    Ok(Some(status)) => println!("exited with: {}", status.code()),
    Ok(None) => {
        println!("status not ready yet, let's really wait");
        let status = child.wait().expect("cannot wait process");
        println!("waited: {}", status.code());
    }
    Err(e) => println!("error attempting to wait: {}", e),
}

pub fn id(&self) -> u32

Returns the process identifier associated with this child.

Examples

use CreateProcessW::Command;

let mut command = Command::new("notepad.exe");

if let Ok(child) = command.spawn() {
    println!("Child's ID is {}", child.id());
} else {
    println!("notepad didn't start");
}

Trait Implementations

impl Debug for Child

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

Formats the value using the given formatter.