Improving support for numeric error codes

[jmillikin]

Related discussion:

• [rust-internals] Pre-RFC: POSIX error numbers in std::os::unix
• RFC: Proposal for POSIX error numbers in std::os::unix

Prototype code: https://github.com/jmillikin/rust-posix-error-numbers (rustdoc)

General background

The POSIX spec defines the concept of "error numbers" (aka "error codes"), which are integers with platform-specific values used to signal error conditions from low-level OS routines. Authors of libraries that interact directly with the OS (for example, via Linux kernel syscalls) need to know the values of each error number. These values can vary between OSes and architectures, and not all error numbers defined by POSIX are necessarily defined for a given (os, arch) target tuple.

Rust currently has limited support for error numbers via auto-generated bindings to the platform's libc, but these are awkward to use in no_std contexts because a common reason to build no_std binaries is specifically to avoid depending on libc:

• The runtime environment may have resource constraints (ram, storage) that are too small to fit a libc.
• The platform vendor might not provide a libc at all, or if it does, it might not be sufficiently standards-compliant to be supported by the libc crate's build system.
• There may be external requirements such as "must not depend on libc", and it is much easier to produce evidence of compliance if the build does not have the libc crate in its transitive dependency graph.

Desired project outcome

Ideally there would be an ErrorCode or ErrorNumber type defined in std, which is re-exported from a sub-crate (similar to alloc defining containers) so that it can be used in no_std mode. Ports of rustc to a target platform would define error codes for that platform as associated constants of ErrorCode, with values appropriate to the target.

Error codes are part of a platform ABI and therefore don't change once defined[0], so the ongoing maintenance overhead of this new type should be low. The primary maintenance burden will land on people adding new target platforms to rustc, and I expect that specifying error codes will not be a material increase in work considering how much is involved in porting the rest of the compiler.

[0] excepting platforms that intentionally do not provide an ABI -- it might not be possible to define the associated constants on such platforms.

[epage]

Looking into this, it seems to be about posix function error codes and not process exit codes (which I'm more interested in).

Some quick thoughts from my dealing with process exit codes that might carry over here

• This is done through a lot of platform conditionals. I find that information tends to get communicated across platforms and ideally we expose the platform specific information in a way that any platform can access.
• This specifically uses NonZeroU16. In process exit codes, you need to expose the 0 case as well since you can't or shouldn't always immediately map a u16 -> Result<(), NonZeroU16>

[Fishrock123]

Linking to #22 "Dealing with process exit codes"