pub unsafe trait FromBytes: FromZeroes {
// Provided methods
fn read_from(bytes: &[u8]) -> Option<Self>
where Self: Sized { ... }
fn read_from_prefix(bytes: &[u8]) -> Option<Self>
where Self: Sized { ... }
fn read_from_suffix(bytes: &[u8]) -> Option<Self>
where Self: Sized { ... }
}Expand description
Types for which any byte pattern is valid.
WARNING: Do not implement this trait yourself! Instead, use
#[derive(FromBytes)] (requires the derive Cargo feature).
FromBytes types can safely be deserialized from an untrusted sequence of
bytes because any byte sequence corresponds to a valid instance of the type.
FromBytes is ignorant of byte order. For byte order-aware types, see the
byteorder module.
Safety
This section describes what is required in order for T: FromBytes, and
what unsafe code may assume of such types. #[derive(FromBytes)] only
permits types which satisfy these requirements. If you don’t plan on
implementing FromBytes manually, and you don’t plan on writing unsafe code
that operates on FromBytes types, then you don’t need to read this
section.
If T: FromBytes, then unsafe code may assume that:
- It is sound to treat any initialized sequence of bytes of length
size_of::<T>()as aT. - Given
b: &[u8]whereb.len() == size_of::<T>()andbis aligned toalign_of::<T>(), it is sound to construct at: &Tat the same address asb, and it is sound for bothbandtto be live at the same time.
If a type is marked as FromBytes which violates this contract, it may
cause undefined behavior.
If a type has the following properties, then it is sound to implement
FromBytes for that type:
- If the type is a struct, all of its fields must satisfy the requirements
to be
FromBytes(they do not actually have to beFromBytes) - If the type is an enum:
- It must be a C-like enum (meaning that all variants have no fields).
- It must have a defined representation (
reprsC,u8,u16,u32,u64,usize,i8,i16,i32,i64, orisize). - The maximum number of discriminants must be used (so that every possible
bit pattern is a valid one). Be very careful when using the
C,usize, orisizerepresentations, as their size is platform-dependent.
- The type must not contain any
UnsafeCells (this is required in order for it to be sound to construct a&[u8]and a&Tto the same region of memory). The type may contain references or pointers toUnsafeCells so long as those values can themselves be initialized from zeroes (FromBytesis not currently implemented for, e.g.,Option<*const UnsafeCell<_>>, but it could be one day).
Rationale
Why isn’t an explicit representation required for structs?
Per the Rust reference,
The representation of a type can change the padding between fields, but does not change the layout of the fields themselves.
Since the layout of structs only consists of padding bytes and field bytes,
a struct is soundly FromBytes if:
- its padding is soundly
FromBytes, and - its fields are soundly
FromBytes.
The answer to the first question is always yes: padding bytes do not have any validity constraints. A discussion of this question in the Unsafe Code Guidelines Working Group concluded that it would be virtually unimaginable for future versions of rustc to add validity constraints to padding bytes.
Whether a struct is soundly FromBytes therefore solely depends on whether
its fields are FromBytes.
Provided Methods§
sourcefn read_from(bytes: &[u8]) -> Option<Self>where
Self: Sized,
fn read_from(bytes: &[u8]) -> Option<Self>where
Self: Sized,
Reads a copy of Self from bytes.
If bytes.len() != size_of::<Self>(), read_from returns None.
sourcefn read_from_prefix(bytes: &[u8]) -> Option<Self>where
Self: Sized,
fn read_from_prefix(bytes: &[u8]) -> Option<Self>where
Self: Sized,
Reads a copy of Self from the prefix of bytes.
read_from_prefix reads a Self from the first size_of::<Self>()
bytes of bytes. If bytes.len() < size_of::<Self>(), it returns
None.
sourcefn read_from_suffix(bytes: &[u8]) -> Option<Self>where
Self: Sized,
fn read_from_suffix(bytes: &[u8]) -> Option<Self>where
Self: Sized,
Reads a copy of Self from the suffix of bytes.
read_from_suffix reads a Self from the last size_of::<Self>()
bytes of bytes. If bytes.len() < size_of::<Self>(), it returns
None.