Rust Reference ยท Primitive Types
Rust raw pointers: *const T and *mut T
Reference for Rust raw pointers: creating them safely, dereferencing in unsafe code, add/offset arithmetic, null checks, Box::into_raw and NonNull.
Raw pointers, *const T and *mut T, are addresses without the guarantees of references. They may be null, dangling, unaligned or alias each other, and the borrow checker ignores them. Creating a raw pointer is safe; dereferencing one is unsafe, because you take over the proof that the address is valid.
You need raw pointers for FFI, for building data structures like linked lists and arenas, and for implementing the standard library's own containers. Everyday code should use references, Box, Rc and slices.
let x = 7; let p: *const i32 = &x; let v = unsafe { *p };
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
&raw const place // *const T, no intermediate reference &raw mut place // *mut T r as *const T // cast a reference or another pointer p.cast::<U>() // change pointee type unsafe { *p } // read; unsafe { *p = v } writes
| Method | Description |
|---|---|
is_null() |
True for the null address. |
add(n), sub(n), offset(n) |
Move by n elements (not bytes); unsafe, and the result must stay inside the same allocation (or one past its end). |
read(), write(v) |
Move a value out of or into the address without dropping the old value on write. |
read_unaligned() |
Reads from an address that may not be aligned for T. |
as_ref(), as_mut() |
Convert to Option<&T>/Option<&mut T>, None for null; unsafe. |
offset_from(other) |
Signed distance in elements within one allocation; unsafe. |
wrapping_add(n) |
Safe arithmetic that may produce an invalid pointer, without undefined behavior until dereferenced. |
Undefined behavior includes: dereferencing null or dangling pointers, reading uninitialized data as a typed value, misaligned reads (outside read_unaligned), creating two live &mut to the same place, and freeing memory with the wrong allocator.
Usage notes
- Prefer
&raw const/&raw mutover&x as *const _when the place may be a packed field or astatic mut: it never creates an intermediate reference. *const Tversus*mut T: casting between them is allowed withas; the distinction is a lint-level hint. For variance,*const Tis covariant and*mut Tinvariant.NonNull<T>is a non-null*mut Twrapper;Option<NonNull<T>>is pointer-sized, which is why linked lists use it.- Ownership:
Box::into_rawleaks the box until you callBox::from_raw; callingfrom_rawtwice is a double free. - Pointers are
!Sendand!Syncby default, so a type holding one needs anunsafe implbefore it crosses threads. - Comparing pointers with
==compares addresses; for fat pointers (slices,dyn) it also compares metadata. - Edition 2024:
unsafe_op_in_unsafe_fnwarns when anunsafe fnbody uses unsafe operations without its ownunsafeblock. - Test unsafe code with Miri (see
cargo miri).