Function core::ptr::with_exposed_provenance

source · 
pub fn with_exposed_provenance<T>(addr: usize) -> *const T
where
    T: Sized,
🔬This is a nightly-only experimental API. (exposed_provenance #95228)
Expand description

Converts an address back to a pointer, picking up a previously ‘exposed’ provenance.

This is a more rigorously specified alternative to addr as *const T. The provenance of the returned pointer is that of any pointer that was previously exposed by passing it to expose_provenance, or a 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, and statics.

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 anymore, 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 function 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 use 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.

It is unclear whether this function can be given a satisfying unambiguous specification. This API and its claimed semantics are part of Exposed Provenance.