| # sptr: The Strict Provenance Polyfill |
| |
| [](https://crates.io/crates/sptr) [](https://docs.rs/sptr)  |
| |
| |
| |
| |
| This library provides a stable polyfill for Rust's [Strict Provenance] experiment. |
| |
| # Mapping to STD APIs: |
| |
| This crate "overlays" a bunch of unstable std apis, here are the mappings: |
| |
| ## core::ptr (sptr) |
| |
| * `pub fn `[`invalid`]`<T>(addr: usize) -> *const T;` |
| * `pub fn `[`invalid_mut`]`<T>(addr: usize) -> *mut T;` |
| * `pub fn `[`from_exposed_addr`]`<T>(addr: usize) -> *const T;` |
| * `pub fn `[`from_exposed_addr_mut`]`<T>(addr: usize) -> *mut T;` |
| |
| |
| ## core::pointer (sptr::Strict) |
| |
| * `pub fn `[`addr`]`(self) -> usize;` |
| * `pub fn `[`expose_addr`]`(self) -> usize;` |
| * `pub fn `[`with_addr`]`(self, addr: usize) -> Self;` |
| * `pub fn `[`map_addr`]`(self, f: impl FnOnce(usize) -> usize) -> Self;` |
| |
| |
| ## NON-STANDARD EXTENSIONS (disabled by default, use at your own risk) |
| |
| * `sptr::`[`uptr`] (feature = uptr) |
| * `sptr::`[`iptr`] (feature = uptr) |
| * `sptr::`[`OpaqueFnPtr`] (feature = opaque_fn) |
| |
| |
| |
| |
| # Applying The Overlay |
| |
| Swapping between sptr and core::ptr should be as simple as switching between `sptr::` and `ptr::` |
| for static functions. For methods, you must import `sptr::Strict` into your module for |
| the extension trait's methods to overlay std. The compiler will (understandably) |
| complain that you are overlaying std, so you will need to also silence that as |
| seen in the following example: |
| |
| ```rust |
| #![allow(unstable_name_collisions)] |
| use sptr::Strict; |
| |
| let ptr = sptr::invalid_mut::<u8>(1); |
| println!("{}", ptr.addr()); |
| ``` |
| |
| By default, this crate will also mark methods on pointers as "deprecated" if they are |
| incompatible with strict_provenance. If you don't want this, set `default-features = false` |
| in your Cargo.toml. |
| |
| Rust is the canonical source of definitions for these APIs and semantics, but the docs |
| here will vaguely try to mirror the docs checked into Rust. |
| |
| |
| [`invalid`]: https://docs.rs/sptr/latest/sptr/fn.invalid.html |
| [`invalid_mut`]: https://docs.rs/sptr/latest/sptr/fn.invalid_mut.html |
| [`from_exposed_addr`]: https://docs.rs/sptr/latest/sptr/fn.from_exposed_addr.html |
| [`from_exposed_addr_mut`]: https://docs.rs/sptr/latest/sptr/fn.from_exposed_addr_mut.html |
| [`addr`]: https://docs.rs/sptr/latest/sptr/trait.Strict.html#tymethod.addr |
| [`expose_addr`]: https://docs.rs/sptr/latest/sptr/trait.Strict.html#tymethod.expose_addr |
| [`with_addr`]: https://docs.rs/sptr/latest/sptr/trait.Strict.html#tymethod.with_addr |
| [`map_addr`]: https://docs.rs/sptr/latest/sptr/trait.Strict.html#tymethod.map_addr |
| [`uptr`]: https://docs.rs/sptr/latest/sptr/int/struct.uptr.html |
| [`iptr`]: https://docs.rs/sptr/latest/sptr/int/struct.iptr.html |
| [`OpaqueFnPtr`]: https://docs.rs/sptr/latest/sptr/func/struct.OpaqueFnPtr.html |
