std/os/fd/
raw.rs

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

std/os/fd/
raw.rs
