Skip to content

Clarify ExitStatusExt documentation#158574

Merged
rust-bors[bot] merged 1 commit into
rust-lang:mainfrom
schneems:schneems/document-exit-status-ext
Jul 2, 2026
Merged

Clarify ExitStatusExt documentation#158574
rust-bors[bot] merged 1 commit into
rust-lang:mainfrom
schneems:schneems/document-exit-status-ext

Conversation

@schneems

@schneems schneems commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

View all comments

Fix struct links

There are several structs (ExitStatus and ExitStatusError) that could be linked, but aren't. Fixed. All links show their struct now instead of previously some showed process::ExitStatus when rendered.

Add wait links

The docs distinguish wait as code, but do not link to what wait they're referring to. As this is Unix extension documentation, adding a link to the POSIX standard for wait. Showing a construction of an ExitStatus for both a signal and an exit code helps to highlight and internalize what wait status, not an exit status means.

Example for from_raw

Current documentation calls out "The value should be a wait status, not an exit status." but it's unclear what exactly that means without a reference or an example. I added a doctest that shows you need to shift by 8 to get the desired result and annotated it with information about how that's derived based on the linked wait documentation.

Example to ExitStatus::signal

Called out that a signaled process does not also produce an exit code. Added an example. Called out that just because a process reports that it was not terminated via a signal doesn't mean it never got one (it could be handled). Also added a note correlating shell behavior to exit codes:

GNU Bash manual: https://web.archive.org/web/20260625050034/https://www.gnu.org/software/bash/manual/bash.html#Exit-Status-1

[...] a fatal signal whose number is N, Bash uses the value 128+N as the exit status.

FreeBSD bash(1) man page: https://man.freebsd.org/bash/1

The return value [...] 128+n if the command is terminated by signal n.

Panic scope on from_raw

This change is based on preference/experience:

When I originally read this documentation, it was because I clicked through Output -> ExitStatus. While the text "Creates a new ExitStatus or ExitStatusError" is present at the top, I didn't internalize what that meant exactly. Therefore, when I got to the panic section, I was mildly confused.

This edit makes the behavior more explicitly attached to the type. While the original format had all of the same information available, it was left for the reader to bridge that "making an ExitStatusError" is referring to ExitStatus::from_raw as that's the only constructor (for now).

