调用 C 函数 ​

核心概念 ​

从 Rust 调用 C 函数是 FFI 最常见的使用方向。流程分三步:首先在 extern "C" 块中声明 C 函数的签名,然后在 unsafe 块中调用这些函数,最后在构建时链接对应的 C 库。调用 C 函数之所以需要 unsafe,是因为 Rust 编译器无法验证外部函数的签名正确性、参数有效性和内存安全性——这些全部由程序员负责保证。

实际项目中,通常会将 unsafe 的 C 函数调用封装在安全的 Rust 函数中,对外提供类型安全、内存安全的接口。很多流行的 C 库(如 OpenSSL、SQLite)都有对应的 Rust 封装 crate(如 openssl、rusqlite),它们的内部就是通过 FFI 调用 C 函数实现的。

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

// 声明 C 标准库函数
extern "C" {
    fn abs(n: c_int) -> c_int;
    fn sqrt(x: c_double) -> c_double;
    fn atoi(s: *const c_char) -> c_int;
    fn getenv(name: *const c_char) -> *const c_char;
}

fn main() {
    // 简单的数值函数
    // SAFETY: abs 和 sqrt 是标准 C 库函数,接受任意数值
    unsafe {
        println!("abs(-42) = {}", abs(-42));
        println!("sqrt(144.0) = {}", sqrt(144.0));
    }

    // 需要字符串参数的函数
    let num_str = CString::new("12345").unwrap();
    // SAFETY: num_str.as_ptr() 是有效的以 null 结尾的 C 字符串
    let num = unsafe { atoi(num_str.as_ptr()) };
    println!("atoi(\"12345\") = {}", num);

    // 返回字符串指针的函数
    let var_name = CString::new("PATH").unwrap();
    // SAFETY: var_name.as_ptr() 是有效的 C 字符串
    let value = unsafe { getenv(var_name.as_ptr()) };
    if !value.is_null() {
        // SAFETY: getenv 返回的非空指针指向有效的 C 字符串
        let s = unsafe { CStr::from_ptr(value) };
        let path = s.to_string_lossy();
        let preview: String = path.chars().take(60).collect();
        println!("PATH = {}...", preview);
    }
}

调用流程 ​

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

// ===== 第一步:声明 C 函数签名 =====
// 签名必须与 C 库中的实际签名完全匹配
extern "C" {
    // int strcmp(const char *s1, const char *s2);
    fn strcmp(s1: *const c_char, s2: *const c_char) -> c_int;

    // size_t strlen(const char *s);
    fn strlen(s: *const c_char) -> usize;

    // void *memset(void *s, int c, size_t n);
    fn memset(s: *mut c_void, c: c_int, n: usize) -> *mut c_void;

    // void *memcpy(void *dest, const void *src, size_t n);
    fn memcpy(dest: *mut c_void, src: *const c_void, n: usize) -> *mut c_void;
}

// ===== 第二步:在 unsafe 块中调用 =====
fn main() {
    // strcmp
    let s1 = CString::new("apple").unwrap();
    let s2 = CString::new("banana").unwrap();
    let s3 = CString::new("apple").unwrap();

    // SAFETY: 所有指针来自有效的 CString
    unsafe {
        let cmp = strcmp(s1.as_ptr(), s2.as_ptr());
        println!("strcmp(\"apple\", \"banana\") = {} (负数=小于)", cmp);

        let cmp = strcmp(s1.as_ptr(), s3.as_ptr());
        println!("strcmp(\"apple\", \"apple\") = {} (0=相等)", cmp);
    }

    // strlen
    let s = CString::new("Hello, World!").unwrap();
    // SAFETY: s.as_ptr() 有效
    let len = unsafe { strlen(s.as_ptr()) };
    println!("strlen = {}", len);

    // memset
    let mut buffer = [0u8; 16];
    // SAFETY: buffer 有效,16 不超过 buffer 大小
    unsafe {
        memset(buffer.as_mut_ptr() as *mut c_void, 0xFF, 16);
    }
    println!("memset 后: {:02X?}", buffer);

    // memcpy
    let src = [1u8, 2, 3, 4, 5];
    let mut dst = [0u8; 5];
    // SAFETY: src 和 dst 都有效,大小为 5,不重叠
    unsafe {
        memcpy(
            dst.as_mut_ptr() as *mut c_void,
            src.as_ptr() as *const c_void,
            5,
        );
    }
    println!("memcpy 后: {:?}", dst);
}

