Function std::ptr::with_exposed_provenance_mut

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

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

This is a more rigorously specified alternative to addr as *mut T. The provenance of the returned pointer is that of any pointer that was previously passed to expose_provenance or a ptr as usize cast. If there is no previously ‘exposed’ provenance that justifies the way this pointer will be used, the program has undefined behavior. 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, 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.