.. default-domain:: coding-guidelines
.. guideline:: Do not create values from uninitialized memory except for union fields
:id: gui_uyp3mCj77FS8
:category: mandatory
:status: draft
:release: <TODO>
:fls: fls_6lg0oaaopc26
:decidability: undecidable
:scope: system
:tags: undefined-behavior, safety, security
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.
.. rationale::
:id: rat_kjFRrhpS8Wu6
:status: draft
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.
.. non_compliant_example::
:id: non_compl_ex_Qb5GqYTP6db1
:status: draft
This noncompliant example creates a value of type ``u32`` from uninitialized memory via
`assume_init <https://doc.rust-lang.org/stable/std/mem/union.MaybeUninit.html#method.assume_init>`_:
.. code-block:: rust
use std::mem::MaybeUninit;
let x: u32 = unsafe { MaybeUninit::uninit().assume_init() }; // UB
.. compliant_example::
:id: compl_ex_Ke869nSXuShU
:status: draft
Types such as ``u8``, ``u16``, ``u32``, and ``i128`` allow all possible bit patterns.
Provided the memory is initialized, there is no undefined behavior.
.. code-block:: rust
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
.. compliant_example::
:id: compl_ex_Ke869nSXuShV
:status: draft
This compliant example calles the ``write`` function to fully initialize low-level memory.
.. code-block:: rust
use std::mem::MaybeUninit;
let mut x = MaybeUninit::<u64>::uninit();
x.write(42);
let val = unsafe { x.assume_init() }; // OK — value was fully initialized
.. non_compliant_example::
:id: non_compl_ex_Qb5GqYTP6db2
:status: draft
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.
.. code-block:: rust
use std::mem::MaybeUninit;
let r: &u32 = unsafe { MaybeUninit::uninit().assume_init() }; // UB — invalid reference
.. non_compliant_example::
:id: non_compl_ex_Qb5GqYTP6db4
:status: draft
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.
.. code-block:: rust
use std::mem::MaybeUninit;
let p: *const u32 = unsafe { MaybeUninit::uninit().assume_init() }; // UB
.. non_compliant_example::
:id: non_compl_ex_Qb5GqYTP6db5
:status: draft
Array elements must individually be valid values.
.. code-block:: rust
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
.. compliant_example::
:id: compl_ex_Ke869nSXuShT
:status: draft
The following code reads a union field:
.. code-block:: rust
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
.. non_compliant_example::
:id: non_compl_ex_Qb5GqYTP6db3
:status: draft
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.
.. code-block:: rust
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
.. compliant_example::
:id: compl_ex_5Rs1t5gYgZLr
:status: draft
Accessing padding bytes is allowed if not interpreted as typed data:
.. code-block:: rust
#[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)