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