From b82f09a48d45dd8cbb8a313d26a94858766f0001 Mon Sep 17 00:00:00 2001 From: Sanidhya Singh Date: Wed, 3 Jun 2026 12:09:35 +0530 Subject: [PATCH] Document error conditions for Command::{spawn, output, status} 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`. --- library/std/src/process.rs | 47 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/library/std/src/process.rs b/library/std/src/process.rs index 0b8db439a6370..990cb0eb8c7e4 100644 --- a/library/std/src/process.rs +++ b/library/std/src/process.rs @@ -1070,6 +1070,26 @@ impl Command { /// /// By default, stdin, stdout and stderr are inherited from the parent. /// + /// # Errors + /// + /// This method returns an [`io::Error`] if the child process could not be + /// spawned. Common reasons include: + /// + /// * the program could not be found (for example, it does not exist, or, + /// when given a bare name, it is not present in the `PATH`); + /// * the current process does not have permission to execute the program + /// (for example, the file is not marked executable, or execution is + /// denied by a security policy such as `seccomp`); + /// * the operating system could not create the new process because of + /// resource exhaustion (for example, a limit on the number of processes + /// was reached). + /// + /// An error is only returned for failures that occur while the child is + /// being spawned. Once the child has started successfully, anything that + /// happens to it afterwards — including being terminated by a signal — is + /// reported through its [`ExitStatus`] rather than as an error from the + /// spawning method. + /// /// # Examples /// /// ```no_run @@ -1092,6 +1112,20 @@ impl Command { /// attempt by the child process to read from the stdin stream will result /// in the stream immediately closing. /// + /// # Errors + /// + /// Like [`spawn`], this method returns an [`io::Error`] if the child + /// process could not be spawned; see [`spawn`] for the common reasons. It + /// may also return an error if reading the child's output or waiting on the + /// child fails. + /// + /// Note that this method does **not** return an error if the child runs and + /// then exits unsuccessfully, or is terminated by a signal. In those cases + /// it still returns [`Ok`], and the outcome is reflected in the + /// [`ExitStatus`] stored in the returned [`Output`]. + /// + /// [`spawn`]: Command::spawn + /// /// # Examples /// /// ```should_panic @@ -1119,6 +1153,19 @@ impl Command { /// /// By default, stdin, stdout and stderr are inherited from the parent. /// + /// # Errors + /// + /// Like [`spawn`], this method returns an [`io::Error`] if the child + /// process could not be spawned; see [`spawn`] for the common reasons. It + /// may also return an error if waiting on the child fails. + /// + /// Note that this method does **not** return an error if the child runs and + /// then exits unsuccessfully, or is terminated by a signal. In those cases + /// it still returns [`Ok`], and the outcome is reflected in the returned + /// [`ExitStatus`]. + /// + /// [`spawn`]: Command::spawn + /// /// # Examples /// /// ```should_panic