I/O safety.

[sunfishcode]

Introduce OwnedFd and BorrowedFd, and the AsFd trait, and
implementations of AsFd, From<OwnedFd> and From<T> for OwnedFd
for relevant types, along with Windows counterparts for handles and
sockets.

Tracking issue: #87074

RFC: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md

Highlights:

• The doc comments at the top of library/std/src/os/unix/io/mod.rs and library/std/src/os/windows/io/mod.rs
• The new types and traits in library/std/src/os/unix/io/fd.rs and library/std/src/os/windows/io/handle.rs
• The removal of the RawHandle struct the Windows impl, which had the same name as the RawHandle type alias, and its functionality is now folded into Handle.

Managing five levels of wrapping (File wraps sys::fs::File wraps sys::fs::FileDesc wraps OwnedFd wraps RawFd, etc.) made for a fair amount of churn and verbose as/into/from sequences in some places. I've managed to simplify some of them, but I'm open to ideas here.

r? @joshtriplett

[joshtriplett]

Managing five levels of wrapping (File wraps sys::fs::File wraps sys::fs::FileDesc wraps OwnedFd wraps RawFd, etc.) made for a fair amount of churn and verbose as/into/from sequences in some places. I've managed to simplify some of them, but I'm open to ideas here.

I don't know how feasible this would be, but I wonder if we could eliminate sys::fs::FileDesc and have sys::fs::File directly use OwnedFd. That would give us what feels like the right amount of indirection: the portable File wraps the UNIX-specific sys::fs::File, which wraps an OwnedFd, which wraps the simple type alias RawFd.

(To clarify, though, that kind of cleanup belongs in a follow-up, not in the initial introduction of this.)

[Thomasdezeeuw]

Looks really good @sunfishcode, just some small comments.

[Thomasdezeeuw]

Same as about with regard to INVALID_HANDLE_VALUE.

[ChrisDenton]

In case it's relevant here, Windows essentially has two types of I/O HANDLE (it also reuses the type for other things but that's off topic):

• Kernel handles. These are "real" handles (i.e. they are an offset into a table of kernel objects).
• Pseudo handles. These are "fake" handles (i.e. managed by the Win32 subsystem). They have resources managed outside of the NT kernel so are often intentionally invalid kernel handles. The meaning of pseudo handles is very context dependent.

In both cases, zero is not a valid handle. It's also guaranteed that a kernel handle will not have the lowest two bits set. A pseudo handle has no such restriction and indeed may intentionally make use of the lowest two bits to distinguish themselves from "real" handles. Therefore INVALID_HANDLE_VALUE is not a valid kernel handle but can be reused as a pseudo handle.

(I'm also pretty sure a kernel handle will always be less than i32::MAX but I'm not sure to what extent that's guaranteed).

I'm uncertain if this information is helpful to anyone but I just wanted to document some of what I know.

[sunfishcode]

Thanks @ChrisDenton! Do you by chance know of an authoritative reference stating that zero is not a valid handle? The code here assumes that, and for various reasons it seems like a safe assumption, but if there's official documentation about this, I'd like to cite it.

[ChrisDenton]

Unfortunately I do not. It shakes out that way, as you note, for various practical reasons but I don't know that it's explicitly documented anywhere.

[ChrisDenton]

@sunfishcode From GetStdHandle:

If an application does not have associated standard handles, such as a service running on an interactive desktop, and has not redirected them, the return value is NULL.

So here a NULL I/O handle means "no handle". You can redirect stdin etc to any I/O handle (where "I/O handle" means "can be passed to WriteFile, etc") therefore no valid I/O handle can be NULL because it would overlap with that meaning.

I admit this falls short of explicit documentation but it's the closest I can find. You could also cite functions such as OpenProcess that use NULL to indicate errors but obviously they're specific to the type of handle.

In short there's no explicit documentation that covers all types of handles but, as the blog you linked to notes, the very fact that it was a "toss up" whether to use NULL to signal an error is a good indication that it's not a valid handle, And unlike INVALID_HANDLE_VALUE there's no documentation that says "for this specific type of handle NULL is treated as a special, valid, handle value".

(more broadly, it would likely break a lot of things if NULL were ever to become valid but this is supposition on my part).

[Nashenas88]

In case this is useful, we discovered that this change adds ambiguity for code that was relying on where T: From<F>, F: FromRawFd (roughly). This was a simple fix on our side, but we did see this breakage:

[115822/211194] RUST password_authenticator_integration_test exe.unstripped/password_authenticator_integration_test
FAILED: password_authenticator_integration_test exe.unstripped/password_authenticator_integration_test
mkdir -p ./exe.unstripped &&  RUST_BACKTRACE=1 ../../../recipe_cleanup/rustupp6g4sd/bin/rustc --color=always --crate-name password_authenticator_integration_test ../../src/identity/tests/password_a...
error[E0283]: type annotations needed
   --> ../../src/identity/tests/password_authenticator_integration/src/account_manager.rs:128:17
    |
128 |                 fs::File::from(fdio::create_fd(ramdisk_handle).expect("create fd of dev root"));
    |                 ^^^^^^^^^^^^^^ --------------------------------------------------------------- this method call resolves to `T`
    |                 |
    |                 cannot infer type for type parameter `T` declared on the trait `From`
    |
    = note: cannot satisfy `std::fs::File: From<_>`
note: required by `from`

error[E0283]: type annotations needed
   --> ../../src/identity/tests/password_authenticator_integration/src/account_manager.rs:250:9
    |
250 |           fs::File::from(
    |           ^^^^^^^^^^^^^^ cannot infer type for type parameter `T` declared on the trait `From`
251 | /             fdio::create_fd(
252 | |                 dev_root_proxy
253 | |                     .into_channel()
254 | |                     .expect("Could not convert dev root DirectoryProxy into channel")
...   |
257 | |             )
258 | |             .expect("create fd of dev root"),
    | |____________________________________________- this method call resolves to `T`
    |
    = note: cannot satisfy `std::fs::File: From<_>`
note: required by `from`

error: aborting due to 2 previous errors

For more information about this error, try `rustc --explain E0283`.

Where fdio::create_fd has a signature of pub fn create_fd<F: FromRawFd>(handle: zx::Handle) -> Result<F, zx::Status>

[sunfishcode]

Thanks for reporting this! I've now filed #89955 to track this.

[adrianheine]

I don't know if there's another way to handle this, but the since of 1.0.0 and 1.1.0 on items are correct for the re-exports under std::os::unix::io but obviously wrong for std::os::fd, which should be since = "1.56.0".