25.3 Raw Pointers in Rust

Rust provides two forms of raw pointers:

  • *const T — a pointer to a constant T (read-only).
  • *mut T — a pointer to a mutable T.

Here, the * is part of the type name, indicating a raw pointer to either a read-only (const) or mutable (mut) target. There is no type of the form *T without const or mut.

Raw pointers permit unrestricted memory access and allow you to construct data structures that Rust’s type system would normally forbid.

25.3.1 Creating vs. Dereferencing Raw Pointers

You can create raw pointers by casting references, and you dereference them with the * operator. While Rust automatically dereferences safe references, it does not do so for raw pointers.

  • Creating, passing around, or comparing raw pointers is safe.
  • Dereferencing a raw pointer to read or write memory is unsafe.

Other pointer operations, like adding an offset, can be safe or unsafe: for example, ptr.add() is considered unsafe, whereas ptr.wrapping_add() is safe, even though it can produce an invalid address.

fn increment_value_by_pointer() {
    let mut value = 10;
    // Converting a mutable reference to a raw pointer is safe.
    let value_ptr = &mut value as *mut i32;
    
    // Dereferencing the raw pointer to modify the value is unsafe.
    unsafe {
        *value_ptr += 1;
        println!("The incremented value is: {}", *value_ptr);
    }
}

fn dereference_raw_pointers() {
    let mut num = 5;
    let r1 = &num as *const i32;
    let r2 = &mut num as *mut i32;

    // Potentially invalid raw pointers:
    let invalid0 = &mut 0 as *const i32;      // Points to a temporary
    let invalid1 = &mut 123456 as *const i32; // Arbitrary invalid address
    let invalid2 = &mut 0xABCD as *mut i32;   // Also invalid

    unsafe {
        println!("r1 is: {}", *r1);
        println!("r2 is: {}", *r2);
        // Dereferencing invalid0, invalid1, or invalid2 here would be undefined behavior.
    }
}

fn main() {
    increment_value_by_pointer();
    dereference_raw_pointers();
}

Because r1 and r2 originate from valid references, we assume it is safe to dereference them. This assumption does not hold for arbitrary raw pointers. Merely owning an invalid pointer is not immediately dangerous, but dereferencing it is undefined behavior.

25.3.2 Pointer Arithmetic

Raw pointers enable arithmetic similar to what you might do in C. For instance, you can move a pointer forward by a certain number of elements in an array:

fn pointer_arithmetic_example() {
    let arr = [10, 20, 30, 40, 50];
    let ptr = arr.as_ptr(); // A raw pointer to the array

    unsafe {
        // Move the pointer forward by 2 elements (not bytes).
        let third_ptr = ptr.add(2);
        println!("The third element is: {}", *third_ptr);
    }
}

fn main() {
    pointer_arithmetic_example();
}

Because ptr.add(2) bypasses Rust’s checks for bounds and layout, using it is inherently unsafe. For more details on raw pointers, see Pointers.

25.3.3 Fat Pointers

A raw pointer to an unsized type is called a fat pointer, akin to an unsized reference or Box. For example, *const [i32] contains both the pointer address and the slice’s length.