Rust 2026 经验谈 - FFI 实战：Rust 调用 C

1
let bindings = bindgen::Builder::default()
2
    .header("wrapper.h")
3
    // 只生成指定符号的绑定
4
    .allowlist_function("sqlite3_.*")
5
    .allowlist_type("sqlite3.*")
6
    .allowlist_var("SQLITE_.*")
7

8
    // 屏蔽不需要的符号
9
    .blocklist_type("__.*")           // 内部类型
10
    .blocklist_function(".*_internal") // 内部函数
11

12
    // 生成 Rust 文档注释
13
    .generate_comments(true)
14

15
    // 处理不透明类型
16
    .opaque_type("sqlite3")           // sqlite3 是不透明指针
17

18
    // 设置默认枚举大小
19
    .default_enum_style(bindgen::EnumVariation::Rust {
20
        non_exhaustive: true,
21
    })
22

23
    // 添加自定义属性
24
    .must_use_type("sqlite3.*")
25

26
    .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
27
    .generate()
28
    .expect("Unable to generate bindings");

1
// bindgen 生成：
2
pub type my_lib_error_code_t = u32;
3
pub const MY_LIB_OK: my_lib_error_code_t = 0;
4
pub const MY_LIB_ERR: my_lib_error_code_t = 1;
5

6
// 可能的问题：
7
// 1. 命名不符合 Rust 惯例（snake_case）
8
// 2. 枚举生成为常量而非 enum
9
// 3. 某些 C 特性（bitfields、flexible array member）不支持
10

11
// 变通：在 build.rs 中手动替换
12
let bindings = bindgen::Builder::default()
13
    .header("wrapper.h")
14
    .raw_line("use std::os::raw::c_int;")  // 手动添加行
15
    .generate()
16
    .unwrap();

1
// C 结构体
2
// struct Point {
3
//     int32_t x;
4
//     int32_t y;
5
//     int32_t z;
6
// };
7

8
// Rust 对应
9
#[repr(C)]
10
struct Point {
11
    x: i32,
12
    y: i32,
13
    z: i32,
14
}
15

16
// 不加 repr(C)，Rust 可能重排字段（虽然 i32 不会）
17
// 但对于不同类型字段，重排可能发生

1
// C: __attribute__((aligned(16)))
2
#[repr(C, align(16))]
3
struct AlignedBuffer {
4
    data: [u8; 64],
5
}
6
assert_eq!(std::mem::align_of::<AlignedBuffer>(), 16);
7

8
// C: #pragma pack(1)
9
#[repr(C, packed)]
10
struct PackedHeader {
11
    magic: u16,
12
    version: u8,
13
    size: u32,  // 未对齐！访问可能 UB
14
}
15
// 注意：packed 结构体中未对齐字段的引用是 UB
16
// 必须通过 copy 访问：
17
let header: PackedHeader = /* ... */;
18
// let size: &u32 = &header.size;  // UB！未对齐引用
19
let size: u32 = header.size;        // OK：copy 出来

1
// C union
2
// union Data {
3
//     int32_t as_int;
4
//     float as_float;
5
//     void* as_ptr;
6
// };
7

8
#[repr(C)]
9
union Data {
10
    as_int: i32,
11
    as_float: f32,
12
    as_ptr: *mut std::ffi::c_void,
13
}
14

15
// 访问联合体字段需要 unsafe
16
let mut d = Data { as_int: 42 };
17
unsafe {
18
    println!("as_int: {}", d.as_int);     // OK：最近写入的是 as_int
19
    // println!("as_float: {}", d.as_float);  // UB：未激活字段
20
}

1
#[repr(C)]
2
struct Header {
3
    version: u8,   // 1 字节
4
    // 3 字节 padding
5
    length: u32,   // 4 字节
6
}
7

8
// 如果用 memcmp 比较两个 Header：
9
// padding 中的值未定义，memcmp 可能返回"不等"即使字段相同
10
// 变通：确保 padding 为零
11
let h1 = Header { version: 1, length: 100 };
12
let h2 = Header { version: 1, length: 100 };
13

