FerrousPath

Nivel 3 · Sistemas· Lección 8 de 11 · 30 min

FFI — hablar con C

Llamar a C desde Rust y a Rust desde C, repr(C), cadenas y propiedad a través de la frontera, bindgen y cbindgen.

La ABI de C es la lengua franca

Casi todos los lenguajes pueden llamar a funciones de C, así que la convención de llamadas de C es la forma en que Rust interopera con todo: sistemas operativos, bibliotecas existentes, extensiones de Python, aplicaciones móviles. La frontera es unsafe por naturaleza —el compilador no puede ver el otro lado—, así que el oficio consiste en hacer pequeña la superficie insegura y envolverla en una API segura.

Llamar a C desde Rust

La biblioteca estándar de C ya está enlazada en todo programa de Rust, así que podemos llamarla directamente:

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

unsafe extern "C" {
    fn strlen(s: *const c_char) -> usize;
    fn abs(x: c_int) -> c_int;
    fn getenv(name: *const c_char) -> *const c_char;
}

/// Un envoltorio seguro: todo el manejo de punteros se queda aquí dentro.
fn env(name: &str) -> Option<String> {
    let name = CString::new(name).ok()?; // falla si `name` contiene un NUL interior
    // SAFETY: `name` es una cadena válida terminada en NUL que sobrevive a la llamada.
    let ptr = unsafe { getenv(name.as_ptr()) };
    if ptr.is_null() {
        return None;
    }
    // SAFETY: getenv devolvió un puntero no nulo a una cadena terminada en NUL.
    // La copiamos inmediatamente, antes de que nada pueda modificar el entorno.
    Some(unsafe { CStr::from_ptr(ptr) }.to_string_lossy().into_owned())
}

fn main() {
    let text = CString::new("hello from Rust").unwrap();
    // SAFETY: cadena válida terminada en NUL; abs no tiene más precondición que x != INT_MIN.
    let (len, a) = unsafe { (strlen(text.as_ptr()), abs(-42)) };
    println!("{len} {a}");
    println!("PATH is set: {}", env("PATH").is_some());
}

Desde la edición 2024 los bloques extern se escriben unsafe extern, lo que reconoce que las propias declaraciones son una promesa: si una firma es incorrecta, las llamadas son comportamiento indefinido. Los elementos individuales pueden marcarse como safe fn cuando de verdad no tienen precondiciones.

Cadenas

Rust C Notas
&str / String — UTF-8, con longitud explícita, sin NUL final, puede contener NUL
&CStr const char * (prestado) Terminada en NUL, bytes arbitrarios
CString char * (propiedad de Rust) Se construye con CString::new; se pasa con .as_ptr()
OsStr / OsString cadenas de la plataforma Rutas, entorno; no necesariamente UTF-8

Un bug clásico: CString::new("x").unwrap().as_ptr() — el CString temporal se libera al final de la sentencia y el puntero queda colgando. Enlaza el CString a una variable que sobreviva a la llamada.

Tipos

Usa los alias de std::ffi (c_int, c_long, c_char, c_void) en lugar de adivinar: long tiene 32 bits en Windows y 64 en Linux. Option<&T>, Option<Box<T>> y Option<extern "C" fn()> tienen garantizado el mismo layout que un puntero que puede ser nulo, lo que los hace cómodos en las firmas.

Layout: repr(C)

use std::mem::{align_of, size_of};

#[repr(C)]
struct CPoint {
    tag: u8,
    x: f64,
    flag: u8,
}

struct RustPoint {
    tag: u8,
    x: f64,
    flag: u8,
}

#[repr(C)]
#[derive(Debug, Clone, Copy)]
enum Status {
    Ok = 0,
    NotFound = 1,
    Denied = 2,
}

fn main() {
    println!("repr(C): size {} align {}", size_of::<CPoint>(), align_of::<CPoint>());
    println!("default: size {} align {}", size_of::<RustPoint>(), align_of::<RustPoint>());
    println!("{:?} = {}", Status::Denied, Status::Denied as i32);
}

repr(C) dispone los campos en el orden de declaración con el relleno de C (24 bytes aquí); la representación por defecto es libre de reordenarlos (16 bytes). Nunca pases por FFI un struct con el repr por defecto. En cuanto a los enums de C, recuerda que el código C puede entregarte cualquier entero; recibir un discriminante fuera de rango en un enum de Rust es UB instantáneo, así que acepta un entero y conviértelo con un TryFrom comprobado.

Llamar a Rust desde C

Compila el crate como una biblioteca de C (crate-type = ["cdylib"] o "staticlib") y exporta las funciones con un nombre sin decorar (unmangled) y la ABI de C:

use std::ffi::{c_char, CStr, CString};
use std::panic::catch_unwind;
use std::ptr;

/// Un manejador opaco: C solo ve un puntero.
pub struct Counter {
    words: usize,
}

