Rust for C-Programmers

25.6 Calling C Functions (FFI)

One of the most common uses of unsafe Rust is calling C libraries via the Foreign Function Interface (FFI). In an extern "C" block, you declare the external functions you wish to call. The "C" indicates the application binary interface (ABI), telling Rust how to invoke these functions at the assembly level. You also use the #[link(...)] attribute to specify the libraries to link against.

#[link(name = "c")]
extern "C" {
    fn abs(input: i32) -> i32;
}

fn main() {
    let value = -42;
    // Calling an external fn is unsafe because Rust cannot verify its implementation.
    unsafe {
        let result = abs(value);
        println!("abs({}) = {}", value, result);
    }
}

When you declare the argument types for a foreign function, Rust cannot verify that your declarations match the function’s actual signature. A mismatch can cause undefined behavior.

25.6.1 Providing Safe Wrappers

A common pattern is to wrap an unsafe call in a safe function:

#[link(name = "c")]
extern "C" {
    fn abs(input: i32) -> i32;
}

fn safe_abs(value: i32) -> i32 {
    unsafe { abs(value) }
}

fn main() {
    println!("abs(-5) = {}", safe_abs(-5));
}

This confines the unsafe portion of your code to a small, isolated area, providing a safer API.