Update the polyfill to the latest I/O safety documentation. (#865)

Update the maybe_polyfill sources to the latest upstream changes.

And fix a missing word in a comment.

Author: sunfishcode

src/fs/statx.rs

@@ -72,8 +72,9 @@ mod compat {
 
     use backend::fs::types::{Statx, StatxFlags};
 
-    // Linux kernel prior to 4.11 old versions of Docker don't support `statx`.
-    // We store the availability in a global to avoid unnecessary syscalls.
+    // Linux kernel prior to 4.11 and old versions of Docker don't support
+    // `statx`. We store the availability in a global to avoid unnecessary
+    // syscalls.
     //
     // 0: Unknown
     // 1: Not available

src/maybe_polyfill/no_std/os/fd/mod.rs

@@ -5,8 +5,11 @@
 //! All code in this file is licensed MIT or Apache 2.0 at your option.
 //!
 //! Owned and borrowed Unix-like file descriptors.
+//!
+//! This module is supported on Unix platforms and WASI, which both use a
+//! similar file descriptor system for referencing OS resources.
 
-#![cfg_attr(staged_api, unstable(feature = "io_safety", issue = "87074"))]
+#![cfg_attr(staged_api, stable(feature = "os_fd", since = "1.66.0"))]
 #![deny(unsafe_op_in_unsafe_fn)]
 
 // `RawFd`, `AsRawFd`, etc.
@@ -15,5 +18,8 @@ mod raw;
 // `OwnedFd`, `AsFd`, etc.
 mod owned;
 
+// Export the types and traits for the public API.
+#[cfg_attr(staged_api, stable(feature = "os_fd", since = "1.66.0"))]
 pub use owned::*;
+#[cfg_attr(staged_api, stable(feature = "os_fd", since = "1.66.0"))]
 pub use raw::*;

src/maybe_polyfill/no_std/os/fd/owned.rs

@@ -1,6 +1,6 @@
 //! The following is derived from Rust's
 //! library/std/src/os/fd/owned.rs at revision
-//! fa68e73e9947be8ffc5b3b46d899e4953a44e7e9.
+//! 334a54cd83191f38ad8046ed94c45de735c86c65.
 //!
 //! All code in this file is licensed MIT or Apache 2.0 at your option.
 //!
@@ -18,8 +18,9 @@ use core::mem::forget;
 
 /// A borrowed file descriptor.
 ///
-/// This has a lifetime parameter to tie it to the lifetime of something that
-/// owns the file descriptor.
+/// This has a lifetime parameter to tie it to the lifetime of something that owns the file
+/// descriptor. For the duration of that lifetime, it is guaranteed that nobody will close the file
+/// descriptor.
 ///
 /// This uses `repr(transparent)` and has the representation of a host file
 /// descriptor, so it can be used in FFI in places where a file descriptor is
@@ -36,16 +37,17 @@ use core::mem::forget;
 // 32-bit c_int. Below is -2, in two's complement, but that only works out
 // because c_int is 32 bits.
 #[cfg_attr(rustc_attrs, rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FE))]
-#[cfg_attr(staged_api, unstable(feature = "io_safety", issue = "87074"))]
 #[cfg_attr(rustc_attrs, rustc_nonnull_optimization_guaranteed)]
+#[cfg_attr(staged_api, stable(feature = "io_safety", since = "1.63.0"))]
 pub struct BorrowedFd<'fd> {
     fd: RawFd,
     _phantom: PhantomData<&'fd OwnedFd>,
 }
 
 /// An owned file descriptor.
 ///
-/// This closes the file descriptor on drop.
+/// This closes the file descriptor on drop. It is guaranteed that nobody else will close the file
+/// descriptor.
 ///
 /// This uses `repr(transparent)` and has the representation of a host file
 /// descriptor, so it can be used in FFI in places where a file descriptor is
@@ -71,7 +73,11 @@ impl BorrowedFd<'_> {
     /// The resource pointed to by `fd` must remain open for the duration of
     /// the returned `BorrowedFd`, and it must not have the value `-1`.
     #[inline]
-    #[cfg_attr(staged_api, unstable(feature = "io_safety", issue = "87074"))]
+    #[cfg_attr(
+        staged_api,
+        rustc_const_stable(feature = "io_safety", since = "1.63.0")
+    )]
+    #[cfg_attr(staged_api, stable(feature = "io_safety", since = "1.63.0"))]
     pub const unsafe fn borrow_raw(fd: RawFd) -> Self {
         assert!(fd != u32::MAX as RawFd);
         // SAFETY: we just asserted that the value is in the valid range and isn't `-1` (the only value bigger than `0xFF_FF_FF_FE` unsigned)
@@ -184,7 +190,9 @@ impl FromRawFd for OwnedFd {
     /// # Safety
     ///
     /// The resource pointed to by `fd` must be open and suitable for assuming
-    /// ownership. The resource must not require any cleanup other than `close`.
+    /// [ownership][io-safety]. The resource must not require any cleanup other than `close`.
+    ///
+    /// [io-safety]: io#io-safety
     #[inline]
     unsafe fn from_raw_fd(fd: RawFd) -> Self {
         assert_ne!(fd, u32::MAX as RawFd);

src/maybe_polyfill/no_std/os/fd/raw.rs

@@ -1,6 +1,6 @@
 //! The following is derived from Rust's
 //! library/std/src/os/fd/raw.rs at revision
-//! fa68e73e9947be8ffc5b3b46d899e4953a44e7e9.
+//! 334a54cd83191f38ad8046ed94c45de735c86c65.
 //!
 //! All code in this file is licensed MIT or Apache 2.0 at your option.
 //!
@@ -71,7 +71,10 @@ pub trait FromRawFd {
     ///
     /// # Safety
     ///
-    /// The `fd` passed in must be a valid an open file descriptor.
+    /// The `fd` passed in must be an [owned file descriptor][io-safety];
+    /// in particular, it must be open.
+    ///
+    /// [io-safety]: io#io-safety
     ///
     /// # Example
     ///