From 138895ab773443ccaa2c7f2cea52953c5939cbb9 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Sun, 1 Oct 2023 15:15:58 -0700 Subject: [PATCH] Update the polyfill to the latest I/O safety documentation. Update the maybe_polyfill sources to the latest upstream changes. And fix a missing word in a comment. --- src/fs/statx.rs | 5 +++-- src/maybe_polyfill/no_std/os/fd/mod.rs | 8 +++++++- src/maybe_polyfill/no_std/os/fd/owned.rs | 19 ++++++++++++------- src/maybe_polyfill/no_std/os/fd/raw.rs | 7 +++++-- 4 files changed, 27 insertions(+), 12 deletions(-) diff --git a/src/fs/statx.rs b/src/fs/statx.rs index 28fd61b1d..0e4cd8f5b 100644 --- a/src/fs/statx.rs +++ b/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 diff --git a/src/maybe_polyfill/no_std/os/fd/mod.rs b/src/maybe_polyfill/no_std/os/fd/mod.rs index 2d88fb076..ea5595345 100644 --- a/src/maybe_polyfill/no_std/os/fd/mod.rs +++ b/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::*; diff --git a/src/maybe_polyfill/no_std/os/fd/owned.rs b/src/maybe_polyfill/no_std/os/fd/owned.rs index fffe34bff..721fc0c3c 100644 --- a/src/maybe_polyfill/no_std/os/fd/owned.rs +++ b/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,8 +37,8 @@ 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>, @@ -45,7 +46,8 @@ pub struct BorrowedFd<'fd> { /// 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,8 @@ 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 +187,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); diff --git a/src/maybe_polyfill/no_std/os/fd/raw.rs b/src/maybe_polyfill/no_std/os/fd/raw.rs index 41968ab04..8f6b75ae1 100644 --- a/src/maybe_polyfill/no_std/os/fd/raw.rs +++ b/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 ///