FFI 外部函数接口 ​

核心概念 ​

FFI(Foreign Function Interface,外部函数接口)是 Rust 与其他编程语言(主要是 C/C++)互相调用函数的机制。Rust 通过 extern 块声明外部函数,通过 extern "C" 指定调用约定,使得 Rust 代码可以调用 C 库函数,也可以将 Rust 函数暴露给 C 代码使用。

FFI 是 unsafe 的,原因有几个:编译器无法验证外部函数的签名是否正确、无法保证传入的参数满足外部函数的要求、无法追踪外部代码中的内存管理。但 FFI 是 Rust 生态的重要基石——大量的系统库(OpenSSL、SQLite、zlib 等)都是 C 写的,通过 FFI 可以直接复用这些成熟的库。

rust
use std::ffi::c_int;

// 声明外部 C 函数
extern "C" {
    // C 标准库中的 abs 函数
    fn abs(input: c_int) -> c_int;

    // C 标准库中的 strlen 函数
    fn strlen(s: *const std::ffi::c_char) -> usize;
}

fn main() {
    // 调用外部函数需要 unsafe
    // SAFETY: abs 是 C 标准库函数,接受任意 c_int 值
    let result = unsafe { abs(-42) };
    println!("abs(-42) = {}", result);

    // 使用 C 字符串
    let c_str = std::ffi::CString::new("Hello FFI").unwrap();
    // SAFETY: c_str.as_ptr() 返回有效的以 null 结尾的 C 字符串
    let len = unsafe { strlen(c_str.as_ptr()) };
    println!("strlen(\"Hello FFI\") = {}", len);
}

FFI 的基本组成 ​

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

// === extern 块:声明外部函数 ===
extern "C" {
    // 数学函数
    fn sqrt(x: c_double) -> c_double;
    fn pow(base: c_double, exp: c_double) -> c_double;
    fn sin(x: c_double) -> c_double;
    fn cos(x: c_double) -> c_double;

    // 内存函数
    fn malloc(size: usize) -> *mut std::ffi::c_void;
    fn free(ptr: *mut std::ffi::c_void);
    fn memcpy(
        dest: *mut std::ffi::c_void,
        src: *const std::ffi::c_void,
        n: usize,
    ) -> *mut std::ffi::c_void;

    // 环境变量
    fn getenv(name: *const c_char) -> *const c_char;
}

fn main() {
    // 调用数学函数
    // SAFETY: sqrt, pow, sin, cos 都是标准数学函数,接受任意 double 值
    unsafe {
        println!("sqrt(16.0) = {}", sqrt(16.0));
        println!("pow(2.0, 10.0) = {}", pow(2.0, 10.0));
        println!("sin(0.0) = {}", sin(0.0));
        println!("cos(0.0) = {}", cos(0.0));
    }

    // 调用 malloc/free
    // SAFETY: malloc 分配 4 字节内存
    unsafe {
        let ptr = malloc(4) as *mut i32;
        if !ptr.is_null() {
            *ptr = 42;
            println!("malloc 分配: {}", *ptr);
            free(ptr as *mut std::ffi::c_void);
        }
    }

    // 读取环境变量
    let name = CString::new("PATH").unwrap();
    // SAFETY: name.as_ptr() 是有效的 C 字符串
    unsafe {
        let value = getenv(name.as_ptr());
        if !value.is_null() {
            let path = CStr::from_ptr(value);
            // 只打印前100个字符
            let s = path.to_string_lossy();
            let preview: String = s.chars().take(80).collect();
            println!("PATH: {}...", preview);
        }
    }
}

Rust 与 C 的类型对应 ​

rust
use std::ffi::{c_int, c_uint, c_long, c_char, c_void, c_float, c_double};

fn main() {
    // Rust 提供了 std::ffi 模块中的 C 兼容类型
    println!("=== 类型大小 ===");
    println!("c_char:   {} 字节", std::mem::size_of::<c_char>());
    println!("c_int:    {} 字节", std::mem::size_of::<c_int>());
    println!("c_uint:   {} 字节", std::mem::size_of::<c_uint>());
    println!("c_long:   {} 字节", std::mem::size_of::<c_long>());
    println!("c_float:  {} 字节", std::mem::size_of::<c_float>());
    println!("c_double: {} 字节", std::mem::size_of::<c_double>());
    println!("*mut c_void: {} 字节", std::mem::size_of::<*mut c_void>());
}
C 类型Rust FFI 类型Rust 原生等价
charc_chari8 或 u8(平台相关)
intc_int通常 i32
unsigned intc_uint通常 u32
longc_longi32 或 i64(平台相关)
floatc_floatf32
doublec_doublef64
void**mut c_void通用指针
const char**const c_charC 字符串指针
size_tusize平台相关的无符号整数
boolboolbool(C99 的 _Bool)

