kmc-solid: Document I/O safety in `std::os::solid::io`

Mostly copied from `std::os::unix::io`, except quantifying file
descriptors with SOLID Sockets and removing the paragraph mentioning
`mmap`.

1 files changed, 44 insertions, 0 deletions

diff --git a/library/std/src/os/solid/io.rs b/library/std/src/os/solid/io.rs
index ab17a01e411..6bddfc779fb 100644
--- a/library/std/src/os/solid/io.rs
+++ b/library/std/src/os/solid/io.rs
@@ -1,4 +1,48 @@
 //! SOLID-specific extensions to general I/O primitives
+//!
+//! Just like raw pointers, raw SOLID Sockets file descriptors point to
+//! resources with dynamic lifetimes, and they can dangle if they outlive their
+//! resources or be forged if they're created from invalid values.
+//!
+//! This module provides three types for representing raw file descriptors
+//! with different ownership properties: raw, borrowed, and owned, which are
+//! analogous to types used for representing pointers:
+//!
+//! | Type               | Analogous to |
+//! | ------------------ | ------------ |
+//! | [`RawFd`]          | `*const _`   |
+//! | [`BorrowedFd<'a>`] | `&'a _`      |
+//! | [`OwnedFd`]        | `Box<_>`     |
+//!
+//! 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,
+//! either by adding `unsafe` to APIs that dereference `RawFd` values, or by
+//! using to `BorrowedFd` or `OwnedFd` instead.
+//!
+//! Like references, `BorrowedFd` values are tied to a lifetime, to ensure
+//! that they don't outlive the resource they point to. These are safe to
+//! use. `BorrowedFd` values may be used in APIs which provide safe access to
+//! any system call except for:
+//!
+//!  - `close`, because that would end the dynamic lifetime of the resource
+//!    without ending the lifetime of the file descriptor.
+//!
+//!  - `dup2`/`dup3`, in the second argument, because this argument is
+//!    closed and assigned a new resource, which may break the assumptions
+//!    other code using that file descriptor.
+//!
+//! `BorrowedFd` values may be used in APIs which provide safe access to `dup`
+//! system calls, so types implementing `AsFd` or `From<OwnedFd>` should not
+//! assume they always have exclusive access to the underlying file
+//! description.
+//!
+//! Like boxes, `OwnedFd` values conceptually own the resource they point to,
+//! and free (close) it when they are dropped.
+//!
+//! [`BorrowedFd<'a>`]: crate::os::solid::io::BorrowedFd
 
 #![deny(unsafe_op_in_unsafe_fn)]
 #![unstable(feature = "solid_ext", issue = "none")]