A program shall not create a value of any type from uninitialized memory,
except when accessing a field of a union type,
where such reads are explicitly defined to be permitted even if the bytes of that field are uninitialized.
It is prohibited to interpret uninitialized memory as a value of any Rust type such as a
primitive, aggregate, reference, pointer, struct, enum, array, or tuple.
Exception: You can access a field of a union even when the backing bytes of that field are uninitialized provided that:
The resulting value has an unspecified but well-defined bit pattern. Interpreting that value must still comply with the requirements of the accessed type
(e.g., no invalid enum discriminants, no invalid pointer values, etc.).
For example, reading an uninitialized u32 field of a union is allowed;
reading an uninitialized bool field is disallowed because not all bit patterns are valid.
|
|
|
|
Rust’s memory model treats all types except unions as having an invariant that all bytes must be initialized before a value may be constructed.
Reading uninitialized memory:
creates undefined behavior for most types, may violate niche or discriminant validity, may create invalid pointer values, or may produce values that violate type invariants.
The sole exception is that unions work like C unions: any union field may be read, even if it was never written.
The resulting bytes must, however, form a valid representation for the field’s type,
which is not guaranteed if the union contains arbitrary data.
|
|
|
|
|
This noncompliant example creates a value of type u32 from uninitialized memory via
assume_init:
use std::mem::MaybeUninit;
let x: u32 = unsafe { MaybeUninit::uninit().assume_init() }; // UB
|
|
|
|
|
Types such as u8, u16, u32, and i128 allow all possible bit patterns.
Provided the memory is initialized, there is no undefined behavior.
union U {
n: u32,
bytes: [u8; 4],
}
let u = U { bytes: [0xFF, 0xEE, 0xDD, 0xCC] };
let n = unsafe { u.n }; // OK — all bit patterns valid for u32
|
|
|
|
|
This compliant example calls the write function to fully initialize low-level memory.
use std::mem::MaybeUninit;
let mut x = MaybeUninit::<u64>::uninit();
x.write(42);
let val = unsafe { x.assume_init() }; // OK — value was fully initialized
|
|
|
|
|
Creating a reference from arbitrary or uninitialized bytes is always undefined behavior.
References must be valid, aligned, properly dereferenceable, and non-null.
Uninitialized memory cannot satisfy these invariants.
use std::mem::MaybeUninit;
let r: &u32 = unsafe { MaybeUninit::uninit().assume_init() }; // UB — invalid reference
|
|
|
|
|
Not all bit patterns are valid pointers for all operations (e.g., provenance rules).
You cannot create a pointer from unspecified bytes.
Even a raw pointer type (e.g., *const T) has validity rules.
use std::mem::MaybeUninit;
let p: *const u32 = unsafe { MaybeUninit::uninit().assume_init() }; // UB
|
|
|
|
|
Array elements must individually be valid values.
use std::mem::MaybeUninit;
let mut arr: [MaybeUninit<u8>; 4] = unsafe { MaybeUninit::uninit().assume_init() };
let a = unsafe { std::mem::transmute::<_, [u8; 4]>(arr) }; // UB — not all elements initialized
|
|
|
|
|
The following code reads a union field:
union U {
x: u32,
y: f32,
}
let u = U { x: 123 }; // write to one field
let f = unsafe { u.y }; // reading the other field is allowed
|
|
|
|
|
Even though unions allow reads of any field, not all bit patterns are valid for a bool.
Unions do not relax type validity requirements.
Only the read itself is allowed;
the resulting bytes must still be a valid bool.
union U {
b: bool,
x: u8,
}
let u = U { x: 255 }; // 255 is not a valid bool representation
let b = unsafe { u.b }; // UB — invalid bool
|
|
|
|
|
Accessing padding bytes is allowed if not interpreted as typed data:
#[repr(C)]
struct S {
a: u8,
b: u32,
}
let mut buf = [0u8; std::mem::size_of::<S>()];
buf[0] = 10;
buf[1] = 20; // writing padding is fine
let p = buf.as_ptr() as *const S;
let s = unsafe { p.read_unaligned() }; // OK — all *fields* are initialized (padding doesn't matter)
|
|