Add identifiers to behaviour-considered-undefined.md

Author: chorman0773

src/behavior-considered-undefined.md

@@ -1,11 +1,15 @@
 ## Behavior considered undefined
 
+r[undefined]
+
+r[undefined.general]
 Rust code is incorrect if it exhibits any of the behaviors in the following
 list. This includes code within `unsafe` blocks and `unsafe` functions.
 `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.
 
+r[undefined.soundness]
 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
@@ -26,13 +30,20 @@ Please read the [Rustonomicon] before writing unsafe code.
 
 </div>
 
+r[undefined.race]
 * Data races.
+
+r[undefined.pointer-access]
 * Accessing (loading from or storing to) a place that is [dangling] or [based on
   a misaligned pointer].
+
+r[undefined.place-projection]
 * Performing a place projection that violates the requirements of [in-bounds
   pointer arithmetic][offset]. A place projection is a [field
   expression][project-field], a [tuple index expression][project-tuple], or an
   [array/slice index expression][project-slice].
+
+r[undefined.alias]
 * Breaking the [pointer aliasing rules]. `Box<T>`, `&mut T` and `&T` follow
   LLVM’s scoped [noalias] model, except if the `&T` contains an
   [`UnsafeCell<U>`]. References and boxes must not be [dangling] while they are
@@ -49,22 +60,36 @@ Please read the [Rustonomicon] before writing unsafe code.
   All this also applies when values of these
   types are passed in a (nested) field of a compound type, but not behind
   pointer indirections.
+
+r[undefined.immutable]
 * Mutating immutable bytes. All bytes inside a [`const`] item are immutable.
   The bytes owned by an immutable binding or immutable `static` are immutable, unless those bytes are part of an [`UnsafeCell<U>`].
 
   Moreover, the bytes [pointed to] by a shared reference, including transitively through other references (both shared and mutable) and `Box`es, 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).
+
+r[undefined.intrinsic]
 * Invoking undefined behavior via compiler intrinsics.
+
+r[undefined.target-feature]
 * 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.
+
+r[undefined.call]
 * Calling a function with the wrong call ABI or unwinding from a function with the wrong unwind ABI.
+
+r[undefined.invalid]
 * Producing an [invalid value][invalid-values]. "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.
+
+r[undefined.asm]
 * Incorrect use of inline assembly. For more details, refer to the [rules] to
   follow when writing code that uses inline assembly.
+
+r[undefined.const-transmute-ptr2int]
 * **In [const context](const_eval.md#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).
@@ -79,11 +104,15 @@ Please read the [Rustonomicon] before writing unsafe code.
 
 ### Pointed-to bytes
 
+r[undefined.pointed-to]
 The span of bytes a pointer or reference "points to" is determined by the pointer value and the size of the pointee type (using `size_of_val`).
 
 ### Places based on misaligned pointers
 [based on a misaligned pointer]: #places-based-on-misaligned-pointers
 
+r[undefined.misaligned]
+
+r[undefined.misaligned.general]
 A place is said to be "based on a misaligned pointer" if the last `*` projection
 during place computation was performed on a pointer that was not aligned for its
 type. (If there is no `*` projection in the place expression, then this is
@@ -101,69 +130,114 @@ alignment 1). In other words, the alignment requirement derives from the type of
 the pointer that was dereferenced, *not* the type of the field that is being
 accessed.
 
+r[undefined.misaligned.load-store]
 Note that a place based on a misaligned pointer only leads to Undefined Behavior
-when it is loaded from or stored to. `addr_of!`/`addr_of_mut!` on such a place
-is allowed. `&`/`&mut` on a place requires the alignment of the field type (or
+when it is loaded from or stored to.
+
+r[undefined.misaligned.addr_of]
+`addr_of!`/`addr_of_mut!` on such a place is allowed.
+
+r[undefined.misaligned.reference]
+`&`/`&mut` on a place requires the alignment of the field type (or
 else the program would be "producing an invalid value"), which generally is a
-less restrictive requirement than being based on an aligned pointer. Taking a
-reference will lead to a compiler error in cases where the field type might be
+less restrictive requirement than being based on an aligned pointer.
+
+r[undefined.misaligned.packed]
+Taking a reference will lead to a compiler error in cases where the field type might be
 more aligned than the type that contains it, i.e., `repr(packed)`. This means
 that being based on an aligned pointer is always sufficient to ensure that the
 new reference is aligned, but it is not always necessary.
 
 ### Dangling pointers
 [dangling]: #dangling-pointers
 
+r[undefined.dangling]
+
+r[undefined.dangling.general]
 A reference/pointer is "dangling" if 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).
 
+r[undefined.dangling.zero-size]
 If the size is 0, then the pointer is trivially never "dangling"
 (even if it is a null pointer).
 
+r[undefined.dangling.dynamic-size]
 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 `size_of_val`)
+entire range, so it is important that the length metadata is never too large.
+
+r[undefined.dangling.alloc-limit]
+In particular, the dynamic size of a Rust value (as determined by `size_of_val`)
 must never exceed `isize::MAX`, since it is impossible for a single allocation
 to be larger than `isize::MAX`.
 
 ### Invalid values
 [invalid-values]: #invalid-values
 
+r[undefined.validity]
+
+
+r[undefined.validity.general]
 The Rust compiler assumes that all values produced during program execution are
 "valid", and producing an invalid value is hence immediate UB.
 
 Whether a value is valid depends on the type:
+
+r[undefined.validity.bool]
 * A [`bool`] value must be `false` (`0`) or `true` (`1`).
+
+r[undefined.validity.fn-pointer]
 * A `fn` pointer value must be non-null.
+
+r[undefined.validity.char]
 * A `char` value must not be a surrogate (i.e., must not be in the range `0xD800..=0xDFFF`) and must be equal to or less than `char::MAX`.
+
+r[undefined.validity.never]
 * A `!` value must never exist.
+
+r[undefined.validity.scalar]
 * An integer (`i*`/`u*`), floating point value (`f*`), or raw pointer must be
   initialized, i.e., must not be obtained from [uninitialized memory][undef].
+
+
+r[undefined.validity.str]
 * A `str` value is treated like `[u8]`, i.e. it must be initialized.
+
+r[undefined.validity.enum]
 * An `enum` must have a valid discriminant, and all fields of the variant indicated by that discriminant must be valid at their respective type.
+
+r[undefined.validity.struct]
 * A `struct`, tuple, and array requires all fields/elements to be valid at their respective type.
+
+r[undefined.validity.union]
 * For a `union`, the exact validity requirements are not decided yet.
   Obviously, all values that can be created entirely in safe code are valid.
   If the union has a zero-sized field, then every possible value is valid.
   Further details are [still being debated](https://github.com/rust-lang/unsafe-code-guidelines/issues/438).
+
+r[undefined.validity.reference-box]
 * A reference or [`Box<T>`] must be aligned, it cannot be [dangling], and it must point to a valid value
   (in case of dynamically sized types, using the actual dynamic type of the
   pointee as determined by the metadata).
   Note that the last point (about pointing to a valid value) remains a subject of some debate.
+
+r[undefined.validity.wide]
 * The metadata of a wide reference, [`Box<T>`], or raw pointer must match
   the type of the unsized tail:
   * `dyn Trait` metadata must be a pointer to a compiler-generated vtable for `Trait`.
     (For raw pointers, this requirement remains a subject of some debate.)
   * Slice (`[T]`) metadata must be a valid `usize`.
     Furthermore, for wide references and [`Box<T>`], slice metadata is invalid
     if it makes the total size of the pointed-to value bigger than `isize::MAX`.
+
+r[undefined.validity.valid-range]
 * If a type has a custom range of a valid values, then a valid value must be in that range.
   In the standard library, this affects [`NonNull<T>`] and [`NonZero<T>`].
 
   > **Note**: `rustc` achieves this with the unstable
   > `rustc_layout_scalar_valid_range_*` attributes.
 
+r[undefined.validity.undef]
 **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 `union`s and in "padding"