1 //! Unix-specific I/O extensions.
2 
3 cfg_not_docs! {
4     pub use std::os::unix::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd};
5 }
6 
7 cfg_docs! {
8     /// Raw file descriptors.
9     pub type RawFd = std::os::raw::c_int;
10 
11     /// A trait to extract the raw unix file descriptor from an underlying
12     /// object.
13     ///
14     /// This is only available on unix platforms and must be imported in order
15     /// to call the method. Windows platforms have a corresponding `AsRawHandle`
16     /// and `AsRawSocket` set of traits.
17     pub trait AsRawFd {
18         /// Extracts the raw file descriptor.
19         ///
20         /// This method does **not** pass ownership of the raw file descriptor
21         /// to the caller. The descriptor is only guaranteed to be valid while
22         /// the original object has not yet been destroyed.
23         fn as_raw_fd(&self) -> RawFd;
24     }
25 
26     /// A trait to express the ability to construct an object from a raw file
27     /// descriptor.
28     pub trait FromRawFd {
29         /// Constructs a new instance of `Self` from the given raw file
30         /// descriptor.
31         ///
32         /// This function **consumes ownership** of the specified file
33         /// descriptor. The returned object will take responsibility for closing
34         /// it when the object goes out of scope.
35         ///
36         /// This function is also unsafe as the primitives currently returned
37         /// have the contract that they are the sole owner of the file
38         /// descriptor they are wrapping. Usage of this function could
39         /// accidentally allow violating this contract which can cause memory
40         /// unsafety in code that relies on it being true.
41         unsafe fn from_raw_fd(fd: RawFd) -> Self;
42     }
43 
44     /// A trait to express the ability to consume an object and acquire ownership of
45     /// its raw file descriptor.
46     pub trait IntoRawFd {
47         /// Consumes this object, returning the raw underlying file descriptor.
48         ///
49         /// This function **transfers ownership** of the underlying file descriptor
50         /// to the caller. Callers are then the unique owners of the file descriptor
51         /// and must close the descriptor once it's no longer needed.
52         fn into_raw_fd(self) -> RawFd;
53     }
54 }
55