被 C 调用
核心概念
Rust 不仅可以调用 C 函数,也可以将自己的函数暴露给 C 代码调用。要实现这一点,Rust 函数需要满足三个条件:使用 extern "C" 指定 C 调用约定、使用 #[no_mangle] 防止编译器修饰函数名、参数和返回值使用 C 兼容的类型。Rust 代码通常被编译为静态库(.a/.lib)或动态库(.so/.dll/.dylib),然后由 C/C++ 项目链接使用。
这种能力使得 Rust 可以作为 C 项目的"安全模块"——在性能关键或安全关键的部分用 Rust 重写,然后无缝集成到现有的 C 项目中。
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()); // 空指针安全
}函数暴露的三要素
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 | 允许外部链接 | 函数不会出现在库的导出表中 |
不透明类型模式
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());
}错误处理
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);
}构建配置
// 在 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 使用:
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 头文件。