# Module std::os::windows::io

1.0.0 · source ·
Available on Windows only.
Expand description

Windows-specific extensions to general I/O primitives.

Just like raw pointers, raw Windows handles and sockets point to resources with dynamic lifetimes, and they can dangle if they outlive their resources or be forged if they’re created from invalid values.

This module provides three types for representing raw handles and sockets with different ownership properties: raw, borrowed, and owned, which are analogous to types used for representing pointers. These types reflect concepts of I/O safety on Windows.

Type | Analogous to
--- | ---
`RawHandle` | `*const _`
`RawSocket` | `*const _`
`BorrowedHandle<'a>` | `&'a _`
`BorrowedSocket<'a>` | `&'a _`
`OwnedHandle` | `Box<_>`
`OwnedSocket` | `Box<_>`

Like raw pointers, `RawHandle` and `RawSocket` values are primitive values. And in new code, they should be considered unsafe to do I/O on (analogous to dereferencing them). Rust did not always provide this guidance, so existing code in the Rust ecosystem often doesn’t mark `RawHandle` and `RawSocket` usage as unsafe. Libraries are encouraged to migrate, either by adding `unsafe` to APIs that dereference `RawHandle` and `RawSocket` values, or by using to `BorrowedHandle`, `BorrowedSocket`, `OwnedHandle`, or `OwnedSocket`.

Like references, `BorrowedHandle` and `BorrowedSocket` values are tied to a lifetime, to ensure that they don’t outlive the resource they point to. These are safe to use. `BorrowedHandle` and `BorrowedSocket` values may be used in APIs which provide safe access to any system call except for `CloseHandle`, `closesocket`, or any other call that would end the dynamic lifetime of the resource without ending the lifetime of the handle or socket.

`BorrowedHandle` and `BorrowedSocket` values may be used in APIs which provide safe access to `DuplicateHandle` and `WSADuplicateSocketW` and related functions, so types implementing `AsHandle`, `AsSocket`, `From<OwnedHandle>`, or `From<OwnedSocket>` should not assume they always have exclusive access to the underlying object.

Like boxes, `OwnedHandle` and `OwnedSocket` values conceptually own the resource they point to, and free (close) it when they are dropped.

See the `io` module docs for a general explanation of I/O safety.

## Structs

- BorrowedHandle
  A borrowed handle.
- BorrowedSocket
  A borrowed socket.
- HandleOrInvalid
  FFI type for handles in return values or out parameters, where `INVALID_HANDLE_VALUE` is used as a sentry value to indicate errors, such as in the return value of `CreateFileW`. This uses `repr(transparent)` and has the representation of a host handle, so that it can be used in such FFI declarations.
- HandleOrNull
  FFI type for handles in return values or out parameters, where `NULL` is used as a sentry value to indicate errors, such as in the return value of `CreateThread`. This uses `repr(transparent)` and has the representation of a host handle, so that it can be used in such FFI declarations.
- InvalidHandleError
  This is the error type used by `HandleOrInvalid` when attempting to convert into a handle, to indicate that the value is `INVALID_HANDLE_VALUE`.
- NullHandleError
  This is the error type used by `HandleOrNull` when attempting to convert into a handle, to indicate that the value is null.
- OwnedHandle
  An owned handle.
- OwnedSocket
  An owned socket.

## Traits

- AsHandle
  A trait to borrow the handle from an underlying object.
- AsRawHandle
  Extracts raw handles.
- AsRawSocket
  Extracts raw sockets.
- AsSocket
  A trait to borrow the socket from an underlying object.
- FromRawHandle
  Construct I/O objects from raw handles.
- FromRawSocket
  Creates I/O objects from raw sockets.
- IntoRawHandle
  A trait to express the ability to consume an object and acquire ownership of its raw `HANDLE`.
- IntoRawSocket
  A trait to express the ability to consume an object and acquire ownership of its raw `SOCKET`.

## Type Aliases

- RawHandle
  Raw HANDLEs.
- RawSocket
  Raw SOCKETs.