Module io

Available on Windows only.

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

Constructs 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.