1 //! Raw Unix-like file descriptors.
3 #![stable(feature = "rust1", since = "1.0.0")]
8 #[cfg(all(doc, not(target_arch = "wasm32")))]
9 use crate::os::unix::io::AsFd;
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};
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;
21 /// A trait to extract the raw file descriptor from an underlying object.
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")]
29 /// Extracts the raw file descriptor.
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
37 /// However, borrowing is not strictly required. See [`AsFd::as_fd`]
38 /// for an API which strictly borrows a file descriptor.
43 /// use std::fs::File;
45 /// #[cfg(any(unix, target_os = "wasi"))]
46 /// use std::os::fd::{AsRawFd, RawFd};
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>(())
54 #[stable(feature = "rust1", since = "1.0.0")]
55 fn as_raw_fd(&self) -> RawFd;
58 /// A trait to express the ability to construct an object from a raw file
60 #[rustc_allowed_through_unstable_modules]
61 #[stable(feature = "from_raw_os", since = "1.1.0")]
63 /// Constructs a new instance of `Self` from the given raw file
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
71 /// However, consuming ownership is not strictly required. Use a
72 /// [`From<OwnedFd>::from`] implementation for an API which strictly
73 /// consumes ownership.
77 /// The `fd` passed in must be a valid and open file descriptor.
82 /// use std::fs::File;
84 /// #[cfg(any(unix, target_os = "wasi"))]
85 /// use std::os::fd::{FromRawFd, IntoRawFd, RawFd};
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>(())
96 #[stable(feature = "from_raw_os", since = "1.1.0")]
97 unsafe fn from_raw_fd(fd: RawFd) -> Self;
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.
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.
111 /// However, transferring ownership is not strictly required. Use a
112 /// [`Into<OwnedFd>::into`] implementation for an API which strictly
113 /// transfers ownership.
118 /// use std::fs::File;
120 /// #[cfg(any(unix, target_os = "wasi"))]
121 /// use std::os::fd::{IntoRawFd, RawFd};
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>(())
128 #[stable(feature = "into_raw_os", since = "1.4.0")]
129 fn into_raw_fd(self) -> RawFd;
132 #[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")]
133 impl AsRawFd for RawFd {
135 fn as_raw_fd(&self) -> RawFd {
139 #[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")]
140 impl IntoRawFd for RawFd {
142 fn into_raw_fd(self) -> RawFd {
146 #[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")]
147 impl FromRawFd for RawFd {
149 unsafe fn from_raw_fd(fd: RawFd) -> RawFd {
154 #[stable(feature = "rust1", since = "1.0.0")]
155 impl AsRawFd for fs::File {
157 fn as_raw_fd(&self) -> RawFd {
158 self.as_inner().as_raw_fd()
161 #[stable(feature = "from_raw_os", since = "1.1.0")]
162 impl FromRawFd for fs::File {
164 unsafe fn from_raw_fd(fd: RawFd) -> fs::File {
165 unsafe { fs::File::from(OwnedFd::from_raw_fd(fd)) }
168 #[stable(feature = "into_raw_os", since = "1.4.0")]
169 impl IntoRawFd for fs::File {
171 fn into_raw_fd(self) -> RawFd {
172 self.into_inner().into_inner().into_raw_fd()
176 #[stable(feature = "asraw_stdio", since = "1.21.0")]
177 impl AsRawFd for io::Stdin {
179 fn as_raw_fd(&self) -> RawFd {
184 #[stable(feature = "asraw_stdio", since = "1.21.0")]
185 impl AsRawFd for io::Stdout {
187 fn as_raw_fd(&self) -> RawFd {
192 #[stable(feature = "asraw_stdio", since = "1.21.0")]
193 impl AsRawFd for io::Stderr {
195 fn as_raw_fd(&self) -> RawFd {
200 #[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
201 impl<'a> AsRawFd for io::StdinLock<'a> {
203 fn as_raw_fd(&self) -> RawFd {
208 #[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
209 impl<'a> AsRawFd for io::StdoutLock<'a> {
211 fn as_raw_fd(&self) -> RawFd {
216 #[stable(feature = "asraw_stdio_locks", since = "1.35.0")]
217 impl<'a> AsRawFd for io::StderrLock<'a> {
219 fn as_raw_fd(&self) -> RawFd {
224 /// This impl allows implementing traits that require `AsRawFd` on Arc.
226 /// # #[cfg(any(unix, target_os = "wasi"))] mod group_cfg {
227 /// # #[cfg(target_os = "wasi")]
228 /// # use std::os::wasi::io::AsRawFd;
230 /// # use std::os::unix::io::AsRawFd;
231 /// use std::net::UdpSocket;
232 /// use std::sync::Arc;
233 /// trait MyTrait: AsRawFd {
235 /// impl MyTrait for Arc<UdpSocket> {}
236 /// impl MyTrait for Box<UdpSocket> {}
239 #[stable(feature = "asrawfd_ptrs", since = "1.63.0")]
240 impl<T: AsRawFd> AsRawFd for crate::sync::Arc<T> {
242 fn as_raw_fd(&self) -> RawFd {
247 #[stable(feature = "asrawfd_ptrs", since = "1.63.0")]
248 impl<T: AsRawFd> AsRawFd for Box<T> {
250 fn as_raw_fd(&self) -> RawFd {