当前位置：首页 > news >正文

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

news 2026/6/8 19:51:02

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, }