Document error conditions for Command::{spawn, output, status}#157360
Open
sanidhyasin wants to merge 1 commit into
Open
Document error conditions for Command::{spawn, output, status}#157360sanidhyasin wants to merge 1 commit into
Command::{spawn, output, status}#157360sanidhyasin wants to merge 1 commit into
Conversation
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`.
Collaborator
|
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 (
Why was this reviewer chosen?The reviewer was selected based on:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #150361.
Command::spawn,Command::output, andCommand::statusall returnio::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
# Errorssection to each method:spawndescribes 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 asseccomp), 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 itsExitStatus.outputandstatusrefer back tospawnfor the spawn failures, and explicitly note that a child which exits unsuccessfully or is terminated by a signal is not an error — they still returnOk, with the outcome reflected in the resultingExitStatus.The error conditions and the signal/
ExitStatusbehavior were confirmed by@bjorn3in 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