library/std/src/os/windows/io/handle.rs

   1 //! Owned and borrowed OS handles.
   2
   3 #![unstable(feature = "io_safety", issue = "87074")]
   4
   5 use super::raw::{AsRawHandle, FromRawHandle, IntoRawHandle, RawHandle};
   6 use crate::convert::TryFrom;
   7 use crate::fmt;
   8 use crate::fs;
   9 use crate::io;
  10 use crate::marker::PhantomData;
  11 use crate::mem::forget;
  12 use crate::sys::c;
  13 use crate::sys::cvt;
  14 use crate::sys_common::{AsInner, FromInner, IntoInner};
  15
  16 /// A borrowed handle.
  17 ///
  18 /// This has a lifetime parameter to tie it to the lifetime of something that
  19 /// owns the handle.
  20 ///
  21 /// This uses `repr(transparent)` and has the representation of a host handle,
  22 /// so it can be used in FFI in places where a handle is passed as an argument,
  23 /// it is not captured or consumed.
  24 ///
  25 /// Note that it *may* have the value `INVALID_HANDLE_VALUE` (-1), which is
  26 /// sometimes a valid handle value. See [here] for the full story.
  27 ///
  28 /// And, it *may* have the value `NULL` (0), which can occur when consoles are
  29 /// detached from processes, or when `windows_subsystem` is used.
  30 ///
  31 /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
  32 #[derive(Copy, Clone)]
  33 #[repr(transparent)]
  34 #[unstable(feature = "io_safety", issue = "87074")]
  35 pub struct BorrowedHandle<'handle> {
  36     handle: RawHandle,
  37     _phantom: PhantomData<&'handle OwnedHandle>,
  38 }
  39
  40 /// An owned handle.
  41 ///
  42 /// This closes the handle on drop.
  43 ///
  44 /// Note that it *may* have the value `INVALID_HANDLE_VALUE` (-1), which is
  45 /// sometimes a valid handle value. See [here] for the full story.
  46 ///
  47 /// And, it *may* have the value `NULL` (0), which can occur when consoles are
  48 /// detached from processes, or when `windows_subsystem` is used.
  49 ///
  50 /// `OwnedHandle` uses [`CloseHandle`] to close its handle on drop. As such,
  51 /// it must not be used with handles to open registry keys which need to be
  52 /// closed with [`RegCloseKey`] instead.
  53 ///
  54 /// [`CloseHandle`]: https://docs.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle
  55 /// [`RegCloseKey`]: https://docs.microsoft.com/en-us/windows/win32/api/winreg/nf-winreg-regclosekey
  56 ///
  57 /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
  58 #[unstable(feature = "io_safety", issue = "87074")]
  59 pub struct OwnedHandle {
  60     handle: RawHandle,
  61 }
  62
  63 /// FFI type for handles in return values or out parameters, where `NULL` is used
  64 /// as a sentry value to indicate errors, such as in the return value of `CreateThread`. This uses
  65 /// `repr(transparent)` and has the representation of a host handle, so that it can be used in such
  66 /// FFI declarations.
  67 ///
  68 /// The only thing you can usefully do with a `HandleOrNull` is to convert it into an
  69 /// `OwnedHandle` using its [`TryFrom`] implementation; this conversion takes care of the check for
  70 /// `NULL`. This ensures that such FFI calls cannot start using the handle without
  71 /// checking for `NULL` first.
  72 ///
  73 /// This type concerns any value other than `NULL` to be valid, including `INVALID_HANDLE_VALUE`.
  74 /// This is because APIs that use `NULL` as their sentry value don't treat `INVALID_HANDLE_VALUE`
  75 /// as special.
  76 ///
  77 /// If this holds a valid handle, it will close the handle on drop.
  78 #[repr(transparent)]
  79 #[unstable(feature = "io_safety", issue = "87074")]
  80 #[derive(Debug)]
  81 pub struct HandleOrNull(OwnedHandle);
  82
  83 /// FFI type for handles in return values or out parameters, where `INVALID_HANDLE_VALUE` is used
  84 /// as a sentry value to indicate errors, such as in the return value of `CreateFileW`. This uses
  85 /// `repr(transparent)` and has the representation of a host handle, so that it can be used in such
  86 /// FFI declarations.
  87 ///
  88 /// The only thing you can usefully do with a `HandleOrInvalid` is to convert it into an
  89 /// `OwnedHandle` using its [`TryFrom`] implementation; this conversion takes care of the check for
  90 /// `INVALID_HANDLE_VALUE`. This ensures that such FFI calls cannot start using the handle without
  91 /// checking for `INVALID_HANDLE_VALUE` first.
  92 ///
  93 /// This type concerns any value other than `INVALID_HANDLE_VALUE` to be valid, including `NULL`.
  94 /// This is because APIs that use `INVALID_HANDLE_VALUE` as their sentry value may return `NULL`
  95 /// under `windows_subsystem = "windows"` or other situations where I/O devices are detached.
  96 ///
  97 /// If this holds a valid handle, it will close the handle on drop.
  98 #[repr(transparent)]
  99 #[unstable(feature = "io_safety", issue = "87074")]
 100 #[derive(Debug)]
 101 pub struct HandleOrInvalid(OwnedHandle);
 102
 103 // The Windows [`HANDLE`] type may be transferred across and shared between
 104 // thread boundaries (despite containing a `*mut void`, which in general isn't
 105 // `Send` or `Sync`).
 106 //
 107 // [`HANDLE`]: std::os::windows::raw::HANDLE
 108 unsafe impl Send for OwnedHandle {}
 109 unsafe impl Send for HandleOrNull {}
 110 unsafe impl Send for HandleOrInvalid {}
 111 unsafe impl Send for BorrowedHandle<'_> {}
 112 unsafe impl Sync for OwnedHandle {}
 113 unsafe impl Sync for HandleOrNull {}
 114 unsafe impl Sync for HandleOrInvalid {}
 115 unsafe impl Sync for BorrowedHandle<'_> {}
 116
 117 impl BorrowedHandle<'_> {
 118     /// Return a `BorrowedHandle` holding the given raw handle.
 119     ///
 120     /// # Safety
 121     ///
 122     /// The resource pointed to by `handle` must be a valid open handle, it
 123     /// must remain open for the duration of the returned `BorrowedHandle`.
 124     ///
 125     /// Note that it *may* have the value `INVALID_HANDLE_VALUE` (-1), which is
 126     /// sometimes a valid handle value. See [here] for the full story.
 127     ///
 128     /// And, it *may* have the value `NULL` (0), which can occur when consoles are
 129     /// detached from processes, or when `windows_subsystem` is used.
 130     ///
 131     /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
 132     #[inline]
 133     #[unstable(feature = "io_safety", issue = "87074")]
 134     pub unsafe fn borrow_raw_handle(handle: RawHandle) -> Self {
 135         Self { handle, _phantom: PhantomData }
 136     }
 137 }
 138
 139 impl TryFrom<HandleOrNull> for OwnedHandle {
 140     type Error = ();
 141
 142     #[inline]
 143     fn try_from(handle_or_null: HandleOrNull) -> Result<Self, ()> {
 144         let owned_handle = handle_or_null.0;
 145         if owned_handle.handle.is_null() { Err(()) } else { Ok(owned_handle) }
 146     }
 147 }
 148
 149 impl OwnedHandle {
 150     /// Creates a new `OwnedHandle` instance that shares the same underlying file handle
 151     /// as the existing `OwnedHandle` instance.
 152     pub fn try_clone(&self) -> crate::io::Result<Self> {
 153         self.duplicate(0, false, c::DUPLICATE_SAME_ACCESS)
 154     }
 155
 156     pub(crate) fn duplicate(
 157         &self,
 158         access: c::DWORD,
 159         inherit: bool,
 160         options: c::DWORD,
 161     ) -> io::Result<Self> {
 162         let mut ret = 0 as c::HANDLE;
 163         cvt(unsafe {
 164             let cur_proc = c::GetCurrentProcess();
 165             c::DuplicateHandle(
 166                 cur_proc,
 167                 self.as_raw_handle(),
 168                 cur_proc,
 169                 &mut ret,
 170                 access,
 171                 inherit as c::BOOL,
 172                 options,
 173             )
 174         })?;
 175         unsafe { Ok(Self::from_raw_handle(ret)) }
 176     }
 177 }
 178
 179 impl TryFrom<HandleOrInvalid> for OwnedHandle {
 180     type Error = ();
 181
 182     #[inline]
 183     fn try_from(handle_or_invalid: HandleOrInvalid) -> Result<Self, ()> {
 184         let owned_handle = handle_or_invalid.0;
 185         if owned_handle.handle == c::INVALID_HANDLE_VALUE { Err(()) } else { Ok(owned_handle) }
 186     }
 187 }
 188
 189 impl AsRawHandle for BorrowedHandle<'_> {
 190     #[inline]
 191     fn as_raw_handle(&self) -> RawHandle {
 192         self.handle
 193     }
 194 }
 195
 196 impl AsRawHandle for OwnedHandle {
 197     #[inline]
 198     fn as_raw_handle(&self) -> RawHandle {
 199         self.handle
 200     }
 201 }
 202
 203 impl IntoRawHandle for OwnedHandle {
 204     #[inline]
 205     fn into_raw_handle(self) -> RawHandle {
 206         let handle = self.handle;
 207         forget(self);
 208         handle
 209     }
 210 }
 211
 212 impl FromRawHandle for OwnedHandle {
 213     /// Constructs a new instance of `Self` from the given raw handle.
 214     ///
 215     /// # Safety
 216     ///
 217     /// The resource pointed to by `handle` must be open and suitable for
 218     /// assuming ownership. The resource must not require any cleanup other
 219     /// than `CloseHandle`.
 220     ///
 221     /// In particular, it must not be used with handles to open registry
 222     /// keys which need to be closed with [`RegCloseKey`] instead.
 223     ///
 224     /// Note that it *may* have the value `INVALID_HANDLE_VALUE` (-1), which is
 225     /// sometimes a valid handle value. See [here] for the full story.
 226     ///
 227     /// [`RegCloseKey`]: https://docs.microsoft.com/en-us/windows/win32/api/winreg/nf-winreg-regclosekey
 228     /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
 229     #[inline]
 230     unsafe fn from_raw_handle(handle: RawHandle) -> Self {
 231         Self { handle }
 232     }
 233 }
 234
 235 impl FromRawHandle for HandleOrNull {
 236     /// Constructs a new instance of `Self` from the given `RawHandle` returned
 237     /// from a Windows API that uses null to indicate failure, such as
 238     /// `CreateThread`.
 239     ///
 240     /// Use `HandleOrInvalid` instead of `HandleOrNull` for APIs that
 241     /// use `INVALID_HANDLE_VALUE` to indicate failure.
 242     ///
 243     /// # Safety
 244     ///
 245     /// The resource pointed to by `handle` must be either open and otherwise
 246     /// unowned, or null. Note that not all Windows APIs use null for errors;
 247     /// see [here] for the full story.
 248     ///
 249     /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
 250     #[inline]
 251     unsafe fn from_raw_handle(handle: RawHandle) -> Self {
 252         Self(OwnedHandle::from_raw_handle(handle))
 253     }
 254 }
 255
 256 impl FromRawHandle for HandleOrInvalid {
 257     /// Constructs a new instance of `Self` from the given `RawHandle` returned
 258     /// from a Windows API that uses `INVALID_HANDLE_VALUE` to indicate
 259     /// failure, such as `CreateFileW`.
 260     ///
 261     /// Use `HandleOrNull` instead of `HandleOrInvalid` for APIs that
 262     /// use null to indicate failure.
 263     ///
 264     /// # Safety
 265     ///
 266     /// The resource pointed to by `handle` must be either open and otherwise
 267     /// unowned, null, or equal to `INVALID_HANDLE_VALUE` (-1). Note that not
 268     /// all Windows APIs use `INVALID_HANDLE_VALUE` for errors; see [here] for
 269     /// the full story.
 270     ///
 271     /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443
 272     #[inline]
 273     unsafe fn from_raw_handle(handle: RawHandle) -> Self {
 274         Self(OwnedHandle::from_raw_handle(handle))
 275     }
 276 }
 277
 278 impl Drop for OwnedHandle {
 279     #[inline]
 280     fn drop(&mut self) {
 281         unsafe {
 282             let _ = c::CloseHandle(self.handle);
 283         }
 284     }
 285 }
 286
 287 impl fmt::Debug for BorrowedHandle<'_> {
 288     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 289         f.debug_struct("BorrowedHandle").field("handle", &self.handle).finish()
 290     }
 291 }
 292
 293 impl fmt::Debug for OwnedHandle {
 294     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 295         f.debug_struct("OwnedHandle").field("handle", &self.handle).finish()
 296     }
 297 }
 298
 299 /// A trait to borrow the handle from an underlying object.
 300 #[unstable(feature = "io_safety", issue = "87074")]
 301 pub trait AsHandle {
 302     /// Borrows the handle.
 303     ///
 304     /// # Example
 305     ///
 306     /// ```rust,no_run
 307     /// # #![feature(io_safety)]
 308     /// use std::fs::File;
 309     /// # use std::io;
 310     /// use std::os::windows::io::{AsHandle, BorrowedHandle};
 311     ///
 312     /// let mut f = File::open("foo.txt")?;
 313     /// let borrowed_handle: BorrowedHandle<'_> = f.as_handle();
 314     /// # Ok::<(), io::Error>(())
 315     /// ```
 316     fn as_handle(&self) -> BorrowedHandle<'_>;
 317 }
 318
 319 #[unstable(feature = "io_safety", issue = "87074")]
 320 impl<T: AsHandle> AsHandle for &T {
 321     #[inline]
 322     fn as_handle(&self) -> BorrowedHandle<'_> {
 323         T::as_handle(self)
 324     }
 325 }
 326
 327 #[unstable(feature = "io_safety", issue = "87074")]
 328 impl<T: AsHandle> AsHandle for &mut T {
 329     #[inline]
 330     fn as_handle(&self) -> BorrowedHandle<'_> {
 331         T::as_handle(self)
 332     }
 333 }
 334
 335 impl AsHandle for BorrowedHandle<'_> {
 336     #[inline]
 337     fn as_handle(&self) -> BorrowedHandle<'_> {
 338         *self
 339     }
 340 }
 341
 342 impl AsHandle for OwnedHandle {
 343     #[inline]
 344     fn as_handle(&self) -> BorrowedHandle<'_> {
 345         // Safety: `OwnedHandle` and `BorrowedHandle` have the same validity
 346         // invariants, and the `BorrowdHandle` is bounded by the lifetime
 347         // of `&self`.
 348         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 349     }
 350 }
 351
 352 impl AsHandle for fs::File {
 353     #[inline]
 354     fn as_handle(&self) -> BorrowedHandle<'_> {
 355         self.as_inner().as_handle()
 356     }
 357 }
 358
 359 impl From<fs::File> for OwnedHandle {
 360     #[inline]
 361     fn from(file: fs::File) -> OwnedHandle {
 362         file.into_inner().into_inner().into_inner().into()
 363     }
 364 }
 365
 366 impl From<OwnedHandle> for fs::File {
 367     #[inline]
 368     fn from(owned: OwnedHandle) -> Self {
 369         Self::from_inner(FromInner::from_inner(FromInner::from_inner(owned)))
 370     }
 371 }
 372
 373 impl AsHandle for crate::io::Stdin {
 374     #[inline]
 375     fn as_handle(&self) -> BorrowedHandle<'_> {
 376         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 377     }
 378 }
 379
 380 impl<'a> AsHandle for crate::io::StdinLock<'a> {
 381     #[inline]
 382     fn as_handle(&self) -> BorrowedHandle<'_> {
 383         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 384     }
 385 }
 386
 387 impl AsHandle for crate::io::Stdout {
 388     #[inline]
 389     fn as_handle(&self) -> BorrowedHandle<'_> {
 390         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 391     }
 392 }
 393
 394 impl<'a> AsHandle for crate::io::StdoutLock<'a> {
 395     #[inline]
 396     fn as_handle(&self) -> BorrowedHandle<'_> {
 397         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 398     }
 399 }
 400
 401 impl AsHandle for crate::io::Stderr {
 402     #[inline]
 403     fn as_handle(&self) -> BorrowedHandle<'_> {
 404         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 405     }
 406 }
 407
 408 impl<'a> AsHandle for crate::io::StderrLock<'a> {
 409     #[inline]
 410     fn as_handle(&self) -> BorrowedHandle<'_> {
 411         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 412     }
 413 }
 414
 415 impl AsHandle for crate::process::ChildStdin {
 416     #[inline]
 417     fn as_handle(&self) -> BorrowedHandle<'_> {
 418         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 419     }
 420 }
 421
 422 impl From<crate::process::ChildStdin> for OwnedHandle {
 423     #[inline]
 424     fn from(child_stdin: crate::process::ChildStdin) -> OwnedHandle {
 425         unsafe { OwnedHandle::from_raw_handle(child_stdin.into_raw_handle()) }
 426     }
 427 }
 428
 429 impl AsHandle for crate::process::ChildStdout {
 430     #[inline]
 431     fn as_handle(&self) -> BorrowedHandle<'_> {
 432         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 433     }
 434 }
 435
 436 impl From<crate::process::ChildStdout> for OwnedHandle {
 437     #[inline]
 438     fn from(child_stdout: crate::process::ChildStdout) -> OwnedHandle {
 439         unsafe { OwnedHandle::from_raw_handle(child_stdout.into_raw_handle()) }
 440     }
 441 }
 442
 443 impl AsHandle for crate::process::ChildStderr {
 444     #[inline]
 445     fn as_handle(&self) -> BorrowedHandle<'_> {
 446         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 447     }
 448 }
 449
 450 impl From<crate::process::ChildStderr> for OwnedHandle {
 451     #[inline]
 452     fn from(child_stderr: crate::process::ChildStderr) -> OwnedHandle {
 453         unsafe { OwnedHandle::from_raw_handle(child_stderr.into_raw_handle()) }
 454     }
 455 }
 456
 457 impl<T> AsHandle for crate::thread::JoinHandle<T> {
 458     #[inline]
 459     fn as_handle(&self) -> BorrowedHandle<'_> {
 460         unsafe { BorrowedHandle::borrow_raw_handle(self.as_raw_handle()) }
 461     }
 462 }
 463
 464 impl<T> From<crate::thread::JoinHandle<T>> for OwnedHandle {
 465     #[inline]
 466     fn from(join_handle: crate::thread::JoinHandle<T>) -> OwnedHandle {
 467         join_handle.into_inner().into_handle().into_inner()
 468     }
 469 }