FFI with C Libraries

An extern block is a set of promises about other people's code: these symbols exist, they follow the C calling convention, and their signatures are exactly as written. Nothing is type-checked against the real library — the compiler trusts your declaration, and the linker is the first component that can tell you that you lied, usually with undefined reference to 'deflateInit_' at the end of a build that otherwise succeeded.

use std::ffi::{c_char, CStr, CString};

unsafe extern "C" {
    fn strlen(s: *const c_char) -> usize;
    fn getenv(name: *const c_char) -> *const c_char;   // returns memory C owns
}

fn main() {
    let key = CString::new("PATH").unwrap();          // Rust bytes -> NUL-terminated
    unsafe {
        let raw = getenv(key.as_ptr());               // null on a miss — check before use
        if !raw.is_null() {
            let value = CStr::from_ptr(raw);          // borrow C's memory, do not free it
            println!("{}", value.to_string_lossy());
            let _len = strlen(raw);
        }
    }
}

Four details in that snippet are the whole discipline. The unsafe on the block (mandatory in edition 2024, accepted everywhere since 1.82) means the caller upholds the C contract: pointer arguments really point at NUL-terminated data, return values may be null, and C functions that set errno or return error codes are your problem to interpret. Each call is wrapped in its own unsafe { } rather than the whole function. Strings cross the boundary as CString on the way out and CStr on the way back, because C has no idea what a Rust String is — its bytes may lack the trailing NUL, and its memory must not be freed by the wrong allocator. And getenv returns a pointer C owns, so you read it and leave it alone.

The classic self-inflicted wound looks like this:

let p = CString::new("hello").unwrap().as_ptr();   // dangles at the semicolon
unsafe { register(p); }                            // use-after-free, no warning

CString::new(...) produces a temporary; .as_ptr() borrows it; the temporary drops at the end of the statement, so register receives a freed pointer. The fix is to bind the CString to a variable that lives across the call — let c = CString::new("hello")?; unsafe { register(c.as_ptr()) }.

Wiring the symbols up is a build concern, not a source concern. For a system library you either declare it:

#[link(name = "z")]
unsafe extern "C" {
    fn zlibVersion() -> *const c_char;
}

or instruct Cargo from build.rs, which is what generated bindings prefer:

// build.rs
fn main() {
    println!("cargo:rustc-link-lib=static=z");
    println!("cargo:rustc-link-search=native=/opt/zlib/lib");
    println!("cargo:rerun-if-changed=vendor/zlib.h");
}

Direction matters when you export instead of import. A Rust function callable from C needs the C ABI and a stable symbol name — #[unsafe(no_mangle)] extern "C" fn free_buffer(p: *mut u8, len: usize) (in editions ≤2021, plain #[no_mangle]). extern "C" here also controls unwinding: a panic reaching that boundary would run C code with Rust unwinding through it, which is undefined behavior, so Rust aborts the process instead. extern "C-unwind" is the deliberate opt-in for callbacks C is allowed to call back into.

One asymmetry to hold onto: the linker validates names, never signatures. Declaring fn strlen(s: *const u8) -> usize, or transposing two i32 parameters, links perfectly and then reads or writes the wrong bytes. Nothing on the Rust side can catch that, which is why declarations should come from the header itself or be pinned by a C-side compile-time assertion. Returning borrowed data through this boundary — a &str handed to C — is precisely the pointer-lifetime contract from Raw Pointers, now enforced by a party who cannot read Rust. The signature you declare is half the contract; the memory layout is the other half, and that is where the default Rust representation silently disqualifies you.

You can declare a function correctly and still corrupt memory, because an extern "C" signature says nothing about struct layout. Rust's default representation is deliberately unspecified: the compiler may reorder fields, insert padding, or skip trailing padding entirely, and it may change that decision between releases. C's representation is fixed by the platform ABI: fields in declaration order, padding inserted to satisfy alignment, a stable size. Only #[repr(C)] opts you into the second one.

#[repr(C)]
struct Rect { w: u8, h: u32 }     // C layout: w at 0, 3 pad bytes, h at 4, size 8

struct Snek { w: u8, h: u32 }     // repr(Rust): may reorder h before w — size and
                                  // offsets are NOT what a C compiler will assume

A C function taking Rect by value reads bytes 4..8 as the height. If you pass Snek and the compiler chose to place h first, C reads your padding as data. The same rule covers every shape that crosses the boundary:

Two entries deserve emphasis because they are interview favorites. First, Option<extern "C" fn()> is the niche optimization the language guarantees — None is represented as a null function pointer — so C callbacks can be optional with no wrapper. Do not assume the same for your own Option<YourStruct>: niche elision for user types is an implementation detail, and #[repr(C)] can even remove the freedom that made it possible. Second, never write i64 for a C long: Windows uses the LLP64 model where long is 32 bits, and your i64 argument will be silently misread. c_int, c_long, c_char, c_void from std::ffi exist precisely so the declaration compiles to the right width on every target.

