pub fn run_command(
command: OwnedCommand,
input: Option<&[u8]>,
options: &RunOptions,
) -> Result<RunOutput>Expand description
run / run_with_stdin for a command the caller configured: its program, arguments,
environment (including a cleared or allow-listed one), working directory and any other
OwnedCommand setting are used as given. The crate sets stdin, stdout and stderr (pipes;
stdin is null when input is None) and the window mode from options.no_window, replacing
whatever the caller set for those, including the stdio of an explicit or automatic
WindowsSpawnConfig on a Windows inherit_handles_only command (its environment, raw
arguments and security settings are kept). If a capture’s pipe read fails the call returns
that error instead of an Ok with partial output.
input of Some(bytes) is written to the child’s stdin on its own thread while output is
drained concurrently, so input larger than a pipe buffer cannot deadlock against a chatty
child; the writer closes stdin when done, delivering EOF (Some(&[]) delivers EOF at once).
A child that exits before consuming the input closes the pipe: that broken-pipe outcome is
a normal early exit, not an error, and the child’s status/output are returned as usual.
Any other stdin write failure is returned as Err after the tree is down. A process that
outlived the tree and still holds stdin without reading it cannot hold the call past its
deadline: once the tree is down the writer gets a short grace, then it is cancelled (Unix:
non-blocking write end; Windows: CancelIoEx) and joined.
What a return guarantees about the writer:
- Every
Okreturn: the writer thread has been joined and the write end is closed. - A writer that cannot be stopped within its bound makes the call fail with
ErrorKind::TimedOut. - Any other
Err(an early failure, such as output capture or waiting on the child) still cancels the writer with the same bound before returning, but reports that original error, not the cleanup outcome. - Unix, every return: the parent has closed the write end, so a writer thread that is still alive can deliver nothing more and ends on its next step.
- Windows, after
TimedOutor an earlyErr: a writer that did not stop within the bound may still be alive and blocked in a write, owning the write end, with its cancel flag set. This needs a pendingCancelIoExthat fails to abort the write, which is not expected.
Everything else (the deadline, the tree kill, the output caps, what Err means before the
program starts) is as documented on run, which delegates here.