mod.rs - source
Skip to main content core/ptr/ mod.rs 1 //! Manually manage memory through raw pointers. 2 //! 3 //! *[See also the pointer primitive types](pointer).* 4 //! 5 //! # Safety 6 //! 7 //! Many functions in this module take raw pointers as arguments and read from or write to them. For 8 //! this to be safe, these pointers must be *valid* for the given access. Whether a pointer is valid 9 //! depends on the operation it is used for (read or write), and the extent of the memory that is 10 //! accessed (i.e., how many bytes are read/written) -- it makes no sense to ask "is this pointer 11 //! valid"; one has to ask "is this pointer valid for a given access".
Most functions use `*mut T` 12 //! and `*const T` to access only a single value, in which case the documentation omits the size and 13 //! implicitly assumes it to be `size_of::<T>()` bytes. 14 //! 15 //! The precise rules for validity are not determined yet. The guarantees that are 16 //! provided at this point are very minimal: 17 //! 18 //! * A [null] pointer is *never* valid for reads/writes. 19 //! * For memory accesses of [size zero][zst], *every* non-null pointer is valid for reads/writes.
20 //! The following points are only concerned with non-zero-sized accesses. 21 //! * For a pointer to be valid for reads/writes, it is necessary, but not always sufficient, that 22 //! the pointer be *dereferenceable*. The [provenance] of the pointer is used to determine which 23 //! [allocation] it is derived from; a pointer is dereferenceable if the memory range of the given 24 //! size starting at the pointer is entirely contained within the bounds of that allocation.
Note 25 //! that in Rust, every (stack-allocated) variable is considered a separate allocation. 26 //! * All accesses performed by functions in this module are *non-atomic* in the sense 27 //! of [atomic operations] used to synchronize between threads. This means it is 28 //! undefined behavior to perform two concurrent accesses to the same location from different 29 //! threads unless both accesses only read from memory.
30 //! * The result of casting a reference to a pointer is valid for reads/writes for as long as the 31 //! underlying allocation is live and no reference (just raw pointers) is used to 32 //! access the same memory. That is, reference and pointer accesses cannot be 33 //! interleaved. 34 //! 35 //! These axioms, along with careful use of [`offset`] for pointer arithmetic, 36 //! are enough to correctly implement many useful things in unsafe code.
Stronger guarantees 37 //! will be provided eventually, as the [aliasing] rules are being determined. For more 38 //! information, see the [book] as well as the section in the reference devoted 39 //! to [undefined behavior][ub]. 40 //! 41 //! Note that some operations such as [`read`] and [`write`][`write()`] do allow null pointers if 42 //! the total size of the access is zero. However, other operations internally convert pointers into 43 //! references.
Therefore, the general notion of "valid for reads/writes" excludes null pointers, 44 //! and the specific operations that permit null pointers mention that as an exception. Furthermore, 45 //! [`read_volatile`] and [`write_volatile`] can be used in even more situations; see their 46 //! documentation for details. 47 //! 48 //! We say that a pointer is "dangling" if it is not valid for any non-zero-sized accesses. This 49 //! means out-of-bounds pointers, pointers to freed memory, null pointers, and pointers created with 50 //! [`NonNull::dangling`] are all dangling.
51 //! 52 //! ## Alignment 53 //! 54 //! Valid raw pointers as defined above are not necessarily properly aligned (where 55 //! "proper" alignment is defined by the pointee type, i.e., `*const T` must be 56 //! aligned to `align_of::<T>()`). However, most functions require their 57 //! arguments to be properly aligned, and will explicitly state 58 //! this requirement in their documentation. Notable exceptions to this are 59 //! [`read_unaligned`] and [`write_unaligned`].
60 //! 61 //! When a function requires proper alignment, it does so even if the access 62 //! has size 0, i.e., even if memory is not actually touched. Consider using 63 //! [`NonNull::dangling`] in such cases. 64 //! 65 //! ## Pointer to reference conversion 66 //! 67 //! When converting a pointer to a reference (e.g. via `&*ptr` or `&mut *ptr`), 68 //! there are several rules that must be followed: 69 //! 70 //! * The pointer must be properly aligned.
71 //! 72 //! * It must be non-null. 73 //! 74 //! * It must be "dereferenceable" in the sense defined above. 75 //! 76 //! * The pointer must point to a [valid value] of type `T`. 77 //! 78 //! * You must enforce Rust's aliasing rules. The exact aliasing rules are not decided yet, so we 79 //! only give a rough overview here. The rules also depend on whether a mutable or a shared 80 //! reference is being created. 81 //! * When creating a mutable reference, then while this reference exists, the memory it points to 82 //! must not get accessed (read or written) through any other pointer or reference not derived 83 //! from this reference.
84 //! * When creating a shared reference, then while this reference exists, the memory it points to 85 //! must not get mutated (except inside `UnsafeCell`). 86 //! 87 //! If a pointer follows all of these rules, it is said to be 88 //! *convertible to a (mutable or shared) reference*. 89 // ^ we use this term instead of saying that the produced reference must 90 // be valid, as the validity of a reference is easily confused for the 91 // validity of the thing it refers to, and while the two concepts are 92 // closely related, they are not identical.
93 //! 94 //! These rules apply even if the result is unused! 95 //! (The part about being initialized is not yet fully decided, but until 96 //! it is, the only safe approach is to ensure that they are indeed initialized.) 97 //! 98 //! An example of the implications of the above rules is that an expression such 99 //! as `unsafe { &*(0 as *const u8) }` is Immediate Undefined Behavior. 100 //! 101 //! [valid value]: ../../reference/behavior-considered-undefined.html#invalid-values 102 //!
103 //! ## Allocation 104 //! 105 //! <a id="allocated-object"></a> <!-- keep old URLs working --> 106 //! 107 //! An *allocation* is a subset of program memory which is addressable 108 //! from Rust, and within which pointer arithmetic is possible. Examples of 109 //! allocations include heap allocations, stack-allocated variables, 110 //! statics, and consts. The safety preconditions of some Rust operations - 111 //! such as `offset` and field projections (`expr.field`) - are defined in 112 //! terms of the allocations on which they operate.
113 //! 114 //! An allocation has a base address, a size, and a set of memory 115 //! addresses. It is possible for an allocation to have zero size, but 116 //! such an allocation will still have a base address. The base address 117 //! of an allocation is not necessarily unique. While it is currently the 118 //! case that an allocation always has a set of memory addresses which is 119 //! fully contiguous (i.e., has no "holes"), there is no guarantee that this 120 //! will not change in the future.
121 //! 122 //! An allocation can be either mutable (the common case) or *read-only*. 123 //! Read-only allocations are implicitly introduced by the compiler for `static` items without 124 //! interior mutability and for `const` items. Writing or creating a mutable reference to a 125 //! read-only allocation is undefined behavior, and most atomic operations are not supported 126 //! for read-only allocations either (see [here][atomic-ro] for exceptions).
127 //! Additionally, some target-specific intrinsics are not supported on read-only 128 //! allocations even if their memory write is masked off, such as [`_mm_maskmoveu_si128`]. 129 //! 130 //! [atomic-ro]: crate::sync::atomic#atomic-accesses-to-read-only-memory 131 //! [`_mm_maskmoveu_si128`]: ..
The rest of this page is on the live site.