25.2 Unsafe Blocks and Unsafe Functions

Rust permits unsafe operations only within blocks or functions explicitly marked with the unsafe keyword.

25.2.1 Declaring an Unsafe Block

An unsafe block is a code block prefixed with unsafe, intended for operations that the compiler cannot verify as safe.

A primary use of an unsafe block is dereferencing raw pointers.
Raw pointers in Rust are similar to C pointers and are discussed in the next section. Creating a raw pointer is safe, but dereferencing it is unsafe because the compiler cannot ensure the pointer is valid. The unsafe { ... } block explicitly indicates that you, the programmer, are taking responsibility for upholding memory safety.

In the example below, we define a mutable raw pointer using *mut. Dereferencing it is permitted only inside an unsafe block:

fn main() {
    let mut num: i32 = 42;
    let r: *mut i32 = &mut num; // Create a raw mutable pointer to num

    unsafe {
        *r = 99; // Dereference and modify the value through the raw pointer
        println!("The value of num is: {}", *r);
    }
}

Explanation:

  • We create a raw mutable pointer r that points to num.
  • Inside an unsafe block, we dereference r and modify the value.

Though this example is safe in practice, that is only because r originates from a valid reference that remains in scope.

25.2.2 Declaring an Unsafe Function

You can mark a function with unsafe if its correct usage depends on the caller upholding certain invariants that Rust cannot verify. Within an unsafe function, both safe and unsafe code can be used freely, but any call to such a function must occur in an unsafe block:

unsafe fn dangerous_function(ptr: *const i32) -> i32 {
    // Dereferencing a raw pointer is allowed here.
    *ptr
}

fn main() {
    let x = 42;
    let ptr = &x as *const i32;

    // Any call to an unsafe function must be wrapped in an unsafe block.
    unsafe {
        println!("Value: {}", dangerous_function(ptr));
    }
}

Here, unsafe indicates that this function has requirements the caller must satisfy (for example, only passing valid pointers to i32). Calling it inside an unsafe block implies you’ve read the function’s documentation and will ensure its invariants are upheld.

25.2.3 Unsafe Block or Unsafe Function?

When deciding whether to use an unsafe block or mark a function as unsafe, focus on the function’s contract rather than on whether it contains unsafe code:

  • Use unsafe fn if misuse (yet still compiling) could cause undefined behavior. In other words, the function itself requires the caller to meet certain safety guarantees.
  • Keep the function safe if no well-typed call could lead to undefined behavior. Even if the function body includes an unsafe block, that block may internally fulfill all necessary guarantees.

Avoid marking a function as unsafe just because it contains unsafe code—doing so might mislead callers into assuming extra safety hazards. In general, use an unsafe block unless you truly need an unsafe function contract.

A common approach is to encapsulate unsafe code inside a safe function that offers a straightforward interface, confining any dangerous operations to a small, well-audited section of your code.