]>
Commit | Line | Data |
---|---|---|
94222f64 XL |
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 | |
781aab86 FG |
9 | //! analogous to types used for representing pointers. These types reflect concepts of [I/O |
10 | //! safety][io-safety] on Unix. | |
94222f64 XL |
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 | |
781aab86 FG |
21 | //! Rust ecosystem often doesn't mark `RawFd` usage as unsafe. |
22 | //! Libraries are encouraged to migrate, | |
94222f64 XL |
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: | |
923072b8 | 30 | //! |
94222f64 XL |
31 | //! - `close`, because that would end the dynamic lifetime of the resource |
32 | //! without ending the lifetime of the file descriptor. | |
923072b8 | 33 | //! |
94222f64 XL |
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. | |
923072b8 FG |
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. | |
94222f64 XL |
54 | //! |
55 | //! Like boxes, `OwnedFd` values conceptually own the resource they point to, | |
56 | //! and free (close) it when they are dropped. | |
57 | //! | |
781aab86 FG |
58 | //! See the [`io` module docs][io-safety] for a general explanation of I/O safety. |
59 | //! | |
923072b8 FG |
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 | |
781aab86 FG |
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. | |
923072b8 FG |
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 | //! | |
94222f64 | 79 | //! [`BorrowedFd<'a>`]: crate::os::unix::io::BorrowedFd |
781aab86 | 80 | //! [io-safety]: crate::io#io-safety |
94222f64 XL |
81 | |
82 | #![stable(feature = "rust1", since = "1.0.0")] | |
83 | ||
94222f64 | 84 | #[stable(feature = "rust1", since = "1.0.0")] |
2b03887a FG |
85 | pub use crate::os::fd::*; |
86 | ||
87 | // Tests for this module | |
88 | #[cfg(test)] | |
89 | mod tests; |