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

1
// Rust 的 bool 是 1 字节，值为 0 或 1
2
// C99 没有 bool，C11 的 _Bool 也是 1 字节
3
// 但很多 C 代码用 int 表示布尔值——任何非零为 true
4

5
// 危险！C 传 int 2 作为 bool，Rust 视为 true 但可能 UB
6
#[unsafe(no_mangle)]
7
pub extern "C" fn my_lib_set_enabled(enabled: bool) {
8
    // 如果 C 侧传了 2 作为 bool：
9
    // Rust 保证 bool 必须是 0 或 1
10
    // 传其他值是 UB！
11
    if enabled {
12
        println!("enabled");
13
    }
14
}
15

16
// 安全做法：C 侧用 c_int，Rust 侧转换
17
#[unsafe(no_mangle)]
18
pub extern "C" fn my_lib_set_enabled_safe(enabled: std::os::raw::c_int) {
19
    let enabled = enabled != 0;
20
    if enabled {
21
        println!("enabled");
22
    }
23
}

1
pub struct MyContext {
2
    data: Vec<u8>,
3
    config: Config,
4
    connected: bool,
5
}
6

7
pub struct Config {
8
    max_size: usize,
9
    timeout_ms: u64,
10
}
11

12
#[unsafe(no_mangle)]
13
pub extern "C" fn my_lib_context_create(max_size: usize, timeout_ms: u64) -> *mut MyContext {
14
    let ctx = Box::new(MyContext {
15
        data: Vec::with_capacity(max_size),
16
        config: Config { max_size, timeout_ms },
17
        connected: false,
18
    });
19
    Box::into_raw(ctx)
20
}
21

22
#[unsafe(no_mangle)]
23
pub extern "C" fn my_lib_context_destroy(ctx: *mut MyContext) {
24
    if !ctx.is_null() {
25
        unsafe { drop(Box::from_raw(ctx)); }
26
    }
27
}
28

29
#[unsafe(no_mangle)]
30
pub extern "C" fn my_lib_context_connect(ctx: *mut MyContext) -> i32 {
31
    if ctx.is_null() {
32
        return -1;
33
    }
34
    let ctx = unsafe { &mut *ctx };
35
    ctx.connected = true;
36
    0
37
}
38

39
#[unsafe(no_mangle)]
40
pub extern "C" fn my_lib_context_write(ctx: *mut MyContext, data: *const u8, len: usize) -> i32 {
41
    if ctx.is_null() || data.is_null() {
42
        return -1;
43
    }
44
    let ctx = unsafe { &mut *ctx };
45
    let slice = unsafe { std::slice::from_raw_parts(data, len) };
46
    if slice.len() > ctx.config.max_size {
47
        return -2;
48
    }
49
    ctx.data.extend_from_slice(slice);
50
    0
51
}

1
struct Inner { x: i32 }
2
struct Wrapper { inner: Inner, extra: i32 }
3

4
#[unsafe(no_mangle)]
5
pub extern "C" fn create() -> *mut Wrapper {
6
    Box::into_raw(Box::new(Wrapper { inner: Inner { x: 0 }, extra: 0 }))
7
}
8

9
// 错误！用 Inner 释放 Wrapper
10
// #[unsafe(no_mangle)]
11
// pub extern "C" fn destroy_bad(ptr: *mut Inner) {
12
//     unsafe { drop(Box::from_raw(ptr)); }  // 类型不匹配——UB！
13
// }
14

15
// 正确：类型必须一致
16
#[unsafe(no_mangle)]
17
pub extern "C" fn destroy(ptr: *mut Wrapper) {
18
    if !ptr.is_null() {
19
        unsafe { drop(Box::from_raw(ptr)); }
20
    }
21
}

1
use std::sync::Mutex;
2

3
pub struct SharedContext {
4
    inner: Mutex<ContextInner>,
5
}
6

7
struct ContextInner {
8
    data: Vec<u8>,
9
    count: u64,
10
}
11

12
#[unsafe(no_mangle)]
13
pub extern "C" fn my_lib_shared_create() -> *mut SharedContext {
14
    let ctx = Box::new(SharedContext {
15
        inner: Mutex::new(ContextInner {
16
            data: Vec::new(),
17
            count: 0,
18
        }),
19
    });
20
    Box::into_raw(ctx)
21
}
22

23
#[unsafe(no_mangle)]
24
pub extern "C" fn my_lib_shared_increment(ctx: *mut SharedContext) -> u64 {
25
    if ctx.is_null() {
26
        return 0;
27
    }
28
    let ctx = unsafe { &*ctx };
29
    let mut inner = ctx.inner.lock().unwrap();
30
    inner.count += 1;
31
    inner.count
32
}

1
pub const MY_LIB_OK: i32 = 0;
2
pub const MY_LIB_ERR_NULL: i32 = -1;
3
pub const MY_LIB_ERR_OOM: i32 = -2;
4
pub const MY_LIB_ERR_INVALID: i32 = -3;
5
pub const MY_LIB_ERR_IO: i32 = -4;
6