// ===== 第三步:链接 C 库 =====
// C 标准库(libc)在大多数平台上自动链接
// 其他库需要在 build.rs 中指定:
// println!("cargo:rustc-link-lib=库名");
// 或者在 extern 块上加 #[link(name = "库名")]

参数传递 ​

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

extern "C" {
    fn abs(n: c_int) -> c_int;
    fn strlen(s: *const c_char) -> usize;
    fn qsort(
        base: *mut c_void,     // 数组指针
        nmemb: usize,          // 元素数量
        size: usize,           // 每个元素的大小
        compar: extern "C" fn(*const c_void, *const c_void) -> c_int,  // 比较函数
    );
}

// qsort 的比较回调
extern "C" fn compare_ints(a: *const c_void, b: *const c_void) -> c_int {
    // SAFETY: qsort 传入的指针指向有效的 c_int
    let a = unsafe { *(a as *const c_int) };
    let b = unsafe { *(b as *const c_int) };
    a - b
}

fn main() {
    // === 值传递 ===
    // 基本类型直接传递
    // SAFETY: abs 接受任意 c_int
    let result = unsafe { abs(-100) };
    println!("值传递: abs(-100) = {}", result);

    // === 指针传递(不可变)===
    let s = CString::new("Rust FFI").unwrap();
    // SAFETY: s.as_ptr() 有效
    let len = unsafe { strlen(s.as_ptr()) };
    println!("指针传递: strlen = {}", len);

    // === 指针传递(可变)+ 回调 ===
    let mut data: Vec<c_int> = vec![5, 2, 8, 1, 9, 3, 7, 4, 6];
    println!("\n排序前: {:?}", data);

    // SAFETY: data 是连续的 c_int 数组,compare_ints 是正确的比较函数
    unsafe {
        qsort(
            data.as_mut_ptr() as *mut c_void,
            data.len(),
            std::mem::size_of::<c_int>(),
            compare_ints,
        );
    }
    println!("排序后: {:?}", data);

    // === 结构体指针传递 ===
    #[repr(C)]
    struct Point {
        x: f64,
        y: f64,
    }

    extern "C" fn point_distance(p: *const Point) -> f64 {
        if p.is_null() { return 0.0; }
        // SAFETY: 调用者保证 p 有效
        let p = unsafe { &*p };
        (p.x * p.x + p.y * p.y).sqrt()
    }

    let p = Point { x: 3.0, y: 4.0 };
    let dist = point_distance(&p as *const Point);
    println!("\n结构体指针: distance = {}", dist);
}
传递方式C 签名Rust 签名适用场景
值传递int f(int x)fn f(x: c_int) -> c_int基本类型
不可变指针int f(const int *p)fn f(p: *const c_int) -> c_int只读数据
可变指针void f(int *p)fn f(p: *mut c_int)修改数据/输出参数
回调函数void f(int (*cb)(int))fn f(cb: extern "C" fn(c_int) -> c_int)回调
void 指针void f(void *p)fn f(p: *mut c_void)泛型数据

安全封装模式 ​

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

extern "C" {
    fn abs(n: c_int) -> c_int;
    fn sqrt(x: c_double) -> c_double;
    fn strlen(s: *const c_char) -> usize;
    fn getenv(name: *const c_char) -> *const c_char;
}

// === 简单封装:直接转发 ===
pub fn safe_abs(n: i32) -> i32 {
    // SAFETY: abs 接受任意 c_int
    unsafe { abs(n as c_int) as i32 }
}

// === 计算封装:添加输入验证 ===
pub fn safe_sqrt(x: f64) -> Option<f64> {
    if x < 0.0 {
        return None;  // C 的 sqrt 对负数返回 NaN,我们返回 None
    }
    // SAFETY: x >= 0.0,sqrt 有效
    Some(unsafe { sqrt(x) })
}

// === 字符串封装:处理 CString 转换 ===
pub fn safe_strlen(s: &str) -> Option<usize> {
    let c_str = CString::new(s).ok()?;  // 包含 null 字节时返回 None
    // SAFETY: c_str.as_ptr() 有效
    Some(unsafe { strlen(c_str.as_ptr()) })
}

