no_mangle 属性 ​

核心概念 ​

#[no_mangle] 是一个编译器属性,用于阻止 Rust 编译器对函数名或静态变量名进行名称修饰(name mangling)。名称修饰是编译器为了支持泛型、模块系统和重载等特性,将源码中的标识符转换为包含额外信息的唯一符号名的过程。例如,一个名为 add 的函数可能被修饰为 _ZN8my_crate3add17h1a2b3c4d5e6f7g8hE 这样的名称。

C 语言没有名称修饰机制,C 代码通过原始函数名来查找和链接函数。如果 Rust 函数要被 C 代码调用,就必须用 #[no_mangle] 保持函数名不变,否则 C 代码的链接器找不到这个函数。#[no_mangle] 通常与 extern "C" 和 pub 一起使用。

rust
use std::ffi::c_int;

// 没有 #[no_mangle]:函数名会被修饰
// 编译后的符号名类似 _ZN7my_crate8mangled17h1234567890abcdefE
// C 代码无法找到这个函数
fn mangled_func() -> c_int {
    42
}

// 有 #[no_mangle]:函数名保持为 "unmangled_func"
// C 代码可以通过 "unmangled_func" 找到它
#[no_mangle]
pub extern "C" fn unmangled_func() -> c_int {
    42
}

fn main() {
    println!("mangled: {}", mangled_func());
    println!("unmangled: {}", unmangled_func());
}

名称修饰的原理 ​

rust
// Rust 的名称修饰包含以下信息:
// - crate 名称
// - 模块路径
// - 函数名
// - 类型参数(泛型)
// - 一个哈希值(防止冲突)

// 例如:
// 模块 my_crate::math::utils 中的 add 函数
// 可能被修饰为:_ZN8my_crate4math5utils3add17hABCDEF1234567890E

// 名称修饰的作用:
// 1. 区分同名但不同模块的函数
mod module_a {
    pub fn process() -> &'static str { "A" }
}

mod module_b {
    pub fn process() -> &'static str { "B" }
}

// 2. 区分泛型函数的不同实例化
fn generic_func<T: std::fmt::Debug>(x: T) {
    println!("{:?}", x);
}

// 3. 支持 trait 方法的多态
trait Greeting {
    fn hello(&self) -> &str;
}

struct English;
struct Chinese;

impl Greeting for English {
    fn hello(&self) -> &str { "Hello" }
}
impl Greeting for Chinese {
    fn hello(&self) -> &str { "你好" }
}

fn main() {
    // 同名函数,不同模块
    println!("{}", module_a::process());
    println!("{}", module_b::process());

    // 泛型的不同实例化
    generic_func(42_i32);     // 编译为 generic_func::<i32>
    generic_func("hello");    // 编译为 generic_func::<&str>

    // trait 方法
    let e = English;
    let c = Chinese;
    println!("{}", e.hello());
    println!("{}", c.hello());

    // 编译后,上述所有函数都有不同的修饰名
    // 即使源码中函数名相同
}

#[no_mangle] 的使用场景 ​

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

// === 场景1:暴露函数给 C 调用 ===
#[no_mangle]
pub extern "C" fn rust_add(a: c_int, b: c_int) -> c_int {
    a + b
}

// === 场景2:暴露静态变量给 C 访问 ===
#[no_mangle]
pub static RUST_VERSION: c_int = 2026;

// 对应 C 代码:extern int RUST_VERSION;

// === 场景3:动态库的入口点 ===
// 某些系统要求特定名称的入口函数
#[no_mangle]
pub extern "C" fn plugin_init() -> c_int {
    println!("插件初始化");
    0
}

#[no_mangle]
pub extern "C" fn plugin_cleanup() {
    println!("插件清理");
}

// === 场景4:与链接脚本配合 ===
// 嵌入式系统中,链接脚本可能引用特定名称的函数
// #[no_mangle]
// pub extern "C" fn _start() -> ! { loop {} }

// === 场景5:自定义 panic 处理器(no_std 环境)===
// #[no_mangle]
// pub extern "C" fn _panic_handler(info: &core::panic::PanicInfo) -> ! {
//     loop {}
// }

fn main() {
    println!("rust_add(3, 4) = {}", rust_add(3, 4));
    println!("RUST_VERSION = {}", RUST_VERSION);
    plugin_init();
    plugin_cleanup();
}

#[no_mangle] 与 #[export_name] ​

rust
use std::ffi::c_int;

// #[no_mangle] 保持原始函数名
#[no_mangle]
pub extern "C" fn original_name() -> c_int {
    1
}
// 导出符号名:original_name

