Unsafe Function

An unsafe function in Rust is a function prefixed with the unsafe keyword, indicating that it possesses preconditions that the Rust compiler cannot statically verify. By marking a function as unsafe, the author establishes an API-level contract signaling that invoking the function requires the caller to manually uphold specific memory safety and soundness guarantees to prevent Undefined Behavior (UB).

Syntax and Declaration

To declare an unsafe function, the unsafe keyword is placed immediately before the fn keyword.

unsafe fn perform_unchecked_operation(ptr: *const u8) -> u8 {
    // The body of an unsafe function implicitly acts as an `unsafe` block
    *ptr 
}

Invocation Rules

The Rust compiler enforces strict isolation for unsafe functions. You cannot call an unsafe function from normal, safe Rust code. It must be invoked within an explicit unsafe block or from within the body of another unsafe function. This forces the caller to explicitly acknowledge and accept the responsibility of the safety contract.

unsafe fn dangerous_call() {}

fn safe_context() {
    // Compilation error: call to unsafe function requires unsafe function or block
    // dangerous_call(); 

    // Correct: The programmer asserts that preconditions are met
    unsafe {
        dangerous_call();
    }
}

unsafe fn another_unsafe_context() {
    // Valid: implicitly inside an unsafe scope
    dangerous_call(); 
}

The Unsafe Contract and Compiler Behavior

Marking a function as unsafe alters compiler behavior and developer responsibility in specific ways:

1. Contract Definition, Not Suspension of Rules: The unsafe keyword does not disable the borrow checker or Rust’s standard type checking within the function body. Variables are still subject to ownership and lifetime rules.
2. Implicit Unsafe Scope: Historically, the entire body of an unsafe fn is treated as an unsafe block, allowing the use of unsafe operations (e.g., dereferencing raw pointers, accessing mutable statics, or calling other unsafe functions) without additional unsafe blocks. (Note: The unsafe_op_in_unsafe_fn lint, standard in newer editions, requires explicit unsafe blocks even inside unsafe functions to narrow the scope of unsafe operations).
3. Foreign Function Interface (FFI): Functions declared inside an extern block are implicitly unsafe to call. Because the Rust compiler cannot analyze the implementation of functions written in C, C++, or assembly, it assumes all FFI calls carry the risk of UB.

extern "C" {
    // Implicitly unsafe to invoke
    fn c_library_function(input: i32) -> i32; 
}

fn call_ffi() {
    unsafe {
        c_library_function(42);
    }
}

Safety Documentation Convention

Because the compiler cannot enforce the preconditions of an unsafe function, standard Rust tooling (like rustdoc) and community conventions dictate that every unsafe fn must include a # Safety section in its documentation. This section explicitly details the invariants the caller must uphold to avoid UB.

/// Reads an integer from a raw pointer.
///
/// # Safety
///
/// The caller must guarantee that:
/// - `ptr` is not null.
/// - `ptr` is properly aligned for an `i32`.
/// - `ptr` points to initialized memory valid for reads.
pub unsafe fn read_int(ptr: *const i32) -> i32 {
    *ptr
}

Master Rust with Deep Grasping Methodology!

Learn More