Convert an address back to a pointer, picking up a previously ‘exposed’ provenance.
This is equivalent to
addr as *const T. The provenance of the returned pointer is that of any
pointer that was previously exposed by passing it to
ptr as usize cast. In addition, memory which is outside the control of the Rust abstract
machine (MMIO registers, for example) is always considered to be exposed, so long as this memory
is disjoint from memory that will be used by the abstract machine such as the stack, heap,
If there is no ‘exposed’ provenance that justifies the way this pointer will be used, the program has undefined behavior. In particular, the aliasing rules still apply: pointers and references that have been invalidated due to aliasing accesses cannot be used any more, even if they have been exposed!
Note that there is no algorithm that decides which provenance will be used. You can think of this as “guessing” the right provenance, and the guess will be “maximally in your favor”, in the sense that if there is any way to avoid undefined behavior (while upholding all aliasing requirements), then that is the guess that will be taken.
On platforms with multiple address spaces, it is your responsibility to ensure that the address makes sense in the address space that this pointer will be used with.
Using this method means that code is not following strict provenance rules. “Guessing” a
suitable provenance complicates specification and reasoning and may not be supported by
tools that help you to stay conformant with the Rust memory model, so it is recommended to
with_addr wherever possible.
On most platforms this will produce a value with the same bytes as the address. Platforms which need to store additional information in a pointer may not support this operation, since it is generally not possible to actually compute which provenance the returned pointer has to pick up.
This API and its claimed semantics are part of the Strict Provenance experiment, see the module documentation for details.