Also check whether a C char is signed on your target — it is signed on x86 Linux and macOS, unsigned on ARM — which is why c_char is its own type rather than a rebranded i8. Packed structs, bitfields, and unions are handled with #[repr(C, packed(n))], #[repr(align(n))], and explicit union declarations; when the C header does something exotic, this is exactly the code you should stop writing by hand.

Layout claims deserve a check that runs without invoking C at all: put the assertion next to the type so a refactor that moves a field fails the build instead of a production request.

#[repr(C)]
struct Rect { w: u8, h: u32 }

const _: () = assert!(std::mem::size_of::<Rect>() == 8);
const _: () = assert!(std::mem::offset_of!(Rect, h) == 4);

Because hand-written layouts are a maintenance trap, the working setup generates them from the header. That is the next chapter — and once the declarations exist, the invariants you must document live in Encapsulating Unsafe with Invariants.

A real C header carries hundreds of typedefs, macros, and calling conventions. Hand-transcribing them is how you end up with i32 where the header said long, and a wrong signature across FFI is undefined behavior that compiles happily. bindgen reads the header with the same parser family Clang uses and emits Rust declarations, so the mechanical half of the job is generated:

// build.rs — bindgen as a build-dependency
fn main() {
    let bindings = bindgen::Builder::default()
        .header("vendor/zlib.h")
        .allowlist_function("inflate.*|deflate.*")
        .allowlist_type("z_stream|gz_header")
        .allowlist_var("ZLIB_VERSION|Z_.*")
        .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
        .generate()
        .expect("bindgen failed to parse vendor/zlib.h");

    let out = std::path::PathBuf::from(std::env::var("OUT_DIR").unwrap());
    bindings
        .write_to_file(out.join("bindings.rs"))
        .expect("couldn't write bindings");
}

// src/ffi.rs
#![allow(dead_code, non_upper_case_globals, non_camel_case_types)]
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

The allowlist is not a nicety: without it bindgen will happily emit every type reachable from the header — platform-specific unions, variadic functions it cannot represent, va_list — and your build breaks on constructs Rust has no equivalent for. Generation also tracks header edits via cargo:rerun-if-changed, so a signature change in C fails your build instead of surviving as a stale declaration.

What bindgen generates is shape, never contract. It will faithfully emit pub fn inflate(strm: z_streamp, flush: c_int) -> c_int; and tell you nothing about who frees strm->next_out, whether the function may return Z_STREAM_END twice, or that the return code must be checked before you touch the output buffer. Three categories of obligation always remain human:

• Ownership and lifetime. Does the callee allocate? Does it retain the pointer after returning? Every retained pointer is a promise that the Rust buffer will not move, reallocate, or drop — the reallocation trap from Raw Pointers applies verbatim.
• Callbacks. A function pointer you hand to C must be extern "C", cannot capture state, and must not unwind. The standard shape is a trampoline: pass extern "C" fn(*mut c_void, u32) plus a user_data pointer back into Rust, then cast user_data to &mut Context inside — with the aliasing obligation, once again, on you.
• Error paths. C signals failure with NULL, negative codes, or errno. A wrapper that unwraps a NULL converts a recoverable error into UB-adjacent panic; a wrapper that ignores a return code converts it into silent corruption.

Two practical notes before you rely on it in CI. bindgen parses with libclang, not with Rust, so the build machine needs Clang installed: without it build.rs dies with Unable to find libclang, and a pinned Docker image must install libclang-dev (or set LIBCLANG_PATH) or the first clean build fails. Second, generated code is not automatically correct code — pin the bindgen version in build-dependencies, review its diff when the header changes, and keep the output in one module so cargo expand or a reviewer can see exactly what was emitted.

The strongest check is the one that lets C contradict you. Compile a tiny assertion file against the same header and run it from the build script:

/* build/layout_check.c — compiled by build.rs via the cc crate */
#include <stddef.h>
_Static_assert(sizeof(struct Rect) == 8, "Rect size drifted from Rust's #[repr(C)]");
_Static_assert(offsetof(struct Rect, h) == 4, "Rect.h moved");

If a C refactor reorders a field, the build fails at the source of truth rather than at runtime. Layout is now pinned on both sides; ownership, lifetimes, and error paths are not — they stay human.

The wrap-up pattern: bindgen declares inside one private module, and you hand the crate a safe, idiomatic API whose methods do the null checks, own the CStrings, and return Result. At that point the unsafe surface is small enough for a reviewer to certify — which is the subject of Encapsulating Unsafe with Invariants.