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//! * For memory accesses of [size zero][zst], *every* pointer is valid, including the [null]
19//! pointer. The following points are only concerned with non-zero-sized accesses.
20//! * A [null] pointer is *never* valid.
21//! * For a pointer to be valid, it is necessary, but not always sufficient, that the pointer be
22//! *dereferenceable*. The [provenance] of the pointer is used to determine which [allocation]
23//! it is derived from; a pointer is dereferenceable if the memory range of the given size
24//! 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. Notice that this explicitly
30//! includes [`read_volatile`] and [`write_volatile`]: Volatile accesses cannot
31//! be used for inter-thread synchronization.
32//! * The result of casting a reference to a pointer is valid for as long as the
33//! underlying allocation is live and no reference (just raw pointers) is used to
34//! access the same memory. That is, reference and pointer accesses cannot be
35//! interleaved.
36//!
37//! These axioms, along with careful use of [`offset`] for pointer arithmetic,
38//! are enough to correctly implement many useful things in unsafe code. Stronger guarantees
39//! will be provided eventually, as the [aliasing] rules are being determined. For more
40//! information, see the [book] as well as the section in the reference devoted
41//! to [undefined behavior][ub].
42//!
43//! We say that a pointer is "dangling" if it is not valid for any non-zero-sized accesses. This
44//! means out-of-bounds pointers, pointers to freed memory, null pointers, and pointers created with
45//! [`NonNull::dangling`] are all dangling.
46//!
47//! ## Alignment
48//!
49//! Valid raw pointers as defined above are not necessarily properly aligned (where
50//! "proper" alignment is defined by the pointee type, i.e., `*const T` must be
51//! aligned to `align_of::<T>()`). However, most functions require their
52//! arguments to be properly aligned, and will explicitly state
53//! this requirement in their documentation. Notable exceptions to this are
54//! [`read_unaligned`] and [`write_unaligned`].
55//!
56//! When a function requires proper alignment, it does so even if the access
57//! has size 0, i.e., even if memory is not actually touched. Consider using
58//! [`NonNull::dangling`] in such cases.
59//!
60//! ## Pointer to reference conversion
61//!
62//! When converting a pointer to a reference (e.g. via `&*ptr` or `&mut *ptr`),
63//! there are several rules that must be followed:
64//!
65//! * The pointer must be properly aligned.
66//!
67//! * It must be non-null.
68//!
69//! * It must be "dereferenceable" in the sense defined above.
70//!
71//! * The pointer must point to a [valid value] of type `T`.
72//!
73//! * You must enforce Rust's aliasing rules. The exact aliasing rules are not decided yet, so we
74//! only give a rough overview here. The rules also depend on whether a mutable or a shared
75//! reference is being created.
76//! * When creating a mutable reference, then while this reference exists, the memory it points to
77//! must not get accessed (read or written) through any other pointer or reference not derived
78//! from this reference.
79//! * When creating a shared reference, then while this reference exists, the memory it points to
80//! must not get mutated (except inside `UnsafeCell`).
81//!
82//! If a pointer follows all of these rules, it is said to be
83//! *convertible to a (mutable or shared) reference*.
84// ^ we use this term instead of saying that the produced reference must
85// be valid, as the validity of a reference is easily confused for the
86// validity of the thing it refers to, and while the two concepts are
87// closely related, they are not identical.
88//!
89//! These rules apply even if the result is unused!
90//! (The part about being initialized is not yet fully decided, but until
91//! it is, the only safe approach is to ensure that they are indeed initialized.)
92//!
93//! An example of the implications of the above rules is that an expression such
94//! as `unsafe { &*(0 as *const u8) }` is Immediate Undefined Behavior.
95//!
96//! [valid value]: ../../reference/behavior-considered-undefined.html#invalid-values
97//!
98//! ## Allocation
99//!
100//! <a id="allocated-object"></a> <!-- keep old URLs working -->
101//!
102//! An *allocation* is a subset of program memory which is addressable
103//! from Rust, and within which pointer arithmetic is possible. Examples of
104//! allocations include heap allocations, stack-allocated variables,
105//! statics, and consts. The safety preconditions of some Rust operations -
106//! such as `offset` and field projections (`expr.field`) - are defined in
107//! terms of the allocations on which they operate.
108//!
109//! An allocation has a base address, a size, and a set of memory
110//! addresses. It is possible for an allocation to have zero size, but
111//! such an allocation will still have a base address. The base address
112//! of an allocation is not necessarily unique. While it is currently the
113//! case that an allocation always has a set of memory addresses which is
114//! fully contiguous (i.e., has no "holes"), there is no guarantee that this
115//! will not change in the future.
116//!
117//! For any allocation with `base` address, `size`, and a set of
118//! `addresses`, the following are guaranteed:
119//! - For all addresses `a` in `addresses`, `a` is in the range `base .. (base +
120//! size)` (note that this requires `a < base + size`, not `a <= base + size`)
121//! - `base` is not equal to [`null()`] (i.e., the address with the numerical
122//! value 0)
123//! - `base + size <= usize::MAX`
124//! - `size <= isize::MAX`
125//!
126//! As a consequence of these guarantees, given any address `a` within the set
127//! of addresses of an allocation:
128//! - It is guaranteed that `a - base` does not overflow `isize`
129//! - It is guaranteed that `a - base` is non-negative
130//! - It is guaranteed that, given `o = a - base` (i.e., the offset of `a` within
131//! the allocation), `base + o` will not wrap around the address space (in
132//! other words, will not overflow `usize`)
133//!
134//! [`null()`]: null
135//!
136//! # Provenance
137//!
138//! Pointers are not *simply* an "integer" or "address". For instance, it's uncontroversial
139//! to say that a Use After Free is clearly Undefined Behavior, even if you "get lucky"
140//! and the freed memory gets reallocated before your read/write (in fact this is the
141//! worst-case scenario, UAFs would be much less concerning if this didn't happen!).
142//! As another example, consider that [`wrapping_offset`] is documented to "remember"
143//! the allocation that the original pointer points to, even if it is offset far
144//! outside the memory range occupied by that allocation.
145//! To rationalize claims like this, pointers need to somehow be *more* than just their addresses:
146//! they must have **provenance**.
147//!
148//! A pointer value in Rust semantically contains the following information:
149//!
150//! * The **address** it points to, which can be represented by a `usize`.
151//! * The **provenance** it has, defining the memory it has permission to access. Provenance can be
152//! absent, in which case the pointer does not have permission to access any memory.
153//!
154//! The exact structure of provenance is not yet specified, but the permission defined by a
155//! pointer's provenance have a *spatial* component, a *temporal* component, and a *mutability*
156//! component:
157//!
158//! * Spatial: The set of memory addresses that the pointer is allowed to access.
159//! * Temporal: The timespan during which the pointer is allowed to access those memory addresses.
160//! * Mutability: Whether the pointer may only access the memory for reads, or also access it for
161//! writes. Note that this can interact with the other components, e.g. a pointer might permit
162//! mutation only for a subset of addresses, or only for a subset of its maximal timespan.
163//!
164//! When an [allocation] is created, it has a unique Original Pointer. For alloc
165//! APIs this is literally the pointer the call returns, and for local variables and statics,
166//! this is the name of the variable/static. (This is mildly overloading the term "pointer"
167//! for the sake of brevity/exposition.)
168//!
169//! The Original Pointer for an allocation has provenance that constrains the *spatial*
170//! permissions of this pointer to the memory range of the allocation, and the *temporal*
171//! permissions to the lifetime of the allocation. Provenance is implicitly inherited by all
172//! pointers transitively derived from the Original Pointer through operations like [`offset`],
173//! borrowing, and pointer casts. Some operations may *shrink* the permissions of the derived
174//! provenance, limiting how much memory it can access or how long it's valid for (i.e. borrowing a
175//! subfield and subslicing can shrink the spatial component of provenance, and all borrowing can
176//! shrink the temporal component of provenance). However, no operation can ever *grow* the
177//! permissions of the derived provenance: even if you "know" there is a larger allocation, you
178//! can't derive a pointer with a larger provenance. Similarly, you cannot "recombine" two
179//! contiguous provenances back into one (i.e. with a `fn merge(&[T], &[T]) -> &[T]`).
180//!
181//! A reference to a place always has provenance over at least the memory that place occupies.
182//! A reference to a slice always has provenance over at least the range that slice describes.
183//! Whether and when exactly the provenance of a reference gets "shrunk" to *exactly* fit
184//! the memory it points to is not yet determined.
185//!
186//! A *shared* reference only ever has provenance that permits reading from memory,
187//! and never permits writes, except inside [`UnsafeCell`].
188//!
189//! Provenance can affect whether a program has undefined behavior:
190//!
191//! * It is undefined behavior to access memory through a pointer that does not have provenance over
192//! that memory. Note that a pointer "at the end" of its provenance is not actually outside its
193//! provenance, it just has 0 bytes it can load/store. Zero-sized accesses do not require any
194//! provenance since they access an empty range of memory.
195//!
196//! * It is undefined behavior to [`offset`] a pointer across a memory range that is not contained
197//! in the allocation it is derived from, or to [`offset_from`] two pointers not derived
198//! from the same allocation. Provenance is used to say what exactly "derived from" even
199//! means: the lineage of a pointer is traced back to the Original Pointer it descends from, and
200//! that identifies the relevant allocation. In particular, it's always UB to offset a
201//! pointer derived from something that is now deallocated, except if the offset is 0.
202//!
203//! But it *is* still sound to:
204//!
205//! * Create a pointer without provenance from just an address (see [`without_provenance`]). Such a
206//! pointer cannot be used for memory accesses (except for zero-sized accesses). This can still be
207//! useful for sentinel values like `null` *or* to represent a tagged pointer that will never be
208//! dereferenceable. In general, it is always sound for an integer to pretend to be a pointer "for
209//! fun" as long as you don't use operations on it which require it to be valid (non-zero-sized
210//! offset, read, write, etc).
211//!
212//! * Forge an allocation of size zero at any sufficiently aligned non-null address.
213//! i.e. the usual "ZSTs are fake, do what you want" rules apply.
214//!
215//! * [`wrapping_offset`] a pointer outside its provenance. This includes pointers
216//! which have "no" provenance. In particular, this makes it sound to do pointer tagging tricks.
217//!
218//! * Compare arbitrary pointers by address. Pointer comparison ignores provenance and addresses
219//! *are* just integers, so there is always a coherent answer, even if the pointers are dangling
220//! or from different provenances. Note that if you get "lucky" and notice that a pointer at the
221//! end of one allocation is the "same" address as the start of another allocation,
222//! anything you do with that fact is *probably* going to be gibberish. The scope of that
223//! gibberish is kept under control by the fact that the two pointers *still* aren't allowed to
224//! access the other's allocation (bytes), because they still have different provenance.
225//!
226//! Note that the full definition of provenance in Rust is not decided yet, as this interacts
227//! with the as-yet undecided [aliasing] rules.
228//!
229//! ## Pointers Vs Integers
230//!
231//! From this discussion, it becomes very clear that a `usize` *cannot* accurately represent a pointer,
232//! and converting from a pointer to a `usize` is generally an operation which *only* extracts the
233//! address. Converting this address back into pointer requires somehow answering the question:
234//! which provenance should the resulting pointer have?
235//!
236//! Rust provides two ways of dealing with this situation: *Strict Provenance* and *Exposed Provenance*.
237//!
238//! Note that a pointer *can* represent a `usize` (via [`without_provenance`]), so the right type to
239//! use in situations where a value is "sometimes a pointer and sometimes a bare `usize`" is a
240//! pointer type.
241//!
242//! ## Strict Provenance
243//!
244//! "Strict Provenance" refers to a set of APIs designed to make working with provenance more
245//! explicit. They are intended as substitutes for casting a pointer to an integer and back.
246//!
247//! Entirely avoiding integer-to-pointer casts successfully side-steps the inherent ambiguity of
248//! that operation. This benefits compiler optimizations, and it is pretty much a requirement for
249//! using tools like [Miri] and architectures like [CHERI] that aim to detect and diagnose pointer
250//! misuse.
251//!
252//! The key insight to making programming without integer-to-pointer casts *at all* viable is the
253//! [`with_addr`] method:
254//!
255//! ```text
256//! /// Creates a new pointer with the given address.
257//! ///
258//! /// This performs the same operation as an `addr as ptr` cast, but copies
259//! /// the *provenance* of `self` to the new pointer.
260//! /// This allows us to dynamically preserve and propagate this important
261//! /// information in a way that is otherwise impossible with a unary cast.
262//! ///
263//! /// This is equivalent to using `wrapping_offset` to offset `self` to the
264//! /// given address, and therefore has all the same capabilities and restrictions.
265//! pub fn with_addr(self, addr: usize) -> Self;
266//! ```
267//!
268//! So you're still able to drop down to the address representation and do whatever
269//! clever bit tricks you want *as long as* you're able to keep around a pointer
270//! into the allocation you care about that can "reconstitute" the provenance.
271//! Usually this is very easy, because you only are taking a pointer, messing with the address,
272//! and then immediately converting back to a pointer. To make this use case more ergonomic,
273//! we provide the [`map_addr`] method.
274//!
275//! To help make it clear that code is "following" Strict Provenance semantics, we also provide an
276//! [`addr`] method which promises that the returned address is not part of a
277//! pointer-integer-pointer roundtrip. In the future we may provide a lint for pointer<->integer
278//! casts to help you audit if your code conforms to strict provenance.
279//!
280//! ### Using Strict Provenance
281//!
282//! Most code needs no changes to conform to strict provenance, as the only really concerning
283//! operation is casts from `usize` to a pointer. For code which *does* cast a `usize` to a pointer,
284//! the scope of the change depends on exactly what you're doing.
285//!
286//! In general, you just need to make sure that if you want to convert a `usize` address to a
287//! pointer and then use that pointer to read/write memory, you need to keep around a pointer
288//! that has sufficient provenance to perform that read/write itself. In this way all of your
289//! casts from an address to a pointer are essentially just applying offsets/indexing.
290//!
291//! This is generally trivial to do for simple cases like tagged pointers *as long as you
292//! represent the tagged pointer as an actual pointer and not a `usize`*. For instance:
293//!
294//! ```
295//! unsafe {
296//! // A flag we want to pack into our pointer
297//! static HAS_DATA: usize = 0x1;
298//! static FLAG_MASK: usize = !HAS_DATA;
299//!
300//! // Our value, which must have enough alignment to have spare least-significant-bits.
301//! let my_precious_data: u32 = 17;
302//! assert!(align_of::<u32>() > 1);
303//!
304//! // Create a tagged pointer
305//! let ptr = &my_precious_data as *const u32;
306//! let tagged = ptr.map_addr(|addr| addr | HAS_DATA);
307//!
308//! // Check the flag:
309//! if tagged.addr() & HAS_DATA != 0 {
310//! // Untag and read the pointer
311//! let data = *tagged.map_addr(|addr| addr & FLAG_MASK);
312//! assert_eq!(data, 17);
313//! } else {
314//! unreachable!()
315//! }
316//! }
317//! ```
318//!
319//! (Yes, if you've been using [`AtomicUsize`] for pointers in concurrent datastructures, you should
320//! be using [`AtomicPtr`] instead. If that messes up the way you atomically manipulate pointers,
321//! we would like to know why, and what needs to be done to fix it.)
322//!
323//! Situations where a valid pointer *must* be created from just an address, such as baremetal code
324//! accessing a memory-mapped interface at a fixed address, cannot currently be handled with strict
325//! provenance APIs and should use [exposed provenance](#exposed-provenance).
326//!
327//! ## Exposed Provenance
328//!
329//! As discussed above, integer-to-pointer casts are not possible with Strict Provenance APIs.
330//! This is by design: the goal of Strict Provenance is to provide a clear specification that we are
331//! confident can be formalized unambiguously and can be subject to precise formal reasoning.
332//! Integer-to-pointer casts do not (currently) have such a clear specification.
333//!
334//! However, there exist situations where integer-to-pointer casts cannot be avoided, or
335//! where avoiding them would require major refactoring. Legacy platform APIs also regularly assume
336//! that `usize` can capture all the information that makes up a pointer.
337//! Bare-metal platforms can also require the synthesis of a pointer "out of thin air" without
338//! anywhere to obtain proper provenance from.
339//!
340//! Rust's model for dealing with integer-to-pointer casts is called *Exposed Provenance*. However,
341//! the semantics of Exposed Provenance are on much less solid footing than Strict Provenance, and
342//! at this point it is not yet clear whether a satisfying unambiguous semantics can be defined for
343//! Exposed Provenance. (If that sounds bad, be reassured that other popular languages that provide
344//! integer-to-pointer casts are not faring any better.) Furthermore, Exposed Provenance will not
345//! work (well) with tools like [Miri] and [CHERI].
346//!
347//! Exposed Provenance is provided by the [`expose_provenance`] and [`with_exposed_provenance`] methods,
348//! which are equivalent to `as` casts between pointers and integers.
349//! - [`expose_provenance`] is a lot like [`addr`], but additionally adds the provenance of the
350//! pointer to a global list of 'exposed' provenances. (This list is purely conceptual, it exists
351//! for the purpose of specifying Rust but is not materialized in actual executions, except in
352//! tools like [Miri].)
353//! Memory which is outside the control of the Rust abstract machine (MMIO registers, for example)
354//! is always considered to be exposed, so long as this memory is disjoint from memory that will
355//! be used by the abstract machine such as the stack, heap, and statics.
356//! - [`with_exposed_provenance`] can be used to construct a pointer with one of these previously
357//! 'exposed' provenances. [`with_exposed_provenance`] takes only `addr: usize` as arguments, so
358//! unlike in [`with_addr`] there is no indication of what the correct provenance for the returned
359//! pointer is -- and that is exactly what makes integer-to-pointer casts so tricky to rigorously
360//! specify! The compiler will do its best to pick the right provenance for you, but currently we
361//! cannot provide any guarantees about which provenance the resulting pointer will have. Only one
362//! thing is clear: if there is *no* previously 'exposed' provenance that justifies the way the
363//! returned pointer will be used, the program has undefined behavior.
364//!
365//! If at all possible, we encourage code to be ported to [Strict Provenance] APIs, thus avoiding
366//! the need for Exposed Provenance. Maximizing the amount of such code is a major win for avoiding
367//! specification complexity and to facilitate adoption of tools like [CHERI] and [Miri] that can be
368//! a big help in increasing the confidence in (unsafe) Rust code. However, we acknowledge that this
369//! is not always possible, and offer Exposed Provenance as a way to explicit "opt out" of the
370//! well-defined semantics of Strict Provenance, and "opt in" to the unclear semantics of
371//! integer-to-pointer casts.
372//!
373//! [aliasing]: ../../nomicon/aliasing.html
374//! [allocation]: #allocation
375//! [provenance]: #provenance
376//! [book]: ../../book/ch19-01-unsafe-rust.html#dereferencing-a-raw-pointer
377//! [ub]: ../../reference/behavior-considered-undefined.html
378//! [zst]: ../../nomicon/exotic-sizes.html#zero-sized-types-zsts
379//! [atomic operations]: crate::sync::atomic
380//! [`offset`]: pointer::offset
381//! [`offset_from`]: pointer::offset_from
382//! [`wrapping_offset`]: pointer::wrapping_offset
383//! [`with_addr`]: pointer::with_addr
384//! [`map_addr`]: pointer::map_addr
385//! [`addr`]: pointer::addr
386//! [`AtomicUsize`]: crate::sync::atomic::AtomicUsize
387//! [`AtomicPtr`]: crate::sync::atomic::AtomicPtr
388//! [`expose_provenance`]: pointer::expose_provenance
389//! [`with_exposed_provenance`]: with_exposed_provenance
390//! [Miri]: https://github.com/rust-lang/miri
391//! [CHERI]: https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/
392//! [Strict Provenance]: #strict-provenance
393//! [`UnsafeCell`]: core::cell::UnsafeCell
394
395#![stable(feature = "rust1", since = "1.0.0")]
396// There are many unsafe functions taking pointers that don't dereference them.
397#![allow(clippy::not_unsafe_ptr_arg_deref)]
398
399use crate::cmp::Ordering;
400use crate::intrinsics::const_eval_select;
401use crate::marker::FnPtr;
402use crate::mem::{self, MaybeUninit, SizedTypeProperties};
403use crate::num::NonZero;
404use crate::{fmt, hash, intrinsics, ub_checks};
405
406mod alignment;
407#[unstable(feature = "ptr_alignment_type", issue = "102070")]
408pub use alignment::Alignment;
409
410mod metadata;
411#[unstable(feature = "ptr_metadata", issue = "81513")]
412pub use metadata::{DynMetadata, Pointee, Thin, from_raw_parts, from_raw_parts_mut, metadata};
413
414mod non_null;
415#[stable(feature = "nonnull", since = "1.25.0")]
416pub use non_null::NonNull;
417
418mod unique;
419#[unstable(feature = "ptr_internals", issue = "none")]
420pub use unique::Unique;
421
422mod const_ptr;
423mod mut_ptr;
424
425// Some functions are defined here because they accidentally got made
426// available in this module on stable. See <https://github.com/rust-lang/rust/issues/15702>.
427// (`transmute` also falls into this category, but it cannot be wrapped due to the
428// check that `T` and `U` have the same size.)
429
430/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
431/// and destination must *not* overlap.
432///
433/// For regions of memory which might overlap, use [`copy`] instead.
434///
435/// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but
436/// with the source and destination arguments swapped,
437/// and `count` counting the number of `T`s instead of bytes.
438///
439/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
440/// requirements of `T`. The initialization state is preserved exactly.
441///
442/// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy
443///
444/// # Safety
445///
446/// Behavior is undefined if any of the following conditions are violated:
447///
448/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
449///
450/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
451///
452/// * Both `src` and `dst` must be properly aligned.
453///
454/// * The region of memory beginning at `src` with a size of `count *
455/// size_of::<T>()` bytes must *not* overlap with the region of memory
456/// beginning at `dst` with the same size.
457///
458/// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
459/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
460/// in the region beginning at `*src` and the region beginning at `*dst` can
461/// [violate memory safety][read-ownership].
462///
463/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
464/// `0`, the pointers must be properly aligned.
465///
466/// [`read`]: crate::ptr::read
467/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
468/// [valid]: crate::ptr#safety
469///
470/// # Examples
471///
472/// Manually implement [`Vec::append`]:
473///
474/// ```
475/// use std::ptr;
476///
477/// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
478/// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
479/// let src_len = src.len();
480/// let dst_len = dst.len();
481///
482/// // Ensure that `dst` has enough capacity to hold all of `src`.
483/// dst.reserve(src_len);
484///
485/// unsafe {
486/// // The call to add is always safe because `Vec` will never
487/// // allocate more than `isize::MAX` bytes.
488/// let dst_ptr = dst.as_mut_ptr().add(dst_len);
489/// let src_ptr = src.as_ptr();
490///
491/// // Truncate `src` without dropping its contents. We do this first,
492/// // to avoid problems in case something further down panics.
493/// src.set_len(0);
494///
495/// // The two regions cannot overlap because mutable references do
496/// // not alias, and two different vectors cannot own the same
497/// // memory.
498/// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);
499///
500/// // Notify `dst` that it now holds the contents of `src`.
501/// dst.set_len(dst_len + src_len);
502/// }
503/// }
504///
505/// let mut a = vec!['r'];
506/// let mut b = vec!['u', 's', 't'];
507///
508/// append(&mut a, &mut b);
509///
510/// assert_eq!(a, &['r', 'u', 's', 't']);
511/// assert!(b.is_empty());
512/// ```
513///
514/// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append
515#[doc(alias = "memcpy")]
516#[stable(feature = "rust1", since = "1.0.0")]
517#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
518#[inline(always)]
519#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
520#[rustc_diagnostic_item = "ptr_copy_nonoverlapping"]
521pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
522 ub_checks::assert_unsafe_precondition!(
523 check_language_ub,
524 "ptr::copy_nonoverlapping requires that both pointer arguments are aligned and non-null \
525 and the specified memory ranges do not overlap",
526 (
527 src: *const () = src as *const (),
528 dst: *mut () = dst as *mut (),
529 size: usize = size_of::<T>(),
530 align: usize = align_of::<T>(),
531 count: usize = count,
532 ) => {
533 let zero_size = count == 0 || size == 0;
534 ub_checks::maybe_is_aligned_and_not_null(src, align, zero_size)
535 && ub_checks::maybe_is_aligned_and_not_null(dst, align, zero_size)
536 && ub_checks::maybe_is_nonoverlapping(src, dst, size, count)
537 }
538 );
539
540 // SAFETY: the safety contract for `copy_nonoverlapping` must be
541 // upheld by the caller.
542 unsafe { crate::intrinsics::copy_nonoverlapping(src, dst, count) }
543}
544
545/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
546/// and destination may overlap.
547///
548/// If the source and destination will *never* overlap,
549/// [`copy_nonoverlapping`] can be used instead.
550///
551/// `copy` is semantically equivalent to C's [`memmove`], but
552/// with the source and destination arguments swapped,
553/// and `count` counting the number of `T`s instead of bytes.
554/// Copying takes place as if the bytes were copied from `src`
555/// to a temporary array and then copied from the array to `dst`.
556///
557/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the
558/// requirements of `T`. The initialization state is preserved exactly.
559///
560/// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove
561///
562/// # Safety
563///
564/// Behavior is undefined if any of the following conditions are violated:
565///
566/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
567///
568/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes, and must remain valid even
569/// when `src` is read for `count * size_of::<T>()` bytes. (This means if the memory ranges
570/// overlap, the `dst` pointer must not be invalidated by `src` reads.)
571///
572/// * Both `src` and `dst` must be properly aligned.
573///
574/// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
575/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
576/// in the region beginning at `*src` and the region beginning at `*dst` can
577/// [violate memory safety][read-ownership].
578///
579/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
580/// `0`, the pointers must be properly aligned.
581///
582/// [`read`]: crate::ptr::read
583/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value
584/// [valid]: crate::ptr#safety
585///
586/// # Examples
587///
588/// Efficiently create a Rust vector from an unsafe buffer:
589///
590/// ```
591/// use std::ptr;
592///
593/// /// # Safety
594/// ///
595/// /// * `ptr` must be correctly aligned for its type and non-zero.
596/// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`.
597/// /// * Those elements must not be used after calling this function unless `T: Copy`.
598/// # #[allow(dead_code)]
599/// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
600/// let mut dst = Vec::with_capacity(elts);
601///
602/// // SAFETY: Our precondition ensures the source is aligned and valid,
603/// // and `Vec::with_capacity` ensures that we have usable space to write them.
604/// unsafe { ptr::copy(ptr, dst.as_mut_ptr(), elts); }
605///
606/// // SAFETY: We created it with this much capacity earlier,
607/// // and the previous `copy` has initialized these elements.
608/// unsafe { dst.set_len(elts); }
609/// dst
610/// }
611/// ```
612#[doc(alias = "memmove")]
613#[stable(feature = "rust1", since = "1.0.0")]
614#[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
615#[inline(always)]
616#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
617#[rustc_diagnostic_item = "ptr_copy"]
618pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize) {
619 // SAFETY: the safety contract for `copy` must be upheld by the caller.
620 unsafe {
621 ub_checks::assert_unsafe_precondition!(
622 check_language_ub,
623 "ptr::copy requires that both pointer arguments are aligned and non-null",
624 (
625 src: *const () = src as *const (),
626 dst: *mut () = dst as *mut (),
627 align: usize = align_of::<T>(),
628 zero_size: bool = T::IS_ZST || count == 0,
629 ) =>
630 ub_checks::maybe_is_aligned_and_not_null(src, align, zero_size)
631 && ub_checks::maybe_is_aligned_and_not_null(dst, align, zero_size)
632 );
633 crate::intrinsics::copy(src, dst, count)
634 }
635}
636
637/// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
638/// `val`.
639///
640/// `write_bytes` is similar to C's [`memset`], but sets `count *
641/// size_of::<T>()` bytes to `val`.
642///
643/// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
644///
645/// # Safety
646///
647/// Behavior is undefined if any of the following conditions are violated:
648///
649/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
650///
651/// * `dst` must be properly aligned.
652///
653/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
654/// `0`, the pointer must be properly aligned.
655///
656/// Additionally, note that changing `*dst` in this way can easily lead to undefined behavior (UB)
657/// later if the written bytes are not a valid representation of some `T`. For instance, the
658/// following is an **incorrect** use of this function:
659///
660/// ```rust,no_run
661/// unsafe {
662/// let mut value: u8 = 0;
663/// let ptr: *mut bool = &mut value as *mut u8 as *mut bool;
664/// let _bool = ptr.read(); // This is fine, `ptr` points to a valid `bool`.
665/// ptr.write_bytes(42u8, 1); // This function itself does not cause UB...
666/// let _bool = ptr.read(); // ...but it makes this operation UB! ⚠️
667/// }
668/// ```
669///
670/// [valid]: crate::ptr#safety
671///
672/// # Examples
673///
674/// Basic usage:
675///
676/// ```
677/// use std::ptr;
678///
679/// let mut vec = vec![0u32; 4];
680/// unsafe {
681/// let vec_ptr = vec.as_mut_ptr();
682/// ptr::write_bytes(vec_ptr, 0xfe, 2);
683/// }
684/// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
685/// ```
686#[doc(alias = "memset")]
687#[stable(feature = "rust1", since = "1.0.0")]
688#[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
689#[inline(always)]
690#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
691#[rustc_diagnostic_item = "ptr_write_bytes"]
692pub const unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize) {
693 // SAFETY: the safety contract for `write_bytes` must be upheld by the caller.
694 unsafe {
695 ub_checks::assert_unsafe_precondition!(
696 check_language_ub,
697 "ptr::write_bytes requires that the destination pointer is aligned and non-null",
698 (
699 addr: *const () = dst as *const (),
700 align: usize = align_of::<T>(),
701 zero_size: bool = T::IS_ZST || count == 0,
702 ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, zero_size)
703 );
704 crate::intrinsics::write_bytes(dst, val, count)
705 }
706}
707
708/// Executes the destructor (if any) of the pointed-to value.
709///
710/// This is almost the same as calling [`ptr::read`] and discarding
711/// the result, but has the following advantages:
712// FIXME: say something more useful than "almost the same"?
713// There are open questions here: `read` requires the value to be fully valid, e.g. if `T` is a
714// `bool` it must be 0 or 1, if it is a reference then it must be dereferenceable. `drop_in_place`
715// only requires that `*to_drop` be "valid for dropping" and we have not defined what that means. In
716// Miri it currently (May 2024) requires nothing at all for types without drop glue.
717///
718/// * It is *required* to use `drop_in_place` to drop unsized types like
719/// trait objects, because they can't be read out onto the stack and
720/// dropped normally.
721///
722/// * It is friendlier to the optimizer to do this over [`ptr::read`] when
723/// dropping manually allocated memory (e.g., in the implementations of
724/// `Box`/`Rc`/`Vec`), as the compiler doesn't need to prove that it's
725/// sound to elide the copy.
726///
727/// * It can be used to drop [pinned] data when `T` is not `repr(packed)`
728/// (pinned data must not be moved before it is dropped).
729///
730/// Unaligned values cannot be dropped in place, they must be copied to an aligned
731/// location first using [`ptr::read_unaligned`]. For packed structs, this move is
732/// done automatically by the compiler. This means the fields of packed structs
733/// are not dropped in-place.
734///
735/// [`ptr::read`]: self::read
736/// [`ptr::read_unaligned`]: self::read_unaligned
737/// [pinned]: crate::pin
738///
739/// # Safety
740///
741/// Behavior is undefined if any of the following conditions are violated:
742///
743/// * `to_drop` must be [valid] for both reads and writes.
744///
745/// * `to_drop` must be properly aligned, even if `T` has size 0.
746///
747/// * `to_drop` must be nonnull, even if `T` has size 0.
748///
749/// * The value `to_drop` points to must be valid for dropping, which may mean
750/// it must uphold additional invariants. These invariants depend on the type
751/// of the value being dropped. For instance, when dropping a Box, the box's
752/// pointer to the heap must be valid.
753///
754/// * While `drop_in_place` is executing, the only way to access parts of
755/// `to_drop` is through the `&mut self` references supplied to the
756/// `Drop::drop` methods that `drop_in_place` invokes.
757///
758/// Additionally, if `T` is not [`Copy`], using the pointed-to value after
759/// calling `drop_in_place` can cause undefined behavior. Note that `*to_drop =
760/// foo` counts as a use because it will cause the value to be dropped
761/// again. [`write()`] can be used to overwrite data without causing it to be
762/// dropped.
763///
764/// [valid]: self#safety
765///
766/// # Examples
767///
768/// Manually remove the last item from a vector:
769///
770/// ```
771/// use std::ptr;
772/// use std::rc::Rc;
773///
774/// let last = Rc::new(1);
775/// let weak = Rc::downgrade(&last);
776///
777/// let mut v = vec![Rc::new(0), last];
778///
779/// unsafe {
780/// // Get a raw pointer to the last element in `v`.
781/// let ptr = &mut v[1] as *mut _;
782/// // Shorten `v` to prevent the last item from being dropped. We do that first,
783/// // to prevent issues if the `drop_in_place` below panics.
784/// v.set_len(1);
785/// // Without a call `drop_in_place`, the last item would never be dropped,
786/// // and the memory it manages would be leaked.
787/// ptr::drop_in_place(ptr);
788/// }
789///
790/// assert_eq!(v, &[0.into()]);
791///
792/// // Ensure that the last item was dropped.
793/// assert!(weak.upgrade().is_none());
794/// ```
795#[stable(feature = "drop_in_place", since = "1.8.0")]
796#[lang = "drop_in_place"]
797#[allow(unconditional_recursion)]
798#[rustc_diagnostic_item = "ptr_drop_in_place"]
799pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T) {
800 // Code here does not matter - this is replaced by the
801 // real drop glue by the compiler.
802
803 // SAFETY: see comment above
804 unsafe { drop_in_place(to_drop) }
805}
806
807/// Creates a null raw pointer.
808///
809/// This function is equivalent to zero-initializing the pointer:
810/// `MaybeUninit::<*const T>::zeroed().assume_init()`.
811/// The resulting pointer has the address 0.
812///
813/// # Examples
814///
815/// ```
816/// use std::ptr;
817///
818/// let p: *const i32 = ptr::null();
819/// assert!(p.is_null());
820/// assert_eq!(p as usize, 0); // this pointer has the address 0
821/// ```
822#[inline(always)]
823#[must_use]
824#[stable(feature = "rust1", since = "1.0.0")]
825#[rustc_promotable]
826#[rustc_const_stable(feature = "const_ptr_null", since = "1.24.0")]
827#[rustc_diagnostic_item = "ptr_null"]
828pub const fn null<T: ?Sized + Thin>() -> *const T {
829 from_raw_parts(data_pointer:without_provenance::<()>(0), ())
830}
831
832/// Creates a null mutable raw pointer.
833///
834/// This function is equivalent to zero-initializing the pointer:
835/// `MaybeUninit::<*mut T>::zeroed().assume_init()`.
836/// The resulting pointer has the address 0.
837///
838/// # Examples
839///
840/// ```
841/// use std::ptr;
842///
843/// let p: *mut i32 = ptr::null_mut();
844/// assert!(p.is_null());
845/// assert_eq!(p as usize, 0); // this pointer has the address 0
846/// ```
847#[inline(always)]
848#[must_use]
849#[stable(feature = "rust1", since = "1.0.0")]
850#[rustc_promotable]
851#[rustc_const_stable(feature = "const_ptr_null", since = "1.24.0")]
852#[rustc_diagnostic_item = "ptr_null_mut"]
853pub const fn null_mut<T: ?Sized + Thin>() -> *mut T {
854 from_raw_parts_mut(data_pointer:without_provenance_mut::<()>(0), ())
855}
856
857/// Creates a pointer with the given address and no [provenance][crate::ptr#provenance].
858///
859/// This is equivalent to `ptr::null().with_addr(addr)`.
860///
861/// Without provenance, this pointer is not associated with any actual allocation. Such a
862/// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but
863/// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are
864/// little more than a `usize` address in disguise.
865///
866/// This is different from `addr as *const T`, which creates a pointer that picks up a previously
867/// exposed provenance. See [`with_exposed_provenance`] for more details on that operation.
868///
869/// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
870#[inline(always)]
871#[must_use]
872#[stable(feature = "strict_provenance", since = "1.84.0")]
873#[rustc_const_stable(feature = "strict_provenance", since = "1.84.0")]
874pub const fn without_provenance<T>(addr: usize) -> *const T {
875 without_provenance_mut(addr)
876}
877
878/// Creates a new pointer that is dangling, but non-null and well-aligned.
879///
880/// This is useful for initializing types which lazily allocate, like
881/// `Vec::new` does.
882///
883/// Note that the pointer value may potentially represent a valid pointer to
884/// a `T`, which means this must not be used as a "not yet initialized"
885/// sentinel value. Types that lazily allocate must track initialization by
886/// some other means.
887#[inline(always)]
888#[must_use]
889#[stable(feature = "strict_provenance", since = "1.84.0")]
890#[rustc_const_stable(feature = "strict_provenance", since = "1.84.0")]
891pub const fn dangling<T>() -> *const T {
892 dangling_mut()
893}
894
895/// Creates a pointer with the given address and no [provenance][crate::ptr#provenance].
896///
897/// This is equivalent to `ptr::null_mut().with_addr(addr)`.
898///
899/// Without provenance, this pointer is not associated with any actual allocation. Such a
900/// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but
901/// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are
902/// little more than a `usize` address in disguise.
903///
904/// This is different from `addr as *mut T`, which creates a pointer that picks up a previously
905/// exposed provenance. See [`with_exposed_provenance_mut`] for more details on that operation.
906///
907/// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
908#[inline(always)]
909#[must_use]
910#[stable(feature = "strict_provenance", since = "1.84.0")]
911#[rustc_const_stable(feature = "strict_provenance", since = "1.84.0")]
912pub const fn without_provenance_mut<T>(addr: usize) -> *mut T {
913 // An int-to-pointer transmute currently has exactly the intended semantics: it creates a
914 // pointer without provenance. Note that this is *not* a stable guarantee about transmute
915 // semantics, it relies on sysroot crates having special status.
916 // SAFETY: every valid integer is also a valid pointer (as long as you don't dereference that
917 // pointer).
918 unsafe { mem::transmute(src:addr) }
919}
920
921/// Creates a new pointer that is dangling, but non-null and well-aligned.
922///
923/// This is useful for initializing types which lazily allocate, like
924/// `Vec::new` does.
925///
926/// Note that the pointer value may potentially represent a valid pointer to
927/// a `T`, which means this must not be used as a "not yet initialized"
928/// sentinel value. Types that lazily allocate must track initialization by
929/// some other means.
930#[inline(always)]
931#[must_use]
932#[stable(feature = "strict_provenance", since = "1.84.0")]
933#[rustc_const_stable(feature = "strict_provenance", since = "1.84.0")]
934pub const fn dangling_mut<T>() -> *mut T {
935 NonNull::dangling().as_ptr()
936}
937
938/// Converts an address back to a pointer, picking up some previously 'exposed'
939/// [provenance][crate::ptr#provenance].
940///
941/// This is fully equivalent to `addr as *const T`. The provenance of the returned pointer is that
942/// of *some* pointer that was previously exposed by passing it to
943/// [`expose_provenance`][pointer::expose_provenance], or a `ptr as usize` cast. In addition, memory
944/// which is outside the control of the Rust abstract machine (MMIO registers, for example) is
945/// always considered to be accessible with an exposed provenance, so long as this memory is disjoint
946/// from memory that will be used by the abstract machine such as the stack, heap, and statics.
947///
948/// The exact provenance that gets picked is not specified. The compiler will do its best to pick
949/// the "right" provenance for you (whatever that may be), but currently we cannot provide any
950/// guarantees about which provenance the resulting pointer will have -- and therefore there
951/// is no definite specification for which memory the resulting pointer may access.
952///
953/// If there is *no* previously 'exposed' provenance that justifies the way the returned pointer
954/// will be used, the program has undefined behavior. In particular, the aliasing rules still apply:
955/// pointers and references that have been invalidated due to aliasing accesses cannot be used
956/// anymore, even if they have been exposed!
957///
958/// Due to its inherent ambiguity, this operation may not be supported by tools that help you to
959/// stay conformant with the Rust memory model. It is recommended to use [Strict
960/// Provenance][self#strict-provenance] APIs such as [`with_addr`][pointer::with_addr] wherever
961/// possible.
962///
963/// On most platforms this will produce a value with the same bytes as the address. Platforms
964/// which need to store additional information in a pointer may not support this operation,
965/// since it is generally not possible to actually *compute* which provenance the returned
966/// pointer has to pick up.
967///
968/// This is an [Exposed Provenance][crate::ptr#exposed-provenance] API.
969#[must_use]
970#[inline(always)]
971#[stable(feature = "exposed_provenance", since = "1.84.0")]
972#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
973#[allow(fuzzy_provenance_casts)] // this *is* the explicit provenance API one should use instead
974pub fn with_exposed_provenance<T>(addr: usize) -> *const T {
975 addr as *const T
976}
977
978/// Converts an address back to a mutable pointer, picking up some previously 'exposed'
979/// [provenance][crate::ptr#provenance].
980///
981/// This is fully equivalent to `addr as *mut T`. The provenance of the returned pointer is that
982/// of *some* pointer that was previously exposed by passing it to
983/// [`expose_provenance`][pointer::expose_provenance], or a `ptr as usize` cast. In addition, memory
984/// which is outside the control of the Rust abstract machine (MMIO registers, for example) is
985/// always considered to be accessible with an exposed provenance, so long as this memory is disjoint
986/// from memory that will be used by the abstract machine such as the stack, heap, and statics.
987///
988/// The exact provenance that gets picked is not specified. The compiler will do its best to pick
989/// the "right" provenance for you (whatever that may be), but currently we cannot provide any
990/// guarantees about which provenance the resulting pointer will have -- and therefore there
991/// is no definite specification for which memory the resulting pointer may access.
992///
993/// If there is *no* previously 'exposed' provenance that justifies the way the returned pointer
994/// will be used, the program has undefined behavior. In particular, the aliasing rules still apply:
995/// pointers and references that have been invalidated due to aliasing accesses cannot be used
996/// anymore, even if they have been exposed!
997///
998/// Due to its inherent ambiguity, this operation may not be supported by tools that help you to
999/// stay conformant with the Rust memory model. It is recommended to use [Strict
1000/// Provenance][self#strict-provenance] APIs such as [`with_addr`][pointer::with_addr] wherever
1001/// possible.
1002///
1003/// On most platforms this will produce a value with the same bytes as the address. Platforms
1004/// which need to store additional information in a pointer may not support this operation,
1005/// since it is generally not possible to actually *compute* which provenance the returned
1006/// pointer has to pick up.
1007///
1008/// This is an [Exposed Provenance][crate::ptr#exposed-provenance] API.
1009#[must_use]
1010#[inline(always)]
1011#[stable(feature = "exposed_provenance", since = "1.84.0")]
1012#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1013#[allow(fuzzy_provenance_casts)] // this *is* the explicit provenance API one should use instead
1014pub fn with_exposed_provenance_mut<T>(addr: usize) -> *mut T {
1015 addr as *mut T
1016}
1017
1018/// Converts a reference to a raw pointer.
1019///
1020/// For `r: &T`, `from_ref(r)` is equivalent to `r as *const T` (except for the caveat noted below),
1021/// but is a bit safer since it will never silently change type or mutability, in particular if the
1022/// code is refactored.
1023///
1024/// The caller must ensure that the pointee outlives the pointer this function returns, or else it
1025/// will end up dangling.
1026///
1027/// The caller must also ensure that the memory the pointer (non-transitively) points to is never
1028/// written to (except inside an `UnsafeCell`) using this pointer or any pointer derived from it. If
1029/// you need to mutate the pointee, use [`from_mut`]. Specifically, to turn a mutable reference `m:
1030/// &mut T` into `*const T`, prefer `from_mut(m).cast_const()` to obtain a pointer that can later be
1031/// used for mutation.
1032///
1033/// ## Interaction with lifetime extension
1034///
1035/// Note that this has subtle interactions with the rules for lifetime extension of temporaries in
1036/// tail expressions. This code is valid, albeit in a non-obvious way:
1037/// ```rust
1038/// # type T = i32;
1039/// # fn foo() -> T { 42 }
1040/// // The temporary holding the return value of `foo` has its lifetime extended,
1041/// // because the surrounding expression involves no function call.
1042/// let p = &foo() as *const T;
1043/// unsafe { p.read() };
1044/// ```
1045/// Naively replacing the cast with `from_ref` is not valid:
1046/// ```rust,no_run
1047/// # use std::ptr;
1048/// # type T = i32;
1049/// # fn foo() -> T { 42 }
1050/// // The temporary holding the return value of `foo` does *not* have its lifetime extended,
1051/// // because the surrounding expression involves a function call.
1052/// let p = ptr::from_ref(&foo());
1053/// unsafe { p.read() }; // UB! Reading from a dangling pointer ⚠️
1054/// ```
1055/// The recommended way to write this code is to avoid relying on lifetime extension
1056/// when raw pointers are involved:
1057/// ```rust
1058/// # use std::ptr;
1059/// # type T = i32;
1060/// # fn foo() -> T { 42 }
1061/// let x = foo();
1062/// let p = ptr::from_ref(&x);
1063/// unsafe { p.read() };
1064/// ```
1065#[inline(always)]
1066#[must_use]
1067#[stable(feature = "ptr_from_ref", since = "1.76.0")]
1068#[rustc_const_stable(feature = "ptr_from_ref", since = "1.76.0")]
1069#[rustc_never_returns_null_ptr]
1070#[rustc_diagnostic_item = "ptr_from_ref"]
1071pub const fn from_ref<T: ?Sized>(r: &T) -> *const T {
1072 r
1073}
1074
1075/// Converts a mutable reference to a raw pointer.
1076///
1077/// For `r: &mut T`, `from_mut(r)` is equivalent to `r as *mut T` (except for the caveat noted
1078/// below), but is a bit safer since it will never silently change type or mutability, in particular
1079/// if the code is refactored.
1080///
1081/// The caller must ensure that the pointee outlives the pointer this function returns, or else it
1082/// will end up dangling.
1083///
1084/// ## Interaction with lifetime extension
1085///
1086/// Note that this has subtle interactions with the rules for lifetime extension of temporaries in
1087/// tail expressions. This code is valid, albeit in a non-obvious way:
1088/// ```rust
1089/// # type T = i32;
1090/// # fn foo() -> T { 42 }
1091/// // The temporary holding the return value of `foo` has its lifetime extended,
1092/// // because the surrounding expression involves no function call.
1093/// let p = &mut foo() as *mut T;
1094/// unsafe { p.write(T::default()) };
1095/// ```
1096/// Naively replacing the cast with `from_mut` is not valid:
1097/// ```rust,no_run
1098/// # use std::ptr;
1099/// # type T = i32;
1100/// # fn foo() -> T { 42 }
1101/// // The temporary holding the return value of `foo` does *not* have its lifetime extended,
1102/// // because the surrounding expression involves a function call.
1103/// let p = ptr::from_mut(&mut foo());
1104/// unsafe { p.write(T::default()) }; // UB! Writing to a dangling pointer ⚠️
1105/// ```
1106/// The recommended way to write this code is to avoid relying on lifetime extension
1107/// when raw pointers are involved:
1108/// ```rust
1109/// # use std::ptr;
1110/// # type T = i32;
1111/// # fn foo() -> T { 42 }
1112/// let mut x = foo();
1113/// let p = ptr::from_mut(&mut x);
1114/// unsafe { p.write(T::default()) };
1115/// ```
1116#[inline(always)]
1117#[must_use]
1118#[stable(feature = "ptr_from_ref", since = "1.76.0")]
1119#[rustc_const_stable(feature = "ptr_from_ref", since = "1.76.0")]
1120#[rustc_never_returns_null_ptr]
1121pub const fn from_mut<T: ?Sized>(r: &mut T) -> *mut T {
1122 r
1123}
1124
1125/// Forms a raw slice from a pointer and a length.
1126///
1127/// The `len` argument is the number of **elements**, not the number of bytes.
1128///
1129/// This function is safe, but actually using the return value is unsafe.
1130/// See the documentation of [`slice::from_raw_parts`] for slice safety requirements.
1131///
1132/// [`slice::from_raw_parts`]: crate::slice::from_raw_parts
1133///
1134/// # Examples
1135///
1136/// ```rust
1137/// use std::ptr;
1138///
1139/// // create a slice pointer when starting out with a pointer to the first element
1140/// let x = [5, 6, 7];
1141/// let raw_pointer = x.as_ptr();
1142/// let slice = ptr::slice_from_raw_parts(raw_pointer, 3);
1143/// assert_eq!(unsafe { &*slice }[2], 7);
1144/// ```
1145///
1146/// You must ensure that the pointer is valid and not null before dereferencing
1147/// the raw slice. A slice reference must never have a null pointer, even if it's empty.
1148///
1149/// ```rust,should_panic
1150/// use std::ptr;
1151/// let danger: *const [u8] = ptr::slice_from_raw_parts(ptr::null(), 0);
1152/// unsafe {
1153/// danger.as_ref().expect("references must not be null");
1154/// }
1155/// ```
1156#[inline]
1157#[stable(feature = "slice_from_raw_parts", since = "1.42.0")]
1158#[rustc_const_stable(feature = "const_slice_from_raw_parts", since = "1.64.0")]
1159#[rustc_diagnostic_item = "ptr_slice_from_raw_parts"]
1160pub const fn slice_from_raw_parts<T>(data: *const T, len: usize) -> *const [T] {
1161 from_raw_parts(data, metadata:len)
1162}
1163
1164/// Forms a raw mutable slice from a pointer and a length.
1165///
1166/// The `len` argument is the number of **elements**, not the number of bytes.
1167///
1168/// Performs the same functionality as [`slice_from_raw_parts`], except that a
1169/// raw mutable slice is returned, as opposed to a raw immutable slice.
1170///
1171/// This function is safe, but actually using the return value is unsafe.
1172/// See the documentation of [`slice::from_raw_parts_mut`] for slice safety requirements.
1173///
1174/// [`slice::from_raw_parts_mut`]: crate::slice::from_raw_parts_mut
1175///
1176/// # Examples
1177///
1178/// ```rust
1179/// use std::ptr;
1180///
1181/// let x = &mut [5, 6, 7];
1182/// let raw_pointer = x.as_mut_ptr();
1183/// let slice = ptr::slice_from_raw_parts_mut(raw_pointer, 3);
1184///
1185/// unsafe {
1186/// (*slice)[2] = 99; // assign a value at an index in the slice
1187/// };
1188///
1189/// assert_eq!(unsafe { &*slice }[2], 99);
1190/// ```
1191///
1192/// You must ensure that the pointer is valid and not null before dereferencing
1193/// the raw slice. A slice reference must never have a null pointer, even if it's empty.
1194///
1195/// ```rust,should_panic
1196/// use std::ptr;
1197/// let danger: *mut [u8] = ptr::slice_from_raw_parts_mut(ptr::null_mut(), 0);
1198/// unsafe {
1199/// danger.as_mut().expect("references must not be null");
1200/// }
1201/// ```
1202#[inline]
1203#[stable(feature = "slice_from_raw_parts", since = "1.42.0")]
1204#[rustc_const_stable(feature = "const_slice_from_raw_parts_mut", since = "1.83.0")]
1205#[rustc_diagnostic_item = "ptr_slice_from_raw_parts_mut"]
1206pub const fn slice_from_raw_parts_mut<T>(data: *mut T, len: usize) -> *mut [T] {
1207 from_raw_parts_mut(data, metadata:len)
1208}
1209
1210/// Swaps the values at two mutable locations of the same type, without
1211/// deinitializing either.
1212///
1213/// But for the following exceptions, this function is semantically
1214/// equivalent to [`mem::swap`]:
1215///
1216/// * It operates on raw pointers instead of references. When references are
1217/// available, [`mem::swap`] should be preferred.
1218///
1219/// * The two pointed-to values may overlap. If the values do overlap, then the
1220/// overlapping region of memory from `x` will be used. This is demonstrated
1221/// in the second example below.
1222///
1223/// * The operation is "untyped" in the sense that data may be uninitialized or otherwise violate
1224/// the requirements of `T`. The initialization state is preserved exactly.
1225///
1226/// # Safety
1227///
1228/// Behavior is undefined if any of the following conditions are violated:
1229///
1230/// * Both `x` and `y` must be [valid] for both reads and writes. They must remain valid even when the
1231/// other pointer is written. (This means if the memory ranges overlap, the two pointers must not
1232/// be subject to aliasing restrictions relative to each other.)
1233///
1234/// * Both `x` and `y` must be properly aligned.
1235///
1236/// Note that even if `T` has size `0`, the pointers must be properly aligned.
1237///
1238/// [valid]: self#safety
1239///
1240/// # Examples
1241///
1242/// Swapping two non-overlapping regions:
1243///
1244/// ```
1245/// use std::ptr;
1246///
1247/// let mut array = [0, 1, 2, 3];
1248///
1249/// let (x, y) = array.split_at_mut(2);
1250/// let x = x.as_mut_ptr().cast::<[u32; 2]>(); // this is `array[0..2]`
1251/// let y = y.as_mut_ptr().cast::<[u32; 2]>(); // this is `array[2..4]`
1252///
1253/// unsafe {
1254/// ptr::swap(x, y);
1255/// assert_eq!([2, 3, 0, 1], array);
1256/// }
1257/// ```
1258///
1259/// Swapping two overlapping regions:
1260///
1261/// ```
1262/// use std::ptr;
1263///
1264/// let mut array: [i32; 4] = [0, 1, 2, 3];
1265///
1266/// let array_ptr: *mut i32 = array.as_mut_ptr();
1267///
1268/// let x = array_ptr as *mut [i32; 3]; // this is `array[0..3]`
1269/// let y = unsafe { array_ptr.add(1) } as *mut [i32; 3]; // this is `array[1..4]`
1270///
1271/// unsafe {
1272/// ptr::swap(x, y);
1273/// // The indices `1..3` of the slice overlap between `x` and `y`.
1274/// // Reasonable results would be for to them be `[2, 3]`, so that indices `0..3` are
1275/// // `[1, 2, 3]` (matching `y` before the `swap`); or for them to be `[0, 1]`
1276/// // so that indices `1..4` are `[0, 1, 2]` (matching `x` before the `swap`).
1277/// // This implementation is defined to make the latter choice.
1278/// assert_eq!([1, 0, 1, 2], array);
1279/// }
1280/// ```
1281#[inline]
1282#[stable(feature = "rust1", since = "1.0.0")]
1283#[rustc_const_stable(feature = "const_swap", since = "1.85.0")]
1284#[rustc_diagnostic_item = "ptr_swap"]
1285pub const unsafe fn swap<T>(x: *mut T, y: *mut T) {
1286 // Give ourselves some scratch space to work with.
1287 // We do not have to worry about drops: `MaybeUninit` does nothing when dropped.
1288 let mut tmp: MaybeUninit = MaybeUninit::<T>::uninit();
1289
1290 // Perform the swap
1291 // SAFETY: the caller must guarantee that `x` and `y` are
1292 // valid for writes and properly aligned. `tmp` cannot be
1293 // overlapping either `x` or `y` because `tmp` was just allocated
1294 // on the stack as a separate allocation.
1295 unsafe {
1296 copy_nonoverlapping(src:x, dst:tmp.as_mut_ptr(), count:1);
1297 copy(src:y, dst:x, count:1); // `x` and `y` may overlap
1298 copy_nonoverlapping(src:tmp.as_ptr(), dst:y, count:1);
1299 }
1300}
1301
1302/// Swaps `count * size_of::<T>()` bytes between the two regions of memory
1303/// beginning at `x` and `y`. The two regions must *not* overlap.
1304///
1305/// The operation is "untyped" in the sense that data may be uninitialized or otherwise violate the
1306/// requirements of `T`. The initialization state is preserved exactly.
1307///
1308/// # Safety
1309///
1310/// Behavior is undefined if any of the following conditions are violated:
1311///
1312/// * Both `x` and `y` must be [valid] for both reads and writes of `count *
1313/// size_of::<T>()` bytes.
1314///
1315/// * Both `x` and `y` must be properly aligned.
1316///
1317/// * The region of memory beginning at `x` with a size of `count *
1318/// size_of::<T>()` bytes must *not* overlap with the region of memory
1319/// beginning at `y` with the same size.
1320///
1321/// Note that even if the effectively copied size (`count * size_of::<T>()`) is `0`,
1322/// the pointers must be properly aligned.
1323///
1324/// [valid]: self#safety
1325///
1326/// # Examples
1327///
1328/// Basic usage:
1329///
1330/// ```
1331/// use std::ptr;
1332///
1333/// let mut x = [1, 2, 3, 4];
1334/// let mut y = [7, 8, 9];
1335///
1336/// unsafe {
1337/// ptr::swap_nonoverlapping(x.as_mut_ptr(), y.as_mut_ptr(), 2);
1338/// }
1339///
1340/// assert_eq!(x, [7, 8, 3, 4]);
1341/// assert_eq!(y, [1, 2, 9]);
1342/// ```
1343///
1344/// # Const evaluation limitations
1345///
1346/// If this function is invoked during const-evaluation, the current implementation has a small (and
1347/// rarely relevant) limitation: if `count` is at least 2 and the data pointed to by `x` or `y`
1348/// contains a pointer that crosses the boundary of two `T`-sized chunks of memory, the function may
1349/// fail to evaluate (similar to a panic during const-evaluation). This behavior may change in the
1350/// future.
1351///
1352/// The limitation is illustrated by the following example:
1353///
1354/// ```
1355/// use std::mem::size_of;
1356/// use std::ptr;
1357///
1358/// const { unsafe {
1359/// const PTR_SIZE: usize = size_of::<*const i32>();
1360/// let mut data1 = [0u8; PTR_SIZE];
1361/// let mut data2 = [0u8; PTR_SIZE];
1362/// // Store a pointer in `data1`.
1363/// data1.as_mut_ptr().cast::<*const i32>().write_unaligned(&42);
1364/// // Swap the contents of `data1` and `data2` by swapping `PTR_SIZE` many `u8`-sized chunks.
1365/// // This call will fail, because the pointer in `data1` crosses the boundary
1366/// // between several of the 1-byte chunks that are being swapped here.
1367/// //ptr::swap_nonoverlapping(data1.as_mut_ptr(), data2.as_mut_ptr(), PTR_SIZE);
1368/// // Swap the contents of `data1` and `data2` by swapping a single chunk of size
1369/// // `[u8; PTR_SIZE]`. That works, as there is no pointer crossing the boundary between
1370/// // two chunks.
1371/// ptr::swap_nonoverlapping(&mut data1, &mut data2, 1);
1372/// // Read the pointer from `data2` and dereference it.
1373/// let ptr = data2.as_ptr().cast::<*const i32>().read_unaligned();
1374/// assert!(*ptr == 42);
1375/// } }
1376/// ```
1377#[inline]
1378#[stable(feature = "swap_nonoverlapping", since = "1.27.0")]
1379#[rustc_const_stable(feature = "const_swap_nonoverlapping", since = "1.88.0")]
1380#[rustc_diagnostic_item = "ptr_swap_nonoverlapping"]
1381#[rustc_allow_const_fn_unstable(const_eval_select)] // both implementations behave the same
1382#[track_caller]
1383pub const unsafe fn swap_nonoverlapping<T>(x: *mut T, y: *mut T, count: usize) {
1384 ub_checks::assert_unsafe_precondition!(
1385 check_library_ub,
1386 "ptr::swap_nonoverlapping requires that both pointer arguments are aligned and non-null \
1387 and the specified memory ranges do not overlap",
1388 (
1389 x: *mut () = x as *mut (),
1390 y: *mut () = y as *mut (),
1391 size: usize = size_of::<T>(),
1392 align: usize = align_of::<T>(),
1393 count: usize = count,
1394 ) => {
1395 let zero_size = size == 0 || count == 0;
1396 ub_checks::maybe_is_aligned_and_not_null(x, align, zero_size)
1397 && ub_checks::maybe_is_aligned_and_not_null(y, align, zero_size)
1398 && ub_checks::maybe_is_nonoverlapping(x, y, size, count)
1399 }
1400 );
1401
1402 const_eval_select!(
1403 @capture[T] { x: *mut T, y: *mut T, count: usize }:
1404 if const {
1405 // At compile-time we want to always copy this in chunks of `T`, to ensure that if there
1406 // are pointers inside `T` we will copy them in one go rather than trying to copy a part
1407 // of a pointer (which would not work).
1408 // SAFETY: Same preconditions as this function
1409 unsafe { swap_nonoverlapping_const(x, y, count) }
1410 } else {
1411 // Going though a slice here helps codegen know the size fits in `isize`
1412 let slice = slice_from_raw_parts_mut(x, count);
1413 // SAFETY: This is all readable from the pointer, meaning it's one
1414 // allocation, and thus cannot be more than isize::MAX bytes.
1415 let bytes = unsafe { mem::size_of_val_raw::<[T]>(slice) };
1416 if let Some(bytes) = NonZero::new(bytes) {
1417 // SAFETY: These are the same ranges, just expressed in a different
1418 // type, so they're still non-overlapping.
1419 unsafe { swap_nonoverlapping_bytes(x.cast(), y.cast(), bytes) };
1420 }
1421 }
1422 )
1423}
1424
1425/// Same behavior and safety conditions as [`swap_nonoverlapping`]
1426#[inline]
1427const unsafe fn swap_nonoverlapping_const<T>(x: *mut T, y: *mut T, count: usize) {
1428 let mut i: usize = 0;
1429 while i < count {
1430 // SAFETY: By precondition, `i` is in-bounds because it's below `n`
1431 let x: *mut T = unsafe { x.add(count:i) };
1432 // SAFETY: By precondition, `i` is in-bounds because it's below `n`
1433 // and it's distinct from `x` since the ranges are non-overlapping
1434 let y: *mut T = unsafe { y.add(count:i) };
1435
1436 // SAFETY: we're only ever given pointers that are valid to read/write,
1437 // including being aligned, and nothing here panics so it's drop-safe.
1438 unsafe {
1439 // Note that it's critical that these use `copy_nonoverlapping`,
1440 // rather than `read`/`write`, to avoid #134713 if T has padding.
1441 let mut temp: MaybeUninit = MaybeUninit::<T>::uninit();
1442 copy_nonoverlapping(src:x, dst:temp.as_mut_ptr(), count:1);
1443 copy_nonoverlapping(src:y, dst:x, count:1);
1444 copy_nonoverlapping(src:temp.as_ptr(), dst:y, count:1);
1445 }
1446
1447 i += 1;
1448 }
1449}
1450
1451// Don't let MIR inline this, because we really want it to keep its noalias metadata
1452#[rustc_no_mir_inline]
1453#[inline]
1454fn swap_chunk<const N: usize>(x: &mut MaybeUninit<[u8; N]>, y: &mut MaybeUninit<[u8; N]>) {
1455 let a: MaybeUninit<[u8; N]> = *x;
1456 let b: MaybeUninit<[u8; N]> = *y;
1457 *x = b;
1458 *y = a;
1459}
1460
1461#[inline]
1462unsafe fn swap_nonoverlapping_bytes(x: *mut u8, y: *mut u8, bytes: NonZero<usize>) {
1463 // Same as `swap_nonoverlapping::<[u8; N]>`.
1464 unsafe fn swap_nonoverlapping_chunks<const N: usize>(
1465 x: *mut MaybeUninit<[u8; N]>,
1466 y: *mut MaybeUninit<[u8; N]>,
1467 chunks: NonZero<usize>,
1468 ) {
1469 let chunks = chunks.get();
1470 for i in 0..chunks {
1471 // SAFETY: i is in [0, chunks) so the adds and dereferences are in-bounds.
1472 unsafe { swap_chunk(&mut *x.add(i), &mut *y.add(i)) };
1473 }
1474 }
1475
1476 // Same as `swap_nonoverlapping_bytes`, but accepts at most 1+2+4=7 bytes
1477 #[inline]
1478 unsafe fn swap_nonoverlapping_short(x: *mut u8, y: *mut u8, bytes: NonZero<usize>) {
1479 // Tail handling for auto-vectorized code sometimes has element-at-a-time behaviour,
1480 // see <https://github.com/rust-lang/rust/issues/134946>.
1481 // By swapping as different sizes, rather than as a loop over bytes,
1482 // we make sure not to end up with, say, seven byte-at-a-time copies.
1483
1484 let bytes = bytes.get();
1485 let mut i = 0;
1486 macro_rules! swap_prefix {
1487 ($($n:literal)+) => {$(
1488 if (bytes & $n) != 0 {
1489 // SAFETY: `i` can only have the same bits set as those in bytes,
1490 // so these `add`s are in-bounds of `bytes`. But the bit for
1491 // `$n` hasn't been set yet, so the `$n` bytes that `swap_chunk`
1492 // will read and write are within the usable range.
1493 unsafe { swap_chunk::<$n>(&mut*x.add(i).cast(), &mut*y.add(i).cast()) };
1494 i |= $n;
1495 }
1496 )+};
1497 }
1498 swap_prefix!(4 2 1);
1499 debug_assert_eq!(i, bytes);
1500 }
1501
1502 const CHUNK_SIZE: usize = size_of::<*const ()>();
1503 let bytes = bytes.get();
1504
1505 let chunks = bytes / CHUNK_SIZE;
1506 let tail = bytes % CHUNK_SIZE;
1507 if let Some(chunks) = NonZero::new(chunks) {
1508 // SAFETY: this is bytes/CHUNK_SIZE*CHUNK_SIZE bytes, which is <= bytes,
1509 // so it's within the range of our non-overlapping bytes.
1510 unsafe { swap_nonoverlapping_chunks::<CHUNK_SIZE>(x.cast(), y.cast(), chunks) };
1511 }
1512 if let Some(tail) = NonZero::new(tail) {
1513 const { assert!(CHUNK_SIZE <= 8) };
1514 let delta = chunks * CHUNK_SIZE;
1515 // SAFETY: the tail length is below CHUNK SIZE because of the remainder,
1516 // and CHUNK_SIZE is at most 8 by the const assert, so tail <= 7
1517 unsafe { swap_nonoverlapping_short(x.add(delta), y.add(delta), tail) };
1518 }
1519}
1520
1521/// Moves `src` into the pointed `dst`, returning the previous `dst` value.
1522///
1523/// Neither value is dropped.
1524///
1525/// This function is semantically equivalent to [`mem::replace`] except that it
1526/// operates on raw pointers instead of references. When references are
1527/// available, [`mem::replace`] should be preferred.
1528///
1529/// # Safety
1530///
1531/// Behavior is undefined if any of the following conditions are violated:
1532///
1533/// * `dst` must be [valid] for both reads and writes.
1534///
1535/// * `dst` must be properly aligned.
1536///
1537/// * `dst` must point to a properly initialized value of type `T`.
1538///
1539/// Note that even if `T` has size `0`, the pointer must be properly aligned.
1540///
1541/// [valid]: self#safety
1542///
1543/// # Examples
1544///
1545/// ```
1546/// use std::ptr;
1547///
1548/// let mut rust = vec!['b', 'u', 's', 't'];
1549///
1550/// // `mem::replace` would have the same effect without requiring the unsafe
1551/// // block.
1552/// let b = unsafe {
1553/// ptr::replace(&mut rust[0], 'r')
1554/// };
1555///
1556/// assert_eq!(b, 'b');
1557/// assert_eq!(rust, &['r', 'u', 's', 't']);
1558/// ```
1559#[inline]
1560#[stable(feature = "rust1", since = "1.0.0")]
1561#[rustc_const_stable(feature = "const_replace", since = "1.83.0")]
1562#[rustc_diagnostic_item = "ptr_replace"]
1563#[track_caller]
1564pub const unsafe fn replace<T>(dst: *mut T, src: T) -> T {
1565 // SAFETY: the caller must guarantee that `dst` is valid to be
1566 // cast to a mutable reference (valid for writes, aligned, initialized),
1567 // and cannot overlap `src` since `dst` must point to a distinct
1568 // allocation.
1569 unsafe {
1570 ub_checks::assert_unsafe_precondition!(
1571 check_language_ub,
1572 "ptr::replace requires that the pointer argument is aligned and non-null",
1573 (
1574 addr: *const () = dst as *const (),
1575 align: usize = align_of::<T>(),
1576 is_zst: bool = T::IS_ZST,
1577 ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, is_zst)
1578 );
1579 mem::replace(&mut *dst, src)
1580 }
1581}
1582
1583/// Reads the value from `src` without moving it. This leaves the
1584/// memory in `src` unchanged.
1585///
1586/// # Safety
1587///
1588/// Behavior is undefined if any of the following conditions are violated:
1589///
1590/// * `src` must be [valid] for reads.
1591///
1592/// * `src` must be properly aligned. Use [`read_unaligned`] if this is not the
1593/// case.
1594///
1595/// * `src` must point to a properly initialized value of type `T`.
1596///
1597/// Note that even if `T` has size `0`, the pointer must be properly aligned.
1598///
1599/// # Examples
1600///
1601/// Basic usage:
1602///
1603/// ```
1604/// let x = 12;
1605/// let y = &x as *const i32;
1606///
1607/// unsafe {
1608/// assert_eq!(std::ptr::read(y), 12);
1609/// }
1610/// ```
1611///
1612/// Manually implement [`mem::swap`]:
1613///
1614/// ```
1615/// use std::ptr;
1616///
1617/// fn swap<T>(a: &mut T, b: &mut T) {
1618/// unsafe {
1619/// // Create a bitwise copy of the value at `a` in `tmp`.
1620/// let tmp = ptr::read(a);
1621///
1622/// // Exiting at this point (either by explicitly returning or by
1623/// // calling a function which panics) would cause the value in `tmp` to
1624/// // be dropped while the same value is still referenced by `a`. This
1625/// // could trigger undefined behavior if `T` is not `Copy`.
1626///
1627/// // Create a bitwise copy of the value at `b` in `a`.
1628/// // This is safe because mutable references cannot alias.
1629/// ptr::copy_nonoverlapping(b, a, 1);
1630///
1631/// // As above, exiting here could trigger undefined behavior because
1632/// // the same value is referenced by `a` and `b`.
1633///
1634/// // Move `tmp` into `b`.
1635/// ptr::write(b, tmp);
1636///
1637/// // `tmp` has been moved (`write` takes ownership of its second argument),
1638/// // so nothing is dropped implicitly here.
1639/// }
1640/// }
1641///
1642/// let mut foo = "foo".to_owned();
1643/// let mut bar = "bar".to_owned();
1644///
1645/// swap(&mut foo, &mut bar);
1646///
1647/// assert_eq!(foo, "bar");
1648/// assert_eq!(bar, "foo");
1649/// ```
1650///
1651/// ## Ownership of the Returned Value
1652///
1653/// `read` creates a bitwise copy of `T`, regardless of whether `T` is [`Copy`].
1654/// If `T` is not [`Copy`], using both the returned value and the value at
1655/// `*src` can violate memory safety. Note that assigning to `*src` counts as a
1656/// use because it will attempt to drop the value at `*src`.
1657///
1658/// [`write()`] can be used to overwrite data without causing it to be dropped.
1659///
1660/// ```
1661/// use std::ptr;
1662///
1663/// let mut s = String::from("foo");
1664/// unsafe {
1665/// // `s2` now points to the same underlying memory as `s`.
1666/// let mut s2: String = ptr::read(&s);
1667///
1668/// assert_eq!(s2, "foo");
1669///
1670/// // Assigning to `s2` causes its original value to be dropped. Beyond
1671/// // this point, `s` must no longer be used, as the underlying memory has
1672/// // been freed.
1673/// s2 = String::default();
1674/// assert_eq!(s2, "");
1675///
1676/// // Assigning to `s` would cause the old value to be dropped again,
1677/// // resulting in undefined behavior.
1678/// // s = String::from("bar"); // ERROR
1679///
1680/// // `ptr::write` can be used to overwrite a value without dropping it.
1681/// ptr::write(&mut s, String::from("bar"));
1682/// }
1683///
1684/// assert_eq!(s, "bar");
1685/// ```
1686///
1687/// [valid]: self#safety
1688#[inline]
1689#[stable(feature = "rust1", since = "1.0.0")]
1690#[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]
1691#[track_caller]
1692#[rustc_diagnostic_item = "ptr_read"]
1693pub const unsafe fn read<T>(src: *const T) -> T {
1694 // It would be semantically correct to implement this via `copy_nonoverlapping`
1695 // and `MaybeUninit`, as was done before PR #109035. Calling `assume_init`
1696 // provides enough information to know that this is a typed operation.
1697
1698 // However, as of March 2023 the compiler was not capable of taking advantage
1699 // of that information. Thus, the implementation here switched to an intrinsic,
1700 // which lowers to `_0 = *src` in MIR, to address a few issues:
1701 //
1702 // - Using `MaybeUninit::assume_init` after a `copy_nonoverlapping` was not
1703 // turning the untyped copy into a typed load. As such, the generated
1704 // `load` in LLVM didn't get various metadata, such as `!range` (#73258),
1705 // `!nonnull`, and `!noundef`, resulting in poorer optimization.
1706 // - Going through the extra local resulted in multiple extra copies, even
1707 // in optimized MIR. (Ignoring StorageLive/Dead, the intrinsic is one
1708 // MIR statement, while the previous implementation was eight.) LLVM
1709 // could sometimes optimize them away, but because `read` is at the core
1710 // of so many things, not having them in the first place improves what we
1711 // hand off to the backend. For example, `mem::replace::<Big>` previously
1712 // emitted 4 `alloca` and 6 `memcpy`s, but is now 1 `alloc` and 3 `memcpy`s.
1713 // - In general, this approach keeps us from getting any more bugs (like
1714 // #106369) that boil down to "`read(p)` is worse than `*p`", as this
1715 // makes them look identical to the backend (or other MIR consumers).
1716 //
1717 // Future enhancements to MIR optimizations might well allow this to return
1718 // to the previous implementation, rather than using an intrinsic.
1719
1720 // SAFETY: the caller must guarantee that `src` is valid for reads.
1721 unsafe {
1722 #[cfg(debug_assertions)] // Too expensive to always enable (for now?)
1723 ub_checks::assert_unsafe_precondition!(
1724 check_language_ub,
1725 "ptr::read requires that the pointer argument is aligned and non-null",
1726 (
1727 addr: *const () = src as *const (),
1728 align: usize = align_of::<T>(),
1729 is_zst: bool = T::IS_ZST,
1730 ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, is_zst)
1731 );
1732 crate::intrinsics::read_via_copy(src)
1733 }
1734}
1735
1736/// Reads the value from `src` without moving it. This leaves the
1737/// memory in `src` unchanged.
1738///
1739/// Unlike [`read`], `read_unaligned` works with unaligned pointers.
1740///
1741/// # Safety
1742///
1743/// Behavior is undefined if any of the following conditions are violated:
1744///
1745/// * `src` must be [valid] for reads.
1746///
1747/// * `src` must point to a properly initialized value of type `T`.
1748///
1749/// Like [`read`], `read_unaligned` creates a bitwise copy of `T`, regardless of
1750/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned
1751/// value and the value at `*src` can [violate memory safety][read-ownership].
1752///
1753/// [read-ownership]: read#ownership-of-the-returned-value
1754/// [valid]: self#safety
1755///
1756/// ## On `packed` structs
1757///
1758/// Attempting to create a raw pointer to an `unaligned` struct field with
1759/// an expression such as `&packed.unaligned as *const FieldType` creates an
1760/// intermediate unaligned reference before converting that to a raw pointer.
1761/// That this reference is temporary and immediately cast is inconsequential
1762/// as the compiler always expects references to be properly aligned.
1763/// As a result, using `&packed.unaligned as *const FieldType` causes immediate
1764/// *undefined behavior* in your program.
1765///
1766/// Instead you must use the `&raw const` syntax to create the pointer.
1767/// You may use that constructed pointer together with this function.
1768///
1769/// An example of what not to do and how this relates to `read_unaligned` is:
1770///
1771/// ```
1772/// #[repr(packed, C)]
1773/// struct Packed {
1774/// _padding: u8,
1775/// unaligned: u32,
1776/// }
1777///
1778/// let packed = Packed {
1779/// _padding: 0x00,
1780/// unaligned: 0x01020304,
1781/// };
1782///
1783/// // Take the address of a 32-bit integer which is not aligned.
1784/// // In contrast to `&packed.unaligned as *const _`, this has no undefined behavior.
1785/// let unaligned = &raw const packed.unaligned;
1786///
1787/// let v = unsafe { std::ptr::read_unaligned(unaligned) };
1788/// assert_eq!(v, 0x01020304);
1789/// ```
1790///
1791/// Accessing unaligned fields directly with e.g. `packed.unaligned` is safe however.
1792///
1793/// # Examples
1794///
1795/// Read a `usize` value from a byte buffer:
1796///
1797/// ```
1798/// fn read_usize(x: &[u8]) -> usize {
1799/// assert!(x.len() >= size_of::<usize>());
1800///
1801/// let ptr = x.as_ptr() as *const usize;
1802///
1803/// unsafe { ptr.read_unaligned() }
1804/// }
1805/// ```
1806#[inline]
1807#[stable(feature = "ptr_unaligned", since = "1.17.0")]
1808#[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]
1809#[track_caller]
1810#[rustc_diagnostic_item = "ptr_read_unaligned"]
1811pub const unsafe fn read_unaligned<T>(src: *const T) -> T {
1812 let mut tmp: MaybeUninit = MaybeUninit::<T>::uninit();
1813 // SAFETY: the caller must guarantee that `src` is valid for reads.
1814 // `src` cannot overlap `tmp` because `tmp` was just allocated on
1815 // the stack as a separate allocation.
1816 //
1817 // Also, since we just wrote a valid value into `tmp`, it is guaranteed
1818 // to be properly initialized.
1819 unsafe {
1820 copy_nonoverlapping(src as *const u8, dst:tmp.as_mut_ptr() as *mut u8, count:size_of::<T>());
1821 tmp.assume_init()
1822 }
1823}
1824
1825/// Overwrites a memory location with the given value without reading or
1826/// dropping the old value.
1827///
1828/// `write` does not drop the contents of `dst`. This is safe, but it could leak
1829/// allocations or resources, so care should be taken not to overwrite an object
1830/// that should be dropped.
1831///
1832/// Additionally, it does not drop `src`. Semantically, `src` is moved into the
1833/// location pointed to by `dst`.
1834///
1835/// This is appropriate for initializing uninitialized memory, or overwriting
1836/// memory that has previously been [`read`] from.
1837///
1838/// # Safety
1839///
1840/// Behavior is undefined if any of the following conditions are violated:
1841///
1842/// * `dst` must be [valid] for writes.
1843///
1844/// * `dst` must be properly aligned. Use [`write_unaligned`] if this is not the
1845/// case.
1846///
1847/// Note that even if `T` has size `0`, the pointer must be properly aligned.
1848///
1849/// [valid]: self#safety
1850///
1851/// # Examples
1852///
1853/// Basic usage:
1854///
1855/// ```
1856/// let mut x = 0;
1857/// let y = &mut x as *mut i32;
1858/// let z = 12;
1859///
1860/// unsafe {
1861/// std::ptr::write(y, z);
1862/// assert_eq!(std::ptr::read(y), 12);
1863/// }
1864/// ```
1865///
1866/// Manually implement [`mem::swap`]:
1867///
1868/// ```
1869/// use std::ptr;
1870///
1871/// fn swap<T>(a: &mut T, b: &mut T) {
1872/// unsafe {
1873/// // Create a bitwise copy of the value at `a` in `tmp`.
1874/// let tmp = ptr::read(a);
1875///
1876/// // Exiting at this point (either by explicitly returning or by
1877/// // calling a function which panics) would cause the value in `tmp` to
1878/// // be dropped while the same value is still referenced by `a`. This
1879/// // could trigger undefined behavior if `T` is not `Copy`.
1880///
1881/// // Create a bitwise copy of the value at `b` in `a`.
1882/// // This is safe because mutable references cannot alias.
1883/// ptr::copy_nonoverlapping(b, a, 1);
1884///
1885/// // As above, exiting here could trigger undefined behavior because
1886/// // the same value is referenced by `a` and `b`.
1887///
1888/// // Move `tmp` into `b`.
1889/// ptr::write(b, tmp);
1890///
1891/// // `tmp` has been moved (`write` takes ownership of its second argument),
1892/// // so nothing is dropped implicitly here.
1893/// }
1894/// }
1895///
1896/// let mut foo = "foo".to_owned();
1897/// let mut bar = "bar".to_owned();
1898///
1899/// swap(&mut foo, &mut bar);
1900///
1901/// assert_eq!(foo, "bar");
1902/// assert_eq!(bar, "foo");
1903/// ```
1904#[inline]
1905#[stable(feature = "rust1", since = "1.0.0")]
1906#[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
1907#[rustc_diagnostic_item = "ptr_write"]
1908#[track_caller]
1909pub const unsafe fn write<T>(dst: *mut T, src: T) {
1910 // Semantically, it would be fine for this to be implemented as a
1911 // `copy_nonoverlapping` and appropriate drop suppression of `src`.
1912
1913 // However, implementing via that currently produces more MIR than is ideal.
1914 // Using an intrinsic keeps it down to just the simple `*dst = move src` in
1915 // MIR (11 statements shorter, at the time of writing), and also allows
1916 // `src` to stay an SSA value in codegen_ssa, rather than a memory one.
1917
1918 // SAFETY: the caller must guarantee that `dst` is valid for writes.
1919 // `dst` cannot overlap `src` because the caller has mutable access
1920 // to `dst` while `src` is owned by this function.
1921 unsafe {
1922 #[cfg(debug_assertions)] // Too expensive to always enable (for now?)
1923 ub_checks::assert_unsafe_precondition!(
1924 check_language_ub,
1925 "ptr::write requires that the pointer argument is aligned and non-null",
1926 (
1927 addr: *mut () = dst as *mut (),
1928 align: usize = align_of::<T>(),
1929 is_zst: bool = T::IS_ZST,
1930 ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, is_zst)
1931 );
1932 intrinsics::write_via_move(dst, src)
1933 }
1934}
1935
1936/// Overwrites a memory location with the given value without reading or
1937/// dropping the old value.
1938///
1939/// Unlike [`write()`], the pointer may be unaligned.
1940///
1941/// `write_unaligned` does not drop the contents of `dst`. This is safe, but it
1942/// could leak allocations or resources, so care should be taken not to overwrite
1943/// an object that should be dropped.
1944///
1945/// Additionally, it does not drop `src`. Semantically, `src` is moved into the
1946/// location pointed to by `dst`.
1947///
1948/// This is appropriate for initializing uninitialized memory, or overwriting
1949/// memory that has previously been read with [`read_unaligned`].
1950///
1951/// # Safety
1952///
1953/// Behavior is undefined if any of the following conditions are violated:
1954///
1955/// * `dst` must be [valid] for writes.
1956///
1957/// [valid]: self#safety
1958///
1959/// ## On `packed` structs
1960///
1961/// Attempting to create a raw pointer to an `unaligned` struct field with
1962/// an expression such as `&packed.unaligned as *const FieldType` creates an
1963/// intermediate unaligned reference before converting that to a raw pointer.
1964/// That this reference is temporary and immediately cast is inconsequential
1965/// as the compiler always expects references to be properly aligned.
1966/// As a result, using `&packed.unaligned as *const FieldType` causes immediate
1967/// *undefined behavior* in your program.
1968///
1969/// Instead, you must use the `&raw mut` syntax to create the pointer.
1970/// You may use that constructed pointer together with this function.
1971///
1972/// An example of how to do it and how this relates to `write_unaligned` is:
1973///
1974/// ```
1975/// #[repr(packed, C)]
1976/// struct Packed {
1977/// _padding: u8,
1978/// unaligned: u32,
1979/// }
1980///
1981/// let mut packed: Packed = unsafe { std::mem::zeroed() };
1982///
1983/// // Take the address of a 32-bit integer which is not aligned.
1984/// // In contrast to `&packed.unaligned as *mut _`, this has no undefined behavior.
1985/// let unaligned = &raw mut packed.unaligned;
1986///
1987/// unsafe { std::ptr::write_unaligned(unaligned, 42) };
1988///
1989/// assert_eq!({packed.unaligned}, 42); // `{...}` forces copying the field instead of creating a reference.
1990/// ```
1991///
1992/// Accessing unaligned fields directly with e.g. `packed.unaligned` is safe however
1993/// (as can be seen in the `assert_eq!` above).
1994///
1995/// # Examples
1996///
1997/// Write a `usize` value to a byte buffer:
1998///
1999/// ```
2000/// fn write_usize(x: &mut [u8], val: usize) {
2001/// assert!(x.len() >= size_of::<usize>());
2002///
2003/// let ptr = x.as_mut_ptr() as *mut usize;
2004///
2005/// unsafe { ptr.write_unaligned(val) }
2006/// }
2007/// ```
2008#[inline]
2009#[stable(feature = "ptr_unaligned", since = "1.17.0")]
2010#[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
2011#[rustc_diagnostic_item = "ptr_write_unaligned"]
2012#[track_caller]
2013pub const unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
2014 // SAFETY: the caller must guarantee that `dst` is valid for writes.
2015 // `dst` cannot overlap `src` because the caller has mutable access
2016 // to `dst` while `src` is owned by this function.
2017 unsafe {
2018 copy_nonoverlapping((&raw const src) as *const u8, dst as *mut u8, count:size_of::<T>());
2019 // We are calling the intrinsic directly to avoid function calls in the generated code.
2020 intrinsics::forget(src);
2021 }
2022}
2023
2024/// Performs a volatile read of the value from `src` without moving it. This
2025/// leaves the memory in `src` unchanged.
2026///
2027/// Volatile operations are intended to act on I/O memory, and are guaranteed
2028/// to not be elided or reordered by the compiler across other volatile
2029/// operations.
2030///
2031/// # Notes
2032///
2033/// Rust does not currently have a rigorously and formally defined memory model,
2034/// so the precise semantics of what "volatile" means here is subject to change
2035/// over time. That being said, the semantics will almost always end up pretty
2036/// similar to [C11's definition of volatile][c11].
2037///
2038/// The compiler shouldn't change the relative order or number of volatile
2039/// memory operations. However, volatile memory operations on zero-sized types
2040/// (e.g., if a zero-sized type is passed to `read_volatile`) are noops
2041/// and may be ignored.
2042///
2043/// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
2044///
2045/// # Safety
2046///
2047/// Behavior is undefined if any of the following conditions are violated:
2048///
2049/// * `src` must be [valid] for reads.
2050///
2051/// * `src` must be properly aligned.
2052///
2053/// * `src` must point to a properly initialized value of type `T`.
2054///
2055/// Like [`read`], `read_volatile` creates a bitwise copy of `T`, regardless of
2056/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned
2057/// value and the value at `*src` can [violate memory safety][read-ownership].
2058/// However, storing non-[`Copy`] types in volatile memory is almost certainly
2059/// incorrect.
2060///
2061/// Note that even if `T` has size `0`, the pointer must be properly aligned.
2062///
2063/// [valid]: self#safety
2064/// [read-ownership]: read#ownership-of-the-returned-value
2065///
2066/// Just like in C, whether an operation is volatile has no bearing whatsoever
2067/// on questions involving concurrent access from multiple threads. Volatile
2068/// accesses behave exactly like non-atomic accesses in that regard. In particular,
2069/// a race between a `read_volatile` and any write operation to the same location
2070/// is undefined behavior.
2071///
2072/// # Examples
2073///
2074/// Basic usage:
2075///
2076/// ```
2077/// let x = 12;
2078/// let y = &x as *const i32;
2079///
2080/// unsafe {
2081/// assert_eq!(std::ptr::read_volatile(y), 12);
2082/// }
2083/// ```
2084#[inline]
2085#[stable(feature = "volatile", since = "1.9.0")]
2086#[track_caller]
2087#[rustc_diagnostic_item = "ptr_read_volatile"]
2088pub unsafe fn read_volatile<T>(src: *const T) -> T {
2089 // SAFETY: the caller must uphold the safety contract for `volatile_load`.
2090 unsafe {
2091 ub_checks::assert_unsafe_precondition!(
2092 check_language_ub,
2093 "ptr::read_volatile requires that the pointer argument is aligned and non-null",
2094 (
2095 addr: *const () = src as *const (),
2096 align: usize = align_of::<T>(),
2097 is_zst: bool = T::IS_ZST,
2098 ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, is_zst)
2099 );
2100 intrinsics::volatile_load(src)
2101 }
2102}
2103
2104/// Performs a volatile write of a memory location with the given value without
2105/// reading or dropping the old value.
2106///
2107/// Volatile operations are intended to act on I/O memory, and are guaranteed
2108/// to not be elided or reordered by the compiler across other volatile
2109/// operations.
2110///
2111/// `write_volatile` does not drop the contents of `dst`. This is safe, but it
2112/// could leak allocations or resources, so care should be taken not to overwrite
2113/// an object that should be dropped.
2114///
2115/// Additionally, it does not drop `src`. Semantically, `src` is moved into the
2116/// location pointed to by `dst`.
2117///
2118/// # Notes
2119///
2120/// Rust does not currently have a rigorously and formally defined memory model,
2121/// so the precise semantics of what "volatile" means here is subject to change
2122/// over time. That being said, the semantics will almost always end up pretty
2123/// similar to [C11's definition of volatile][c11].
2124///
2125/// The compiler shouldn't change the relative order or number of volatile
2126/// memory operations. However, volatile memory operations on zero-sized types
2127/// (e.g., if a zero-sized type is passed to `write_volatile`) are noops
2128/// and may be ignored.
2129///
2130/// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
2131///
2132/// # Safety
2133///
2134/// Behavior is undefined if any of the following conditions are violated:
2135///
2136/// * `dst` must be [valid] for writes.
2137///
2138/// * `dst` must be properly aligned.
2139///
2140/// Note that even if `T` has size `0`, the pointer must be properly aligned.
2141///
2142/// [valid]: self#safety
2143///
2144/// Just like in C, whether an operation is volatile has no bearing whatsoever
2145/// on questions involving concurrent access from multiple threads. Volatile
2146/// accesses behave exactly like non-atomic accesses in that regard. In particular,
2147/// a race between a `write_volatile` and any other operation (reading or writing)
2148/// on the same location is undefined behavior.
2149///
2150/// # Examples
2151///
2152/// Basic usage:
2153///
2154/// ```
2155/// let mut x = 0;
2156/// let y = &mut x as *mut i32;
2157/// let z = 12;
2158///
2159/// unsafe {
2160/// std::ptr::write_volatile(y, z);
2161/// assert_eq!(std::ptr::read_volatile(y), 12);
2162/// }
2163/// ```
2164#[inline]
2165#[stable(feature = "volatile", since = "1.9.0")]
2166#[rustc_diagnostic_item = "ptr_write_volatile"]
2167#[track_caller]
2168pub unsafe fn write_volatile<T>(dst: *mut T, src: T) {
2169 // SAFETY: the caller must uphold the safety contract for `volatile_store`.
2170 unsafe {
2171 ub_checks::assert_unsafe_precondition!(
2172 check_language_ub,
2173 "ptr::write_volatile requires that the pointer argument is aligned and non-null",
2174 (
2175 addr: *mut () = dst as *mut (),
2176 align: usize = align_of::<T>(),
2177 is_zst: bool = T::IS_ZST,
2178 ) => ub_checks::maybe_is_aligned_and_not_null(addr, align, is_zst)
2179 );
2180 intrinsics::volatile_store(dst, val:src);
2181 }
2182}
2183
2184/// Align pointer `p`.
2185///
2186/// Calculate offset (in terms of elements of `size_of::<T>()` stride) that has to be applied
2187/// to pointer `p` so that pointer `p` would get aligned to `a`.
2188///
2189/// # Safety
2190/// `a` must be a power of two.
2191///
2192/// # Notes
2193/// This implementation has been carefully tailored to not panic. It is UB for this to panic.
2194/// The only real change that can be made here is change of `INV_TABLE_MOD_16` and associated
2195/// constants.
2196///
2197/// If we ever decide to make it possible to call the intrinsic with `a` that is not a
2198/// power-of-two, it will probably be more prudent to just change to a naive implementation rather
2199/// than trying to adapt this to accommodate that change.
2200///
2201/// Any questions go to @nagisa.
2202#[allow(ptr_to_integer_transmute_in_consts)]
2203pub(crate) unsafe fn align_offset<T: Sized>(p: *const T, a: usize) -> usize {
2204 // FIXME(#75598): Direct use of these intrinsics improves codegen significantly at opt-level <=
2205 // 1, where the method versions of these operations are not inlined.
2206 use intrinsics::{
2207 assume, cttz_nonzero, exact_div, mul_with_overflow, unchecked_rem, unchecked_shl,
2208 unchecked_shr, unchecked_sub, wrapping_add, wrapping_mul, wrapping_sub,
2209 };
2210
2211 /// Calculate multiplicative modular inverse of `x` modulo `m`.
2212 ///
2213 /// This implementation is tailored for `align_offset` and has following preconditions:
2214 ///
2215 /// * `m` is a power-of-two;
2216 /// * `x < m`; (if `x ≥ m`, pass in `x % m` instead)
2217 ///
2218 /// Implementation of this function shall not panic. Ever.
2219 #[inline]
2220 const unsafe fn mod_inv(x: usize, m: usize) -> usize {
2221 /// Multiplicative modular inverse table modulo 2⁴ = 16.
2222 ///
2223 /// Note, that this table does not contain values where inverse does not exist (i.e., for
2224 /// `0⁻¹ mod 16`, `2⁻¹ mod 16`, etc.)
2225 const INV_TABLE_MOD_16: [u8; 8] = [1, 11, 13, 7, 9, 3, 5, 15];
2226 /// Modulo for which the `INV_TABLE_MOD_16` is intended.
2227 const INV_TABLE_MOD: usize = 16;
2228
2229 // SAFETY: `m` is required to be a power-of-two, hence non-zero.
2230 let m_minus_one = unsafe { unchecked_sub(m, 1) };
2231 let mut inverse = INV_TABLE_MOD_16[(x & (INV_TABLE_MOD - 1)) >> 1] as usize;
2232 let mut mod_gate = INV_TABLE_MOD;
2233 // We iterate "up" using the following formula:
2234 //
2235 // $$ xy ≡ 1 (mod 2ⁿ) → xy (2 - xy) ≡ 1 (mod 2²ⁿ) $$
2236 //
2237 // This application needs to be applied at least until `2²ⁿ ≥ m`, at which point we can
2238 // finally reduce the computation to our desired `m` by taking `inverse mod m`.
2239 //
2240 // This computation is `O(log log m)`, which is to say, that on 64-bit machines this loop
2241 // will always finish in at most 4 iterations.
2242 loop {
2243 // y = y * (2 - xy) mod n
2244 //
2245 // Note, that we use wrapping operations here intentionally – the original formula
2246 // uses e.g., subtraction `mod n`. It is entirely fine to do them `mod
2247 // usize::MAX` instead, because we take the result `mod n` at the end
2248 // anyway.
2249 if mod_gate >= m {
2250 break;
2251 }
2252 inverse = wrapping_mul(inverse, wrapping_sub(2usize, wrapping_mul(x, inverse)));
2253 let (new_gate, overflow) = mul_with_overflow(mod_gate, mod_gate);
2254 if overflow {
2255 break;
2256 }
2257 mod_gate = new_gate;
2258 }
2259 inverse & m_minus_one
2260 }
2261
2262 let stride = size_of::<T>();
2263
2264 let addr: usize = p.addr();
2265
2266 // SAFETY: `a` is a power-of-two, therefore non-zero.
2267 let a_minus_one = unsafe { unchecked_sub(a, 1) };
2268
2269 if stride == 0 {
2270 // SPECIAL_CASE: handle 0-sized types. No matter how many times we step, the address will
2271 // stay the same, so no offset will be able to align the pointer unless it is already
2272 // aligned. This branch _will_ be optimized out as `stride` is known at compile-time.
2273 let p_mod_a = addr & a_minus_one;
2274 return if p_mod_a == 0 { 0 } else { usize::MAX };
2275 }
2276
2277 // SAFETY: `stride == 0` case has been handled by the special case above.
2278 let a_mod_stride = unsafe { unchecked_rem(a, stride) };
2279 if a_mod_stride == 0 {
2280 // SPECIAL_CASE: In cases where the `a` is divisible by `stride`, byte offset to align a
2281 // pointer can be computed more simply through `-p (mod a)`. In the off-chance the byte
2282 // offset is not a multiple of `stride`, the input pointer was misaligned and no pointer
2283 // offset will be able to produce a `p` aligned to the specified `a`.
2284 //
2285 // The naive `-p (mod a)` equation inhibits LLVM's ability to select instructions
2286 // like `lea`. We compute `(round_up_to_next_alignment(p, a) - p)` instead. This
2287 // redistributes operations around the load-bearing, but pessimizing `and` instruction
2288 // sufficiently for LLVM to be able to utilize the various optimizations it knows about.
2289 //
2290 // LLVM handles the branch here particularly nicely. If this branch needs to be evaluated
2291 // at runtime, it will produce a mask `if addr_mod_stride == 0 { 0 } else { usize::MAX }`
2292 // in a branch-free way and then bitwise-OR it with whatever result the `-p mod a`
2293 // computation produces.
2294
2295 let aligned_address = wrapping_add(addr, a_minus_one) & wrapping_sub(0, a);
2296 let byte_offset = wrapping_sub(aligned_address, addr);
2297 // FIXME: Remove the assume after <https://github.com/llvm/llvm-project/issues/62502>
2298 // SAFETY: Masking by `-a` can only affect the low bits, and thus cannot have reduced
2299 // the value by more than `a-1`, so even though the intermediate values might have
2300 // wrapped, the byte_offset is always in `[0, a)`.
2301 unsafe { assume(byte_offset < a) };
2302
2303 // SAFETY: `stride == 0` case has been handled by the special case above.
2304 let addr_mod_stride = unsafe { unchecked_rem(addr, stride) };
2305
2306 return if addr_mod_stride == 0 {
2307 // SAFETY: `stride` is non-zero. This is guaranteed to divide exactly as well, because
2308 // addr has been verified to be aligned to the original type’s alignment requirements.
2309 unsafe { exact_div(byte_offset, stride) }
2310 } else {
2311 usize::MAX
2312 };
2313 }
2314
2315 // GENERAL_CASE: From here on we’re handling the very general case where `addr` may be
2316 // misaligned, there isn’t an obvious relationship between `stride` and `a` that we can take an
2317 // advantage of, etc. This case produces machine code that isn’t particularly high quality,
2318 // compared to the special cases above. The code produced here is still within the realm of
2319 // miracles, given the situations this case has to deal with.
2320
2321 // SAFETY: a is power-of-two hence non-zero. stride == 0 case is handled above.
2322 // FIXME(const-hack) replace with min
2323 let gcdpow = unsafe {
2324 let x = cttz_nonzero(stride);
2325 let y = cttz_nonzero(a);
2326 if x < y { x } else { y }
2327 };
2328 // SAFETY: gcdpow has an upper-bound that’s at most the number of bits in a `usize`.
2329 let gcd = unsafe { unchecked_shl(1usize, gcdpow) };
2330 // SAFETY: gcd is always greater or equal to 1.
2331 if addr & unsafe { unchecked_sub(gcd, 1) } == 0 {
2332 // This branch solves for the following linear congruence equation:
2333 //
2334 // ` p + so = 0 mod a `
2335 //
2336 // `p` here is the pointer value, `s` - stride of `T`, `o` offset in `T`s, and `a` - the
2337 // requested alignment.
2338 //
2339 // With `g = gcd(a, s)`, and the above condition asserting that `p` is also divisible by
2340 // `g`, we can denote `a' = a/g`, `s' = s/g`, `p' = p/g`, then this becomes equivalent to:
2341 //
2342 // ` p' + s'o = 0 mod a' `
2343 // ` o = (a' - (p' mod a')) * (s'^-1 mod a') `
2344 //
2345 // The first term is "the relative alignment of `p` to `a`" (divided by the `g`), the
2346 // second term is "how does incrementing `p` by `s` bytes change the relative alignment of
2347 // `p`" (again divided by `g`). Division by `g` is necessary to make the inverse well
2348 // formed if `a` and `s` are not co-prime.
2349 //
2350 // Furthermore, the result produced by this solution is not "minimal", so it is necessary
2351 // to take the result `o mod lcm(s, a)`. This `lcm(s, a)` is the same as `a'`.
2352
2353 // SAFETY: `gcdpow` has an upper-bound not greater than the number of trailing 0-bits in
2354 // `a`.
2355 let a2 = unsafe { unchecked_shr(a, gcdpow) };
2356 // SAFETY: `a2` is non-zero. Shifting `a` by `gcdpow` cannot shift out any of the set bits
2357 // in `a` (of which it has exactly one).
2358 let a2minus1 = unsafe { unchecked_sub(a2, 1) };
2359 // SAFETY: `gcdpow` has an upper-bound not greater than the number of trailing 0-bits in
2360 // `a`.
2361 let s2 = unsafe { unchecked_shr(stride & a_minus_one, gcdpow) };
2362 // SAFETY: `gcdpow` has an upper-bound not greater than the number of trailing 0-bits in
2363 // `a`. Furthermore, the subtraction cannot overflow, because `a2 = a >> gcdpow` will
2364 // always be strictly greater than `(p % a) >> gcdpow`.
2365 let minusp2 = unsafe { unchecked_sub(a2, unchecked_shr(addr & a_minus_one, gcdpow)) };
2366 // SAFETY: `a2` is a power-of-two, as proven above. `s2` is strictly less than `a2`
2367 // because `(s % a) >> gcdpow` is strictly less than `a >> gcdpow`.
2368 return wrapping_mul(minusp2, unsafe { mod_inv(s2, a2) }) & a2minus1;
2369 }
2370
2371 // Cannot be aligned at all.
2372 usize::MAX
2373}
2374
2375/// Compares raw pointers for equality.
2376///
2377/// This is the same as using the `==` operator, but less generic:
2378/// the arguments have to be `*const T` raw pointers,
2379/// not anything that implements `PartialEq`.
2380///
2381/// This can be used to compare `&T` references (which coerce to `*const T` implicitly)
2382/// by their address rather than comparing the values they point to
2383/// (which is what the `PartialEq for &T` implementation does).
2384///
2385/// When comparing wide pointers, both the address and the metadata are tested for equality.
2386/// However, note that comparing trait object pointers (`*const dyn Trait`) is unreliable: pointers
2387/// to values of the same underlying type can compare inequal (because vtables are duplicated in
2388/// multiple codegen units), and pointers to values of *different* underlying type can compare equal
2389/// (since identical vtables can be deduplicated within a codegen unit).
2390///
2391/// # Examples
2392///
2393/// ```
2394/// use std::ptr;
2395///
2396/// let five = 5;
2397/// let other_five = 5;
2398/// let five_ref = &five;
2399/// let same_five_ref = &five;
2400/// let other_five_ref = &other_five;
2401///
2402/// assert!(five_ref == same_five_ref);
2403/// assert!(ptr::eq(five_ref, same_five_ref));
2404///
2405/// assert!(five_ref == other_five_ref);
2406/// assert!(!ptr::eq(five_ref, other_five_ref));
2407/// ```
2408///
2409/// Slices are also compared by their length (fat pointers):
2410///
2411/// ```
2412/// let a = [1, 2, 3];
2413/// assert!(std::ptr::eq(&a[..3], &a[..3]));
2414/// assert!(!std::ptr::eq(&a[..2], &a[..3]));
2415/// assert!(!std::ptr::eq(&a[0..2], &a[1..3]));
2416/// ```
2417#[stable(feature = "ptr_eq", since = "1.17.0")]
2418#[inline(always)]
2419#[must_use = "pointer comparison produces a value"]
2420#[rustc_diagnostic_item = "ptr_eq"]
2421#[allow(ambiguous_wide_pointer_comparisons)] // it's actually clear here
2422pub fn eq<T: ?Sized>(a: *const T, b: *const T) -> bool {
2423 a == b
2424}
2425
2426/// Compares the *addresses* of the two pointers for equality,
2427/// ignoring any metadata in fat pointers.
2428///
2429/// If the arguments are thin pointers of the same type,
2430/// then this is the same as [`eq`].
2431///
2432/// # Examples
2433///
2434/// ```
2435/// use std::ptr;
2436///
2437/// let whole: &[i32; 3] = &[1, 2, 3];
2438/// let first: &i32 = &whole[0];
2439///
2440/// assert!(ptr::addr_eq(whole, first));
2441/// assert!(!ptr::eq::<dyn std::fmt::Debug>(whole, first));
2442/// ```
2443#[stable(feature = "ptr_addr_eq", since = "1.76.0")]
2444#[inline(always)]
2445#[must_use = "pointer comparison produces a value"]
2446pub fn addr_eq<T: ?Sized, U: ?Sized>(p: *const T, q: *const U) -> bool {
2447 (p as *const ()) == (q as *const ())
2448}
2449
2450/// Compares the *addresses* of the two function pointers for equality.
2451///
2452/// This is the same as `f == g`, but using this function makes clear that the potentially
2453/// surprising semantics of function pointer comparison are involved.
2454///
2455/// There are **very few guarantees** about how functions are compiled and they have no intrinsic
2456/// “identity”; in particular, this comparison:
2457///
2458/// * May return `true` unexpectedly, in cases where functions are equivalent.
2459///
2460/// For example, the following program is likely (but not guaranteed) to print `(true, true)`
2461/// when compiled with optimization:
2462///
2463/// ```
2464/// let f: fn(i32) -> i32 = |x| x;
2465/// let g: fn(i32) -> i32 = |x| x + 0; // different closure, different body
2466/// let h: fn(u32) -> u32 = |x| x + 0; // different signature too
2467/// dbg!(std::ptr::fn_addr_eq(f, g), std::ptr::fn_addr_eq(f, h)); // not guaranteed to be equal
2468/// ```
2469///
2470/// * May return `false` in any case.
2471///
2472/// This is particularly likely with generic functions but may happen with any function.
2473/// (From an implementation perspective, this is possible because functions may sometimes be
2474/// processed more than once by the compiler, resulting in duplicate machine code.)
2475///
2476/// Despite these false positives and false negatives, this comparison can still be useful.
2477/// Specifically, if
2478///
2479/// * `T` is the same type as `U`, `T` is a [subtype] of `U`, or `U` is a [subtype] of `T`, and
2480/// * `ptr::fn_addr_eq(f, g)` returns true,
2481///
2482/// then calling `f` and calling `g` will be equivalent.
2483///
2484///
2485/// # Examples
2486///
2487/// ```
2488/// use std::ptr;
2489///
2490/// fn a() { println!("a"); }
2491/// fn b() { println!("b"); }
2492/// assert!(!ptr::fn_addr_eq(a as fn(), b as fn()));
2493/// ```
2494///
2495/// [subtype]: https://doc.rust-lang.org/reference/subtyping.html
2496#[stable(feature = "ptr_fn_addr_eq", since = "1.85.0")]
2497#[inline(always)]
2498#[must_use = "function pointer comparison produces a value"]
2499pub fn fn_addr_eq<T: FnPtr, U: FnPtr>(f: T, g: U) -> bool {
2500 f.addr() == g.addr()
2501}
2502
2503/// Hash a raw pointer.
2504///
2505/// This can be used to hash a `&T` reference (which coerces to `*const T` implicitly)
2506/// by its address rather than the value it points to
2507/// (which is what the `Hash for &T` implementation does).
2508///
2509/// # Examples
2510///
2511/// ```
2512/// use std::hash::{DefaultHasher, Hash, Hasher};
2513/// use std::ptr;
2514///
2515/// let five = 5;
2516/// let five_ref = &five;
2517///
2518/// let mut hasher = DefaultHasher::new();
2519/// ptr::hash(five_ref, &mut hasher);
2520/// let actual = hasher.finish();
2521///
2522/// let mut hasher = DefaultHasher::new();
2523/// (five_ref as *const i32).hash(&mut hasher);
2524/// let expected = hasher.finish();
2525///
2526/// assert_eq!(actual, expected);
2527/// ```
2528#[stable(feature = "ptr_hash", since = "1.35.0")]
2529pub fn hash<T: ?Sized, S: hash::Hasher>(hashee: *const T, into: &mut S) {
2530 use crate::hash::Hash;
2531 hashee.hash(state:into);
2532}
2533
2534#[stable(feature = "fnptr_impls", since = "1.4.0")]
2535impl<F: FnPtr> PartialEq for F {
2536 #[inline]
2537 fn eq(&self, other: &Self) -> bool {
2538 self.addr() == other.addr()
2539 }
2540}
2541#[stable(feature = "fnptr_impls", since = "1.4.0")]
2542impl<F: FnPtr> Eq for F {}
2543
2544#[stable(feature = "fnptr_impls", since = "1.4.0")]
2545impl<F: FnPtr> PartialOrd for F {
2546 #[inline]
2547 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
2548 self.addr().partial_cmp(&other.addr())
2549 }
2550}
2551#[stable(feature = "fnptr_impls", since = "1.4.0")]
2552impl<F: FnPtr> Ord for F {
2553 #[inline]
2554 fn cmp(&self, other: &Self) -> Ordering {
2555 self.addr().cmp(&other.addr())
2556 }
2557}
2558
2559#[stable(feature = "fnptr_impls", since = "1.4.0")]
2560impl<F: FnPtr> hash::Hash for F {
2561 fn hash<HH: hash::Hasher>(&self, state: &mut HH) {
2562 state.write_usize(self.addr() as _)
2563 }
2564}
2565
2566#[stable(feature = "fnptr_impls", since = "1.4.0")]
2567impl<F: FnPtr> fmt::Pointer for F {
2568 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2569 fmt::pointer_fmt_inner(self.addr() as _, f)
2570 }
2571}
2572
2573#[stable(feature = "fnptr_impls", since = "1.4.0")]
2574impl<F: FnPtr> fmt::Debug for F {
2575 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2576 fmt::pointer_fmt_inner(self.addr() as _, f)
2577 }
2578}
2579
2580/// Creates a `const` raw pointer to a place, without creating an intermediate reference.
2581///
2582/// `addr_of!(expr)` is equivalent to `&raw const expr`. The macro is *soft-deprecated*;
2583/// use `&raw const` instead.
2584///
2585/// It is still an open question under which conditions writing through an `addr_of!`-created
2586/// pointer is permitted. If the place `expr` evaluates to is based on a raw pointer, then the
2587/// result of `addr_of!` inherits all permissions from that raw pointer. However, if the place is
2588/// based on a reference, local variable, or `static`, then until all details are decided, the same
2589/// rules as for shared references apply: it is UB to write through a pointer created with this
2590/// operation, except for bytes located inside an `UnsafeCell`. Use `&raw mut` (or [`addr_of_mut`])
2591/// to create a raw pointer that definitely permits mutation.
2592///
2593/// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned
2594/// and points to initialized data. For cases where those requirements do not hold,
2595/// raw pointers should be used instead. However, `&expr as *const _` creates a reference
2596/// before casting it to a raw pointer, and that reference is subject to the same rules
2597/// as all other references. This macro can create a raw pointer *without* creating
2598/// a reference first.
2599///
2600/// See [`addr_of_mut`] for how to create a pointer to uninitialized data.
2601/// Doing that with `addr_of` would not make much sense since one could only
2602/// read the data, and that would be Undefined Behavior.
2603///
2604/// # Safety
2605///
2606/// The `expr` in `addr_of!(expr)` is evaluated as a place expression, but never loads from the
2607/// place or requires the place to be dereferenceable. This means that `addr_of!((*ptr).field)`
2608/// still requires the projection to `field` to be in-bounds, using the same rules as [`offset`].
2609/// However, `addr_of!(*ptr)` is defined behavior even if `ptr` is null, dangling, or misaligned.
2610///
2611/// Note that `Deref`/`Index` coercions (and their mutable counterparts) are applied inside
2612/// `addr_of!` like everywhere else, in which case a reference is created to call `Deref::deref` or
2613/// `Index::index`, respectively. The statements above only apply when no such coercions are
2614/// applied.
2615///
2616/// [`offset`]: pointer::offset
2617///
2618/// # Example
2619///
2620/// **Correct usage: Creating a pointer to unaligned data**
2621///
2622/// ```
2623/// use std::ptr;
2624///
2625/// #[repr(packed)]
2626/// struct Packed {
2627/// f1: u8,
2628/// f2: u16,
2629/// }
2630///
2631/// let packed = Packed { f1: 1, f2: 2 };
2632/// // `&packed.f2` would create an unaligned reference, and thus be Undefined Behavior!
2633/// let raw_f2 = ptr::addr_of!(packed.f2);
2634/// assert_eq!(unsafe { raw_f2.read_unaligned() }, 2);
2635/// ```
2636///
2637/// **Incorrect usage: Out-of-bounds fields projection**
2638///
2639/// ```rust,no_run
2640/// use std::ptr;
2641///
2642/// #[repr(C)]
2643/// struct MyStruct {
2644/// field1: i32,
2645/// field2: i32,
2646/// }
2647///
2648/// let ptr: *const MyStruct = ptr::null();
2649/// let fieldptr = unsafe { ptr::addr_of!((*ptr).field2) }; // Undefined Behavior ⚠️
2650/// ```
2651///
2652/// The field projection `.field2` would offset the pointer by 4 bytes,
2653/// but the pointer is not in-bounds of an allocation for 4 bytes,
2654/// so this offset is Undefined Behavior.
2655/// See the [`offset`] docs for a full list of requirements for inbounds pointer arithmetic; the
2656/// same requirements apply to field projections, even inside `addr_of!`. (In particular, it makes
2657/// no difference whether the pointer is null or dangling.)
2658#[stable(feature = "raw_ref_macros", since = "1.51.0")]
2659#[rustc_macro_transparency = "semitransparent"]
2660pub macro addr_of($place:expr) {
2661 &raw const $place
2662}
2663
2664/// Creates a `mut` raw pointer to a place, without creating an intermediate reference.
2665///
2666/// `addr_of_mut!(expr)` is equivalent to `&raw mut expr`. The macro is *soft-deprecated*;
2667/// use `&raw mut` instead.
2668///
2669/// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned
2670/// and points to initialized data. For cases where those requirements do not hold,
2671/// raw pointers should be used instead. However, `&mut expr as *mut _` creates a reference
2672/// before casting it to a raw pointer, and that reference is subject to the same rules
2673/// as all other references. This macro can create a raw pointer *without* creating
2674/// a reference first.
2675///
2676/// # Safety
2677///
2678/// The `expr` in `addr_of_mut!(expr)` is evaluated as a place expression, but never loads from the
2679/// place or requires the place to be dereferenceable. This means that `addr_of_mut!((*ptr).field)`
2680/// still requires the projection to `field` to be in-bounds, using the same rules as [`offset`].
2681/// However, `addr_of_mut!(*ptr)` is defined behavior even if `ptr` is null, dangling, or misaligned.
2682///
2683/// Note that `Deref`/`Index` coercions (and their mutable counterparts) are applied inside
2684/// `addr_of_mut!` like everywhere else, in which case a reference is created to call `Deref::deref`
2685/// or `Index::index`, respectively. The statements above only apply when no such coercions are
2686/// applied.
2687///
2688/// [`offset`]: pointer::offset
2689///
2690/// # Examples
2691///
2692/// **Correct usage: Creating a pointer to unaligned data**
2693///
2694/// ```
2695/// use std::ptr;
2696///
2697/// #[repr(packed)]
2698/// struct Packed {
2699/// f1: u8,
2700/// f2: u16,
2701/// }
2702///
2703/// let mut packed = Packed { f1: 1, f2: 2 };
2704/// // `&mut packed.f2` would create an unaligned reference, and thus be Undefined Behavior!
2705/// let raw_f2 = ptr::addr_of_mut!(packed.f2);
2706/// unsafe { raw_f2.write_unaligned(42); }
2707/// assert_eq!({packed.f2}, 42); // `{...}` forces copying the field instead of creating a reference.
2708/// ```
2709///
2710/// **Correct usage: Creating a pointer to uninitialized data**
2711///
2712/// ```rust
2713/// use std::{ptr, mem::MaybeUninit};
2714///
2715/// struct Demo {
2716/// field: bool,
2717/// }
2718///
2719/// let mut uninit = MaybeUninit::<Demo>::uninit();
2720/// // `&uninit.as_mut().field` would create a reference to an uninitialized `bool`,
2721/// // and thus be Undefined Behavior!
2722/// let f1_ptr = unsafe { ptr::addr_of_mut!((*uninit.as_mut_ptr()).field) };
2723/// unsafe { f1_ptr.write(true); }
2724/// let init = unsafe { uninit.assume_init() };
2725/// ```
2726///
2727/// **Incorrect usage: Out-of-bounds fields projection**
2728///
2729/// ```rust,no_run
2730/// use std::ptr;
2731///
2732/// #[repr(C)]
2733/// struct MyStruct {
2734/// field1: i32,
2735/// field2: i32,
2736/// }
2737///
2738/// let ptr: *mut MyStruct = ptr::null_mut();
2739/// let fieldptr = unsafe { ptr::addr_of_mut!((*ptr).field2) }; // Undefined Behavior ⚠️
2740/// ```
2741///
2742/// The field projection `.field2` would offset the pointer by 4 bytes,
2743/// but the pointer is not in-bounds of an allocation for 4 bytes,
2744/// so this offset is Undefined Behavior.
2745/// See the [`offset`] docs for a full list of requirements for inbounds pointer arithmetic; the
2746/// same requirements apply to field projections, even inside `addr_of_mut!`. (In particular, it
2747/// makes no difference whether the pointer is null or dangling.)
2748#[stable(feature = "raw_ref_macros", since = "1.51.0")]
2749#[rustc_macro_transparency = "semitransparent"]
2750pub macro addr_of_mut($place:expr) {
2751 &raw mut $place
2752}
2753