Struct openssh::Child

pub struct Child<S> { /* private fields */ }

Representation of a running or exited remote child process.

This structure is used to represent and manage remote child processes. A remote child process is created via the OwningCommand struct through Session::command or one of its variants, which configures the spawning process and can itself be constructed using a builder-style interface.

Calling wait (or other functions that wrap around it) will make the parent process wait until the child has actually exited before continuing.

Unlike std::process::Child, Child does implement Drop, and will terminate the local ssh process corresponding to the remote process when it goes out of scope. Note that this does not terminate the remote process. If you want to do that, you will need to kill it yourself by executing a remote command like pkill to kill it on the remote side.

As a result, Child cannot expose stdin, stdout, and stderr as fields for split-borrows like std::process::Child does. Instead, it exposes stdin, stdout, and stderr as methods. Callers can call .take() to get the same effect as a split borrow and use multiple streams concurrently. Note that for the streams to be available,Stdio::piped() should be passed to the corresponding method on OwningCommand.

NOTE that once Child is dropped, any data written to stdin will not be sent to the remote process and stdout and stderr will yield EOF immediately.

let stdin = child.stdin().take().unwrap();
let stdout = child.stdout().take().unwrap();
tokio::io::copy(&mut stdout, &mut stdin).await;

Implementations

impl<S> Child<S>

pub async fn disconnect(self) -> Result<()>

Disconnect from this given remote child process.

Note that disconnecting does not kill the remote process, it merely kills the local handle to that remote process.

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

Waits for the remote 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, if any, will be closed before waiting. This helps avoid deadlock: it ensures that the child does not block waiting for input from the parent, while the parent waits for the child to exit.

pub async fn wait_with_output(self) -> Result<Output, Error>

Simultaneously waits for the remote child to exit and collect all remaining output on the stdout/stderr handles, returning an Output instance.

The stdin handle to the child process, if any, will be closed before waiting. This helps avoid deadlock: it ensures that the child does not block waiting for input from the parent, while the parent waits for the child to exit.

By default, stdin, stdout and stderr are inherited from the parent. In order to capture the output into this Result<Output> it is necessary to create new pipes between parent and child. Use stdout(Stdio::piped()) or stderr(Stdio::piped()), respectively.

pub fn stdin(&mut self) -> &mut Option<ChildStdin>

Access the handle for reading from the remote child’s standard input (stdin), if requested.

pub fn stdout(&mut self) -> &mut Option<ChildStdout>

Access the handle for reading from the remote child’s standard output (stdout), if requested.

pub fn stderr(&mut self) -> &mut Option<ChildStderr>

Access the handle for reading from the remote child’s standard error (stderr), if requested.

impl<S: Clone> Child<S>

pub fn session(&self) -> S

Access the SSH session that this remote process was spawned from.

Trait Implementations

impl<S: Debug> Debug for Child<S>

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

Formats the value using the given formatter.