调用 C 函数
核心概念
从 Rust 调用 C 函数是 FFI 最常见的使用方向。流程分三步:首先在 extern "C" 块中声明 C 函数的签名,然后在 unsafe 块中调用这些函数,最后在构建时链接对应的 C 库。调用 C 函数之所以需要 unsafe,是因为 Rust 编译器无法验证外部函数的签名正确性、参数有效性和内存安全性——这些全部由程序员负责保证。
实际项目中,通常会将 unsafe 的 C 函数调用封装在安全的 Rust 函数中,对外提供类型安全、内存安全的接口。很多流行的 C 库(如 OpenSSL、SQLite)都有对应的 Rust 封装 crate(如 openssl、rusqlite),它们的内部就是通过 FFI 调用 C 函数实现的。
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);
}
}调用流程
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 = "库名")]参数传递
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) | 泛型数据 |
安全封装模式
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 标准库函数的各种场景:
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 函数释放,不能混用。