字符串在 FFI 中的处理 ​

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

extern "C" {
    fn strlen(s: *const c_char) -> usize;
}

fn main() {
    // === Rust String → C 字符串 ===

    // CString:拥有所有权的、以 null 结尾的 C 字符串
    let rust_str = "Hello, C world!";
    let c_string = CString::new(rust_str).expect("字符串中不能包含 null 字节");

    // 获取 C 字符串指针
    let c_ptr: *const c_char = c_string.as_ptr();

    // SAFETY: c_ptr 来自有效的 CString
    let len = unsafe { strlen(c_ptr) };
    println!("C strlen: {}", len);

    // 注意:CString 被 drop 后指针失效
    // 不要在 CString 被 drop 后使用 c_ptr

    // === C 字符串 → Rust String ===

    // CStr:不拥有所有权的 C 字符串引用
    let c_str_ref: &CStr = c_string.as_c_str();
    println!("CStr: {:?}", c_str_ref);

    // CStr → &str(可能失败,因为 C 字符串不一定是有效 UTF-8)
    match c_str_ref.to_str() {
        Ok(s) => println!("有效 UTF-8: {}", s),
        Err(e) => println!("无效 UTF-8: {}", e),
    }

    // CStr → String(有损转换,替换无效 UTF-8 字节)
    let lossy = c_str_ref.to_string_lossy();
    println!("有损转换: {}", lossy);

    // === 从外部函数获取的 C 字符串 ===
    let raw_ptr: *const c_char = c_string.as_ptr();
    // SAFETY: raw_ptr 指向有效的以 null 结尾的 C 字符串
    let from_raw: &CStr = unsafe { CStr::from_ptr(raw_ptr) };
    println!("from_ptr: {:?}", from_raw);

    // === 注意:null 字节 ===
    // C 字符串以 null 结尾,不能包含中间的 null 字节
    let result = CString::new("hello\0world");
    match result {
        Ok(_) => println!("不应该到这里"),
        Err(e) => println!("预期错误: {}", e),
    }
}
类型方向拥有所有权说明
CStringRust → C是Rust 分配的以 null 结尾的字符串
CStrC → Rust否C 字符串的引用视图
*const c_charFFI 传递否原始 C 字符串指针

结构体在 FFI 中的传递 ​

rust
use std::ffi::c_int;

// #[repr(C)] 保证与 C 兼容的内存布局
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct Point {
    x: f64,
    y: f64,
}

#[repr(C)]
#[derive(Debug)]
struct Rect {
    origin: Point,
    size: Point,
}

// 模拟 C 函数(实际项目中这些会在 extern 块中声明)
// 这里用 extern "C" fn 来演示 C 兼容函数
extern "C" fn distance(p1: Point, p2: Point) -> f64 {
    let dx = p1.x - p2.x;
    let dy = p1.y - p2.y;
    (dx * dx + dy * dy).sqrt()
}

extern "C" fn rect_area(rect: *const Rect) -> f64 {
    // SAFETY: 调用者保证 rect 非空且有效
    let r = unsafe { &*rect };
    r.size.x * r.size.y
}

fn main() {
    let p1 = Point { x: 0.0, y: 0.0 };
    let p2 = Point { x: 3.0, y: 4.0 };

    // 值传递
    let dist = distance(p1, p2);
    println!("距离: {}", dist);

    // 指针传递
    let rect = Rect {
        origin: Point { x: 10.0, y: 20.0 },
        size: Point { x: 100.0, y: 50.0 },
    };
    let area = rect_area(&rect as *const Rect);
    println!("面积: {}", area);

    // 内存布局验证
    println!("\n内存布局:");
    println!("Point: {} 字节, 对齐 {} 字节",
        std::mem::size_of::<Point>(),
        std::mem::align_of::<Point>());
    println!("Rect: {} 字节, 对齐 {} 字节",
        std::mem::size_of::<Rect>(),
        std::mem::align_of::<Rect>());
}

