Rust RFC 3641 解析:用 `[unsafe(export_ordinal(n))]` 为 Windows cdylib 指定导出函数序数
Rust RFC 3641 解析:用 #[unsafe(export_ordinal(n))] 为 Windows cdylib 指定导出函数序数
本篇文章以 Rust RFC 仓库中的 RFC 3641:export_function_ordinals 为骨架,深入讲解 Windows 动态链接库(DLL)中"导出函数序数(ordinal)"的概念、当前 .def 文件方案的痛点,以及该 RFC 提出的 #[unsafe(export_ordinal(n))] 属性设计。读者读完后,将理解序数导出的适用场景(如 Microsoft Detours 集成)、新属性与既有 link_ordinal / no_mangle / cdylib 机制的异同,以及该提案在语法约束、错误处理与开放问题上的完整设计考量。
为什么需要指定导出序数:一个真实场景
在 Windows 平台上,DLL 中导出的每个函数除了有符号名(symbol name),还有一个数字编号,即序数(ordinal)。绝大多数情况下,调用方通过函数名访问导出项,序数并不重要;但少数应用会按位置(序数)而不是按名称来调用 DLL 中的函数。
RFC 3641 给出了一个极具代表性的例子:为 Microsoft Detours 这类 Hook 库创建 DLL 时,DetourFinishHelperProcess 函数必须位于 Ordinal 1。这意味着序数不再是可有可无的细节,而是二进制 ABI 的一部分——一旦外部软件按固定序数调用,序数就被"钉死"了。
RFC 指出,Rust 生态当时只解决了"按序数导入"这一半问题:通过 #<a href="https://link.gitcode.com/i/6071779e0e96b1f1a66e3ceda03bc0eb" target="_blank">link_ordinal] 属性(由 [RFC 2627:raw-dylib 引入)可以声明从某个 DLL 按序数导入符号,却没有对应的"按序数导出"能力。
现状方案及其痛点:.def 文件 + build.rs
在 export_ordinal 属性出现之前,要在 Rust 中控制导出序数,只能手工编写模块定义文件(.def),并在 build.rs 中通过链接参数传给链接器:
; lib.def
LIBRARY
EXPORTS
DetourFinishHelperProcess @1
// build.rs
pub fn main() {
let lib_def = "path/to/lib.def";
println!("cargo:rustc-cdylib-link-arg=/DEF:{}", lib_def);
}
这个方案最大的弊端在 RFC 中被明确点出:一旦使用了 .def 文件,就必须把 DLL 中每一个想导出的函数都写进去并逐一指定序数,否则这些函数不会出现在生成的 .lib 导入库中。对于一个导出函数很多的库来说,这是一份极其繁琐且易出错的维护负担。
换句话说,开发者往往只需要"锁定"一两个关键函数的序数,其余函数完全可以交给工具链自动分配——但 .def 文件机制做不到这种"按需指定"的粒度。
提案核心:#[unsafe(export_ordinal(n))]
RFC 3641 的核心方案是引入一个新的、必须标记为 unsafe 的函数属性:
#[unsafe(export_ordinal(1))]
pub extern "C" fn hello() {
println!("Hello, World!");
}
当 crate 以 cdylib 形式编译并链接成 Windows DLL 时,上面的 hello 会被导出为 Ordinal 1——程序若通过序数 1 调用该 DLL 中的函数,实际执行的就是它。
属性可以与其他导出相关的属性组合使用,也可以用于 unsafe extern 函数:
#[no_mangle]
#[unsafe(export_ordinal(1))]
pub fn hello() {}
// Also works with extern and unsafe functions
#[no_mangle]
#[unsafe(export_ordinal(2))]
pub unsafe extern "C" fn world() {}
语法与约束(Reference-level)
RFC 对属性参数 n 给出了三条硬性约束:
- 必须是正整数,
n >= 1; - 必须在整个程序中唯一——若同一序数在多个地方重复指定,编译器应抛出错误;
- 只影响 Windows 目标——序数是 Windows DLL 的专属概念,其他平台上共享库没有序数机制,属性应被忽略(或报错)。
此外还有两条关键要求:
- 属性必须标记为 unsafe,即只能以
#[unsafe(export_ordinal(n))]的形式书写; - 必须置于被导出的函数之上,与
#[no_mangle]的放置方式一致。
行为语义:序数分配与变更风险
RFC 明确了两个重要行为:
- 如果某个导出函数没有
export_ordinal属性,编译器会在编译期间为其分配一个未占用的序数。这正是该方案相对.def文件的优势:只需要"钉"住关键序数,其余导出项交给编译器自动编排。 - 如果外部软件依赖你的函数位于特定序数,那么修改或删除
export_ordinal属性需要极度谨慎——这可能导致调用方调用到错误的函数,甚至根本找不到该函数。这是 ABI 层面的契约,改变它等同于破坏二进制兼容性。
设计对齐:与 link_ordinal 的对称性
RFC 3641 在语法上刻意与既有的 link_ordinal 保持对称。在 RFC 2627 中,#[link_ordinal(116)] 用于在 kind="raw-dylib" 的 extern 块中按序数导入符号:
#[cfg(windows)]
#[link(name = "ws2_32.dll", kind = "raw-dylib")]
#[allow(non_snake_case)]
extern "system" {
#[link_ordinal(116)]
fn WSACleanup() -> i32;
}
link_ordinal 解决的是"导入侧按序数寻址",export_ordinal 解决的是"导出侧按序数编号",二者一进一出,正好补齐了 Windows 序数机制在 Rust 中的两端。RFC 3641 明确写道:这一设计"与已在使用中的 link_ordinal 语法保持一致",从而降低了语言设计师和用户双方的学习成本。
值得注意的差异是:link_ordinal 出现在 extern 块内部的函数声明上,而 export_ordinal 出现在函数定义上;前者是声明属性,后者是定义属性,作用对象天然不同。
为什么必须是 unsafe:与 export_name / no_mangle 同源的风险
RFC 3641 特别强调属性必须标记为 unsafe,理由是它与 export_name 共享同类的安全性顾虑,而 export_name 自 Rust 2024 Edition 起已成为 unsafe 属性。
这一机制在仓库中的 RFC 3325:unsafe_attributes 有完整论述。该 RFC 指出,no_mangle、export_name 等属性可以在没有任何 unsafe 块的情况下引发未定义行为(UB)——例如把函数导出为 write 这样的全局名字,可能与 POSIX 同名函数冲突,导致其他代码误调用、参数错配。因此 Rust 引入了 #[unsafe(...)] 包裹语法,要求开发者显式承认使用这类属性带来的风险。
// SAFETY: there is no other global function of this name
#[unsafe(no_mangle)]
pub fn my_own_write(...) { ... }
RFC 3834:export_visibility 进一步佐证了这一风险模型:#[no_mangle] 与 #[export_name] 默认以公开可见性导出符号,命名冲突可能导致 UB。export_ordinal 的风险与此同构——指定一个错误的序数,等于把错误的函数暴露给按序数寻址的调用方,属于全局符号命名空间层面的 ABI 风险,所以必须用 unsafe(...) 显式声明。
注:根据 RFC 3325 的规则,未来新增的 unsafe 属性可以从诞生之初就硬性要求
unsafe(...)包裹,而不必像no_mangle那样经历向后兼容的 lint 过渡期——export_ordinal正是这一规则的适用对象。
适用语境:cdylib 与符号可见性
export_ordinal 的作用对象是 cdylib 中导出的函数。要准确理解这一点,需要回到 RFC 1510:cdylib 定义的符号可见性规则:
- rdylib(Rust 动态库):像 rlib 一样暴露全部符号;
- cdylib(C 接口动态库):像可执行文件一样只导出特定符号——普通
pub fn foo() {}不会成为导出符号,而#[no_mangle] pub extern fn foo() {}会成为导出符号。
也就是说,cdylib 是 Rust 向其他语言/宿主程序暴露 C ABI 的载体,也是序数导出真正有意义的场景。RFC 3641 中所有示例都隐含这一前提:被指定序数的函数必须同时是实际被导出的符号(通常配合 #<a href="https://link.gitcode.com/i/4792a81a66af32b0e63154be51dba5ff" target="_blank">no_mangle] 或 extern "C" 使用)。[RFC 1717:dllimport 中关于 Windows 链接模型的讨论(dllimport 存储类、#[link(kind="dylib")] 语义)也为此提供了底层背景。
备选方案对比
RFC 3641 在 Rationale 章节中系统对比了几种替代路线:
| 方案 | 主要问题 |
|---|---|
什么都不做,继续用 .def 文件 + cargo:rustc-cdylib-link-arg=/DEF |
只要需要锁定一个序数,就必须把所有导出函数都写进 .def,否则无法链接到导入库;维护成本随导出函数数量线性上升 |
用宏生成 .def 文件 |
一个好的实现很可能需要状态宏(stateful macros),复杂度不亚于直接在语言层解决 |
实现"部分 .def 文件",即允许 .def 未列出的函数保持导出 |
是一个不错的替代方向,但实现可能比属性方案更复杂 |
RFC 的结论是:属性方案让"指定序数"的流程显著简化,同时与既有 link_ordinal 语法保持一致。这也是整个提案的核心设计取舍。
尚未解决的问题(Unresolved questions)
RFC 3641 作者在提案中坦诚列出了一组开放问题,这些细节需要在语言团队讨论和实现阶段敲定:
- 序数能否跳号? 如果指定了序数
1, 3, 4,中间跳过了2,是否应该报错? - 自动分配策略:如果指定了序数
1和3,另有导出函数未指定序数,编译器应为其分配2(下一个未占用序数)还是4(序列中的下一个)? - 替代路线再审视:能否通过修改
.def文件的使用方式,让未列入.def的导出函数继续保持导出状态?
这三个问题直接决定了编译器序数分配算法的行为,也会影响用户对"自动分配序数是否稳定"的预期。
实施与展望
RFC 3641 于 2024-05-19 提出(RFC PR rust-lang/rfcs#3641,Rust Issue rust-lang/rust#154022),属于语言层的属性新增提案,需要经过 RFC 评审、实现与跟踪流程。从仓库现状看,RFC 3641 的文档完整记录了设计意图与约束,而与之配套的 link_ordinal(RFC 2627)、cdylib(RFC 1510)、unsafe 属性机制(RFC 3325)均已在 Rust 中落地,为 export_ordinal 提供了成熟的语法先例与风险管控模型。
对于正在为 Windows 构建 cdylib、且需要与 Detours 等按序数寻址的宿主程序集成的开发者,本文梳理的 #[unsafe(export_ordinal(n))] 设计就是未来可以直接使用的解决方案蓝图;在属性正式稳定前,lib.def + build.rs 仍是可行的临时替代手段,但其"全量列名"的维护负担需要提前规划。
延伸阅读(仓库内相关文档)
- RFC 3641 原文:export_function_ordinals:本提案的完整文本,含动机、参考级设计与开放问题。
- RFC 2627:raw-dylib-kind:
link_ordinal与raw-dylib的原始设计,含 idata 段映射规则与错误约束。 - RFC 1510:cdylib:cdylib crate 类型的符号可见性、LTO 与静态链接语义。
- RFC 3325:unsafe-attributes:
#[unsafe(...)]包裹语法的完整规范与 lint 策略。 - RFC 3834:export-visibility:
no_mangle/export_name的导出可见性与 UB 风险讨论。 - README.md:Rust RFC 流程总览,了解提案从提交、FCP 到跟踪实现的完整生命周期。