前面九篇都在安全 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 在向编译器承诺什么。

安全 API 层:byte_sum(&[u8]),调用方不需要写 unsafe
unsafe 封装层:sum_raw(ptr, len),承诺指针和长度有效
C 库层: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 是否匹配。文档列出的前提,少一条都是未定义行为:

  1. ptr 非空,并且按 T 的对齐要求对齐。
  2. ptr 指向一块连续内存,至少能读 len 个 T,不能越界。
  3. 这块内存在返回的切片生命周期内一直有效,不能被释放或移动。
  4. len * size_of::<T>() 不能超过 isize::MAX,否则长度计算会溢出。
  5. 返回的切片期间,不能有别的代码同时修改这块内存(除非通过合法的同步机制)。
  6. 如果 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。

当天可以自己验证的练习:

  1. 把这篇的完整示例敲一遍,确认输出 C strlen = 9 和 sum = 294;再把 "hello ffi" 改成 "你好",观察 strlen 数的是字节数还是字符数。
  2. 故意把 byte_sum 改成传 bytes.as_ptr() 和一个比实际长度大的数字,看程序是崩溃还是读到垃圾值;想清楚为什么编译器不会拦。
  3. 把 let v = *p; 直接写在安全函数里,读一遍 E0133,然后加 unsafe 块和 SAFETY 注释,说明指针的有效期。
  4. 用 CString::new("a\0b") 构造一个内部含 \0 的字符串,观察 unwrap 的 panic,再改成正确处理 Err。
  5. 写一个 #[repr(C)] 结构体和一个同布局的 Rust 结构体,用 std::mem::size_of 检查大小;再故意改字段顺序,观察大小和对齐是否变化。

下一篇是这一组的收尾:从零写一个小工具:把前面串起来。所有权、错误处理、集合、模块、并发、unsafe,这些知识点单独看都懂,真正写一个能用的命令行工具时才会发现它们互相牵制:解析参数要不要引入依赖、读文件出错怎么把上下文带出去、统计结果怎么排序输出、哪些地方需要并行、什么时候该用 unsafe。下一篇不引入新概念,只把前十篇拼成一个能跑的完整项目。