// #[export_name] 可以指定自定义的导出名
#[export_name = "custom_symbol_name"]
pub extern "C" fn rust_internal_name() -> c_int {
    2
}
// 导出符号名:custom_symbol_name
// C 代码用 custom_symbol_name 调用,而非 rust_internal_name

// #[link_name] 用于 extern 块中,指定要链接的 C 符号名
extern "C" {
    // Rust 中叫 c_abs,实际链接 C 的 abs 函数
    #[link_name = "abs"]
    fn c_abs(n: c_int) -> c_int;
}

fn main() {
    println!("original_name() = {}", original_name());
    println!("rust_internal_name() = {}", rust_internal_name());

    // SAFETY: abs 是标准 C 库函数
    let result = unsafe { c_abs(-42) };
    println!("c_abs(-42) = {}", result);
}
属性位置作用
#[no_mangle]Rust 函数/变量保持原始名称不修饰
#[export_name = "name"]Rust 函数/变量指定自定义导出名
#[link_name = "name"]extern 块中的声明指定要链接的 C 符号名

注意事项和陷阱 ​

rust
use std::ffi::c_int;

// === 陷阱1:名称冲突 ===
// #[no_mangle] 的函数名是全局的
// 如果两个 crate 都有 #[no_mangle] fn init(),链接时会冲突
// 建议加前缀:my_lib_init

#[no_mangle]
pub extern "C" fn mylib_init() -> c_int {
    println!("mylib 初始化");
    0
}

// 不要这样(太容易冲突):
// #[no_mangle]
// pub extern "C" fn init() -> c_int { 0 }

// === 陷阱2:忘记 pub ===
// 没有 pub 的函数不会出现在库的导出表中
// C 代码链接时找不到
#[no_mangle]
extern "C" fn not_public() -> c_int {
    // 注意:没有 pub,某些链接器可能找不到
    42
}

// === 陷阱3:忘记 extern "C" ===
// 没有 extern "C" 使用 Rust 调用约定
// C 代码调用时参数传递方式不匹配,可能崩溃
#[no_mangle]
pub fn no_extern_c() -> c_int {
    // 危险:Rust 调用约定,C 代码调用可能崩溃
    42
}

// === 正确写法 ===
#[no_mangle]
pub extern "C" fn correct_func() -> c_int {
    42
}

// === 陷阱4:泛型函数不能用 #[no_mangle] ===
// 泛型函数会根据类型参数产生多个版本
// 无法用一个固定名称表示
// #[no_mangle]
// pub extern "C" fn generic<T>(x: T) -> T { x }  // 编译错误

fn main() {
    println!("mylib_init: {}", mylib_init());
    println!("correct_func: {}", correct_func());
}

基本示例 ​

用 #[no_mangle] 构建一个完整的 C 兼容库接口:

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

// ===== 库版本信息 =====
#[no_mangle]
pub static MATHLIB_VERSION_MAJOR: c_int = 1;

#[no_mangle]
pub static MATHLIB_VERSION_MINOR: c_int = 0;

#[no_mangle]
pub static MATHLIB_VERSION_PATCH: c_int = 0;

// ===== 数学函数 =====
#[no_mangle]
pub extern "C" fn mathlib_add(a: c_double, b: c_double) -> c_double {
    a + b
}

#[no_mangle]
pub extern "C" fn mathlib_multiply(a: c_double, b: c_double) -> c_double {
    a * b
}

#[no_mangle]
pub extern "C" fn mathlib_power(base: c_double, exp: c_int) -> c_double {
    if exp == 0 { return 1.0; }
    if exp < 0 {
        return 1.0 / mathlib_power(base, -exp);
    }

    let mut result = 1.0;
    for _ in 0..exp {
        result *= base;
    }
    result
}

#[no_mangle]
pub extern "C" fn mathlib_factorial(n: c_int) -> c_int {
    if n < 0 { return -1; }
    if n <= 1 { return 1; }

    let mut result: c_int = 1;
    for i in 2..=n {
        match result.checked_mul(i) {
            Some(r) => result = r,
            None => return -1,  // 溢出
        }
    }
    result
}

#[no_mangle]
pub extern "C" fn mathlib_gcd(mut a: c_int, mut b: c_int) -> c_int {
    a = a.abs();
    b = b.abs();
    while b != 0 {
        let t = b;
        b = a % b;
        a = t;
    }
    a
}

#[no_mangle]
pub extern "C" fn mathlib_is_prime(n: c_int) -> c_int {
    if n < 2 { return 0; }
    if n == 2 || n == 3 { return 1; }
    if n % 2 == 0 || n % 3 == 0 { return 0; }

    let mut i = 5;
    while i * i <= n {
        if n % i == 0 || n % (i + 2) == 0 {
            return 0;
        }
        i += 6;
    }
    1
}