// === 可选值封装:处理 null 返回 ===
pub fn safe_getenv(name: &str) -> Option<String> {
    let c_name = CString::new(name).ok()?;
    // SAFETY: c_name.as_ptr() 有效
    let ptr = unsafe { getenv(c_name.as_ptr()) };
    if ptr.is_null() {
        return None;
    }
    // SAFETY: getenv 返回的非空指针是有效 C 字符串
    let c_str = unsafe { CStr::from_ptr(ptr) };
    Some(c_str.to_string_lossy().into_owned())
}

fn main() {
    // 所有封装函数都是安全的(不需要 unsafe)
    println!("abs(-42) = {}", safe_abs(-42));
    println!("sqrt(16.0) = {:?}", safe_sqrt(16.0));
    println!("sqrt(-1.0) = {:?}", safe_sqrt(-1.0));
    println!("strlen(\"hello\") = {:?}", safe_strlen("hello"));

    match safe_getenv("PATH") {
        Some(path) => {
            let preview: String = path.chars().take(60).collect();
            println!("PATH = {}...", preview);
        }
        None => println!("PATH 未设置"),
    }

    match safe_getenv("NOT_EXIST_VAR_XYZ") {
        Some(val) => println!("值: {}", val),
        None => println!("NOT_EXIST_VAR_XYZ 未设置"),
    }
}

基本示例 ​

完整展示调用 C 标准库函数的各种场景:

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

extern "C" {
    // 数学函数
    fn pow(base: c_double, exp: c_double) -> c_double;
    fn floor(x: c_double) -> c_double;
    fn ceil(x: c_double) -> c_double;
    fn fabs(x: c_double) -> c_double;

    // 字符串函数
    fn strlen(s: *const c_char) -> usize;
    fn strcmp(s1: *const c_char, s2: *const c_char) -> c_int;

    // 内存函数
    fn malloc(size: usize) -> *mut c_void;
    fn free(ptr: *mut c_void);
    fn memset(s: *mut c_void, c: c_int, n: usize) -> *mut c_void;
}

/// 安全的数学运算封装
mod math {
    use std::ffi::c_double;

    extern "C" {
        fn pow(base: c_double, exp: c_double) -> c_double;
        fn floor(x: c_double) -> c_double;
        fn ceil(x: c_double) -> c_double;
        fn fabs(x: c_double) -> c_double;
        fn sqrt(x: c_double) -> c_double;
    }

    pub fn power(base: f64, exp: f64) -> f64 {
        // SAFETY: pow 接受任意 double 值
        unsafe { pow(base, exp) }
    }

    pub fn round_down(x: f64) -> f64 {
        unsafe { floor(x) }
    }

    pub fn round_up(x: f64) -> f64 {
        unsafe { ceil(x) }
    }

    pub fn absolute(x: f64) -> f64 {
        unsafe { fabs(x) }
    }

    pub fn square_root(x: f64) -> Option<f64> {
        if x < 0.0 { return None; }
        Some(unsafe { sqrt(x) })
    }
}

/// 安全的 C 内存分配器封装
struct CBuffer {
    ptr: *mut u8,
    size: usize,
}

impl CBuffer {
    fn new(size: usize) -> Option<Self> {
        // SAFETY: malloc 分配 size 字节
        let ptr = unsafe { malloc(size) as *mut u8 };
        if ptr.is_null() {
            None
        } else {
            // SAFETY: ptr 有效,size 字节
            unsafe { memset(ptr as *mut c_void, 0, size); }
            Some(CBuffer { ptr, size })
        }
    }

    fn write(&mut self, offset: usize, data: &[u8]) -> bool {
        if offset + data.len() > self.size {
            return false;
        }
        // SAFETY: 已检查边界
        unsafe {
            std::ptr::copy_nonoverlapping(
                data.as_ptr(),
                self.ptr.add(offset),
                data.len(),
            );
        }
        true
    }

    fn read(&self, offset: usize, len: usize) -> Option<Vec<u8>> {
        if offset + len > self.size {
            return None;
        }
        let mut result = vec![0u8; len];
        // SAFETY: 已检查边界
        unsafe {
            std::ptr::copy_nonoverlapping(
                self.ptr.add(offset),
                result.as_mut_ptr(),
                len,
            );
        }
        Some(result)
    }

    fn size(&self) -> usize {
        self.size
    }
}

