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_rawpara entregar,Box::from_rawpara 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
Resultni pánicos. catch_unwinden la frontera. Un pánico que escapa de una funciónextern "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 vezunsafeen 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
- Envuelve
qsortde libc en una función segurafn sort_i32(xs: &mut [i32])pasando un comparadorextern "C" fn. - Escribe a mano una cabecera de C para la API de
Counterde arriba y compárala con la salida decbindgen. - Compila el contador como
cdyliby llámalo desde Python conctypes. - ¿Por qué llamar dos veces a
counter_freees 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.¿Por qué un struct compartido con C debe marcarse con
#[repr(C)]?2.Rust reserva una cadena y le pasa el puntero a C. ¿Quién debe liberarla?
3.¿Qué ocurre si un pánico de Rust deshace la pila saliendo de una función
extern "C"hacia código C?