rust-unsafe

Rust unsafe

Purpose

Guide agents through writing, reviewing, and reasoning about unsafe Rust: what operations require unsafe, how to write safe abstractions, audit patterns, common pitfalls, and when to reach for unsafe.

Triggers

• "When do I need to use unsafe in Rust?"
• "How do I write a safe abstraction over unsafe code?"
• "How do I audit an unsafe block?"
• "What are the rules for raw pointers in Rust?"
• "What does transmute do and when is it safe?"
• "How do I implement UnsafeCell correctly?"

Workflow

1. The five unsafe superpowers

unsafe grants exactly five capabilities not available in safe Rust:

1. Dereference raw pointers (*const T, *mut T)
2. Call unsafe functions (including extern "C" functions)
3. Access or modify mutable static variables
4. Implement unsafe traits (Send, Sync)
5. Access fields of unions

Everything else in Rust — including memory allocation, borrowing, closures — follows safe rules even inside unsafe blocks.

2. Raw pointers

// Creating raw pointers (safe — no dereference yet)
let x = 42u32;
let ptr: *const u32 = &x;
let mut_ptr: *mut u32 = &mut some_val as *mut u32;

// Null pointer
let null: *const u32 = std::ptr::null();
let null_mut: *mut u32 = std::ptr::null_mut();

// Dereference (unsafe)
let val = unsafe { *ptr };

// Null check
if !ptr.is_null() {
    let val = unsafe { *ptr };
}

// Offset (safe to compute, unsafe to dereference)
let arr = [1u32, 2, 3, 4, 5];
let p = arr.as_ptr();
let third = unsafe { *p.add(2) };   // arr[2]
let also_third = unsafe { *p.offset(2) };

// Slice from raw parts
let slice: &[u32] = unsafe {
    std::slice::from_raw_parts(p, arr.len())
};

Rules for sound raw pointer dereference:

• Pointer must be non-null
• Pointer must be aligned for T
• Memory must be initialized for T
• Must not violate aliasing rules (only one &mut to a location)
• Memory must be valid for the lifetime of the reference

3. unsafe functions and traits