7
#[unsafe(no_mangle)]
8
pub extern "C" fn my_lib_process(ctx: *mut MyContext, input: *const u8, input_len: usize) -> i32 {
9
    if ctx.is_null() {
10
        return MY_LIB_ERR_NULL;
11
    }
12
    if input.is_null() && input_len > 0 {
13
        return MY_LIB_ERR_INVALID;
14
    }
15

16
    let ctx = unsafe { &mut *ctx };
17
    let data = if input.is_null() || input_len == 0 {
18
        &[]
19
    } else {
20
        unsafe { std::slice::from_raw_parts(input, input_len) }
21
    };
22

23
    match ctx.process(data) {
24
        Ok(()) => MY_LIB_OK,
25
        Err(e) => match e {
26
            MyError::OutOfMemory => MY_LIB_ERR_OOM,
27
            MyError::InvalidInput => MY_LIB_ERR_INVALID,
28
            MyError::Io(_) => MY_LIB_ERR_IO,
29
        },
30
    }
31
}

1
use std::ffi::CString;
2
use std::sync::atomic::{AtomicPtr, Ordering};
3

4
static LAST_ERROR: AtomicPtr<i8> = AtomicPtr::new(std::ptr::null_mut());
5

6
fn set_last_error(msg: &str) {
7
    let c_string = CString::new(msg).unwrap_or_else(|_| CString::new("error contains null byte").unwrap());
8
    let ptr = c_string.into_raw();
9
    let old = LAST_ERROR.swap(ptr, Ordering::SeqCst);
10
    if !old.is_null() {
11
        unsafe { drop(CString::from_raw(old)); }
12
    }
13
}
14

15
#[unsafe(no_mangle)]
16
pub extern "C" fn my_lib_get_last_error() -> *const i8 {
17
    LAST_ERROR.load(Ordering::SeqCst)
18
}
19

20
#[unsafe(no_mangle)]
21
pub extern "C" fn my_lib_clear_error() {
22
    let old = LAST_ERROR.swap(std::ptr::null_mut(), Ordering::SeqCst);
23
    if !old.is_null() {
24
        unsafe { drop(CString::from_raw(old)); }
25
    }
26
}

1
pub struct MyLib {
2
    contexts: Vec<*mut MyContext>,
3
}
4

5
static mut GLOBAL_INSTANCE: *mut MyLib = std::ptr::null_mut();
6

7
#[unsafe(no_mangle)]
8
pub extern "C" fn my_lib_init() -> i32 {
9
    let lib = Box::new(MyLib {
10
        contexts: Vec::new(),
11
    });
12
    unsafe {
13
        if !GLOBAL_INSTANCE.is_null() {
14
            return -1;  // already initialized
15
        }
16
        GLOBAL_INSTANCE = Box::into_raw(lib);
17
    }
18
    0
19
}
20

21
#[unsafe(no_mangle)]
22
pub extern "C" fn my_lib_destroy() {
23
    unsafe {
24
        if GLOBAL_INSTANCE.is_null() {
25
            return;
26
        }
27
        let lib = Box::from_raw(GLOBAL_INSTANCE);
28
        for &ctx in &lib.contexts {
29
            if !ctx.is_null() {
30
                drop(Box::from_raw(ctx));
31
            }
32
        }
33
        GLOBAL_INSTANCE = std::ptr::null_mut();
34
    }
35
}

1
use std::sync::OnceLock;
2

3
static GLOBAL: OnceLock<MyLib> = OnceLock::new();
4

5
pub struct MyLib {
6
    initialized: bool,
7
}
8

9
#[unsafe(no_mangle)]
10
pub extern "C" fn my_lib_init() -> i32 {
11
    match GLOBAL.set(MyLib { initialized: true }) {
12
        Ok(()) => 0,
13
        Err(_) => -1,
14
    }
15
}

1
// 错误！C 侧 free() 释放 Rust 分配的内存——分配器不匹配
2
// #[unsafe(no_mangle)]
3
// pub extern "C" fn bad() -> *mut u8 {
4
//     let v = vec![0u8; 100];
5
//     Box::into_raw(v.into_boxed_slice()) as *mut u8
6
// }
7

8
// 正确：提供配对的释放函数
9
#[unsafe(no_mangle)]
10
pub extern "C" fn my_sdk_alloc(size: usize) -> *mut u8 {
11
    let mut v = Vec::with_capacity(size);
12
    let ptr = v.as_mut_ptr();
13
    std::mem::forget(v);
14
    ptr
15
}
16

17
#[unsafe(no_mangle)]
18
pub extern "C" fn my_sdk_free(ptr: *mut u8, size: usize) {
19
    if !ptr.is_null() {
20
        unsafe { drop(Vec::from_raw_parts(ptr, 0, size)); }
21
    }
22
}