Rust FFI与C互操作实战:在Rust中调用C库的踩坑记录

一、为什么需要FFI:Rust生态的空白地带
Rust的生态在快速增长,但很多领域仍然只有C库可用——系统调用封装、硬件驱动接口、遗留业务逻辑、高性能数学库(BLAS、FFTW)。我遇到的具体场景是:需要调用一个C写的日志解析库,这个库有20年的历史,几百万行代码,不可能用Rust重写。
FFI(Foreign Function Interface)让Rust可以调用C函数,但"能调"和"用好"之间隔着很多坑——内存管理、类型映射、错误处理、线程安全、构建系统集成。本文记录我在Rust中调用C库的踩坑过程。
二、FFI基础:类型映射与函数调用
2.1 类型映射关系
graph LR
subgraph Rust类型
A[i32]
B[u64]
C[f64]
D[*const T]
E[*mut T]
F[CStr]
G[CString]
end
subgraph C类型
A1[int32_t]
B1[uint64_t]
C1[double]
D1[const T*]
E1[T*]
F1[const char*]
G1[char*]
end
A --- A1
B --- B1
C --- C1
D --- D1
E --- E1
F --- F1
G --- G1
2.2 基本FFI声明
use std::os::raw::{c_int, c_char, c_double};
// 声明外部C函数
extern "C" {
// int parse_log(const char* path, LogEntry* entries, int max_entries);
fn parse_log(
path: *const c_char,
entries: *mut LogEntry,
max_entries: c_int,
) -> c_int;
// void free_entries(LogEntry* entries, int count);
fn free_entries(entries: *mut LogEntry, count: c_int);
}
// C结构体对应的Rust表示
#[repr(C)]
#[derive(Debug)]
pub struct LogEntry {
pub timestamp: c_double, // double timestamp
pub level: c_int, // int level
pub message: *mut c_char, // char* message (C分配的内存)
}
2.3 安全封装
use std::ffi::CString;
use std::slice;
pub struct LogParser;
impl LogParser {
/// 安全封装:将C的FFI调用包装为Rust的安全API
pub fn parse(path: &str, max_entries: usize) -> Result<Vec<LogEntryOwned>> {
// Rust字符串 → C字符串
let c_path = CString::new(path)
.map_err(|_| anyhow::anyhow!("Path contains null byte"))?;
// 分配输出缓冲区
let mut entries = Vec::with_capacity(max_entries);
let entries_ptr = entries.as_mut_ptr();
let count = unsafe {
parse_log(c_path.as_ptr(), entries_ptr, max_entries as c_int)
};
if count < 0 {
return Err(anyhow::anyhow!("Parse failed with code: {}", count));
}
let count = count as usize;
// 将C的内存所有权转换为Rust管理
let mut result = Vec::with_capacity(count);
for i in 0..count {
let entry = unsafe { &*entries_ptr.add(i) };
let message = unsafe {
CStr::from_ptr(entry.message)
.to_string_lossy()
.into_owned()
};
result.push(LogEntryOwned {
timestamp: entry.timestamp,
level: entry.level,
message,
});
}
// 释放C分配的内存
unsafe {
free_entries(entries_ptr, count as c_int);
}
// 防止Vec的drop释放C的内存
std::mem::forget(entries);
Ok(result)
}
}
/// 拥有所有权的Rust版本
#[derive(Debug)]
pub struct LogEntryOwned {
pub timestamp: f64,
pub level: i32,
pub message: String,
}
三、构建系统集成:build.rs
3.1 链接已有的C库
// build.rs
fn main() {
// 方式1:链接系统安装的库
println!("cargo:rustc-link-lib=logparser");
// 方式2:指定库搜索路径
println!("cargo:rustc-link-search=/usr/local/lib");
// 告诉cargo在库变化时重新构建
println!("cargo:rerun-if-changed=/usr/local/lib/liblogparser.so");
}
3.2 从源码编译C库
// build.rs
use std::env;
use std::path::PathBuf;
fn main() {
let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
// 编译C源文件
cc::Build::new()
.file("c_src/logparser.c")
.file("c_src/entry.c")
.include("c_src/include")
.opt_level(2)
.compile("logparser");
// 生成Rust绑定(可选,也可以手写)
let bindings = bindgen::Builder::default()
.header("c_src/include/logparser.h")
.parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
.generate()
.expect("Unable to generate bindings");
bindings
.write_to_file(out_dir.join("bindings.rs"))
.expect("Couldn't write bindings");
println!("cargo:rerun-if-changed=c_src/");
}
// src/ffi.rs - 使用生成的绑定
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
3.3 Cargo.toml配置
[build-dependencies]
cc = "1.0"
bindgen = "0.69"
四、高级场景与陷阱
4.1 回调函数
use std::os::raw::c_void;
// C库的回调类型:typedef void (*ProgressCallback)(int percent, void* user_data);
type ProgressCallback = extern "C" fn(c_int, *mut c_void);
extern "C" {
fn parse_log_with_callback(
path: *const c_char,
callback: ProgressCallback,
user_data: *mut c_void,
) -> c_int;
}
// Rust回调函数
extern "C" fn progress_callback(percent: c_int, user_data: *mut c_void) {
let sender = unsafe {
&*(user_data as *const std::sync::mpsc::Sender<i32>)
};
let _ = sender.send(percent);
}
// 使用回调
pub fn parse_with_progress(path: &str) -> Result<Vec<LogEntryOwned>> {
let (tx, rx) = std::sync::mpsc::channel();
let c_path = CString::new(path)?;
let result = unsafe {
parse_log_with_callback(
c_path.as_ptr(),
progress_callback,
&tx as *const _ as *mut c_void,
)
};
// 在另一个线程显示进度
std::thread::spawn(move || {
while let Ok(percent) = rx.recv() {
print!("\rProgress: {}%", percent);
}
println!();
});
if result < 0 {
return Err(anyhow::anyhow!("Parse failed"));
}
// ...
Ok(vec![])
}
4.2 常见陷阱
陷阱1:忘记释放C分配的内存
// 错误:C分配的内存不会被Rust的drop释放
let entry: LogEntry = unsafe { *entries_ptr };
// entry.message是C分配的char*,Rust不会释放它 → 内存泄漏
// 正确:显式调用C的释放函数
unsafe { free_entries(entries_ptr, count); }
std::mem::forget(entries); // 防止Vec的drop重复释放
陷阱2:C字符串的null终止
// CString::new会在末尾添加null字节
// 如果字符串本身包含null字节,会panic
let c_str = CString::new("hello\0world")?; // Error!
// 检查输入
let input = "hello world";
if input.contains('\0') {
return Err(anyhow::anyhow!("String contains null byte"));
}
let c_str = CString::new(input)?;
陷阱3:repr(C)的布局
// 没有repr(C),Rust可能重新排列字段
#[repr(C)] // 必须加!保证与C的内存布局一致
struct LogEntry {
timestamp: f64,
level: i32,
// C可能有padding,Rust也会自动添加
message: *mut c_char,
}
五、架构权衡与边界分析
5.1 手写绑定 vs bindgen
手写绑定灵活可控,但容易出错(类型映射、字段对齐)。bindgen自动生成,减少人为错误,但生成的代码可读性差。建议:简单接口手写,复杂接口用bindgen。
5.2 安全封装的粒度
每个C函数都封装成安全API是理想状态,但工作量大。建议:先封装核心调用路径,边缘功能按需封装。unsafe块越小越好,安全封装层越薄越好。
5.3 跨平台兼容性
C库在不同平台的ABI可能不同(结构体对齐、调用约定)。建议:用CI在多平台测试,用cfg(target_os)处理平台差异。
六、总结
Rust FFI的核心是"最小化unsafe,最大化安全封装"。类型映射用repr(C)保证布局一致,字符串用CString/CStr转换,内存管理遵循"谁分配谁释放"原则,回调函数用extern "C"声明。
build.rs负责构建集成:链接已有库用rustc-link-lib,编译源码用cc crate,生成绑定用bindgen。常见陷阱包括忘记释放C内存、null终止字符串、缺少repr(C)。
落地建议:先用bindgen生成绑定验证可行性,再手写安全封装层;unsafe块尽量小,每个unsafe都有安全注释;回调函数注意线程安全;CI覆盖多平台测试。
413



被折叠的 条评论
为什么被折叠?



