Rust Reference ยท Smart Pointers and Memory
The std::ptr module
Reference for Rust std::ptr: null, null_mut, NonNull, read, write, copy, copy_nonoverlapping, swap, drop_in_place, eq and addr_of!, with safety rules.
std::ptr contains the functions and types for working with raw pointers (*const T and *mut T): creating null pointers, reading and writing through them, copying memory and wrapping pointers in the non-null type NonNull<T>. Creating and comparing raw pointers is safe; dereferencing them is not.
Everything that touches memory through a raw pointer is unsafe, because you must guarantee that the pointer is non-null, aligned, points to initialized and live memory, and that Rust's aliasing rules still hold. The module is the foundation for building containers, FFI wrappers and allocators.
use std::ptr; let mut x = 10; let p: *mut i32 = &mut x; unsafe { ptr::write(p, 11) };
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
pub const fn null<T>() -> *const T; pub const fn null_mut<T>() -> *mut T; pub const unsafe fn read<T>(src: *const T) -> T; pub unsafe fn write<T>(dst: *mut T, src: T); pub const unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize); pub const unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize); pub unsafe fn swap<T>(x: *mut T, y: *mut T); pub unsafe fn replace<T>(dst: *mut T, src: T) -> T; pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T); pub fn eq<T: ?Sized>(a: *const T, b: *const T) -> bool; pub struct NonNull<T: ?Sized> { /* private */ }
| Function | Description |
|---|---|
null() / null_mut() |
The null pointer; check with .is_null(). |
read(p) |
Copies the value out bitwise; leaves the source untouched. For non-Copy types you now have two owners, so you must forget one. |
write(p, v) |
Stores v without dropping the old contents (use for uninitialized memory). |
copy / copy_nonoverlapping |
memmove / memcpy for count elements (not bytes). |
swap, replace |
Exchange or replace values behind raw pointers. |
drop_in_place(p) |
Runs the destructor of the pointee without freeing memory. |
eq(a, b) |
Compares addresses (and metadata); not the pointed values. |
NonNull<T> |
Wrapper for a non-null *mut T; covariant; enables Option<NonNull<T>> as a nullable pointer of the same size. |
Safety requirements. For read/write/copy: the pointer must be valid for the access, properly aligned (use read_unaligned/write_unaligned otherwise) and, for read, point to an initialized value. copy_nonoverlapping additionally requires the two ranges not to overlap.
Usage notes
- Pointer arithmetic with
add,sub,offsetcounts elements, not bytes; stepping outside the original allocation is undefined behavior even if you never dereference it.wrapping_addhas no such rule. - Use
addr_of!(s.field)/&raw constto take a pointer to a packed or uninitialized field without creating a reference. - A pointer is not a reference: creating
&mut *passerts exclusive access for as long as the reference is used. ptr::readfollowed by use of the original is a double drop forStringand friends. Wrap withManuallyDropormem::forget.- Tools such as Miri (
cargo +nightly miri test) catch many violations. Those tools are read-only here. NonNull::dangling()gives an aligned, non-null, unusable pointer, the standard placeholder for empty containers and zero-sized allocations.