Crate unsafe_io[][src]

Non-owning unsafe I/O

In table form, the main types and traits provided by this crate are:

ResourcePosix-ish typeWindows typePlatform-independent types
FileRawFdRawHandleUnsafeHandle or UnsafeFile
PipeRawFdRawHandleUnsafeHandle or UnsafeFile
SocketRawFdRawSocketUnsafeHandle or UnsafeSocket
AnyRawFdRawHandleOrSocketUnsafeHandle

and the main traits are:

TypeAs traitInto traitFrom trait
RawFdAsRawFdIntoRawFdFromRawFd
RawHandleAsRawHandleIntoRawHandleFromRawHandle
RawSocketAsRawSocketIntoRawSocketFromRawSocket
RawHandleOrSocketAsRawHandleOrSocketIntoRawHandleOrSocketFromRawHandleOrSocket
UnsafeFileAsUnsafeFileIntoUnsafeFileFromUnsafeFile
UnsafeSocketAsUnsafeSocketIntoUnsafeSocketFromUnsafeSocket
UnsafeHandleAsUnsafeHandleIntoUnsafeHandleFromUnsafeHandle

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:

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

ReadHalf

Adapt an AsUnsafeReadWriteHandle implementation to implement AsUnsafeHandle with the read handle.

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.

WriteHalf

Adapt an AsUnsafeReadWriteHandle implementation to implement AsUnsafeHandle with the write handle.

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.