回调函数 ​

rust
use std::ffi::c_int;

// C 风格的回调函数类型
type Comparator = extern "C" fn(a: *const c_int, b: *const c_int) -> c_int;

// 模拟 C 库中的排序函数(接受回调)
fn c_sort(data: &mut [c_int], compare: Comparator) {
    // 使用冒泡排序来演示回调的使用
    let len = data.len();
    for i in 0..len {
        for j in 0..len - 1 - i {
            let result = compare(
                &data[j] as *const c_int,
                &data[j + 1] as *const c_int,
            );
            if result > 0 {
                data.swap(j, j + 1);
            }
        }
    }
}

// 升序比较回调
extern "C" fn compare_asc(a: *const c_int, b: *const c_int) -> c_int {
    // SAFETY: 指针由 c_sort 提供,指向有效的 c_int
    let (va, vb) = unsafe { (*a, *b) };
    va - vb
}

// 降序比较回调
extern "C" fn compare_desc(a: *const c_int, b: *const c_int) -> c_int {
    // SAFETY: 指针由 c_sort 提供,指向有效的 c_int
    let (va, vb) = unsafe { (*a, *b) };
    vb - va
}

fn main() {
    let mut data = vec![5, 2, 8, 1, 9, 3, 7, 4, 6];

    println!("原始: {:?}", data);

    c_sort(&mut data, compare_asc);
    println!("升序: {:?}", data);

    c_sort(&mut data, compare_desc);
    println!("降序: {:?}", data);
}

基本示例 ​

综合展示 FFI 的常见使用模式:

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

// ===== 声明 C 标准库函数 =====
extern "C" {
    fn abs(n: c_int) -> c_int;
    fn atoi(s: *const c_char) -> c_int;
    fn strlen(s: *const c_char) -> usize;
    fn strcmp(s1: *const c_char, s2: *const c_char) -> c_int;
}

// ===== 安全封装 =====

/// 安全的 abs 封装
fn safe_abs(n: i32) -> i32 {
    // SAFETY: abs 接受任意 c_int 值
    unsafe { abs(n as c_int) as i32 }
}

/// 安全的字符串转整数
fn safe_atoi(s: &str) -> Option<i32> {
    let c_str = CString::new(s).ok()?;
    // SAFETY: c_str.as_ptr() 是有效的以 null 结尾的 C 字符串
    let result = unsafe { atoi(c_str.as_ptr()) };
    // atoi 在失败时返回 0,无法区分 "0" 和失败
    // 简单处理:检查输入是否以数字开头
    if result == 0 && !s.starts_with('0') && s != "0" {
        if s.trim().is_empty() || !s.trim().starts_with(|c: char| c.is_ascii_digit() || c == '-') {
            return None;
        }
    }
    Some(result as i32)
}

/// 安全的字符串长度
fn safe_strlen(s: &str) -> usize {
    let c_str = match CString::new(s) {
        Ok(cs) => cs,
        Err(_) => return 0,  // 包含 null 字节
    };
    // SAFETY: c_str.as_ptr() 有效
    unsafe { strlen(c_str.as_ptr()) }
}

/// 安全的字符串比较
fn safe_strcmp(s1: &str, s2: &str) -> std::cmp::Ordering {
    let c1 = CString::new(s1).unwrap();
    let c2 = CString::new(s2).unwrap();
    // SAFETY: 两个指针都来自有效的 CString
    let result = unsafe { strcmp(c1.as_ptr(), c2.as_ptr()) };
    result.cmp(&0)
}

// ===== #[repr(C)] 结构体用于 FFI =====
#[repr(C)]
struct TimeVal {
    tv_sec: i64,   // 秒
    tv_usec: i64,  // 微秒
}

// ===== Rust 函数暴露给 C =====
#[no_mangle]
pub extern "C" fn rust_add(a: c_int, b: c_int) -> c_int {
    a + b
}

#[no_mangle]
pub extern "C" fn rust_greet(name: *const c_char) -> c_int {
    if name.is_null() {
        return -1;
    }
    // SAFETY: 调用者保证 name 是有效的 C 字符串
    let c_str = unsafe { CStr::from_ptr(name) };
    match c_str.to_str() {
        Ok(s) => {
            println!("Hello from Rust, {}!", s);
            0
        }
        Err(_) => -1,
    }
}

