wording; and explain some of the possible consequences of violating io-safety

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 |
 //! | ---------------------- | ------------ |