impl Drop for CBuffer {
    fn drop(&mut self) {
        // SAFETY: ptr 来自 malloc
        unsafe { free(self.ptr as *mut c_void); }
    }
}

fn main() {
    // 数学函数
    println!("=== C 数学函数 ===");
    println!("pow(2, 10) = {}", math::power(2.0, 10.0));
    println!("floor(3.7) = {}", math::round_down(3.7));
    println!("ceil(3.2) = {}", math::round_up(3.2));
    println!("fabs(-5.5) = {}", math::absolute(-5.5));
    println!("sqrt(49) = {:?}", math::square_root(49.0));
    println!("sqrt(-1) = {:?}", math::square_root(-1.0));

    // 字符串函数
    println!("\n=== C 字符串函数 ===");
    let s1 = CString::new("hello").unwrap();
    let s2 = CString::new("world").unwrap();
    let s3 = CString::new("hello").unwrap();

    // SAFETY: 所有 CString 指针有效
    unsafe {
        println!("strlen(\"hello\") = {}", strlen(s1.as_ptr()));
        println!("strcmp(hello, world) = {}", strcmp(s1.as_ptr(), s2.as_ptr()));
        println!("strcmp(hello, hello) = {}", strcmp(s1.as_ptr(), s3.as_ptr()));
    }

    // C 内存分配
    println!("\n=== C 内存分配 ===");
    if let Some(mut buf) = CBuffer::new(64) {
        println!("分配 {} 字节", buf.size());

        buf.write(0, b"Hello from C malloc!");
        let data = buf.read(0, 20).unwrap();
        println!("读取: {}", String::from_utf8_lossy(&data));

        buf.write(32, &[0xFF; 8]);
        let bytes = buf.read(32, 8).unwrap();
        println!("字节: {:02X?}", bytes);

        // 边界检查
        println!("越界写入: {}", buf.write(60, &[0; 10]));  // false
    }
    println!("CBuffer 已自动释放(Drop)");
}

常见问题 ​

问题一:C 函数签名写错了会怎样?

会导致未定义行为。比如参数类型或数量不匹配,调用时栈上的数据布局会错乱,可能崩溃、返回垃圾数据或者看起来"正常工作"但实际上破坏了内存。编译器无法检测这种错误。

问题二:C 函数返回的指针谁负责释放?

取决于 C 库的约定。有些函数(如 malloc)返回的指针需要用 free 释放;有些函数(如 getenv)返回的指针指向静态或全局数据,不需要释放。必须查阅 C 库的文档。

问题三:可以用 Rust 的 Box/Vec 来管理 C 分配的内存吗?

不行。Box 和 Vec 使用 Rust 的全局分配器(默认是系统分配器),而 C 的 malloc 可能使用不同的分配器。malloc 分配的内存必须用 free 释放,不能用 Rust 的 dealloc。

问题四:调用 C 函数时 Rust 的 panic 会怎样?

在 extern "C" 函数中 panic 是未定义行为。如果 Rust 代码可能 panic(如数组越界),必须用 catch_unwind 捕获 panic,防止它穿越 FFI 边界。

适用场景 ​

  • 使用系统库:操作系统 API、数学库、加密库
  • 复用 C 生态:SQLite、zlib、libcurl 等
  • 性能关键:某些算法的 C 实现已经高度优化
  • 渐进式迁移:C 项目中逐步引入 Rust 模块

注意事项 ​

  • 函数签名必须与 C 库完全匹配(类型、参数数量、调用约定)
  • 调用 C 函数必须在 unsafe 块中
  • 字符串传递使用 CString/CStr
  • C 分配的内存用 C 函数释放,Rust 分配的用 Rust 释放
  • 不要让 panic 穿越 FFI 边界
  • 注意 C 类型在不同平台上的大小差异

总结 ​

调用 C 函数的流程是:在 extern "C" 块中声明签名、在 unsafe 块中调用、构建时链接对应的库。调用需要 unsafe 是因为编译器无法验证签名正确性和参数有效性。字符串传递用 CString(Rust→C)和 CStr(C→Rust),结构体传递用 #[repr(C)]。实际项目中应将 C 函数调用封装在安全的 Rust 函数中,对外提供类型安全的接口。内存管理必须遵循"谁分配谁释放"的原则——C 分配的用 C 函数释放,不能混用。