被 C 调用 ​

核心概念 ​

Rust 不仅可以调用 C 函数,也可以将自己的函数暴露给 C 代码调用。要实现这一点,Rust 函数需要满足三个条件:使用 extern "C" 指定 C 调用约定、使用 #[no_mangle] 防止编译器修饰函数名、参数和返回值使用 C 兼容的类型。Rust 代码通常被编译为静态库(.a/.lib)或动态库(.so/.dll/.dylib),然后由 C/C++ 项目链接使用。

这种能力使得 Rust 可以作为 C 项目的"安全模块"——在性能关键或安全关键的部分用 Rust 重写,然后无缝集成到现有的 C 项目中。

rust
use std::ffi::{c_int, c_char, CStr};

// 最基本的暴露给 C 的函数
// #[no_mangle] 防止 Rust 修饰函数名
// pub 使其可以被外部链接
// extern "C" 使用 C 调用约定
#[no_mangle]
pub extern "C" fn add(a: c_int, b: c_int) -> c_int {
    a + b
}

// 对应的 C 头文件声明:
// int add(int a, int b);

#[no_mangle]
pub extern "C" fn greet(name: *const c_char) {
    if name.is_null() {
        println!("Hello, stranger!");
        return;
    }
    // SAFETY: 调用者保证 name 是有效的 C 字符串
    let c_str = unsafe { CStr::from_ptr(name) };
    match c_str.to_str() {
        Ok(s) => println!("Hello, {}!", s),
        Err(_) => println!("Hello! (名字包含无效 UTF-8)"),
    }
}

fn main() {
    // 在 Rust 中也可以直接调用这些函数
    println!("add(3, 4) = {}", add(3, 4));

    let name = std::ffi::CString::new("Rust").unwrap();
    greet(name.as_ptr());
    greet(std::ptr::null());  // 空指针安全
}

函数暴露的三要素 ​

rust
use std::ffi::{c_int, c_double};

// === 要素1:#[no_mangle] ===
// Rust 编译器默认会修饰(mangle)函数名
// 例如 my_func 可能变成 _ZN7my_crate7my_func17h1234567890abcdefE
// C 代码无法找到这个修饰后的名称
// #[no_mangle] 保持原始函数名

// 没有 #[no_mangle]:C 无法找到
// pub extern "C" fn invisible_to_c(x: c_int) -> c_int { x }

// 有 #[no_mangle]:C 可以通过 "visible_to_c" 找到
#[no_mangle]
pub extern "C" fn visible_to_c(x: c_int) -> c_int {
    x * 2
}

// === 要素2:extern "C" ===
// 指定 C 调用约定
// 不加 extern "C" 的函数使用 Rust 调用约定,C 代码调用会崩溃

// === 要素3:C 兼容类型 ===
// 参数和返回值必须是 C 能理解的类型
// 不能用 String、Vec、Option 等 Rust 特有类型

// 正确:使用 C 兼容类型
#[no_mangle]
pub extern "C" fn compute(x: c_double, y: c_double) -> c_double {
    (x * x + y * y).sqrt()
}

// 错误示例(不要这样做):
// #[no_mangle]
// pub extern "C" fn bad_func(s: String) -> Vec<i32> { ... }
// String 和 Vec 不是 C 兼容类型

fn main() {
    println!("visible_to_c(5) = {}", visible_to_c(5));
    println!("compute(3.0, 4.0) = {}", compute(3.0, 4.0));
}
要素作用不使用的后果
#[no_mangle]保持函数名不变C 代码找不到函数
extern "C"使用 C 调用约定参数传递方式不匹配,崩溃
C 兼容类型确保类型布局一致数据传递错误
pub允许外部链接函数不会出现在库的导出表中

不透明类型模式 ​

rust
use std::ffi::{c_int, c_char, CStr};

// 不透明类型:对 C 隐藏内部实现
// C 代码只看到一个指针,不知道里面有什么
pub struct Database {
    records: Vec<(String, String)>,
    name: String,
}

// C 头文件中声明为:
// typedef struct Database Database;
// Database* db_open(const char* name);
// void db_close(Database* db);
// int db_insert(Database* db, const char* key, const char* value);
// const char* db_get(Database* db, const char* key);

