Clarify Error::last_os_error can be weird

[workingjubilee]

Fundamentally, querying the OS for error codes is a process that is deeply subject to the whims of chance and fortune. We can account for OS, but not for every combination of platform APIs. A compiled binary may not recognize new errors introduced years later. We should clarify a few especially odd situations, and what they mean: We can effectively promise nothing... if you ask for Rust to decode errors where none have occurred.

This allows removing mention of ErrorKind::Uncategorized.
That error variant is hidden deliberately, so we should not explicitly mention it.

This fixes #106937.

Since you had an opinion also: Does this solution seem acceptable?
r? @ChrisDenton

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[ChrisDenton]

Hm, this does seem to adequately address the issue but I do think it'd be useful for the kind() docs to have some mention of what happens with OS errors (i.e. with last_os_error and from_raw_os_error their kind is automatically determined based on the OS error code). The from_raw_os_error has a relevant example so maybe it's enough to link to that method's docs.

[workingjubilee]

I tried an alternative tack of explaining that if you ask Rust to decode an error where none has actually occurred, it may not make sense. It may have even been set to random values by a truly spiteful OS. We're just a standard library, and are not necessarily capable of suggesting you ask a different question instead.

[ChrisDenton]

To be honest, I think the initial PR was more in the right direction than this alternative tack. There's no need for kind() to get into the nuances of last_os_error(). The important points are, I think, that kind() will either return the io::Kind that was set in a custom io::Error or else return an io::Kind that's inferred from an OS error code.

[workingjubilee]

More like this, then?

[ChrisDenton]

Yeah. I'll admit to still being slightly uncomfortable with the example but I think this is a definite improvement. So...

@bors r+

[bors]

📌 Commit 0f32fd8 has been approved by ChrisDenton

It is now in the queue for this repository.