Making this bridge more explicit also future-proofs us for future constructors (if they're ever added) that may or may not panic. While the context of the panic documentation is directly attached to from_raw, it's slightly (pedantically) more correct to not imply that ANY way of creating an ExitStatusErrorfrom awaitof0` will panic (a different constructor could perhaps return an option instead).

Technically, the syntax isn't correct, as it should be <ExitStatusError as ExitStatusExt>::from_raw, but I think this conveys intent without being overly verbose.

@rustbot rustbot added O-unix Operating system: Unix-like 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 29, 2026
@rustbot

rustbot commented Jun 29, 2026

Copy link
Copy Markdown
Collaborator

r? @Darksonn

rustbot has assigned @Darksonn.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

  • Owners of files modified in this PR: @ChrisDenton, libs
  • @ChrisDenton, libs expanded to 13 candidates
  • Random selection from 6 candidates

@schneems schneems force-pushed the schneems/document-exit-status-ext branch 2 times, most recently from b26864a to c224bea Compare July 1, 2026 03:16
@rustbot

rustbot commented Jul 1, 2026

Copy link
Copy Markdown
Collaborator

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

@schneems schneems closed this Jul 1, 2026
@rustbot rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jul 1, 2026
@schneems schneems reopened this Jul 1, 2026
@rustbot rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jul 1, 2026
Comment thread library/std/src/os/unix/process.rs
Comment thread library/std/src/os/unix/process.rs Outdated
Comment thread library/std/src/os/unix/process.rs Outdated
Comment thread library/std/src/os/unix/process.rs
Comment thread library/std/src/os/unix/process.rs Outdated
Comment thread library/std/src/os/unix/process.rs Outdated
@Darksonn Darksonn added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 1, 2026
@schneems schneems force-pushed the schneems/document-exit-status-ext branch from c224bea to b77be38 Compare July 1, 2026 19:13
@schneems

schneems commented Jul 1, 2026

Copy link
Copy Markdown
Contributor Author

Updated. Replied inline and left comment threads unresolved, assuming you'll do that when you're happy enough with the results.

Comment thread library/std/src/os/unix/process.rs Outdated
/// hold on every target:
///
/// ```
/// # if cfg!(not(target_os = "fuchsia")) {

@Darksonn Darksonn Jul 1, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: You can avoid the # } at the end using

Suggested change
/// # if cfg!(not(target_os = "fuchsia")) {
/// # if cfg!(not(target_os = "fuchsia")) { return; }

View changes since the review

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like that syntax. It is cleaner. Also, needed to swap the logic. Applied locally and pushed.

@Darksonn

Darksonn commented Jul 1, 2026

Copy link
Copy Markdown
Member

@rustbot author

@rustbot

rustbot commented Jul 1, 2026

Copy link
Copy Markdown
Collaborator

Reminder, once the PR becomes ready for a review, use @rustbot ready.

## Fix struct links

There are several structs (`ExitStatus` and `ExitStatusError`) that could be linked, but aren't. Fixed. All links show their struct now instead of previously some showed `process::ExitStatus` when rendered.

## Add `wait` links

The docs distinguish `wait` as code, but do not link to **what** wait they're referring to. As this is Unix extension documentation, adding a link to the POSIX standard for `wait`. Showing a construction of an `ExitStatus` for both a signal and an exit code helps to highlight and internalize what **wait status, not an exit status** means.

## Example for `from_raw`

Current documentation calls out "The value should be a **wait status, not an exit status**." but it's unclear what exactly that means without a reference or an example. I added a doctest that shows you need to shift by 8 to get the desired result and annotated it with information about how that's derived based on the linked `wait` documentation.

## Example to `ExitStatus::signal`

Called out that a signaled process does not also produce an exit code. Added an example. Called out that just because a process reports that it was not terminated via a signal doesn't mean it never got one (it could be handled). Also added a note correlating shell behavior to exit codes:

GNU Bash manual: https://web.archive.org/web/20260625050034/https://www.gnu.org/software/bash/manual/bash.html#Exit-Status-1

> [...] a fatal signal whose number is N, Bash uses the value 128+N as the exit status.

FreeBSD bash(1) man page: https://man.freebsd.org/bash/1

> The return value	[...]  128+n  if the command is terminated by signal n.

## Panic scope on `from_raw`

This change is based on preference/experience:

When I originally read this documentation, it was because I clicked through `Output` -> `ExitStatus`. While the text "Creates a new `ExitStatus` or `ExitStatusError`" is present at the top, I didn't internalize what that meant exactly. Therefore, when I got to the panic section, I was mildly confused.

This edit makes the behavior more explicitly attached to the type. While the original format had all of the same information available, it was left for the reader to bridge that "making an ExitStatusError" is referring to `ExitStatus::from_raw` as that's the only constructor (for now).

Making this bridge more explicit also future-proofs us for future constructors (if they're ever added) that may or may not panic. While the context of the panic documentation is directly attached to `from_raw`, it's slightly (pedantically) more correct to not imply that ANY way of creating an ExitStatusError` from a `wait` of `0` will panic (a different constructor could perhaps return an option instead).

Technically, the syntax isn't correct, as it should be `<ExitStatusError as ExitStatusExt>::from_raw`, but I think this conveys intent without being overly verbose.

Co-authored-by: Colin Casey <casey.colin@gmail.com>
@schneems schneems force-pushed the schneems/document-exit-status-ext branch from b77be38 to 13bcaad Compare July 1, 2026 20:19
@Darksonn

Darksonn commented Jul 1, 2026

Copy link
Copy Markdown
Member

Thanks for the PR!

@bors r+

@rust-bors

rust-bors Bot commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

📌 Commit 13bcaad has been approved by Darksonn

It is now in the queue for this repository.

@rust-bors rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 1, 2026
rust-bors Bot pushed a commit that referenced this pull request Jul 1, 2026
Rollup of 8 pull requests

Successful merges:

 - #156737 (Implement `DoubleEndedIterator::next_chunk_back`)
 - #158180 (std: use `OnceLock` for SGX environment variable storage)
 - #158427 (Implement `ptr::{read,write}_unaligned` via `repr(packed)`)
 - #158531 (Change `adjust_ident_and_get_scope` arg to `LocalDefId`)
 - #158574 (Clarify ExitStatusExt documentation)
 - #158334 (rustdoc: Show use-site paths for unevaluated const array lengths)
 - #158364 (rustc_target/asm: add LoongArch LSX/LASX inline asm register support)
 - #158667 (rustc_sanitizers: use twox-hash without default features)
@rust-bors rust-bors Bot merged commit 35bf13f into rust-lang:main Jul 2, 2026
13 checks passed
@rustbot rustbot added this to the 1.98.0 milestone Jul 2, 2026
rust-timer added a commit that referenced this pull request Jul 2, 2026
Rollup merge of #158574 - schneems:schneems/document-exit-status-ext, r=Darksonn

Clarify ExitStatusExt documentation

## Fix struct links

There are several structs (`ExitStatus` and `ExitStatusError`) that could be linked, but aren't. Fixed. All links show their struct now instead of previously some showed `process::ExitStatus` when rendered.

## Add `wait` links

The docs distinguish `wait` as code, but do not link to **what** wait they're referring to. As this is Unix extension documentation, adding a link to the POSIX standard for `wait`. Showing a construction of an `ExitStatus` for both a signal and an exit code helps to highlight and internalize what **wait status, not an exit status** means.

## Example for `from_raw`

Current documentation calls out "The value should be a **wait status, not an exit status**." but it's unclear what exactly that means without a reference or an example. I added a doctest that shows you need to shift by 8 to get the desired result and annotated it with information about how that's derived based on the linked `wait` documentation.

## Example to `ExitStatus::signal`

Called out that a signaled process does not also produce an exit code. Added an example. Called out that just because a process reports that it was not terminated via a signal doesn't mean it never got one (it could be handled). Also added a note correlating shell behavior to exit codes:

GNU Bash manual: https://web.archive.org/web/20260625050034/https://www.gnu.org/software/bash/manual/bash.html#Exit-Status-1

> [...] a fatal signal whose number is N, Bash uses the value 128+N as the exit status.

FreeBSD bash(1) man page: https://man.freebsd.org/bash/1

> The return value	[...]  128+n  if the command is terminated by signal n.

## Panic scope on `from_raw`

This change is based on preference/experience:

When I originally read this documentation, it was because I clicked through `Output` -> `ExitStatus`. While the text "Creates a new `ExitStatus` or `ExitStatusError`" is present at the top, I didn't internalize what that meant exactly. Therefore, when I got to the panic section, I was mildly confused.

This edit makes the behavior more explicitly attached to the type. While the original format had all of the same information available, it was left for the reader to bridge that "making an ExitStatusError" is referring to `ExitStatus::from_raw` as that's the only constructor (for now).

Making this bridge more explicit also future-proofs us for future constructors (if they're ever added) that may or may not panic. While the context of the panic documentation is directly attached to `from_raw`, it's slightly (pedantically) more correct to not imply that ANY way of creating an ExitStatusError` from a `wait` of `0` will panic (a different constructor could perhaps return an option instead).

Technically, the syntax isn't correct, as it should be `<ExitStatusError as ExitStatusExt>::from_raw`, but I think this conveys intent without being overly verbose.
@schneems

schneems commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review and all your maintenance work! These are somewhat niche interfaces, but it feels good that anyone who needs them doesn't have to re-learn all this from scratch.

Now I'm feeling like POSIX is missing an interface for constructing these exit values. I've never contributed there, but seeing no similar discussion, it might be worth opening one.

@schneems schneems deleted the schneems/document-exit-status-ext branch July 2, 2026 15:13
@Darksonn

Darksonn commented Jul 2, 2026

Copy link
Copy Markdown
Member

I don't know anything about contributing to POSIX unfortunately.

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

Labels

O-unix Operating system: Unix-like S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. 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.

3 participants