fn main() {
    println!("=== abs ===");
    println!("abs(-42) = {}", safe_abs(-42));
    println!("abs(10) = {}", safe_abs(10));

    println!("\n=== atoi ===");
    println!("atoi(\"123\") = {:?}", safe_atoi("123"));
    println!("atoi(\"-456\") = {:?}", safe_atoi("-456"));
    println!("atoi(\"abc\") = {:?}", safe_atoi("abc"));

    println!("\n=== strlen ===");
    println!("strlen(\"Hello\") = {}", safe_strlen("Hello"));
    println!("strlen(\"\") = {}", safe_strlen(""));
    println!("strlen(\"你好\") = {}", safe_strlen("你好"));

    println!("\n=== strcmp ===");
    let cmp = safe_strcmp("apple", "banana");
    println!("strcmp(\"apple\", \"banana\") = {:?}", cmp);
    let cmp = safe_strcmp("hello", "hello");
    println!("strcmp(\"hello\", \"hello\") = {:?}", cmp);

    println!("\n=== Rust 暴露给 C 的函数 ===");
    let sum = rust_add(10, 20);
    println!("rust_add(10, 20) = {}", sum);

    let name = CString::new("World").unwrap();
    rust_greet(name.as_ptr());

    // 空指针检查
    let result = rust_greet(std::ptr::null());
    println!("rust_greet(null) = {}", result);
}

常见问题 ​

问题一:为什么调用 C 函数需要 unsafe?

编译器无法验证 extern 块中的函数签名是否正确——如果声明的参数类型与 C 库中的实际类型不匹配,会导致未定义行为。编译器也无法保证传入的指针参数有效、内存管理正确等。

问题二:CString 和 &str 有什么区别?

&str 是 UTF-8 编码的字符串切片,不以 null 结尾,可以包含 null 字节。C 字符串(*const c_char)以 null 结尾,不能包含 null 字节,编码通常不是 UTF-8。CString 负责在两者之间转换——将 Rust 字符串转为以 null 结尾的格式。

问题三:为什么需要 #[repr(C)]?

Rust 编译器默认会重新排列结构体字段以优化内存布局。#[repr(C)] 强制使用 C 语言的布局规则(字段按声明顺序排列),确保 Rust 结构体和 C 结构体在内存中的布局完全一致。

问题四:如何链接 C 库?

在 build.rs 中使用 println!("cargo:rustc-link-lib=名称") 告诉编译器链接哪个库。系统库(如 libc)通常自动链接。第三方库需要指定库的路径和名称。也可以在 Cargo.toml 中通过 links 字段声明依赖的 C 库。

适用场景 ​

  • 调用系统 API:操作系统提供的 C 接口
  • 使用 C 库:OpenSSL、SQLite、zlib 等成熟的 C 库
  • 嵌入式开发:与硬件驱动的 C 代码交互
  • 渐进式迁移:将 C/C++ 项目逐步迁移到 Rust

注意事项 ​

  • 调用外部函数必须在 unsafe 块中
  • extern 块中的函数签名必须与 C 库中的实际签名完全匹配
  • 字符串传递用 CString/CStr,不能直接传 &str
  • 传递结构体必须使用 #[repr(C)]
  • C 函数分配的内存必须用对应的 C 函数释放(如 malloc→free)
  • 注意 C 类型在不同平台上的大小差异(如 long)
  • 暴露给 C 的函数需要 #[no_mangle] 和 extern "C"

总结 ​

FFI 是 Rust 与 C 代码互操作的机制。通过 extern "C" 块声明外部 C 函数,调用时需要 unsafe。字符串转换使用 CString(Rust→C)和 CStr(C→Rust),结构体传递需要 #[repr(C)] 保证布局兼容。Rust 函数暴露给 C 需要 #[no_mangle] 和 extern "C"。类型映射使用 std::ffi 模块中的 C 兼容类型(c_int、c_char 等)。FFI 调用不安全的根本原因是编译器无法验证外部函数的签名和行为。实际项目中应将 FFI 调用封装在安全的 Rust API 后面,对外提供类型安全和内存安全的接口。