14
unsafe {
15
    // 不能保证 ptr::eq 或 memcmp 正确
16
    // 用字段比较
17
    assert_eq!(h1.version, h2.version);
18
    assert_eq!(h1.length, h2.length);
19
}

1
type Callback = extern "C" fn(event: i32, user_data: *mut std::ffi::c_void);
2

3
unsafe extern "C" {
4
    fn register_callback(cb: Callback, user_data: *mut std::ffi::c_void);
5
}
6

7
extern "C" fn my_callback(event: i32, user_data: *mut std::ffi::c_void) {
8
    // 注意：这个函数不能捕获环境！
9
    let ctx = unsafe { &mut *(user_data as *mut Context) };
10
    match event {
11
        1 => ctx.on_connect(),
12
        2 => ctx.on_disconnect(),
13
        _ => {}
14
    }
15
}
16

17
struct Context {
18
    connected: bool,
19
}
20

21
impl Context {
22
    fn on_connect(&mut self) { self.connected = true; }
23
    fn on_disconnect(&mut self) { self.connected = false; }
24
}
25

26
let mut ctx = Box::new(Context { connected: false });
27
unsafe {
28
    register_callback(my_callback, &mut *ctx as *mut Context as *mut std::ffi::c_void);
29
}

1
use std::ffi::c_void;
2

3
type CCallback = extern "C" fn(i32, *mut c_void);
4

5
unsafe extern "C" {
6
    fn register_callback(cb: CCallback, user_data: *mut c_void);
7
}
8

9
// 桥接函数
10
extern "C" fn trampoline<F: FnMut(i32)>(event: i32, user_data: *mut c_void) {
11
    let closure = unsafe { &mut *(user_data as *mut F) };
12
    closure(event);
13
}
14

15
fn register_rust_callback<F: FnMut(i32) + 'static>(mut closure: F) {
16
    let boxed = Box::new(closure);
17
    let user_data = Box::into_raw(boxed) as *mut c_void;
18

19
    unsafe {
20
        // SAFETY: trampoline 与 CCallback 签名匹配
21
        // user_data 指向堆上的 F
22
        register_callback(trampoline::<F>, user_data);
23
    }
24

25
    // 注意：user_data 的内存何时释放？
26
    // 需要.unregister_callback() 或在库销毁时释放
27
}

1
// 错误！闭包引用了栈上的变量
2
fn bad_callback() {
3
    let local = 42;
4
    register_rust_callback(move |_| {
5
        // local 被移动到闭包中——OK
6
        println!("{}", local);
7
    });
8
}
9

10
// 更危险的情况：
11
fn worse_callback() {
12
    let local = vec![1, 2, 3];
13
    let ptr = &local as *const Vec<i32>;
14
    register_rust_callback(move |_| {
15
        // 如果 local 没有被 move 到闭包中，ptr 可能悬垂
16
        // 用 move 捕获是安全的
17
    });
18
}

1
use std::panic::catch_unwind;
2

3
// catch_unwind 不能捕获：
4
// 1. panic = abort 时（直接终止）
5
// 2. std::process::exit()（不是 panic）
6
// 3. 某些 UB 触发前的 panic
7

8
let result = catch_unwind(|| {
9
    // 这会被捕获
10
    panic!("normal panic");
11
});
12
assert!(result.is_err());
13

14
let result2 = catch_unwind(|| {
15
    // 这不会被捕获（如果设了 panic=abort）
16
    // std::process::exit(1);
17
    todo!()
18
});

1
use std::ffi::CStr;
2

3
unsafe extern "C" {
4
    fn get_string() -> *const i8;
5
}
6

