1//! Unix-specific extensions to general I/O primitives.
2//!
3//! Just like raw pointers, raw file descriptors point to resources with
4//! dynamic lifetimes, and they can dangle if they outlive their resources
5//! or be forged if they're created from invalid values.
6//!
7//! This module provides three types for representing file descriptors,
8//! with different ownership properties: raw, borrowed, and owned, which are
9//! analogous to types used for representing pointers. These types reflect concepts of [I/O
10//! safety][io-safety] on Unix.
11//!
12//! | Type | Analogous to |
13//! | ------------------ | ------------ |
14//! | [`RawFd`] | `*const _` |
15//! | [`BorrowedFd<'a>`] | `&'a _` |
16//! | [`OwnedFd`] | `Box<_>` |
17//!
18//! Like raw pointers, `RawFd` values are primitive values. And in new code,
19//! they should be considered unsafe to do I/O on (analogous to dereferencing
20//! them). Rust did not always provide this guidance, so existing code in the
21//! Rust ecosystem often doesn't mark `RawFd` usage as unsafe.
22//! Libraries are encouraged to migrate,
23//! either by adding `unsafe` to APIs that dereference `RawFd` values, or by
24//! using to `BorrowedFd` or `OwnedFd` instead.
25//!
26//! Like references, `BorrowedFd` values are tied to a lifetime, to ensure
27//! that they don't outlive the resource they point to. These are safe to
28//! use. `BorrowedFd` values may be used in APIs which provide safe access to
29//! any system call except for:
30//!
31//! - `close`, because that would end the dynamic lifetime of the resource
32//! without ending the lifetime of the file descriptor.
33//!
34//! - `dup2`/`dup3`, in the second argument, because this argument is
35//! closed and assigned a new resource, which may break the assumptions
36//! other code using that file descriptor.
37//!
38//! `BorrowedFd` values may be used in APIs which provide safe access to `dup`
39//! system calls, so types implementing `AsFd` or `From<OwnedFd>` should not
40//! assume they always have exclusive access to the underlying file
41//! description.
42//!
43//! `BorrowedFd` values may also be used with `mmap`, since `mmap` uses the
44//! provided file descriptor in a manner similar to `dup` and does not require
45//! the `BorrowedFd` passed to it to live for the lifetime of the resulting
46//! mapping. That said, `mmap` is unsafe for other reasons: it operates on raw
47//! pointers, and it can have undefined behavior if the underlying storage is
48//! mutated. Mutations may come from other processes, or from the same process
49//! if the API provides `BorrowedFd` access, since as mentioned earlier,
50//! `BorrowedFd` values may be used in APIs which provide safe access to any
51//! system call. Consequently, code using `mmap` and presenting a safe API must
52//! take full responsibility for ensuring that safe Rust code cannot evoke
53//! undefined behavior through it.
54//!
55//! Like boxes, `OwnedFd` values conceptually own the resource they point to,
56//! and free (close) it when they are dropped.
57//!
58//! See the [`io` module docs][io-safety] for a general explanation of I/O safety.
59//!
60//! ## `/proc/self/mem` and similar OS features
61//!
62//! Some platforms have special files, such as `/proc/self/mem`, which
63//! provide read and write access to the process's memory. Such reads
64//! and writes happen outside the control of the Rust compiler, so they do not
65//! uphold Rust's memory safety guarantees.
66//!
67//! This does not mean that all APIs that might allow `/proc/self/mem`
68//! to be opened and read from or written must be `unsafe`. Rust's safety guarantees
69//! only cover what the program itself can do, and not what entities outside
70//! the program can do to it. `/proc/self/mem` is considered to be such an
71//! external entity, along with `/proc/self/fd/*`, debugging interfaces, and people with physical
72//! access to the hardware. This is true even in cases where the program is controlling the external
73//! entity.
74//!
75//! If you desire to comprehensively prevent programs from reaching out and
76//! causing external entities to reach back in and violate memory safety, it's
77//! necessary to use *sandboxing*, which is outside the scope of `std`.
78//!
79//! [`BorrowedFd<'a>`]: crate::os::unix::io::BorrowedFd
80//! [io-safety]: crate::io#io-safety
81
82#![stable(feature = "rust1", since = "1.0.0")]
83
84#[stable(feature = "rust1", since = "1.0.0")]
85pub use crate::os::fd::*;
86
87// Tests for this module
88#[cfg(test)]
89mod tests;
90