// ===== 版本字符串 =====
#[no_mangle]
pub extern "C" fn mathlib_version_string() -> *const c_char {
    // 使用静态字符串,生命周期 'static
    static VERSION: &[u8] = b"mathlib 1.0.0\0";
    VERSION.as_ptr() as *const c_char
}

fn main() {
    println!("=== MathLib v{}.{}.{} ===",
        MATHLIB_VERSION_MAJOR, MATHLIB_VERSION_MINOR, MATHLIB_VERSION_PATCH);

    // 版本字符串
    let ver = mathlib_version_string();
    if !ver.is_null() {
        let s = unsafe { CStr::from_ptr(ver) };
        println!("{}", s.to_string_lossy());
    }

    // 基本运算
    println!("\n=== 基本运算 ===");
    println!("add(1.5, 2.5) = {}", mathlib_add(1.5, 2.5));
    println!("multiply(3.0, 4.0) = {}", mathlib_multiply(3.0, 4.0));
    println!("power(2.0, 10) = {}", mathlib_power(2.0, 10));
    println!("power(2.0, -3) = {}", mathlib_power(2.0, -3));

    // 阶乘
    println!("\n=== 阶乘 ===");
    for n in [0, 1, 5, 10, 13] {
        println!("factorial({}) = {}", n, mathlib_factorial(n));
    }

    // GCD
    println!("\n=== GCD ===");
    println!("gcd(12, 8) = {}", mathlib_gcd(12, 8));
    println!("gcd(100, 75) = {}", mathlib_gcd(100, 75));

    // 素数检查
    println!("\n=== 素数 ===");
    let primes: Vec<c_int> = (2..30)
        .filter(|&n| mathlib_is_prime(n) == 1)
        .collect();
    println!("2-29的素数: {:?}", primes);

    // 对应的 C 头文件:
    println!("\n对应的 C 头文件声明:");
    println!("  extern int MATHLIB_VERSION_MAJOR;");
    println!("  double mathlib_add(double a, double b);");
    println!("  int mathlib_factorial(int n);");
    println!("  const char* mathlib_version_string(void);");
    println!("  ...");
}

常见问题 ​

问题一:不加 #[no_mangle] 的函数名会变成什么?

Rust 会将函数名修饰为包含 crate 名、模块路径、函数名和哈希值的唯一符号。具体格式不稳定,可能随 Rust 版本变化。可以用 nm 或 objdump 工具查看编译后的符号名。

问题二:#[no_mangle] 会影响 Rust 内部的调用吗?

不会。在 Rust 代码中仍然用原始函数名调用,#[no_mangle] 只影响编译后的符号名。Rust 编译器知道如何找到正确的函数。

问题三:两个 crate 有同名的 #[no_mangle] 函数会怎样?

链接错误——链接器会报告符号重复定义。建议给 #[no_mangle] 函数加库名前缀(如 mylib_init)避免冲突。

问题四:#[no_mangle] 可以用在方法(impl 块中的函数)上吗?

可以,但通常不建议。方法隐含 self 参数,C 代码很难正确调用。如果需要,应该写一个独立的 extern "C" 包装函数,在内部调用方法。

适用场景 ​

  • FFI 导出:暴露 Rust 函数给 C/C++ 调用
  • 动态库:编写可被其他语言加载的 .so/.dll
  • 嵌入式:入口点函数(_start、中断处理器)
  • 插件系统:动态加载的插件入口

注意事项 ​

  • #[no_mangle] 通常与 extern "C" 和 pub 一起使用
  • 函数名全局唯一,建议加库名前缀避免冲突
  • 不能用于泛型函数
  • 静态变量也可以使用 #[no_mangle]
  • #[export_name] 可以自定义导出名称
  • #[link_name] 用于 extern 块中指定 C 符号名

总结 ​

#[no_mangle] 阻止 Rust 编译器对函数名进行修饰,使导出的符号名保持原始形式。这是将 Rust 函数暴露给 C 代码的必要条件——C 的链接器通过原始名称查找函数。#[no_mangle] 通常与 extern "C"(C 调用约定)和 pub(外部可见)一起使用。函数名在全局符号表中必须唯一,建议加库名前缀避免冲突。不能用于泛型函数。#[export_name] 提供自定义导出名的能力,#[link_name] 则用于在 extern 块中映射 C 符号名。静态变量也可以使用 #[no_mangle] 暴露给 C 代码。