Skip to content

Document error conditions for Command::{spawn, output, status}#157360

Open
sanidhyasin wants to merge 1 commit into
rust-lang:mainfrom
sanidhyasin:document-command-spawn-errors
Open

Document error conditions for Command::{spawn, output, status}#157360
sanidhyasin wants to merge 1 commit into
rust-lang:mainfrom
sanidhyasin:document-command-spawn-errors

Conversation

@sanidhyasin
Copy link
Copy Markdown

@sanidhyasin sanidhyasin commented Jun 3, 2026

Fixes #150361.

Command::spawn, Command::output, and Command::status all return io::Result, but the docs never explain why they can fail, and they do not mention the (easy to get wrong) distinction between a failure to spawn and a child that runs but exits unsuccessfully or is killed by a signal.

This adds an # Errors section to each method:

  • spawn describes the common reasons spawning fails — the program not being found, lacking permission to execute it (e.g. not executable, or blocked by a policy such as seccomp), and the OS being unable to create the process due to resource exhaustion. It also clarifies that an error is only returned for failures while spawning; once the child has started, anything that happens to it (including signals) is reported through its ExitStatus.
  • output and status refer back to spawn for the spawn failures, and explicitly note that a child which exits unsuccessfully or is terminated by a signal is not an error — they still return Ok, with the outcome reflected in the resulting ExitStatus.

The error conditions and the signal/ExitStatus behavior were confirmed by @bjorn3 in the issue discussion.

Docs-only change; no code blocks were added or modified, and all intra-doc links (io::Error, ExitStatus, Output, spawn) follow link patterns already used in this module.

r? libs

These methods return `io::Result` but did not document why they can fail
or, importantly, that a child terminated by a signal is reported through
its `ExitStatus` rather than as an `Err`.

Add `# Errors` sections describing the common reasons spawning a child
can fail (program not found, missing permission, resource exhaustion)
and clarifying that a running child which exits unsuccessfully or is
killed by a signal is not an error: those methods still return `Ok` and
the outcome is reflected in the resulting `ExitStatus`.
@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 3, 2026
@rustbot
Copy link
Copy Markdown
Collaborator

rustbot commented Jun 3, 2026

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @LawnGnome (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

  • @rustbot author: the review is finished, PR author should check the comments and take action accordingly
  • @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue
Why was this reviewer chosen?

The reviewer was selected based on:

  • libs expanded to 8 candidates
  • Random selection from LawnGnome, Mark-Simulacrum, jhpratt

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

std::process::Command::{spawn,output,status} have inadequate docs on their error conditions

3 participants