`Command::status` method doesn't say when it will return an `Err(...)`

[yaymukund]

Location

rustdocs for std

Summary

I think the following methods:

Command::spawn(&mut self)
Command::output(&mut self)
Command::status(&mut self)
Child::wait(&mut self)
Child::try_wait(&mut self)
Child::wait_with_output(self)

ought to mention when they will exit with an Err(_). From a discussion in the community Discord:

"nils, supposedly one of the many: they will error when the command is not found
nils, supposedly one of the many: well
nils, supposedly one of the many: there are probably other conditions than "command not found"
nils, supposedly one of the many: just in general when it failed to spawn it
nils, supposedly one of the many: which can happen for all kinds of issues"

Maybe it should be a module level doc to avoid duplication.

[jyn514]

This is platform-specific so I don't think we should document it in detail. Here is the canonical list for linux: https://man7.org/linux/man-pages/man3/posix_spawn.3.html#ERRORS, which delegates to the fork and clone man pages: https://man7.org/linux/man-pages/man2/clone.2.html#ERRORS, https://man7.org/linux/man-pages/man2/fork.2.html#ERRORS. Things like

EAGAIN The caller is operating under the SCHED_DEADLINE
              scheduling policy and does not have the reset-on-fork flag
              set.  See [sched(7)](https://man7.org/linux/man-pages/man7/sched.7.html).

definitely don't seem like something we want to guarantee, but something like this seems ok:

---

Spawning a command returns an error if:

• The command does not exist, or is not in the platform-specific PATH search list.
• A platform-specific limit on memory, number of processes, or number of threads is reached.
• A dynamic library required by the command could not be found.