]>
Commit | Line | Data |
---|---|---|
8bb4bdeb XL |
1 | ## Behavior considered undefined |
2 | ||
416331ca XL |
3 | Rust code is incorrect if it exhibits any of the behaviors in the following |
4 | list. This includes code within `unsafe` blocks and `unsafe` functions. | |
5 | `unsafe` only means that avoiding undefined behavior is on the programmer; it | |
6 | does not change anything about the fact that Rust programs must never cause | |
7 | undefined behavior. | |
8 | ||
9 | It is the programmer's responsibility when writing `unsafe` code to ensure that | |
10 | any safe code interacting with the `unsafe` code cannot trigger these | |
11 | behaviors. `unsafe` code that satisfies this property for any safe client is | |
12 | called *sound*; if `unsafe` code can be misused by safe code to exhibit | |
13 | undefined behavior, it is *unsound*. | |
8bb4bdeb | 14 | |
b7449926 XL |
15 | <div class="warning"> |
16 | ||
17 | ***Warning:*** The following list is not exhaustive. There is no formal model of | |
18 | Rust's semantics for what is and is not allowed in unsafe code, so there may be | |
19 | more behavior considered unsafe. The following list is just what we know for | |
20 | sure is undefined behavior. Please read the [Rustonomicon] before writing unsafe | |
21 | code. | |
22 | ||
23 | </div> | |
24 | ||
ea8adc8c | 25 | * Data races. |
e1599b0c XL |
26 | * Dereferencing (using the `*` operator on) a dangling or unaligned raw pointer. |
27 | * Breaking the [pointer aliasing rules]. `&mut T` and `&T` follow LLVM’s scoped | |
28 | [noalias] model, except if the `&T` contains an [`UnsafeCell<U>`]. | |
29 | * Mutating immutable data. All data inside a [`const`] item is immutable. Moreover, all | |
30 | data reached through a shared reference or data owned by an immutable binding | |
31 | is immutable, unless that data is contained within an [`UnsafeCell<U>`]. | |
32 | * Invoking undefined behavior via compiler intrinsics. | |
33 | * Executing code compiled with platform features that the current platform | |
34 | does not support (see [`target_feature`]). | |
35 | * Calling a function with the wrong call ABI or unwinding from a function with the wrong unwind ABI. | |
36 | * Producing an invalid value, even in private fields and locals. "Producing" a | |
37 | value happens any time a value is assigned to or read from a place, passed to | |
38 | a function/primitive operation or returned from a function/primitive | |
39 | operation. | |
40 | The following values are invalid (at their respective type): | |
ea8adc8c XL |
41 | * A value other than `false` (`0`) or `true` (`1`) in a `bool`. |
42 | * A discriminant in an `enum` not included in the type definition. | |
e1599b0c | 43 | * A null `fn` pointer. |
ea8adc8c | 44 | * A value in a `char` which is a surrogate or above `char::MAX`. |
e1599b0c XL |
45 | * A `!` (all values are invalid for this type). |
46 | * An integer (`i*`/`u*`), floating point value (`f*`), or raw pointer obtained | |
f9f354fc | 47 | from [uninitialized memory][undef], or uninitialized memory in a `str`. |
e1599b0c XL |
48 | * A reference or `Box<T>` that is dangling, unaligned, or points to an invalid value. |
49 | * Invalid metadata in a wide reference, `Box<T>`, or raw pointer: | |
50 | * `dyn Trait` metadata is invalid if it is not a pointer to a vtable for | |
51 | `Trait` that matches the actual dynamic trait the pointer or reference points to. | |
74b04a01 | 52 | * Slice metadata is invalid if the length is not a valid `usize` |
e1599b0c | 53 | (i.e., it must not be read from uninitialized memory). |
e1599b0c XL |
54 | * Invalid values for a type with a custom definition of invalid values. |
55 | In the standard library, this affects [`NonNull<T>`] and [`NonZero*`]. | |
56 | ||
57 | > **Note**: `rustc` achieves this with the unstable | |
58 | > `rustc_layout_scalar_valid_range_*` attributes. | |
59 | ||
1b1a35ee XL |
60 | **Note:** Uninitialized memory is also implicitly invalid for any type that has |
61 | a restricted set of valid values. In other words, the only cases in which | |
62 | reading uninitialized memory is permitted are inside `union`s and in "padding" | |
63 | (the gaps between the fields/elements of a type). | |
64 | ||
e1599b0c XL |
65 | A reference/pointer is "dangling" if it is null or not all of the bytes it |
66 | points to are part of the same allocation (so in particular they all have to be | |
67 | part of *some* allocation). The span of bytes it points to is determined by the | |
ba9703b0 XL |
68 | pointer value and the size of the pointee type (using `size_of_val`). As a |
69 | consequence, if the span is empty, "dangling" is the same as "non-null". Note | |
f9f354fc XL |
70 | that slices and strings point to their entire range, so it is important that the length |
71 | metadata is never too large. In particular, allocations and therefore slices and strings | |
ba9703b0 | 72 | cannot be bigger than `isize::MAX` bytes. |
532ac7d7 XL |
73 | |
74 | > **Note**: Undefined behavior affects the entire program. For example, calling | |
75 | > a function in C that exhibits undefined behavior of C means your entire | |
76 | > program contains undefined behaviour that can also affect the Rust code. And | |
77 | > vice versa, undefined behavior in Rust can cause adverse affects on code | |
78 | > executed by any FFI calls to other languages. | |
8bb4bdeb | 79 | |
e1599b0c | 80 | [`const`]: items/constant-items.html |
8bb4bdeb | 81 | [noalias]: http://llvm.org/docs/LangRef.html#noalias |
ea8adc8c XL |
82 | [pointer aliasing rules]: http://llvm.org/docs/LangRef.html#pointer-aliasing-rules |
83 | [undef]: http://llvm.org/docs/LangRef.html#undefined-values | |
416331ca | 84 | [`target_feature`]: attributes/codegen.md#the-target_feature-attribute |
532ac7d7 | 85 | [`UnsafeCell<U>`]: ../std/cell/struct.UnsafeCell.html |
b7449926 | 86 | [Rustonomicon]: ../nomicon/index.html |
e1599b0c XL |
87 | [`NonNull<T>`]: ../core/ptr/struct.NonNull.html |
88 | [`NonZero*`]: ../core/num/index.html |