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 undefined behavior.
It is the programmer's responsibility when writing
unsafe code to ensure that any safe code interacting with the
unsafe code cannot trigger these behaviors.
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. 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. The following list is just what we know for sure is undefined behavior. Please read the Rustonomicon before writing unsafe code.
*operator on) a dangling or unaligned raw pointer.
&Tfollow LLVM’s scoped noalias model, except if the
constitem is immutable. Moreover, all data reached through a shared reference or data owned by an immutable binding is immutable, unless that data is contained within an
A value other than
1) in a
A discriminant in an
enum not included in the type definition.
A value in a
char which 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.
usize(i.e., it must not be read from uninitialized memory).
rustcachieves this with the unstable
A reference/pointer is "dangling" if it is null or not all of the bytes it points to are part of the same allocation (so in particular they all have to be part of some allocation). The span of bytes it points to is determined by the pointer value and the size of the pointee type (using
size_of_val). As a consequence, if the span is empty, "dangling" is the same as "non-null". Note that slices and strings point to their entire range, so it is important that the length metadata is never too large. In particular, allocations and therefore slices and strings cannot be bigger than
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.
© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.