Struct openssh::RemoteChild

pub struct RemoteChild<'s> { /* fields omitted */ }

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 Command struct through Session::command, 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, RemoteChild 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, RemoteChild 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 Command.

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

Implementations

impl<'s> RemoteChild<'s>

pub fn session(&self) -> &'s Session

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

pub async fn disconnect(__arg0: 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<'_>(&'_ mut 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 fn try_wait(&mut self) -> Result<Option<ExitStatus>, Error>

Attempts to collect the exit status of the remote 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 on Unix the process ID is reaped. This function is guaranteed to repeatedly return a successful exit status so long as the child has already exited.

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.

Note that unlike wait, this function will not attempt to drop stdin.

pub async fn wait_with_output(__arg0: 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.

Trait Implementations

impl<'s> Debug for RemoteChild<'s>

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

Formats the value using the given formatter.

impl<'_> Drop for RemoteChild<'_>

fn drop(&mut self)

Executes the destructor for this type.