1.17.0[−][src]Function std::ptr::read_unaligned
pub unsafe fn read_unaligned<T>(src: *const T) -> T
Reads the value from src
without moving it. This leaves the
memory in src
unchanged.
Unlike read
, read_unaligned
works with unaligned pointers.
Safety
Behavior is undefined if any of the following conditions are violated:
src
must be valid for reads.
Like read
, read_unaligned
creates a bitwise copy of T
, regardless of
whether T
is Copy
. If T
is not Copy
, using both the returned
value and the value at *src
can violate memory safety.
Note that even if T
has size 0
, the pointer must be non-NULL.
On packed
structs
It is currently impossible to create raw pointers to unaligned fields of a packed struct.
Attempting to create a raw pointer to an unaligned
struct field with
an expression such as &packed.unaligned as *const FieldType
creates an
intermediate unaligned reference before converting that to a raw pointer.
That this reference is temporary and immediately cast is inconsequential
as the compiler always expects references to be properly aligned.
As a result, using &packed.unaligned as *const FieldType
causes immediate
undefined behavior in your program.
An example of what not to do and how this relates to read_unaligned
is:
#[repr(packed, C)] struct Packed { _padding: u8, unaligned: u32, } let packed = Packed { _padding: 0x00, unaligned: 0x01020304, }; let v = unsafe { // Here we attempt to take the address of a 32-bit integer which is not aligned. let unaligned = // A temporary unaligned reference is created here which results in // undefined behavior regardless of whether the reference is used or not. &packed.unaligned // Casting to a raw pointer doesn't help; the mistake already happened. as *const u32; let v = std::ptr::read_unaligned(unaligned); v };Run
Accessing unaligned fields directly with e.g. packed.unaligned
is safe however.
Examples
Read an usize value from a byte buffer:
use std::mem; fn read_usize(x: &[u8]) -> usize { assert!(x.len() >= mem::size_of::<usize>()); let ptr = x.as_ptr() as *const usize; unsafe { ptr.read_unaligned() } }Run