Skip to main content

run_command

Function run_command 

Source
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 Ok return: 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 TimedOut or an early Err: 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 pending CancelIoEx that 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.