From 55f18beddd8a74034a402fae173eb74e046cedaa Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Mon, 14 Aug 2023 08:59:37 +0200 Subject: [PATCH] wording; and explain some of the possible consequences of violating io-safety --- library/std/src/io/mod.rs | 8 +++++++- library/std/src/os/unix/io/mod.rs | 2 +- library/std/src/os/windows/io/mod.rs | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs index c77a6e323c8..5a9a5067957 100644 --- a/library/std/src/io/mod.rs +++ b/library/std/src/io/mod.rs @@ -245,7 +245,7 @@ //! subsume similar concepts that exist across a wide range of operating systems even if they might //! use a different name, such as "handle".) An exclusively owned file descriptor is one that no //! other code is allowed to close, but the owner is allowed to close it any time. A type that owns -//! its file descriptor should close it in its `drop` function. Types like [`File`] generally own +//! its file descriptor should usually close it in its `drop` function. Types like [`File`] generally own //! their file descriptor. Similarly, file descriptors can be *borrowed*. This indicates that the //! file descriptor will not be closed for the lifetime of the borrow, but it does *not* imply any //! right to close this file descriptor, since it will likely be owned by someone else. @@ -257,6 +257,12 @@ //! other words, a safe function that takes a regular integer, treats it as a file descriptor, and //! closes it, is *unsound*. //! +//! Not upholding I/O safety and closing a file descriptor without proof of ownership can lead to +//! misbehavior and even Undefined Behavior in code that relies on ownership of its file +//! descriptors: the closed file descriptor could be re-allocated to some other library (such as the +//! allocator or a memory mapping library) and now accessing the file descriptor will interfere in +//! arbitrarily destructive ways with that other library. +//! //! Note that this does not talk about performing other operations on the file descriptor, such as //! reading or writing. For example, on Unix, the [`OwnedFd`] and [`BorrowedFd`] types from the //! standard library do *not* exclude that there is other code that reads or writes the same diff --git a/library/std/src/os/unix/io/mod.rs b/library/std/src/os/unix/io/mod.rs index b3070a61b68..f49aebefd20 100644 --- a/library/std/src/os/unix/io/mod.rs +++ b/library/std/src/os/unix/io/mod.rs @@ -6,7 +6,7 @@ //! //! 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 realize the Unix version of [I/O safety]. +//! analogous to types used for representing pointers. These types reflect the Unix version of [I/O safety]. //! //! | Type | Analogous to | //! | ------------------ | ------------ | diff --git a/library/std/src/os/windows/io/mod.rs b/library/std/src/os/windows/io/mod.rs index 9c304b8e990..3d4bb96d458 100644 --- a/library/std/src/os/windows/io/mod.rs +++ b/library/std/src/os/windows/io/mod.rs @@ -6,7 +6,7 @@ //! //! 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 realize the Windows version of [I/O safety]. +//! analogous to types used for representing pointers. These types reflect the Windows version of [I/O safety]. //! //! | Type | Analogous to | //! | ---------------------- | ------------ |