1 //! The following is derived from Rust's 2 //! library/std/src/os/fd/raw.rs at revision 3 //! fa68e73e9947be8ffc5b3b46d899e4953a44e7e9. 4 //! 5 //! Raw Unix-like file descriptors. 6 7 #![cfg_attr(staged_api, stable(feature = "rust1", since = "1.0.0"))] 8 #![allow(unsafe_code)] 9 10 use crate::backend::c; 11 12 /// Raw file descriptors. 13 #[cfg_attr(staged_api, stable(feature = "rust1", since = "1.0.0"))] 14 pub type RawFd = c::c_int; 15 16 /// A trait to extract the raw file descriptor from an underlying object. 17 /// 18 /// This is only available on unix and WASI platforms and must be imported in 19 /// order to call the method. Windows platforms have a corresponding 20 /// `AsRawHandle` and `AsRawSocket` set of traits. 21 #[cfg_attr(staged_api, stable(feature = "rust1", since = "1.0.0"))] 22 pub trait AsRawFd { 23 /// Extracts the raw file descriptor. 24 /// 25 /// This function is typically used to **borrow** an owned file descriptor. 26 /// When used in this way, this method does **not** pass ownership of the 27 /// raw file descriptor to the caller, and the file descriptor is only 28 /// guaranteed to be valid while the original object has not yet been 29 /// destroyed. 30 /// 31 /// However, borrowing is not strictly required. See [`AsFd::as_fd`] 32 /// for an API which strictly borrows a file descriptor. 33 /// 34 /// # Example 35 /// 36 /// ```no_run 37 /// use std::fs::File; 38 /// # use std::io; 39 /// #[cfg(unix)] 40 /// use std::os::unix::io::{AsRawFd, RawFd}; 41 /// #[cfg(target_os = "wasi")] 42 /// use std::os::wasi::io::{AsRawFd, RawFd}; 43 /// 44 /// let mut f = File::open("foo.txt")?; 45 /// // `raw_fd` is only valid as long as `f` exists. 46 /// #[cfg(any(unix, target_os = "wasi"))] 47 /// let raw_fd: RawFd = f.as_raw_fd(); 48 /// # Ok::<(), io::Error>(()) 49 /// ``` 50 #[cfg_attr(staged_api, stable(feature = "rust1", since = "1.0.0"))] as_raw_fd(&self) -> RawFd51 fn as_raw_fd(&self) -> RawFd; 52 } 53 54 /// A trait to express the ability to construct an object from a raw file 55 /// descriptor. 56 #[cfg_attr(staged_api, stable(feature = "from_raw_os", since = "1.1.0"))] 57 pub trait FromRawFd { 58 /// Constructs a new instance of `Self` from the given raw file 59 /// descriptor. 60 /// 61 /// This function is typically used to **consume ownership** of the 62 /// specified file descriptor. When used in this way, the returned object 63 /// will take responsibility for closing it when the object goes out of 64 /// scope. 65 /// 66 /// However, consuming ownership is not strictly required. Use a 67 /// [`From<OwnedFd>::from`] implementation for an API which strictly 68 /// consumes ownership. 69 /// 70 /// # Safety 71 /// 72 /// The `fd` passed in must be a valid an open file descriptor. 73 /// 74 /// # Example 75 /// 76 /// ```no_run 77 /// use std::fs::File; 78 /// # use std::io; 79 /// #[cfg(unix)] 80 /// use std::os::unix::io::{FromRawFd, IntoRawFd, RawFd}; 81 /// #[cfg(target_os = "wasi")] 82 /// use std::os::wasi::io::{FromRawFd, IntoRawFd, RawFd}; 83 /// 84 /// let f = File::open("foo.txt")?; 85 /// # #[cfg(any(unix, target_os = "wasi"))] 86 /// let raw_fd: RawFd = f.into_raw_fd(); 87 /// // SAFETY: no other functions should call `from_raw_fd`, so there 88 /// // is only one owner for the file descriptor. 89 /// # #[cfg(any(unix, target_os = "wasi"))] 90 /// let f = unsafe { File::from_raw_fd(raw_fd) }; 91 /// # Ok::<(), io::Error>(()) 92 /// ``` 93 #[cfg_attr(staged_api, stable(feature = "from_raw_os", since = "1.1.0"))] from_raw_fd(fd: RawFd) -> Self94 unsafe fn from_raw_fd(fd: RawFd) -> Self; 95 } 96 97 /// A trait to express the ability to consume an object and acquire ownership of 98 /// its raw file descriptor. 99 #[cfg_attr(staged_api, stable(feature = "into_raw_os", since = "1.4.0"))] 100 pub trait IntoRawFd { 101 /// Consumes this object, returning the raw underlying file descriptor. 102 /// 103 /// This function is typically used to **transfer ownership** of the underlying 104 /// file descriptor to the caller. When used in this way, callers are then the unique 105 /// owners of the file descriptor and must close it once it's no longer needed. 106 /// 107 /// However, transferring ownership is not strictly required. Use a 108 /// [`Into<OwnedFd>::into`] implementation for an API which strictly 109 /// transfers ownership. 110 /// 111 /// # Example 112 /// 113 /// ```no_run 114 /// use std::fs::File; 115 /// # use std::io; 116 /// #[cfg(unix)] 117 /// use std::os::unix::io::{IntoRawFd, RawFd}; 118 /// #[cfg(target_os = "wasi")] 119 /// use std::os::wasi::io::{IntoRawFd, RawFd}; 120 /// 121 /// let f = File::open("foo.txt")?; 122 /// #[cfg(any(unix, target_os = "wasi"))] 123 /// let raw_fd: RawFd = f.into_raw_fd(); 124 /// # Ok::<(), io::Error>(()) 125 /// ``` 126 #[cfg_attr(staged_api, stable(feature = "into_raw_os", since = "1.4.0"))] into_raw_fd(self) -> RawFd127 fn into_raw_fd(self) -> RawFd; 128 } 129 130 #[cfg_attr( 131 staged_api, 132 stable(feature = "raw_fd_reflexive_traits", since = "1.48.0") 133 )] 134 impl AsRawFd for RawFd { 135 #[inline] as_raw_fd(&self) -> RawFd136 fn as_raw_fd(&self) -> RawFd { 137 *self 138 } 139 } 140 #[cfg_attr( 141 staged_api, 142 stable(feature = "raw_fd_reflexive_traits", since = "1.48.0") 143 )] 144 impl IntoRawFd for RawFd { 145 #[inline] into_raw_fd(self) -> RawFd146 fn into_raw_fd(self) -> RawFd { 147 self 148 } 149 } 150 #[cfg_attr( 151 staged_api, 152 stable(feature = "raw_fd_reflexive_traits", since = "1.48.0") 153 )] 154 impl FromRawFd for RawFd { 155 #[inline] from_raw_fd(fd: RawFd) -> RawFd156 unsafe fn from_raw_fd(fd: RawFd) -> RawFd { 157 fd 158 } 159 } 160