#[no_mangle]
pub extern "C" fn db_open(name: *const c_char) -> *mut Database {
    if name.is_null() {
        return std::ptr::null_mut();
    }

    let name_str = unsafe { CStr::from_ptr(name) };
    let name = match name_str.to_str() {
        Ok(s) => s.to_string(),
        Err(_) => return std::ptr::null_mut(),
    };

    let db = Box::new(Database {
        records: Vec::new(),
        name,
    });

    Box::into_raw(db)  // 将 Box 转为裸指针,转移所有权给 C
}

#[no_mangle]
pub extern "C" fn db_close(db: *mut Database) {
    if !db.is_null() {
        // SAFETY: db 来自 db_open 的 Box::into_raw
        unsafe { drop(Box::from_raw(db)); }
    }
}

#[no_mangle]
pub extern "C" fn db_insert(
    db: *mut Database,
    key: *const c_char,
    value: *const c_char,
) -> c_int {
    if db.is_null() || key.is_null() || value.is_null() {
        return -1;
    }

    // SAFETY: db 来自 db_open,key 和 value 由调用者保证有效
    let db = unsafe { &mut *db };
    let key = unsafe { CStr::from_ptr(key) };
    let value = unsafe { CStr::from_ptr(value) };

    let key = match key.to_str() {
        Ok(s) => s.to_string(),
        Err(_) => return -1,
    };
    let value = match value.to_str() {
        Ok(s) => s.to_string(),
        Err(_) => return -1,
    };

    db.records.push((key, value));
    0  // 成功
}

#[no_mangle]
pub extern "C" fn db_count(db: *const Database) -> c_int {
    if db.is_null() {
        return 0;
    }
    // SAFETY: db 有效
    let db = unsafe { &*db };
    db.records.len() as c_int
}

// 注意:返回指向内部数据的指针需要特别小心
// 调用者不能在 db 被修改或释放后使用这个指针
#[no_mangle]
pub extern "C" fn db_name(db: *const Database) -> *const c_char {
    if db.is_null() {
        return std::ptr::null();
    }
    let db = unsafe { &*db };
    // 注意:这里返回 Rust String 内部的指针
    // 只在 db 未被修改期间有效
    db.name.as_ptr() as *const c_char
}

fn main() {
    let name = std::ffi::CString::new("test_db").unwrap();

    // 模拟 C 代码的调用流程
    let db = db_open(name.as_ptr());
    assert!(!db.is_null());
    println!("数据库已打开");

    let k1 = std::ffi::CString::new("name").unwrap();
    let v1 = std::ffi::CString::new("Alice").unwrap();
    let k2 = std::ffi::CString::new("age").unwrap();
    let v2 = std::ffi::CString::new("30").unwrap();

    db_insert(db, k1.as_ptr(), v1.as_ptr());
    db_insert(db, k2.as_ptr(), v2.as_ptr());
    println!("插入 2 条记录");

    println!("记录数: {}", db_count(db));

    // 空指针安全
    println!("null insert: {}", db_insert(std::ptr::null_mut(), k1.as_ptr(), v1.as_ptr()));
    println!("null count: {}", db_count(std::ptr::null()));

    db_close(db);
    println!("数据库已关闭");

    // 释放 null 不会出问题
    db_close(std::ptr::null_mut());
}

错误处理 ​

rust
use std::ffi::{c_int, c_char, CStr, CString};
use std::ptr;

// C 兼容的错误码
pub const OK: c_int = 0;
pub const ERR_NULL_PTR: c_int = -1;
pub const ERR_INVALID_UTF8: c_int = -2;
pub const ERR_OVERFLOW: c_int = -3;
pub const ERR_UNKNOWN: c_int = -99;

// C 兼容的结果结构体
#[repr(C)]
pub struct CResult {
    pub value: c_int,
    pub error_code: c_int,
    pub error_msg: *const c_char,  // 指向静态字符串
}

// 静态错误消息(生命周期 'static,C 代码可以安全使用)
static ERR_MSG_OK: &[u8] = b"success\0";
static ERR_MSG_NULL: &[u8] = b"null pointer\0";
static ERR_MSG_UTF8: &[u8] = b"invalid UTF-8\0";
static ERR_MSG_OVERFLOW: &[u8] = b"integer overflow\0";

