From 813fed2904fde5d5238e89e2e87fc9830b39a67d Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Fri, 22 Sep 2023 13:18:46 +0200 Subject: [PATCH] fix OS-specific I/O safety docs since the io_safety feature is stable --- library/std/src/os/unix/io/mod.rs | 11 +++++++---- library/std/src/os/windows/io/mod.rs | 11 +++++++---- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/library/std/src/os/unix/io/mod.rs b/library/std/src/os/unix/io/mod.rs index c12d89ed637..827278f8b26 100644 --- a/library/std/src/os/unix/io/mod.rs +++ b/library/std/src/os/unix/io/mod.rs @@ -6,7 +6,8 @@ //! //! This module provides three types for representing file descriptors, //! with different ownership properties: raw, borrowed, and owned, which are -//! analogous to types used for representing pointers. These types reflect the Unix version of [I/O safety]. +//! analogous to types used for representing pointers. These types reflect concepts of [I/O +//! safety][io-safety] on Unix. //! //! | Type | Analogous to | //! | ------------------ | ------------ | @@ -17,8 +18,8 @@ //! Like raw pointers, `RawFd` values are primitive values. And in new code, //! they should be considered unsafe to do I/O on (analogous to dereferencing //! them). Rust did not always provide this guidance, so existing code in the -//! Rust ecosystem often doesn't mark `RawFd` usage as unsafe. Once the -//! `io_safety` feature is stable, libraries will be encouraged to migrate, +//! Rust ecosystem often doesn't mark `RawFd` usage as unsafe. +//! Libraries are encouraged to migrate, //! either by adding `unsafe` to APIs that dereference `RawFd` values, or by //! using to `BorrowedFd` or `OwnedFd` instead. //! @@ -54,6 +55,8 @@ //! Like boxes, `OwnedFd` values conceptually own the resource they point to, //! and free (close) it when they are dropped. //! +//! See the [`io` module docs][io-safety] for a general explanation of I/O safety. +//! //! ## `/proc/self/mem` and similar OS features //! //! Some platforms have special files, such as `/proc/self/mem`, which @@ -74,7 +77,7 @@ //! necessary to use *sandboxing*, which is outside the scope of `std`. //! //! [`BorrowedFd<'a>`]: crate::os::unix::io::BorrowedFd -//! [I/O safety]: crate::io#io-safety +//! [io-safety]: crate::io#io-safety #![stable(feature = "rust1", since = "1.0.0")] diff --git a/library/std/src/os/windows/io/mod.rs b/library/std/src/os/windows/io/mod.rs index 3d4bb96d458..3d3ae387886 100644 --- a/library/std/src/os/windows/io/mod.rs +++ b/library/std/src/os/windows/io/mod.rs @@ -6,7 +6,8 @@ //! //! This module provides three types for representing raw handles and sockets //! with different ownership properties: raw, borrowed, and owned, which are -//! analogous to types used for representing pointers. These types reflect the Windows version of [I/O safety]. +//! analogous to types used for representing pointers. These types reflect concepts of [I/O +//! safety][io-safety] on Windows. //! //! | Type | Analogous to | //! | ---------------------- | ------------ | @@ -23,8 +24,8 @@ //! And in new code, they should be considered unsafe to do I/O on (analogous //! to dereferencing them). Rust did not always provide this guidance, so //! existing code in the Rust ecosystem often doesn't mark `RawHandle` and -//! `RawSocket` usage as unsafe. Once the `io_safety` feature is stable, -//! libraries will be encouraged to migrate, either by adding `unsafe` to APIs +//! `RawSocket` usage as unsafe. +//! Libraries are encouraged to migrate, either by adding `unsafe` to APIs //! that dereference `RawHandle` and `RawSocket` values, or by using to //! `BorrowedHandle`, `BorrowedSocket`, `OwnedHandle`, or `OwnedSocket`. //! @@ -45,9 +46,11 @@ //! Like boxes, `OwnedHandle` and `OwnedSocket` values conceptually own the //! resource they point to, and free (close) it when they are dropped. //! +//! See the [`io` module docs][io-safety] for a general explanation of I/O safety. +//! //! [`BorrowedHandle<'a>`]: crate::os::windows::io::BorrowedHandle //! [`BorrowedSocket<'a>`]: crate::os::windows::io::BorrowedSocket -//! [I/O safety]: crate::io#io-safety +//! [io-safety]: crate::io#io-safety #![stable(feature = "rust1", since = "1.0.0")]