Crate unsafe_io

Non-owning unsafe I/O

In table form, the main types and traits provided by this crate 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	FromRawHandleOrSocket
UnsafeFile	AsUnsafeFile	IntoUnsafeFile	FromUnsafeFile
UnsafeSocket	AsUnsafeSocket	IntoUnsafeSocket	FromUnsafeSocket
UnsafeHandle	AsUnsafeHandle	IntoUnsafeHandle	FromUnsafeHandle

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.

Ownership Guarantees

The AsUnsafe* and IntoUnsafe* trait functions return non-owning handles, however these traits do require types that implement them to guarantee that they own the handles. This differs from their AsRaw* and IntoRaw* counterparts, which do not require such a guarantee. This crate defines an OwnsRaw trait which is unsafe to implement and which allows types to declare that they own the handles they hold, allowing them to opt into the blanket AsUnsafe* and IntoUnsafe* implementations. See rust-lang/rust#76969 for further background.

Additional Utilities

This crates also defines several additional utilities:

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

• AsUnsafeFile has functions as_file_view, as_pipe_reader_view, and as_pipe_writer_view (enable the os_pipe feature), and AsUnsafeSocket has functions as_tcp_stream_view, as_tcp_listener_view, as_udp_socket_view, and as_unix_stream_view (on unix platforms), for obtaining a temporary view of a handle as various higher-level types.

• AsUnsafeHandle has an eq_handle function, AsUnsafeFile has an eq_file function, and AsUnsafeSocket has an eq_socket function, for comparing whether two types hold the same handle, and are safe to call.

• FromUnsafeFile has a from_filelike function, and FromUnsafeSocket has a from_socketlike function, for constructing a type from any type which implements IntoUnsafeFile, or IntoUnsafeSocket, respectively. Unlike in the corresponding "Raw" traits, these functions are safe to call.

• 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).

Examples

To use the AsUnsafeHandle trait:

use unsafe_io::AsUnsafeHandle;

// Open a normal file.
let file = std::fs::File::open("Cargo.toml").unwrap();

// Extract the handle.
let unsafe_handle = file.as_unsafe_handle();

Many types implement AsUnsafeHandle, however very few types implement FromUnsafeHandle. Most types implement only FromUnsafeFile or FromUnsafeSocket instead. For an example that extracts a handle and constructs a new file, we use the IntoUnsafeFile and AsUnsafeFile traits:

use unsafe_io::{FromUnsafeFile, IntoUnsafeFile};

// Open a normal file.
let file = std::fs::File::open("Cargo.toml").unwrap();

// Consume the file, returning the handle.
let unsafe_file = file.into_unsafe_file();

// Construct a new file with the handle.
let file = unsafe { std::fs::File::from_unsafe_file(unsafe_file) };

To implement the AsUnsafeHandle trait for a type, implement the AsRawFd trait for Posix-ish platforms and the AsRawHandleOrSocket trait for Windows platforms, and then implement OwnsRaw:

#[cfg(not(windows))]
use unsafe_io::os::posish::{AsRawFd, RawFd};
#[cfg(windows)]
use unsafe_io::os::windows::{AsRawHandleOrSocket, RawHandleOrSocket};
use unsafe_io::OwnsRaw;

struct MyType(std::fs::File);

#[cfg(not(windows))]
impl AsRawFd for MyType {
    fn as_raw_fd(&self) -> RawFd {
        self.0.as_raw_fd()
    }
}

#[cfg(windows)]
impl AsRawHandleOrSocket for MyType {
    fn as_raw_handle_or_socket(&self) -> RawHandleOrSocket {
        self.0.as_raw_handle_or_socket()
    }
}

// Safety: `MyType` owns its handle.
unsafe impl OwnsRaw for MyType {}

This requires unsafe because implementing OwnsRaw asserts that the type owns its raw handle. See the char-device crate for a complete example.

Modules

os	OS-specific functionality.

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 non-owning view of a resource which dereferences to a &Target or &mut Target.

Traits

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	Like AsUnsafeHandle, but for types 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.
FromUnsafeHandle	A trait for types which can be constructed from an unsafe handle.
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.
OwnsRaw	Assert that a type owns its raw file descriptor or handle.