前面九篇都在安全 Rust 里打转:所有权、借用、迭代器、线程,编译器替你守着每一条规则。但有一类需求它守不住——你要调用一个已经存在的 C 库,或者对接一段由 C 写成的采集代码。对方不会给你 Rust 的引用,只给一个指针加一个长度;它也不知道 Rust 的 String 是什么,只认以 \0 结尾的字节数组。
这时就要用 unsafe 和 FFI(Foreign Function Interface,外部函数接口)。很多教程把 unsafe 讲成「关掉编译器检查,后果自负」,这不准确。它其实只放开五项特定能力,其余检查照旧。真正危险的不是 unsafe 这个词,而是你不清楚自己在向编译器承诺什么。
这篇用一个真实的对接场景走完:调用系统的 strlen,再把一段 C 风格的 (指针, 长度) 缓冲区安全地转成 Rust 切片并求和。示例在 Windows + MSVC 工具链、Rust 2021 edition、当前 stable 下实际编译运行过;strlen 走的是系统 C 运行库。
场景走查:把 C 的缓冲区接进 Rust
需求:我们的日志工具要从一个 C 写的采集模块拿数据。它给两样东西:一个指向字节缓冲区的指针,一个表示长度的整数。Rust 侧要算出这段数据的字节和;另外用一个 C 字符串验证对方传过来的消息长度,用系统自带的 strlen,不自己造轮子。
完整代码:
use std::ffi::CString;
use std::os::raw::c_char;
extern "C" {
fn strlen(s: *const c_char) -> usize;
}
fn byte_sum(bytes: &[u8]) -> u32 {
let ptr = bytes.as_ptr();
let len = bytes.len();
// SAFETY: ptr 来自有效切片,len 与切片长度一致,调用期间切片存活
unsafe { sum_raw(ptr, len) }
}
unsafe fn sum_raw(ptr: *const u8, len: usize) -> u32 {
let slice = std::slice::from_raw_parts(ptr, len);
slice.iter().map(|&b| b as u32).sum()
}
fn main() {
let text = CString::new("hello ffi").unwrap();
let len = unsafe { strlen(text.as_ptr()) };
println!("C strlen = {len}");
let sum = byte_sum(b"abc");
println!("sum = {sum}");
}
rustc --edition 2021 main.rs 编译后运行,实测输出:
C strlen = 9
sum = 294
strlen 数出 "hello ffi" 是 9 个字节,对得上。"abc" 的字节和是 97 + 98 + 99 = 294,也对。程序能跑,但真正要讲的是每一处 unsafe 在向编译器承诺什么。
byte_sum(&[u8]),调用方不需要写 unsafesum_raw(ptr, len),承诺指针和长度有效strlen,由系统 C 运行库提供这三层的分法就是本文的主线:C 库那一层我们管不了,但可以在中间加一层薄薄的 unsafe 封装,把「承诺」集中写在一处;最外层只暴露安全函数。这样全项目需要人工检查的地方就只剩几行,而不是散落各处。
unsafe 到底允许了什么
unsafe 不是一个「关闭检查」的开关,它精确地放开五件事:
| 能力 | 为什么必须 unsafe | 例子 |
|---|---|---|
| 解引用裸指针 | 指针可能为空、悬垂、未对齐,编译器无法验证 | *const T / *mut T 的读写 |
调用 unsafe fn | 函数文档里写着「调用者必须满足某些前提」 | slice::from_raw_parts |
| 访问或修改可变静态变量 | 全局可变状态没有借用检查,可能数据竞争 | static mut COUNTER |
实现 unsafe trait | 实现者要保证类型真的满足 trait 的语义承诺 | unsafe impl Send for T |
访问 union 字段 | 编译器不知道当前哪个字段是有效的 | 与 C 的 union 对接 |
除此之外,借用检查、类型检查、生命周期检查在 unsafe 块里全部照常执行。写 unsafe { let x = String::from("a"); let y = x; println!("{x}"); } 一样会报 borrow of moved value。unsafe 只对上面五类操作开口子,这是它和 C 最大的区别:C 是默认什么都不查,Rust 是默认全查,只在这五处让位。
第一次接触时容易把 unsafe 当成「性能开关」,这也是误解。安全 Rust 的边界检查、所有权检查大多在编译期完成,运行时开销很小;unsafe 省下的通常是编译器优化受限的那部分,而不是「检查本身」。为了微优化把整段逻辑包进 unsafe,收益通常远小于引入的风险。
裸指针有效的前提
std::slice::from_raw_parts(ptr, len) 是 FFI 里最常用的转换,它把一个指针和一个长度拼成一个 &[T]。这个函数是 unsafe 的,因为编译器无法验证 ptr 和 len 是否匹配。文档列出的前提,少一条都是未定义行为:
ptr非空,并且按T的对齐要求对齐。ptr指向一块连续内存,至少能读len个T,不能越界。- 这块内存在返回的切片生命周期内一直有效,不能被释放或移动。
len * size_of::<T>()不能超过isize::MAX,否则长度计算会溢出。- 返回的切片期间,不能有别的代码同时修改这块内存(除非通过合法的同步机制)。
- 如果
len是 0,指针仍必须非空且对齐;空切片也不能传空指针。
这些条件听起来抽象,翻译成事故就是:读到别人的内存、读到已经释放的内存、两个线程同时改同一块缓冲区。C 侧最常见的错误是「长度传错」——指针没问题,len 多传了一位,于是切片越界。Rust 侧一旦构造出这个切片,后面所有「安全」代码都建立在一个错误前提上,越界读不会 panic,只会读到垃圾数据,或者直接段错误。
unsafe 块里的代码不会因为「在 unsafe 里」就变得正确。它只是把「编译器证明」换成了「你证明」。如果你的证明错了,后果是未定义行为,可能当场崩溃,也可能静默返回错误结果,还可能在某次升级编译器之后才暴露。所以写 unsafe 时的标准动作是:先用一句话写出「为什么这里安全」,再写代码。Rust 社区管这叫 SAFETY 注释,通常是 // SAFETY: ...。它有三个作用:逼你自己检查一遍、让 reviewer 知道你的依据、让以后改代码的人知道哪条前提被破坏了。示例里 byte_sum 那行注释就是干这个的。
安全封装:把 unsafe 关进小盒子
示例的写法值得单独讲。真正的 unsafe fn sum_raw 暴露的是「给我一个指针和长度」,这对调用方很不友好——每个调用方都要自己保证指针有效,等于把风险复制了多份。更好的做法是像 byte_sum 那样,在外面包一层安全函数:
fn byte_sum(bytes: &[u8]) -> u32 {
let ptr = bytes.as_ptr();
let len = bytes.len();
// SAFETY: ptr 来自有效切片,len 与切片长度一致,调用期间切片存活
unsafe { sum_raw(ptr, len) }
}
安全函数的参数是 &[u8],一个正常的安全引用。指针和长度都从同一个切片里取出来,天然匹配;切片的生命周期覆盖整个调用,所以内存不会在求和途中被释放。调用方完全不需要知道里面有 unsafe,这就是「安全抽象」:把不安全操作封装在一个小函数里,对外只暴露满足所有前提的接口。
这个模式可以推广到所有 FFI 对接。C 给你一个 *const c_char,你在安全函数里用 CStr::from_ptr 包一下,检查空指针,再转成 &str 返回;C 给你一个回调,你在 Rust 侧注册一个 extern "C" fn,内部用 catch_unwind 兜住 panic。原则是:unsafe 的数量越少越好,每一处都有 SAFETY 注释,安全边界尽量靠近 C 接口,不要让它渗进业务逻辑。
还有一个细节:unsafe fn 的函数体在 2021 edition 里被视为隐式的 unsafe 块,所以 sum_raw 里调用 from_raw_parts 不用再套一层。但官方 lint unsafe_op_in_unsafe_fn 建议即使在 unsafe fn 里也显式写 unsafe { },并在 2024 edition 成为默认要求。如果你打算以后升级 edition,提前养成这个习惯会省事。
FFI:ABI、字符串与内存归属
extern "C" { fn strlen(...); } 这行代码声明了一个外部函数,"C" 是 ABI(应用二进制接口)的名字。ABI 规定参数怎么传、返回值放在哪、谁负责清理栈。Rust 默认的 ABI 没有稳定承诺,C 库也不认识;跨语言调用必须显式指定 "C",让双方按同一套约定沟通。
类型要对上。C 的 size_t 对应 Rust 的 usize,int 对应 c_int(通常是 i32,但不要假设),char 对应 c_char(可能是 i8 或 u8,取决于平台)。结构体跨边界时还要考虑字段顺序、对齐和填充,不能直接拿 Rust 的 repr(Rust) 结构体去对应,要加 #[repr(C)]。这些错配不会在编译期报错,只会在运行时表现为乱码、截断或崩溃,所以宁可多查文档。
字符串是重灾区。Rust 的 String/&str 不保证以 \0 结尾,长度单独存;C 的字符串没有长度,靠结尾的 \0 判断。两边直接传,轻则截断,重则越界读。CString 负责把 Rust 字符串转成「以 \0 结尾、堆上分配」的形式:
let text = CString::new("hello ffi").unwrap();
let len = unsafe { strlen(text.as_ptr()) };
CString::new 返回 Result,因为如果字符串内部本来就有 \0,C 侧会在那里提前截断,语义就错了。unwrap 在这里合理,因为字面量里没有 \0;处理外部输入时必须显式处理这个错误。反过来,从 C 拿到 *const c_char,用 CStr::from_ptr 借用,再 to_str 检查 UTF-8,不要直接 transmute 成 &str。
比字符串更容易出事的是内存归属。C 分配的内存必须用 C 的释放函数还回去,Rust 的 Box/Vec 不能去 drop 一个 malloc 出来的指针;反过来,C 也不能 free 一块 Rust 分配的内存。跨边界传递所有权时,双方必须约定「谁分配、谁释放、用什么函数释放」,并且写进文档。Box::into_raw 和 Box::from_raw 是 Rust 侧交接所有权的标准工具,into_raw 之后那块内存就不再由 Rust 管理,必须恰好 from_raw 一次。
还有 panic。Rust 的 panic 默认沿着调用栈展开,但 C 代码不知道什么是 Rust 的展开机制,让它穿过 FFI 边界是未定义行为。正确做法是在 extern "C" fn 里用 std::panic::catch_unwind 把 panic 拦住,转成错误码返回给 C;或者干脆保证这个函数里不 panic。新版 Rust 对 extern "C" 函数里逃逸的 panic 有运行时保护,但依赖这个保护不如自己写清楚。
最后一点是 edition 差异。2021 edition 允许直接写 extern "C" { ... };2024 edition 要求写成 unsafe extern "C" { ... },因为声明一个外部函数本身就是一种「我保证符号存在、签名正确」的承诺。这篇按 2021 讲,你在 2024 项目里看到 unsafe extern 不必奇怪,含义是一样的。
真实报错怎么读
安全 Rust 里解引用裸指针,编译器会直接拦:
error[E0133]: dereference of raw pointer is unsafe and requires
unsafe function or block
--> t10raw.rs:4:13
|
4 | let v = *p;
| ^^ dereference of raw pointer
|
= note: raw pointers may be null, dangling or unaligned; they can
violate aliasing rules and cause data races: all of these are
undefined behavior
人话版:裸指针可能是空、可能指向已经释放的内存、可能没对齐,编译器没法证明它有效,所以不让你直接读。note 那句几乎把未定义行为的清单列全了。修法不是「随便加个 unsafe」,而是先确认指针从哪来、有效期多长,再在 unsafe 块里解引用并写 SAFETY 注释。
调用 unsafe fn 同理:
error[E0133]: call to unsafe function `read` is unsafe and requires
unsafe function or block
--> t10unsafe.rs:7:13
|
7 | let v = read(&x);
| ^^^^^^^^ call to unsafe function
|
= note: consult the function's documentation for information on
how to avoid undefined behavior
这条报错的重点在 consult the function's documentation:unsafe fn 的文档里一定写了调用前提,编译器提醒你去读。加 unsafe 块只是语法动作,真正的工作是确认那些前提成立。如果函数不是你写的,别跳过文档直接包一层就完事。
类型转换也有专门的报错。比如用 transmute 把 u8 转成 u32:
error[E0512]: cannot transmute between types of different sizes,
or dependently-sized types
--> t10trans.rs:3:20
|
3 | let big: u32 = std::mem::transmute(small);
| ^^^^^^^^^^^^^^^^^^^
|
= note: source type: `u8` (8 bits)
= note: target type: `u32` (32 bits)
人话版:transmute 要求源类型和目标类型大小完全一致,它做的是「按位重新解释」,不是数值转换。8 位变 32 位应该用 u32::from(small) 或 as,不是 transmute。transmute 在 FFI 里偶尔用于同布局的结构体转换,但风险很高,能用 #[repr(C)] 加字段对应解决就别用它。
现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
dereference of raw pointer is unsafe(E0133) | 裸指针的有效性编译器无法证明 | 确认指针来源、是否为空、生命周期是否覆盖解引用 |
call to unsafe function ... is unsafe(E0133) | unsafe fn 的调用前提需要调用方保证 | 读函数文档的安全要求,逐条核对后再包 unsafe |
程序立刻退出,错误码 0xC0000005(Windows 访问冲突) | 空指针、悬垂指针、越界读,或 C/Rust 结构体布局不一致 | 打印指针地址和长度;核对 ABI 类型与 #[repr(C)] |
| FFI 返回的字符串乱码、被截断 | 用了 String 直传、缺少 \0,或宽窄字符类型不匹配 | 改用 CString/CStr,确认编码和 c_char 宽度 |
| 内存持续增长,进程被 OOM 杀掉 | 所有权约定不清,C 分配的内存没有用 C 的释放函数还回去 | 查每个跨边界指针的分配方与释放方,写出配对规则 |
| 堆损坏、double free,崩溃位置随机 | 同一块内存被两边释放,或 from_raw 调用了不止一次 | 搜所有 into_raw/from_raw,确保成对且只一次 |
| FFI 调用后进程直接 abort,没有正常 panic 信息 | panic 穿过 extern "C" 边界,跨语言展开没有约定 | 在边界函数里 catch_unwind,转成错误码返回 |
| 同一段 unsafe 代码,某次优化后结果突然错 | 违反了别名规则或数据竞争,属于未定义行为,优化器可以任意处理 | 用 Miri 查纯 Rust 部分;FFI 侧检查同步与生命周期 |
cannot transmute between types of different sizes(E0512) | transmute 要求大小完全一致,不是数值转换 | 换成 as/From;结构体转换检查布局 |
边界与代价
第一层代价是安全责任的转移。安全 Rust 里,编译器是合伙人,出问题它能指出哪条规则被违反;unsafe 里,你是唯一责任人。一个悬垂指针造成的崩溃可能发生在几百行之外,堆栈指向的地方和真正的错误无关。这不是 Rust 的缺陷,而是所有系统语言的共同现实——C 一直如此,Rust 只是把「这段代码需要人工证明」标了出来。
第二层是工具链的局限。Miri 能在解释执行时发现不少未定义行为,比如越界、悬垂、别名冲突,但它对真实 FFI 调用支持有限,遇到 C 函数通常直接报「不支持」。也就是说,跨语言那一侧的正确性,工具帮不上太多忙,只能靠文档、测试和代码审查。可以做的补充是:给 C 接口写对接测试、用 AddressSanitizer 跑 C 侧、把 unsafe 集中到少数文件并加 #![deny(unsafe_op_in_unsafe_fn)]。
第三层是可移植性。c_char 的符号性、c_int 的宽度、结构体对齐、调用约定,都跟平台和编译器有关。在 Linux x86_64 上跑通的 FFI,换到 Windows MSVC 或 ARM 上可能需要调整。#[repr(C)]、std::os::raw 的别名类型是为了减少这类问题,但没法完全消除。涉及多平台时,CI 里至少要跑一遍目标平台的最小调用测试。
第四层是性能预期。FFI 调用本身有开销:跨语言边界、可能的栈切换、不能内联。把一个小函数包成 FFI 再在循环里调用,可能比纯 Rust 慢一个数量级。正确做法是批量传数据、一次调用处理一大块,而不是每字节过一趟边界。反过来,把整个热循环搬进 C 也不一定更快——跨边界的数据转换和内存管理成本经常被低估。
最后是「unsafe 会传染」。一个 unsafe fn 被安全函数调用,安全函数就继承了它的前提;如果这个安全函数又公开出去,调用方以为自己用的是安全 API,实际上依赖的是一个没写进文档的隐含条件。防止传染的办法是把前提写进类型:用 &[u8] 代替 (*const u8, usize),用 CString 代替裸的 *const c_char,让「有效」这件事由类型来保证,而不是靠口头约定。
小结
unsafe 只放开五件事:解引用裸指针、调用 unsafe fn、访问可变静态、实现 unsafe trait、访问 union 字段;其余检查照旧。每处 unsafe 都要有一句 SAFETY 注释,说明为什么这里满足前提。
FFI 的关键是三件事:ABI 对齐(extern "C"、c_int/c_char、#[repr(C)])、字符串约定(CString/CStr、\0 结尾)、内存归属(谁分配谁释放,into_raw/from_raw 恰好成对)。把 unsafe 封装在靠近边界的小函数里,对外只暴露安全 API。
当天可以自己验证的练习:
- 把这篇的完整示例敲一遍,确认输出
C strlen = 9和sum = 294;再把"hello ffi"改成"你好",观察strlen数的是字节数还是字符数。 - 故意把
byte_sum改成传bytes.as_ptr()和一个比实际长度大的数字,看程序是崩溃还是读到垃圾值;想清楚为什么编译器不会拦。 - 把
let v = *p;直接写在安全函数里,读一遍 E0133,然后加unsafe块和 SAFETY 注释,说明指针的有效期。 - 用
CString::new("a\0b")构造一个内部含\0的字符串,观察unwrap的 panic,再改成正确处理Err。 - 写一个
#[repr(C)]结构体和一个同布局的 Rust 结构体,用std::mem::size_of检查大小;再故意改字段顺序,观察大小和对齐是否变化。
下一篇是这一组的收尾:从零写一个小工具:把前面串起来。所有权、错误处理、集合、模块、并发、unsafe,这些知识点单独看都懂,真正写一个能用的命令行工具时才会发现它们互相牵制:解析参数要不要引入依赖、读文件出错怎么把上下文带出去、统计结果怎么排序输出、哪些地方需要并行、什么时候该用 unsafe。下一篇不引入新概念,只把前十篇拼成一个能跑的完整项目。