FFI 完全指南：Rustonomicon 教你安全地与 C 语言交互

【免费下载链接】nomicon The Dark Arts of Advanced and Unsafe Rust Programming 项目地址: https://gitcode.com/gh_mirrors/no/nomicon

Rustonomicon（Rust 黑魔法手册）是学习 Rust 高级和不安全编程的权威资源，其中的 FFI（Foreign Function Interface）章节详细讲解了如何在 Rust 中安全地与 C 语言交互。本文将带你全面了解 Rust FFI 的核心概念、实现步骤和最佳实践，帮助你轻松掌握跨语言调用的终极技巧。

🌟 FFI 基础：Rust 与 C 交互的黄金法则

Rust 与 C 语言交互的基础是 extern "C" 块，它允许声明外部函数并指定 C 调用约定。所有外部函数调用都必须包裹在 unsafe 块中，因为 C 代码不受 Rust 内存安全规则的约束。

use libc::size_t;

#[link(name = "snappy")]
unsafe extern "C" {
    fn snappy_max_compressed_length(source_length: size_t) -> size_t;
}

fn main() {
    let max_len = unsafe { snappy_max_compressed_length(100) };
    println!("100字节数据的最大压缩长度: {}", max_len);
}

关键点：C 函数的参数和返回值类型必须精确匹配，通常使用 libc crate 提供的 C 类型别名（如 size_t、c_int）确保跨平台兼容性。

🛠️ 构建脚本：链接外部库的正确姿势

要在 Rust 项目中使用外部 C 库，需要通过构建脚本告知编译器如何链接库文件。以 snappy 压缩库为例：

1. 在 Cargo.toml 中指定构建脚本：

[package]
build = "build.rs"

2. 创建 build.rs 文件：

// build.rs
fn main() {
    println!("cargo:rustc-link-lib=dylib=stdc++");
    println!("cargo:rustc-link-search=/path/to/snappy/library");
}

最佳实践：使用 pkg-config crate 自动检测系统库路径，避免硬编码路径带来的移植性问题。

🛡️ 安全封装：从 unsafe 到 safe 的转换艺术

将原始 C API 封装为安全的 Rust 接口是 FFI 开发的核心任务。以下是 snappy 压缩函数的安全封装示例：

pub fn compress(src: &[u8]) -> Vec<u8> {
    unsafe {
        let srclen = src.len() as size_t;
        let psrc = src.as_ptr();

        let mut dstlen = snappy_max_compressed_length(srclen);
        let mut dst = Vec::with_capacity(dstlen as usize);
        let pdst = dst.as_mut_ptr();

        snappy_compress(psrc, srclen, pdst, &mut dstlen);
        dst.set_len(dstlen as usize);
        dst
    }
}

封装时需确保：

• 输入参数的有效性检查
• 正确管理内存分配与释放
• 错误处理机制（如返回 Result 类型）
• 遵循 Rust 的所有权规则

🔄 双向交互：从 C 调用 Rust 函数

Rust 不仅能调用 C 函数，还能编译为动态库供 C 调用。关键步骤如下：

1. 在 Rust 中定义对外接口：

#[no_mangle]
pub extern "C" fn hello_from_rust() {
    println!("Hello from Rust!");
}

2. 在 Cargo.toml 中指定输出类型：

[lib]
crate-type = ["cdylib"]

3. 使用 C 代码调用：

extern void hello_from_rust();

int main() {
    hello_from_rust();
    return 0;
}

4. 编译并运行：

cargo build
gcc call_rust.c -o call_rust -lrust_from_c -L./target/debug
LD_LIBRARY_PATH=./target/debug ./call_rust

📞 回调函数：跨语言事件响应机制

C 库常通过回调函数通知状态变化，Rust 函数可以作为回调传递给 C：

// Rust 回调函数
extern fn callback(a: i32) {
    println!("从 C 收到值: {}", a);
}

// C 库接口
#[link(name = "extlib")]
unsafe extern "C" {
    fn register_callback(cb: extern fn(i32)) -> i32;
    fn trigger_callback();
}

fn main() {
    unsafe {
        register_callback(callback);
        trigger_callback(); // 触发回调
    }
}

对于需要访问 Rust 对象的回调，可通过原始指针传递对象：

struct RustObject { a: i32 }

unsafe extern "C" fn callback(target: *mut RustObject, a: i32) {
    (*target).a = a; // 操作 Rust 对象
}

🧩 类型转换：Rust 与 C 数据类型的桥梁

Rust 类型	C 类型	转换工具
&[u8]	const char* + 长度	as_ptr() + len()
Vec<u8>	char* + 长度	into_raw() + from_raw_parts()
String	C 字符串	CString / CStr
结构体	C 结构体	#[repr(C)] 属性

示例：C 字符串处理

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

// Rust 字符串转 C 字符串
let c_str = CString::new("hello").unwrap();
let c_ptr = c_str.as_ptr();

// C 字符串转 Rust 字符串
unsafe {
    let rust_str = CStr::from_ptr(c_ptr).to_str().unwrap();
}

⚠️ 常见陷阱与解决方案

1. 内存安全：避免悬垂指针和内存泄漏，使用 Drop trait 自动释放资源
2. 线程安全：确保跨线程调用的安全性，正确实现 Send 和 Sync trait
3. 异常处理：C 没有异常机制，使用返回值传递错误信息
4. ABI 兼容性：使用 #[repr(C)] 确保结构体布局与 C 兼容
5. 可空指针：使用 Option<*mut T> 表示可空指针，利用 Rust 的空指针优化

📚 深入学习资源

• 官方文档：src/ffi.md
• 安全指南：src/safe-unsafe-meaning.md
• 并发编程：src/concurrency.md
• 类型布局：src/repr-rust.md

要开始实践，可通过以下命令克隆项目：

git clone https://gitcode.com/gh_mirrors/no/nomicon

通过本文的指南，你已经掌握了 Rust FFI 的核心技术。记住，虽然 FFI 涉及 unsafe 代码，但通过正确的封装和严格的安全检查，我们可以在享受 C 语言生态系统的同时，保持 Rust 的内存安全优势。现在就开始探索 Rust 与 C 交互的无限可能吧！

【免费下载链接】nomicon The Dark Arts of Advanced and Unsafe Rust Programming 项目地址: https://gitcode.com/gh_mirrors/no/nomicon