Skip to content
Tutorials Center
My learning

Topics

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.

Rust
use std::ptr;

let mut x = 10;
let p: *mut i32 = &mut x;
unsafe { ptr::write(p, 11) };

Try it

Rust read, write, swap and null checks

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.

Rust copy and NonNull

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

Rust
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, offset counts elements, not bytes; stepping outside the original allocation is undefined behavior even if you never dereference it. wrapping_add has no such rule.
  • Use addr_of!(s.field) / &raw const to take a pointer to a packed or uninitialized field without creating a reference.
  • A pointer is not a reference: creating &mut *p asserts exclusive access for as long as the reference is used.
  • ptr::read followed by use of the original is a double drop for String and friends. Wrap with ManuallyDrop or mem::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.