library/std/src/os/fd/raw.rs

   1 //! Raw Unix-like file descriptors.
   2
   3 #![stable(feature = "rust1", since = "1.0.0")]
   4
   5 use crate::fs;
   6 use crate::io;
   7 use crate::os::raw;
   8 #[cfg(all(doc, not(target_arch = "wasm32")))]
   9 use crate::os::unix::io::AsFd;
  10 #[cfg(unix)]
  11 use crate::os::unix::io::OwnedFd;
  12 #[cfg(target_os = "wasi")]
  13 use crate::os::wasi::io::OwnedFd;
  14 use crate::sys_common::{AsInner, IntoInner};
  15
  16 /// Raw file descriptors.
  17 #[rustc_allowed_through_unstable_modules]
  18 #[stable(feature = "rust1", since = "1.0.0")]
  19 pub type RawFd = raw::c_int;
  20
  21 /// A trait to extract the raw file descriptor from an underlying object.
  22 ///
  23 /// This is only available on unix and WASI platforms and must be imported in
  24 /// order to call the method. Windows platforms have a corresponding
  25 /// `AsRawHandle` and `AsRawSocket` set of traits.
  26 #[rustc_allowed_through_unstable_modules]
  27 #[stable(feature = "rust1", since = "1.0.0")]
  28 pub trait AsRawFd {
  29     /// Extracts the raw file descriptor.
  30     ///
  31     /// This function is typically used to **borrow** an owned file descriptor.
  32     /// When used in this way, this method does **not** pass ownership of the
  33     /// raw file descriptor to the caller, and the file descriptor is only
  34     /// guaranteed to be valid while the original object has not yet been
  35     /// destroyed.
  36     ///
  37     /// However, borrowing is not strictly required. See [`AsFd::as_fd`]
  38     /// for an API which strictly borrows a file descriptor.
  39     ///
  40     /// # Example
  41     ///
  42     /// ```no_run
  43     /// use std::fs::File;
  44     /// # use std::io;
  45     /// #[cfg(any(unix, target_os = "wasi"))]
  46     /// use std::os::fd::{AsRawFd, RawFd};
  47     ///
  48     /// let mut f = File::open("foo.txt")?;
  49     /// // Note that `raw_fd` is only valid as long as `f` exists.
  50     /// #[cfg(any(unix, target_os = "wasi"))]
  51     /// let raw_fd: RawFd = f.as_raw_fd();
  52     /// # Ok::<(), io::Error>(())
  53     /// ```
  54     #[stable(feature = "rust1", since = "1.0.0")]
  55     fn as_raw_fd(&self) -> RawFd;
  56 }
  57
  58 /// A trait to express the ability to construct an object from a raw file
  59 /// descriptor.
  60 #[rustc_allowed_through_unstable_modules]
  61 #[stable(feature = "from_raw_os", since = "1.1.0")]
  62 pub trait FromRawFd {
  63     /// Constructs a new instance of `Self` from the given raw file
  64     /// descriptor.
  65     ///
  66     /// This function is typically used to **consume ownership** of the
  67     /// specified file descriptor. When used in this way, the returned object
  68     /// will take responsibility for closing it when the object goes out of
  69     /// scope.
  70     ///
  71     /// However, consuming ownership is not strictly required. Use a
  72     /// [`From<OwnedFd>::from`] implementation for an API which strictly
  73     /// consumes ownership.
  74     ///
  75     /// # Safety
  76     ///
  77     /// The `fd` passed in must be a valid and open file descriptor.
  78     ///
  79     /// # Example
  80     ///
  81     /// ```no_run
  82     /// use std::fs::File;
  83     /// # use std::io;
  84     /// #[cfg(any(unix, target_os = "wasi"))]
  85     /// use std::os::fd::{FromRawFd, IntoRawFd, RawFd};
  86     ///
  87     /// let f = File::open("foo.txt")?;
  88     /// # #[cfg(any(unix, target_os = "wasi"))]
  89     /// let raw_fd: RawFd = f.into_raw_fd();
  90     /// // SAFETY: no other functions should call `from_raw_fd`, so there
  91     /// // is only one owner for the file descriptor.
  92     /// # #[cfg(any(unix, target_os = "wasi"))]
  93     /// let f = unsafe { File::from_raw_fd(raw_fd) };
  94     /// # Ok::<(), io::Error>(())
  95     /// ```
  96     #[stable(feature = "from_raw_os", since = "1.1.0")]
  97     unsafe fn from_raw_fd(fd: RawFd) -> Self;
  98 }
  99
 100 /// A trait to express the ability to consume an object and acquire ownership of
 101 /// its raw file descriptor.
 102 #[rustc_allowed_through_unstable_modules]
 103 #[stable(feature = "into_raw_os", since = "1.4.0")]
 104 pub trait IntoRawFd {
 105     /// Consumes this object, returning the raw underlying file descriptor.
 106     ///
 107     /// This function is typically used to **transfer ownership** of the underlying
 108     /// file descriptor to the caller. When used in this way, callers are then the unique
 109     /// owners of the file descriptor and must close it once it's no longer needed.
 110     ///
 111     /// However, transferring ownership is not strictly required. Use a
 112     /// [`Into<OwnedFd>::into`] implementation for an API which strictly
 113     /// transfers ownership.
 114     ///
 115     /// # Example
 116     ///
 117     /// ```no_run
 118     /// use std::fs::File;
 119     /// # use std::io;
 120     /// #[cfg(any(unix, target_os = "wasi"))]
 121     /// use std::os::fd::{IntoRawFd, RawFd};
 122     ///
 123     /// let f = File::open("foo.txt")?;
 124     /// #[cfg(any(unix, target_os = "wasi"))]
 125     /// let raw_fd: RawFd = f.into_raw_fd();
 126     /// # Ok::<(), io::Error>(())
 127     /// ```
 128     #[stable(feature = "into_raw_os", since = "1.4.0")]
 129     fn into_raw_fd(self) -> RawFd;
 130 }
 131
 132 #[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")]
 133 impl AsRawFd for RawFd {
 134     #[inline]
 135     fn as_raw_fd(&self) -> RawFd {
 136         *self
 137     }
 138 }
 139 #[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")]
 140 impl IntoRawFd for RawFd {
 141     #[inline]
 142     fn into_raw_fd(self) -> RawFd {
 143         self
 144     }
 145 }
 146 #[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")]
 147 impl FromRawFd for RawFd {
 148     #[inline]
 149     unsafe fn from_raw_fd(fd: RawFd) -> RawFd {
 150         fd
 151     }
 152 }
 153
 154 #[stable(feature = "rust1", since = "1.0.0")]
 155 impl AsRawFd for fs::File {
 156     #[inline]
 157     fn as_raw_fd(&self) -> RawFd {
 158         self.as_inner().as_raw_fd()
 159     }
 160 }
 161 #[stable(feature = "from_raw_os", since = "1.1.0")]
 162 impl FromRawFd for fs::File {
 163     #[inline]
 164     unsafe fn from_raw_fd(fd: RawFd) -> fs::File {
 165         unsafe { fs::File::from(OwnedFd::from_raw_fd(fd)) }
 166     }
 167 }
 168 #[stable(feature = "into_raw_os", since = "1.4.0")]
 169 impl IntoRawFd for fs::File {
 170     #[inline]
 171     fn into_raw_fd(self) -> RawFd {
 172         self.into_inner().into_inner().into_raw_fd()
 173     }
 174 }
 175
 176 #[stable(feature = "asraw_stdio", since = "1.21.0")]
 177 impl AsRawFd for io::Stdin {
 178     #[inline]
 179     fn as_raw_fd(&self) -> RawFd {
 180         libc::STDIN_FILENO
 181     }
 182 }
 183
 184 #[stable(feature = "asraw_stdio", since = "1.21.0")]
 185 impl AsRawFd for io::Stdout {
 186     #[inline]
 187     fn as_raw_fd(&self) -> RawFd {
 188         libc::STDOUT_FILENO
 189     }
 190 }
 191
 192 #[stable(feature = "asraw_stdio", since = "1.21.0")]
 193 impl AsRawFd for io::Stderr {
 194     #[inline]
 195     fn as_raw_fd(&self) -> RawFd {
 196         libc::STDERR_FILENO
 197     }
 198 }
 199
 200 #[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
 201 impl<'a> AsRawFd for io::StdinLock<'a> {
 202     #[inline]
 203     fn as_raw_fd(&self) -> RawFd {
 204         libc::STDIN_FILENO
 205     }
 206 }
 207
 208 #[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
 209 impl<'a> AsRawFd for io::StdoutLock<'a> {
 210     #[inline]
 211     fn as_raw_fd(&self) -> RawFd {
 212         libc::STDOUT_FILENO
 213     }
 214 }
 215
 216 #[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
 217 impl<'a> AsRawFd for io::StderrLock<'a> {
 218     #[inline]
 219     fn as_raw_fd(&self) -> RawFd {
 220         libc::STDERR_FILENO
 221     }
 222 }
 223
 224 /// This impl allows implementing traits that require `AsRawFd` on Arc.
 225 /// ```
 226 /// # #[cfg(any(unix, target_os = "wasi"))] mod group_cfg {
 227 /// # #[cfg(target_os = "wasi")]
 228 /// # use std::os::wasi::io::AsRawFd;
 229 /// # #[cfg(unix)]
 230 /// # use std::os::unix::io::AsRawFd;
 231 /// use std::net::UdpSocket;
 232 /// use std::sync::Arc;
 233 /// trait MyTrait: AsRawFd {
 234 /// }
 235 /// impl MyTrait for Arc<UdpSocket> {}
 236 /// impl MyTrait for Box<UdpSocket> {}
 237 /// # }
 238 /// ```
 239 #[stable(feature = "asrawfd_ptrs", since = "1.63.0")]
 240 impl<T: AsRawFd> AsRawFd for crate::sync::Arc<T> {
 241     #[inline]
 242     fn as_raw_fd(&self) -> RawFd {
 243         (**self).as_raw_fd()
 244     }
 245 }
 246
 247 #[stable(feature = "asrawfd_ptrs", since = "1.63.0")]
 248 impl<T: AsRawFd> AsRawFd for Box<T> {
 249     #[inline]
 250     fn as_raw_fd(&self) -> RawFd {
 251         (**self).as_raw_fd()
 252     }
 253 }