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