Rust code is incorrect if it exhibits any of the behaviors in the following
list. This includes code within
unsafe blocks and
unsafe only means that avoiding undefined behavior is on the programmer; it
does not change anything about the fact that Rust programs must never cause
It is the programmer's responsibility when writing
unsafe code to ensure that
any safe code interacting with the
unsafe code cannot trigger these
unsafe code that satisfies this property for any safe client is
called sound; if
unsafe code can be misused by safe code to exhibit
undefined behavior, it is unsound.
Warning: The following list is not exhaustive; it may grow or shrink. There is no formal model of Rust's semantics for what is and is not allowed in unsafe code, so there may be more behavior considered unsafe. We also reserve the right to make some of the behavior in that list defined in the future. In other words, this list does not say that anything will definitely always be undefined in all future Rust version (but we might make such commitments for some list items in the future).
Please read the Rustonomicon before writing unsafe code.
Breaking the pointer aliasing rules.
&Tfollow LLVM’s scoped noalias model, except if the
UnsafeCell<U>. References and boxes must not be dangling while they are live. The exact liveness duration is not specified, but some bounds exist:
- For references, the liveness duration is upper-bounded by the syntactic lifetime assigned by the borrow checker; it cannot be live any longer than that lifetime.
- Each time a reference or box is passed to or returned from a function, it is considered live.
- When a reference (but not a
Box!) is passed to a function, it is live at least as long as that function call, again except if the
All this also applies when values of these types are passed in a (nested) field of a compound type, but not behind pointer indirections.
Moreover, the bytes pointed to by a shared reference, including transitively through other references (both shared and mutable) and
Boxes, are immutable; transitivity includes those references stored in fields of compound types.
A mutation is any write of more than 0 bytes which overlaps with any of the relevant bytes (even if that write does not change the memory contents).
Invoking undefined behavior via compiler intrinsics.
Executing code compiled with platform features that the current platform does not support (see
target_feature), except if the platform explicitly documents this to be safe.
Calling a function with the wrong call ABI or unwinding from a function with the wrong unwind ABI.
Producing an invalid value, even in private fields and locals. "Producing" a value happens any time a value is assigned to or read from a place, passed to a function/primitive operation or returned from a function/primitive operation. The following values are invalid (at their respective type):
A value other than
1) in a
A discriminant in an
enumnot included in the type definition.
A value in a
charwhich is a surrogate or above
!(all values are invalid for this type).
An integer (
u*), floating point value (
f*), or raw pointer obtained from uninitialized memory, or uninitialized memory in a
A reference or
Box<T>that is dangling, unaligned, or points to an invalid value.
Invalid metadata in a wide reference,
Box<T>, or raw pointer:
dyn Traitmetadata is invalid if it is not a pointer to a vtable for
Traitthat matches the actual dynamic trait the pointer or reference points to.
- Slice metadata is invalid if the length is not a valid
usize(i.e., it must not be read from uninitialized memory).
rustcachieves this with the unstable
Incorrect use of inline assembly. For more details, refer to the rules to follow when writing code that uses inline assembly.
In const context: transmuting or otherwise reinterpreting a pointer (reference, raw pointer, or function pointer) into some allocated object as a non-pointer type (such as integers). 'Reinterpreting' refers to loading the pointer value at integer type without a cast, e.g. by doing raw pointer casts or using a union.
Note: Uninitialized memory is also implicitly invalid for any type that has
a restricted set of valid values. In other words, the only cases in which
reading uninitialized memory is permitted are inside
unions and in "padding"
(the gaps between the fields/elements of a type).
Note: Undefined behavior affects the entire program. For example, calling a function in C that exhibits undefined behavior of C means your entire program contains undefined behaviour that can also affect the Rust code. And vice versa, undefined behavior in Rust can cause adverse affects on code executed by any FFI calls to other languages.
The span of bytes a pointer or reference "points to" is determined by the pointer value and the size of the pointee type (using
A reference/pointer is "dangling" if it is null or not all of the bytes it points to are part of the same live allocation (so in particular they all have to be part of some allocation).
If the size is 0, then the pointer must either point inside of a live allocation (including pointing just after the last byte of the allocation), or it must be directly constructed from a non-zero integer literal.
Note that dynamically sized types (such as slices and strings) point to their
entire range, so it is important that the length metadata is never too large. In
particular, the dynamic size of a Rust value (as determined by
must never exceed