impl CResult {
    fn ok(value: c_int) -> Self {
        CResult {
            value,
            error_code: OK,
            error_msg: ERR_MSG_OK.as_ptr() as *const c_char,
        }
    }

    fn err(code: c_int, msg: &'static [u8]) -> Self {
        CResult {
            value: 0,
            error_code: code,
            error_msg: msg.as_ptr() as *const c_char,
        }
    }
}

#[no_mangle]
pub extern "C" fn safe_add(a: c_int, b: c_int, result: *mut CResult) -> c_int {
    if result.is_null() {
        return ERR_NULL_PTR;
    }

    match a.checked_add(b) {
        Some(sum) => {
            // SAFETY: result 非空
            unsafe { *result = CResult::ok(sum); }
            OK
        }
        None => {
            unsafe { *result = CResult::err(ERR_OVERFLOW, ERR_MSG_OVERFLOW); }
            ERR_OVERFLOW
        }
    }
}

// 防止 panic 穿越 FFI 边界
#[no_mangle]
pub extern "C" fn safe_parse_int(s: *const c_char) -> CResult {
    // 用 catch_unwind 捕获可能的 panic
    let result = std::panic::catch_unwind(|| {
        if s.is_null() {
            return CResult::err(ERR_NULL_PTR, ERR_MSG_NULL);
        }

        let c_str = unsafe { CStr::from_ptr(s) };
        let rust_str = match c_str.to_str() {
            Ok(s) => s,
            Err(_) => return CResult::err(ERR_INVALID_UTF8, ERR_MSG_UTF8),
        };

        match rust_str.parse::<c_int>() {
            Ok(n) => CResult::ok(n),
            Err(_) => CResult::err(ERR_UNKNOWN, b"parse error\0"),
        }
    });

    match result {
        Ok(r) => r,
        Err(_) => CResult::err(ERR_UNKNOWN, b"internal panic\0"),
    }
}

fn main() {
    // 安全加法
    println!("=== safe_add ===");
    let mut result = CResult { value: 0, error_code: 0, error_msg: ptr::null() };

    safe_add(10, 20, &mut result);
    println!("10 + 20 = {}, error: {}", result.value, result.error_code);

    safe_add(c_int::MAX, 1, &mut result);
    println!("MAX + 1: error_code = {}", result.error_code);
    if !result.error_msg.is_null() {
        let msg = unsafe { CStr::from_ptr(result.error_msg) };
        println!("  错误信息: {}", msg.to_string_lossy());
    }

    // 安全解析
    println!("\n=== safe_parse_int ===");
    let tests = ["42", "-100", "abc", ""];
    for s in &tests {
        let cs = CString::new(*s).unwrap();
        let r = safe_parse_int(cs.as_ptr());
        if r.error_code == OK {
            println!("parse(\"{}\") = {}", s, r.value);
        } else {
            let msg = unsafe { CStr::from_ptr(r.error_msg) };
            println!("parse(\"{}\"): 错误 {} - {}", s, r.error_code, msg.to_string_lossy());
        }
    }

    // null 输入
    let r = safe_parse_int(ptr::null());
    println!("parse(null): error = {}", r.error_code);
}

构建配置 ​

rust
// 在 Cargo.toml 中配置库类型:
//
// [lib]
// crate-type = ["cdylib"]    # 动态库 (.so / .dll / .dylib)
// # 或
// crate-type = ["staticlib"] # 静态库 (.a / .lib)
// # 或两者都要
// crate-type = ["cdylib", "staticlib"]

// 生成 C 头文件可以用 cbindgen 工具:
// cargo install cbindgen
// cbindgen --output my_lib.h

// 示例:一个完整的可被 C 调用的库

use std::ffi::{c_int, c_double};

/// 计算两点之间的距离
#[no_mangle]
pub extern "C" fn point_distance(
    x1: c_double, y1: c_double,
    x2: c_double, y2: c_double,
) -> c_double {
    let dx = x2 - x1;
    let dy = y2 - y1;
    (dx * dx + dy * dy).sqrt()
}

