Rust Unsafe

Unsafe Rust & FFI

Core Question

Can this be done without unsafe? If not, what invariants must be upheld?

Most Rust code never needs unsafe. Before reaching for it:

• Check if a safe abstraction already exists in std or a well-audited crate.
• Check if the borrow checker complaint reveals a design problem, not a limitation.
• If unsafe is truly needed, identify every invariant the compiler can no longer enforce.

If you cannot precisely state the invariants, you do not understand the code well enough to use unsafe.

Quick Decisions

Review Checklist

Before approving any unsafe block, verify each applicable item:

Required Documentation

Every unsafe block: // SAFETY: comment

pub fn get(&self, index: usize) -> Option<&T> {
    if index < self.len {
        // SAFETY: bounds check above guarantees index < len,
        // so this access is within the allocated region.
        Some(unsafe { &*self.ptr.as_ptr().add(index) })
    } else {
        None
    }
}

Every unsafe function: /// # Safety doc section

/// Constructs a `Name` from raw UTF-8 bytes without validation.
///
/// # Safety
///
/// - `bytes` must contain valid UTF-8.
/// - `bytes` must not be empty.
/// - The caller retains no mutable reference to `bytes` after this call.
pub unsafe fn from_utf8_unchecked(bytes: Vec<u8>) -> Name {
    Name(String::from_utf8_unchecked(bytes))
}

Every unsafe trait impl: // SAFETY: comment above impl

// SAFETY: All fields of Buffer are Send-safe (Vec<u8> and usize).
// The raw pointer field is only dereferenced while &self is held.
unsafe impl Send for Buffer {}

Enforce with: #![warn(clippy::undocumented_unsafe_blocks)]

Deprecated → Better

FFI Patterns

repr attributes

Safe wrapper pattern

mod ffi {
    use std::os::raw::c_int;

    extern "C" {
        pub fn compress(src: *const u8, src_len: usize,
                        dst: *mut u8, dst_len: *mut usize) -> c_int;
    }
}

pub fn compress(input: &[u8]) -> Result<Vec<u8>, CompressError> {
    let mut buf = vec![0u8; max_compressed_size(input.len())];
    let mut out_len = buf.len();

    // SAFETY: input and buf are valid slices, out_len points to a valid usize.
    // compress() writes at most out_len bytes to dst.
    let rc = unsafe {
        ffi::compress(
            input.as_ptr(), input.len(),
            buf.as_mut_ptr(), &mut out_len,
        )
    };

    if rc != 0 {
        return Err(CompressError(rc));
    }
    buf.truncate(out_len);
    Ok(buf)
}

Usage Scenarios

Scenario 1: "I need to call a C library from Rust." → Use bindgen to generate bindings. Wrap every FFI call in a safe function that validates inputs and checks return codes. Use #[repr(C)] on structs shared across the boundary. Use #[repr(transparent)] for newtype wrappers of C types. Bind CString to a variable before calling .as_ptr().

Scenario 2: "I'm reviewing code that uses unsafe — what do I check?" → Load references/checklist.md. For each unsafe block: verify a // SAFETY: comment exists and is accurate, check every item in the review checklist above, and confirm there is no safe alternative. For unsafe fn, verify the # Safety doc section lists all caller obligations.

Scenario 3: "The borrow checker won't let me do X — should I use unsafe?" → Almost certainly not. Unsafe does not disable the borrow checker's rules — it merely hides UB. Redesign ownership (see rust-ownership), use RefCell for interior mutability, or use Pin for self-referential types.

Reference Files

Cross-References