Crate unsafe_io[−][src]
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:
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 functionsas_readable
andas_writeable
which return similar non-owning typesUnsafeReadable
andUnsafeWriteable
, respectively, which implementRead
andWrite
. -
AsUnsafeFile
has functionsas_file_view
,as_pipe_reader_view
, andas_pipe_writer_view
(enable theos_pipe
feature), andAsUnsafeSocket
has functionsas_tcp_stream_view
,as_tcp_listener_view
,as_udp_socket_view
, andas_unix_stream_view
(onunix
platforms), for obtaining a temporary view of a handle as various higher-level types. -
AsUnsafeHandle
has aneq_handle
function,AsUnsafeFile
has aneq_file
function, andAsUnsafeSocket
has aneq_socket
function, for comparing whether two types hold the same handle, and are safe to call. -
FromUnsafeFile
has afrom_filelike
function, andFromUnsafeSocket
has afrom_socketlike
function, for constructing a type from any type which implementsIntoUnsafeFile
, orIntoUnsafeSocket
, respectively. Unlike in the corresponding “Raw” traits, these functions are safe to call. -
AsUnsafeReadWriteHandle
,AsRawReadWriteFd
, andAsRawReadWriteHandleOrSocket
are traits for working with types that implement bothRead
andWrite
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
ReadHalf | Adapt an |
UnsafeFile | A non-owning unsafe I/O handle which on Windows is limited to handling what
Windows considers to be |
UnsafeHandle | A non-owning unsafe I/O handle. |
UnsafeReadable | A non-owning unsafe I/O handle that implements |
UnsafeSocket | A non-owning unsafe I/O handle which on Windows is limited to handling what
Windows considers to be |
UnsafeWriteable | A non-owning unsafe I/O handle that implements |
View | A non-owning view of a resource which dereferences to a |
WriteHalf | Adapt an |
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 |
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. |