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