library/std/src/sys/windows/handle.rs

   1 #![unstable(issue = "none", feature = "windows_handle")]
   2
   3 use crate::cmp;
   4 use crate::io::{self, ErrorKind, IoSlice, IoSliceMut, Read, ReadBuf};
   5 use crate::mem;
   6 use crate::os::windows::io::{
   7     AsHandle, AsRawHandle, BorrowedHandle, FromRawHandle, IntoRawHandle, OwnedHandle, RawHandle,
   8 };
   9 use crate::ptr;
  10 use crate::sys::c;
  11 use crate::sys::cvt;
  12 use crate::sys_common::{AsInner, FromInner, IntoInner};
  13
  14 /// An owned container for `HANDLE` object, closing them on Drop.
  15 ///
  16 /// All methods are inherited through a `Deref` impl to `RawHandle`
  17 pub struct Handle(OwnedHandle);
  18
  19 impl Handle {
  20     pub fn new_event(manual: bool, init: bool) -> io::Result<Handle> {
  21         unsafe {
  22             let event =
  23                 c::CreateEventW(ptr::null_mut(), manual as c::BOOL, init as c::BOOL, ptr::null());
  24             if event.is_null() {
  25                 Err(io::Error::last_os_error())
  26             } else {
  27                 Ok(Handle::from_raw_handle(event))
  28             }
  29         }
  30     }
  31 }
  32
  33 impl AsInner<OwnedHandle> for Handle {
  34     fn as_inner(&self) -> &OwnedHandle {
  35         &self.0
  36     }
  37 }
  38
  39 impl IntoInner<OwnedHandle> for Handle {
  40     fn into_inner(self) -> OwnedHandle {
  41         self.0
  42     }
  43 }
  44
  45 impl FromInner<OwnedHandle> for Handle {
  46     fn from_inner(file_desc: OwnedHandle) -> Self {
  47         Self(file_desc)
  48     }
  49 }
  50
  51 impl AsHandle for Handle {
  52     fn as_handle(&self) -> BorrowedHandle<'_> {
  53         self.0.as_handle()
  54     }
  55 }
  56
  57 impl AsRawHandle for Handle {
  58     fn as_raw_handle(&self) -> RawHandle {
  59         self.0.as_raw_handle()
  60     }
  61 }
  62
  63 impl IntoRawHandle for Handle {
  64     fn into_raw_handle(self) -> RawHandle {
  65         self.0.into_raw_handle()
  66     }
  67 }
  68
  69 impl FromRawHandle for Handle {
  70     unsafe fn from_raw_handle(raw_handle: RawHandle) -> Self {
  71         Self(FromRawHandle::from_raw_handle(raw_handle))
  72     }
  73 }
  74
  75 impl Handle {
  76     pub fn read(&self, buf: &mut [u8]) -> io::Result<usize> {
  77         let res = unsafe { self.synchronous_read(buf.as_mut_ptr().cast(), buf.len(), None) };
  78
  79         match res {
  80             Ok(read) => Ok(read as usize),
  81
  82             // The special treatment of BrokenPipe is to deal with Windows
  83             // pipe semantics, which yields this error when *reading* from
  84             // a pipe after the other end has closed; we interpret that as
  85             // EOF on the pipe.
  86             Err(ref e) if e.kind() == ErrorKind::BrokenPipe => Ok(0),
  87
  88             Err(e) => Err(e),
  89         }
  90     }
  91
  92     pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
  93         crate::io::default_read_vectored(|buf| self.read(buf), bufs)
  94     }
  95
  96     #[inline]
  97     pub fn is_read_vectored(&self) -> bool {
  98         false
  99     }
 100
 101     pub fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result<usize> {
 102         let res =
 103             unsafe { self.synchronous_read(buf.as_mut_ptr().cast(), buf.len(), Some(offset)) };
 104
 105         match res {
 106             Ok(read) => Ok(read as usize),
 107             Err(ref e) if e.raw_os_error() == Some(c::ERROR_HANDLE_EOF as i32) => Ok(0),
 108             Err(e) => Err(e),
 109         }
 110     }
 111
 112     pub fn read_buf(&self, buf: &mut ReadBuf<'_>) -> io::Result<()> {
 113         let res = unsafe {
 114             self.synchronous_read(buf.unfilled_mut().as_mut_ptr(), buf.remaining(), None)
 115         };
 116
 117         match res {
 118             Ok(read) => {
 119                 // Safety: `read` bytes were written to the initialized portion of the buffer
 120                 unsafe {
 121                     buf.assume_init(read as usize);
 122                 }
 123                 buf.add_filled(read as usize);
 124                 Ok(())
 125             }
 126
 127             // The special treatment of BrokenPipe is to deal with Windows
 128             // pipe semantics, which yields this error when *reading* from
 129             // a pipe after the other end has closed; we interpret that as
 130             // EOF on the pipe.
 131             Err(ref e) if e.kind() == ErrorKind::BrokenPipe => Ok(()),
 132
 133             Err(e) => Err(e),
 134         }
 135     }
 136
 137     pub unsafe fn read_overlapped(
 138         &self,
 139         buf: &mut [u8],
 140         overlapped: *mut c::OVERLAPPED,
 141     ) -> io::Result<Option<usize>> {
 142         let len = cmp::min(buf.len(), <c::DWORD>::MAX as usize) as c::DWORD;
 143         let mut amt = 0;
 144         let res = cvt(c::ReadFile(
 145             self.as_handle(),
 146             buf.as_ptr() as c::LPVOID,
 147             len,
 148             &mut amt,
 149             overlapped,
 150         ));
 151         match res {
 152             Ok(_) => Ok(Some(amt as usize)),
 153             Err(e) => {
 154                 if e.raw_os_error() == Some(c::ERROR_IO_PENDING as i32) {
 155                     Ok(None)
 156                 } else if e.raw_os_error() == Some(c::ERROR_BROKEN_PIPE as i32) {
 157                     Ok(Some(0))
 158                 } else {
 159                     Err(e)
 160                 }
 161             }
 162         }
 163     }
 164
 165     pub fn overlapped_result(
 166         &self,
 167         overlapped: *mut c::OVERLAPPED,
 168         wait: bool,
 169     ) -> io::Result<usize> {
 170         unsafe {
 171             let mut bytes = 0;
 172             let wait = if wait { c::TRUE } else { c::FALSE };
 173             let res =
 174                 cvt(c::GetOverlappedResult(self.as_raw_handle(), overlapped, &mut bytes, wait));
 175             match res {
 176                 Ok(_) => Ok(bytes as usize),
 177                 Err(e) => {
 178                     if e.raw_os_error() == Some(c::ERROR_HANDLE_EOF as i32)
 179                         || e.raw_os_error() == Some(c::ERROR_BROKEN_PIPE as i32)
 180                     {
 181                         Ok(0)
 182                     } else {
 183                         Err(e)
 184                     }
 185                 }
 186             }
 187         }
 188     }
 189
 190     pub fn cancel_io(&self) -> io::Result<()> {
 191         unsafe { cvt(c::CancelIo(self.as_raw_handle())).map(drop) }
 192     }
 193
 194     pub fn write(&self, buf: &[u8]) -> io::Result<usize> {
 195         self.synchronous_write(&buf, None)
 196     }
 197
 198     pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result<usize> {
 199         crate::io::default_write_vectored(|buf| self.write(buf), bufs)
 200     }
 201
 202     #[inline]
 203     pub fn is_write_vectored(&self) -> bool {
 204         false
 205     }
 206
 207     pub fn write_at(&self, buf: &[u8], offset: u64) -> io::Result<usize> {
 208         self.synchronous_write(&buf, Some(offset))
 209     }
 210
 211     pub fn try_clone(&self) -> io::Result<Self> {
 212         Ok(Self(self.0.try_clone()?))
 213     }
 214
 215     pub fn duplicate(
 216         &self,
 217         access: c::DWORD,
 218         inherit: bool,
 219         options: c::DWORD,
 220     ) -> io::Result<Self> {
 221         Ok(Self(self.0.duplicate(access, inherit, options)?))
 222     }
 223
 224     #[cfg(not(target_vendor = "uwp"))]
 225     pub(crate) fn set_inheritable(&self) -> io::Result<()> {
 226         self.0.set_inheritable()
 227     }
 228
 229     /// Performs a synchronous read.
 230     ///
 231     /// If the handle is opened for asynchronous I/O then this abort the process.
 232     /// See #81357.
 233     ///
 234     /// If `offset` is `None` then the current file position is used.
 235     unsafe fn synchronous_read(
 236         &self,
 237         buf: *mut mem::MaybeUninit<u8>,
 238         len: usize,
 239         offset: Option<u64>,
 240     ) -> io::Result<usize> {
 241         let mut io_status = c::IO_STATUS_BLOCK::default();
 242
 243         // The length is clamped at u32::MAX.
 244         let len = cmp::min(len, c::DWORD::MAX as usize) as c::DWORD;
 245         let status = c::NtReadFile(
 246             self.as_handle(),
 247             ptr::null_mut(),
 248             None,
 249             ptr::null_mut(),
 250             &mut io_status,
 251             buf,
 252             len,
 253             offset.map(|n| n as _).as_ref(),
 254             None,
 255         );
 256         match status {
 257             // If the operation has not completed then abort the process.
 258             // Doing otherwise means that the buffer and stack may be written to
 259             // after this function returns.
 260             c::STATUS_PENDING => {
 261                 eprintln!("I/O error: operation failed to complete synchronously");
 262                 crate::process::abort();
 263             }
 264
 265             // Return `Ok(0)` when there's nothing more to read.
 266             c::STATUS_END_OF_FILE => Ok(0),
 267
 268             // Success!
 269             status if c::nt_success(status) => Ok(io_status.Information),
 270
 271             status => {
 272                 let error = c::RtlNtStatusToDosError(status);
 273                 Err(io::Error::from_raw_os_error(error as _))
 274             }
 275         }
 276     }
 277
 278     /// Performs a synchronous write.
 279     ///
 280     /// If the handle is opened for asynchronous I/O then this abort the process.
 281     /// See #81357.
 282     ///
 283     /// If `offset` is `None` then the current file position is used.
 284     fn synchronous_write(&self, buf: &[u8], offset: Option<u64>) -> io::Result<usize> {
 285         let mut io_status = c::IO_STATUS_BLOCK::default();
 286
 287         // The length is clamped at u32::MAX.
 288         let len = cmp::min(buf.len(), c::DWORD::MAX as usize) as c::DWORD;
 289         let status = unsafe {
 290             c::NtWriteFile(
 291                 self.as_handle(),
 292                 ptr::null_mut(),
 293                 None,
 294                 ptr::null_mut(),
 295                 &mut io_status,
 296                 buf.as_ptr(),
 297                 len,
 298                 offset.map(|n| n as _).as_ref(),
 299                 None,
 300             )
 301         };
 302         match status {
 303             // If the operation has not completed then abort the process.
 304             // Doing otherwise means that the buffer may be read and the stack
 305             // written to after this function returns.
 306             c::STATUS_PENDING => {
 307                 rtabort!("I/O error: operation failed to complete synchronously");
 308             }
 309
 310             // Success!
 311             status if c::nt_success(status) => Ok(io_status.Information),
 312
 313             status => {
 314                 let error = unsafe { c::RtlNtStatusToDosError(status) };
 315                 Err(io::Error::from_raw_os_error(error as _))
 316             }
 317         }
 318     }
 319 }
 320
 321 impl<'a> Read for &'a Handle {
 322     fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
 323         (**self).read(buf)
 324     }
 325
 326     fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result<usize> {
 327         (**self).read_vectored(bufs)
 328     }
 329 }