/// 计算阶乘(迭代实现,避免栈溢出)
#[no_mangle]
pub extern "C" fn factorial(n: c_int) -> c_int {
    if n < 0 { return -1; }
    if n <= 1 { return 1; }

    let mut result: c_int = 1;
    for i in 2..=n {
        match result.checked_mul(i) {
            Some(r) => result = r,
            None => return -1,  // 溢出
        }
    }
    result
}

/// 版本号
#[no_mangle]
pub extern "C" fn lib_version() -> c_int {
    // 主版本 * 10000 + 次版本 * 100 + 补丁版本
    // 1.2.3 → 10203
    10203
}

fn main() {
    println!("=== 库函数测试 ===");
    println!("distance((0,0), (3,4)) = {}", point_distance(0.0, 0.0, 3.0, 4.0));
    println!("factorial(5) = {}", factorial(5));
    println!("factorial(10) = {}", factorial(10));
    println!("factorial(-1) = {}", factorial(-1));
    println!("version = {}", lib_version());

    // 对应的 C 头文件内容:
    // #ifndef MY_LIB_H
    // #define MY_LIB_H
    //
    // double point_distance(double x1, double y1, double x2, double y2);
    // int factorial(int n);
    // int lib_version(void);
    //
    // #endif
}

基本示例 ​

一个完整的 Rust 字符串处理库,暴露给 C 使用:

rust
use std::ffi::{c_char, c_int, CStr, CString};
use std::ptr;

// ===== 字符串处理 API =====

/// 创建字符串的大写副本
/// 返回的指针需要用 string_free 释放
#[no_mangle]
pub extern "C" fn string_to_upper(s: *const c_char) -> *mut c_char {
    if s.is_null() {
        return ptr::null_mut();
    }

    let c_str = unsafe { CStr::from_ptr(s) };
    let rust_str = match c_str.to_str() {
        Ok(s) => s,
        Err(_) => return ptr::null_mut(),
    };

    let upper = rust_str.to_uppercase();
    match CString::new(upper) {
        Ok(cs) => cs.into_raw(),  // 转移所有权给 C
        Err(_) => ptr::null_mut(),
    }
}

/// 创建字符串的小写副本
#[no_mangle]
pub extern "C" fn string_to_lower(s: *const c_char) -> *mut c_char {
    if s.is_null() {
        return ptr::null_mut();
    }

    let c_str = unsafe { CStr::from_ptr(s) };
    let rust_str = match c_str.to_str() {
        Ok(s) => s,
        Err(_) => return ptr::null_mut(),
    };

    let lower = rust_str.to_lowercase();
    match CString::new(lower) {
        Ok(cs) => cs.into_raw(),
        Err(_) => ptr::null_mut(),
    }
}

/// 检查字符串是否包含子串
#[no_mangle]
pub extern "C" fn string_contains(
    haystack: *const c_char,
    needle: *const c_char,
) -> c_int {
    if haystack.is_null() || needle.is_null() {
        return 0;
    }

    let h = unsafe { CStr::from_ptr(haystack) };
    let n = unsafe { CStr::from_ptr(needle) };

    let h_str = match h.to_str() {
        Ok(s) => s,
        Err(_) => return 0,
    };
    let n_str = match n.to_str() {
        Ok(s) => s,
        Err(_) => return 0,
    };

    if h_str.contains(n_str) { 1 } else { 0 }
}

/// 反转字符串
#[no_mangle]
pub extern "C" fn string_reverse(s: *const c_char) -> *mut c_char {
    if s.is_null() {
        return ptr::null_mut();
    }

    let c_str = unsafe { CStr::from_ptr(s) };
    let rust_str = match c_str.to_str() {
        Ok(s) => s,
        Err(_) => return ptr::null_mut(),
    };

    let reversed: String = rust_str.chars().rev().collect();
    match CString::new(reversed) {
        Ok(cs) => cs.into_raw(),
        Err(_) => ptr::null_mut(),
    }
}

/// 释放由本库分配的字符串
#[no_mangle]
pub extern "C" fn string_free(s: *mut c_char) {
    if !s.is_null() {
        // SAFETY: s 来自 CString::into_raw
        unsafe { drop(CString::from_raw(s)); }
    }
}

