Crate unsafe_io

Non-owning unsafe I/O

A brief explanation of the naming convention:

Raw is for platform-specific types and traits, such as std's RawFd, AsRawFd, RawHandle, AsRawHandle, and similar, as well as unsafe-io's RawHandleOrSocket, AsRawHandleOrSocket, and similar. "Handle" in this context means a Windows HANDLE.

Unsafe is for minimal platform-independent abstractions on top of the platform-specific types, such as UnsafeHandle (abstracts over RawFd and RawHandleOrSocket), UnsafeFile (abstracts over RawFd and RawHandle), and UnsafeSocket (abstracts over RawFd and RawSocket). "Handle" in this context means any kind of I/O handle.

In table form, the main types are:

Resource	Posix-ish type	Windows type		Platform-independent types
File	RawFd	RawHandle		UnsafeHandle or UnsafeFile
Pipe	RawFd	RawHandle		UnsafeHandle or UnsafeFile
Socket	RawFd	RawSocket		UnsafeHandle or UnsafeSocket
Any	RawFd	RawHandleOrSocket		UnsafeHandle

and the main traits are:

Type	As trait	Into trait	From trait
RawFd	AsRawFd	IntoRawFd	FromRawFd
RawHandle	AsRawHandle	IntoRawHandle	FromRawHandle
RawSocket	AsRawSocket	IntoRawSocket	FromRawSocket
RawHandleOrSocket	AsRawHandleOrSocket	IntoRawHandleOrSocket	*
UnsafeFile	AsUnsafeFile	IntoUnsafeFile	FromUnsafeFile
UnsafeSocket	AsUnsafeSocket	IntoUnsafeSocket	FromUnsafeSocket
UnsafeHandle	AsUnsafeHandle	IntoUnsafeHandle	*

* These types do not have From traits.

This crates also defines several additional utilities:

UnsafeHandle has methods as_readable and as_writeable which return similar non-owning types UnsafeReadable and UnsafeWriteable, respectively, which implement Read and Write.

AsUnsafeReadWriteHandle, AsRawReadWriteFd, and AsRawReadWriteHandleOrSocket, are traits for working with types that implement both Read and Write and may contain either one handle (such as a socket) or two (such as stdin and stdout, or a pair of pipes).

Structs

UnsafeFile	A non-owning unsafe I/O handle which on Windows is limited to handling what Windows considers to be RawHandles—mainly files and pipes.
UnsafeHandle	A non-owning unsafe I/O handle.
UnsafeReadable	A non-owning unsafe I/O handle that implements Read. Read functions are considered safe, so this type requires unsafe to construct.
UnsafeSocket	A non-owning unsafe I/O handle which on Windows is limited to handling what Windows considers to be RawSockets—mainly TCP streams and listeners and UDP sockets.
UnsafeWriteable	A non-owning unsafe I/O handle that implements Write. Write functions considered are safe, so this type requires unsafe to construct.
View	A view of a resource which dereferences to a &Target or &mut Target.

Traits

AsRawReadWriteFd	Like AsRawFd, but specifically for use with implementations which may contain both reading and writing file descriptors.
AsUnsafeFile	A trait for types which contain an unsafe file and can expose it.
AsUnsafeHandle	A trait for types which contain an unsafe handle and can expose it.
AsUnsafeReadWriteHandle	An analog of AsUnsafeHandle for streams which may have one or two handles, for reading and writing.
AsUnsafeSocket	A trait for types which contain an unsafe socket and can expose it.
FromUnsafeFile	A trait for types which can be constructed from unsafe files.
FromUnsafeSocket	A trait for types which can be constructed from unsafe sockets.
IntoUnsafeFile	A trait for types which can be converted into unsafe files.
IntoUnsafeHandle	A trait for types which can be converted into an unsafe handle.
IntoUnsafeSocket	A trait for types which can be converted into unsafe sockets.