7
let ptr = unsafe { get_string() };
8
if !ptr.is_null() {
9
    let c_str = unsafe { CStr::from_ptr(ptr) };
10
    // c_str 是 &CStr，借用 C 的字符串
11

12
    // 转为 Rust &str（可能失败——不是 UTF-8）
13
    let rust_str: Result<&str, _> = c_str.to_str();
14
    if let Ok(s) = rust_str {
15
        println!("Got: {}", s);
16
    }
17

18
    // 转为 String（总是成功，但会替换非 UTF-8 字节）
19
    let owned = c_str.to_string_lossy().into_owned();
20
}

1
use std::ffi::{CString, CStr};
2

3
// 模式一：Rust 分配，Rust 释放
4
fn pass_to_c(s: &str) -> i32 {
5
    let c_str = CString::new(s).unwrap();
6
    unsafe { c_count_chars(c_str.as_ptr()) }
7
}
8

9
// 模式二：C 分配，C 释放
10
fn get_from_c() -> String {
11
    let ptr = unsafe { c_get_string() };
12
    let c_str = unsafe { CStr::from_ptr(ptr) };
13
    let result = c_str.to_string_lossy().into_owned();
14
    unsafe { c_free_string(ptr as *mut i8); }
15
    result
16
}
17

18
// 模式三：C 分配，Rust 释放（需要 C 用 malloc，Rust 用 libc::free）
19
fn take_ownership_from_c() -> String {
20
    let ptr = unsafe { c_get_malloc_string() };
21
    let c_str = unsafe { CStr::from_ptr(ptr) };
22
    let result = c_str.to_string_lossy().into_owned();
23
    unsafe { libc::free(ptr as *mut libc::c_void); }
24
    result
25
}
26

27
// 注意：c_count_chars, c_get_string, c_free_string, c_get_malloc_string
28
// 需要在 unsafe extern "C" {} 中声明（Edition 2024）

1
// 错误！Rust enum 可能是 1 字节，C enum 可能是 4 字节
2
#[repr(C)]
3
enum Status {
4
    Ok = 0,
5
    Error = 1,
6
    Pending = 2,
7
}
8

9
// 正确：显式指定大小
10
#[repr(C, i32)]  // 保证是 i32（4 字节）
11
enum Status {
12
    Ok = 0,
13
    Error = 1,
14
    Pending = 2,
15
}
16

17
// 或更安全：用常量 + 类型别名
18
type Status = u32;
19
const STATUS_OK: Status = 0;
20
const STATUS_ERROR: Status = 1;
21
const STATUS_PENDING: Status = 2;

1
// bindgen 对 bitfield 的支持有限
2
// 生成的绑定可能无法正确访问 bitfield
3
// 变通：手动实现 getter/setter
4

5
#[repr(C)]
6
struct Flags {
7
    bits: u32,  // 整体存储
8
}
9

10
impl Flags {
11
    fn a(&self) -> u32 { self.bits & 0x1 }
12
    fn b(&self) -> u32 { (self.bits >> 1) & 0x7 }
13
    fn c(&self) -> u32 { (self.bits >> 4) & 0xF }
14

15
    fn set_a(&mut self, val: u32) { self.bits = (self.bits & !0x1) | (val & 0x1); }
16
    fn set_b(&mut self, val: u32) { self.bits = (self.bits & !(0x7 << 1)) | ((val & 0x7) << 1); }
17
    fn set_c(&mut self, val: u32) { self.bits = (self.bits & !(0xF << 4)) | ((val & 0xF) << 4); }
18
}

1
// Rust 不支持 flexible array member
2
// 变通：用原始指针 + 手动偏移
3

4
#[repr(C)]
5
struct MessageHeader {
6
    msg_type: i32,
7
    length: i32,
8
    // data 字段不直接表示
9
}
10

11
impl MessageHeader {
12
    fn data_ptr(&self) -> *const u8 {
13
        unsafe {
14
            (self as *const Self as *const u8).add(std::mem::size_of::<MessageHeader>())
15
        }
16
    }
17

18
    fn data_slice(&self) -> &[u8] {
19
        unsafe {
20
            std::slice::from_raw_parts(self.data_ptr(), self.length as usize)
21
        }
22
    }
23
}