fn main() {
    println!("=== 字符串处理库测试 ===");

    // to_upper
    let input = CString::new("Hello, Rust!").unwrap();
    let upper = string_to_upper(input.as_ptr());
    if !upper.is_null() {
        let result = unsafe { CStr::from_ptr(upper) };
        println!("to_upper: {}", result.to_string_lossy());
        string_free(upper);
    }

    // to_lower
    let input = CString::new("Hello, WORLD!").unwrap();
    let lower = string_to_lower(input.as_ptr());
    if !lower.is_null() {
        let result = unsafe { CStr::from_ptr(lower) };
        println!("to_lower: {}", result.to_string_lossy());
        string_free(lower);
    }

    // contains
    let hay = CString::new("Hello World").unwrap();
    let needle1 = CString::new("World").unwrap();
    let needle2 = CString::new("xyz").unwrap();
    println!("contains 'World': {}", string_contains(hay.as_ptr(), needle1.as_ptr()));
    println!("contains 'xyz': {}", string_contains(hay.as_ptr(), needle2.as_ptr()));

    // reverse
    let input = CString::new("abcdef").unwrap();
    let rev = string_reverse(input.as_ptr());
    if !rev.is_null() {
        let result = unsafe { CStr::from_ptr(rev) };
        println!("reverse: {}", result.to_string_lossy());
        string_free(rev);
    }

    // null 安全
    println!("\n=== null 安全 ===");
    println!("to_upper(null): {:p}", string_to_upper(ptr::null()));
    println!("contains(null, ...): {}", string_contains(ptr::null(), ptr::null()));
    string_free(ptr::null_mut());  // 不会崩溃
    println!("string_free(null): 安全");
}

常见问题 ​

问题一:Rust 函数中可以使用 String、Vec 等类型吗?

函数内部可以自由使用任何 Rust 类型。但参数和返回值必须是 C 兼容类型。内部用 String 处理,返回时转为 *mut c_char(通过 CString::into_raw),释放时用专门的 free 函数。

问题二:Rust 库的 panic 会影响 C 代码吗?

panic 穿越 FFI 边界是未定义行为。暴露给 C 的函数应该用 std::panic::catch_unwind 捕获所有可能的 panic,转为错误码返回。

问题三:如何生成 C 头文件?

使用 cbindgen 工具。安装后运行 cbindgen --output my_lib.h,它会自动从 Rust 代码生成对应的 C 头文件。也可以在 build.rs 中集成 cbindgen 自动生成。

问题四:cdylib 和 staticlib 选哪个?

cdylib 生成动态库(.so/.dll),适合运行时加载、插件系统。staticlib 生成静态库(.a/.lib),适合编译时链接,不需要运行时依赖。根据 C 项目的需求选择。

适用场景 ​

  • C 项目中引入 Rust 模块:安全关键的功能用 Rust 实现
  • 跨语言库:编写可被多种语言调用的库
  • 渐进式迁移:将 C 项目逐步用 Rust 重写
  • 插件系统:以动态库形式提供插件

注意事项 ​

  • 必须使用 #[no_mangle] + extern "C" + pub
  • 参数和返回值只能是 C 兼容类型
  • 不能让 panic 穿越 FFI 边界
  • Rust 分配的内存(CString::into_raw、Box::into_raw)必须用 Rust 函数释放
  • 在 Cargo.toml 中设置 crate-type = ["cdylib"] 或 ["staticlib"]
  • 用 cbindgen 生成 C 头文件
  • 所有指针参数都应做 null 检查

总结 ​

将 Rust 函数暴露给 C 调用需要三个要素:#[no_mangle](保持函数名)、extern "C"(C 调用约定)、C 兼容类型(参数和返回值)。常用的设计模式是不透明类型——C 代码只持有指针,通过 create/destroy/操作 系列函数管理对象。返回动态分配的数据(如字符串)时,需要提供配对的 free 函数。错误处理通过返回错误码或结构体实现。panic 必须用 catch_unwind 捕获,不能穿越 FFI 边界。构建时在 Cargo.toml 中设置 crate-type,用 cbindgen 生成 C 头文件。