#[unsafe(no_mangle)]
pub extern "C" fn counter_new() -> *mut Counter {
    Box::into_raw(Box::new(Counter { words: 0 })) // entrega la propiedad a C
}

/// # Safety
/// `c` debe venir de `counter_new` y no haber sido liberado; `text` debe terminar en NUL.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn counter_feed(c: *mut Counter, text: *const c_char) -> i32 {
    if c.is_null() || text.is_null() {
        return -1;
    }
    let result = catch_unwind(|| {
        // SAFETY: arriba se comprobó que no son nulos; la validez es el contrato de quien llama.
        let (c, text) = unsafe { (&mut *c, CStr::from_ptr(text)) };
        match text.to_str() {
            Ok(s) => { c.words += s.split_whitespace().count(); 0 }
            Err(_) => -2, // no es UTF-8
        }
    });
    result.unwrap_or(-3) // nunca dejes que un pánico cruce la frontera
}

/// # Safety
/// `c` debe venir de `counter_new` y no haber sido liberado.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn counter_report(c: *const Counter) -> *mut c_char {
    let Some(c) = (unsafe { c.as_ref() }) else { return ptr::null_mut() };
    CString::new(format!("{} words", c.words)).unwrap().into_raw()
}

/// # Safety
/// `s` debe venir de `counter_report` y no debe usarse después.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn counter_string_free(s: *mut c_char) {
    if !s.is_null() {
        drop(unsafe { CString::from_raw(s) }); // Rust la reservó, Rust la libera
    }
}

/// # Safety
/// `c` debe venir de `counter_new` y no debe usarse después.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn counter_free(c: *mut Counter) {
    if !c.is_null() {
        drop(unsafe { Box::from_raw(c) }); // recupera la propiedad y libera
    }
}

fn main() {
    // Ejercitamos la API de C desde Rust, exactamente como lo haría un programa en C.
    unsafe {
        let c = counter_new();
        let text = CString::new("the quick brown fox").unwrap();
        assert_eq!(counter_feed(c, text.as_ptr()), 0);
        let report = counter_report(c);
        println!("{}", CStr::from_ptr(report).to_str().unwrap());
        counter_string_free(report);
        counter_free(c);
    }
}

Los patrones que hay que recordar:

  • Manejadores opacos: Box::into_raw para entregar, Box::from_raw para recuperar. C nunca ve el layout.
  • Toda reserva tiene una función de liberación a juego, exportada por el lado que reservó.
  • Los errores son códigos de retorno, con parámetros de salida para los resultados. Ni Result ni pánicos.
  • catch_unwind en la frontera. Un pánico que escapa de una función extern "C" aborta el proceso.
  • Comprueba que ningún puntero es nulo, y documenta todas las demás precondiciones bajo # Safety.
  • #[unsafe(no_mangle)] es a su vez unsafe en la edición 2024: un nombre de símbolo que choca con otro es comportamiento indefinido en el enlazado.

Herramientas

Herramienta Dirección Qué hace
bindgen C → Rust Genera declaraciones extern y tipos repr(C) a partir de cabeceras de C
cc C → Rust Compila fuentes de C/C++ incluidas, desde build.rs
pkg-config, vcpkg C → Rust Localiza bibliotecas del sistema desde build.rs
cbindgen Rust → C Genera una cabecera de C a partir de tu API extern "C"
cxx C++ ↔ Rust Un puente seguro con tipos compartidos y firmas comprobadas
PyO3, napi-rs, uniffi Rust → Python / Node / Swift, Kotlin Bindings de alto nivel, sin capa de C escrita a mano

Convención: un crate foo-sys contiene los bindings crudos e inseguros y el script de compilación; un crate foo lo envuelve en una API segura e idiomática. Las retrollamadas (callbacks) hacia Rust se pasan como punteros extern "C" fn más un puntero de datos de usuario *mut c_void que lleva el estado de tu clausura.

Ejercicios

  1. Envuelve qsort de libc en una función segura fn sort_i32(xs: &mut [i32]) pasando un comparador extern "C" fn.
  2. Escribe a mano una cabecera de C para la API de Counter de arriba y compárala con la salida de cbindgen.
  3. Compila el contador como cdylib y llámalo desde Python con ctypes.
  4. ¿Por qué llamar dos veces a counter_free es comportamiento indefinido, y cómo podría detectarlo un diseño de manejadores más seguro (por ejemplo, manejadores enteros que indexan una tabla)?

Comprueba lo que has entendido

Elige una respuesta para ver la explicación.

  1. 1.¿Por qué un struct compartido con C debe marcarse con #[repr(C)]?

  2. 2.Rust reserva una cadena y le pasa el puntero a C. ¿Quién debe liberarla?

  3. 3.¿Qué ocurre si un pánico de Rust deshace la pila saliendo de una función extern "C" hacia código C?

Términos clave de esta lección

¿Has terminado la lección y los ejercicios?