extern "C" 声明 ​

核心概念 ​

extern "C" 是 Rust 中用于指定 C 调用约定(calling convention)的关键语法。调用约定决定了函数参数如何传递(通过寄存器还是栈)、返回值如何处理、栈由谁清理等底层细节。不同语言和平台有不同的调用约定,extern "C" 告诉 Rust 编译器使用 C 语言的标准调用约定,这是跨语言互操作最常用的约定。

extern "C" 在两个方向上使用:在 extern "C" { } 块中声明要调用的外部 C 函数;在 Rust 函数签名前加 extern "C" 使其可以被 C 代码调用。

rust
use std::ffi::c_int;

// === 方向1:声明外部 C 函数 ===
extern "C" {
    fn abs(n: c_int) -> c_int;
}

// === 方向2:Rust 函数暴露给 C ===
#[no_mangle]
pub extern "C" fn rust_multiply(a: c_int, b: c_int) -> c_int {
    a * b
}

fn main() {
    // 调用外部 C 函数
    // SAFETY: abs 接受任意 c_int
    let result = unsafe { abs(-10) };
    println!("abs(-10) = {}", result);

    // 直接调用 extern "C" 的 Rust 函数(不需要 unsafe)
    let product = rust_multiply(6, 7);
    println!("rust_multiply(6, 7) = {}", product);
}

调用约定 ​

rust
// Rust 支持多种调用约定,通过 extern "ABI" 指定

// "C" - C 语言标准调用约定(最常用)
extern "C" fn c_convention(x: i32) -> i32 { x + 1 }

// "Rust" - Rust 默认调用约定(不写 extern 时的默认值)
// Rust 的调用约定不稳定,不保证跨版本兼容
fn rust_convention(x: i32) -> i32 { x + 1 }

// "system" - 系统调用约定
// Windows 上等于 "stdcall",其他平台等于 "C"
// 用于调用 Windows API
extern "system" fn system_convention(x: i32) -> i32 { x + 1 }

// "stdcall" - Windows 标准调用约定
// 主要用于 Windows API(如 WinAPI)
// extern "stdcall" fn stdcall_convention(x: i32) -> i32 { x + 1 }

fn main() {
    println!("C:      {}", c_convention(10));
    println!("Rust:   {}", rust_convention(10));
    println!("system: {}", system_convention(10));

    // 函数指针类型也包含调用约定
    let fp: extern "C" fn(i32) -> i32 = c_convention;
    println!("函数指针: {}", fp(20));
}
调用约定语法用途
extern "C"C 标准FFI 通用,跨语言互操作
extern "Rust"Rust 默认Rust 内部(不稳定)
extern "system"系统Windows API 调用
extern "stdcall"WindowsWin32 API
extern "cdecl"C 声明与 extern "C" 类似

extern "C" 块的详细用法 ​

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

// extern "C" 块中可以声明多个函数
extern "C" {
    // 函数声明(不需要函数体)
    fn abs(n: c_int) -> c_int;
    fn sqrt(x: c_double) -> c_double;

    // 可以声明全局变量
    // static errno: c_int;  // C 的全局错误码

    // 可以用 #[link_name] 指定 C 中的实际符号名
    // 当 Rust 名称和 C 符号名不同时使用
    #[link_name = "strlen"]
    fn c_strlen(s: *const c_char) -> usize;
}

// 可以用 #[link] 指定要链接的库
// #[link(name = "m")]  // 链接 libm(数学库)
// extern "C" {
//     fn sin(x: c_double) -> c_double;
//     fn cos(x: c_double) -> c_double;
// }

// 可以有多个 extern "C" 块
extern "C" {
    fn malloc(size: usize) -> *mut c_void;
    fn free(ptr: *mut c_void);
}

// 可变参数函数(如 printf)
// 使用 ... 表示可变参数
// extern "C" {
//     fn printf(format: *const c_char, ...) -> c_int;
// }

fn main() {
    // SAFETY: 标准 C 库函数
    unsafe {
        println!("abs(-5) = {}", abs(-5));
        println!("sqrt(25.0) = {}", sqrt(25.0));
    }

    // 使用 link_name 别名的函数
    let s = std::ffi::CString::new("hello").unwrap();
    // SAFETY: s.as_ptr() 是有效的 C 字符串
    let len = unsafe { c_strlen(s.as_ptr()) };
    println!("c_strlen(\"hello\") = {}", len);

    // malloc/free
    // SAFETY: 分配 16 字节
    unsafe {
        let ptr = malloc(16);
        if !ptr.is_null() {
            println!("malloc 分配成功: {:p}", ptr);
            free(ptr);
            println!("free 释放成功");
        }
    }
}

将 Rust 函数暴露给 C ​

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

// === 简单函数 ===
#[no_mangle]
pub extern "C" fn add(a: c_int, b: c_int) -> c_int {
    a + b
}

// === 处理字符串参数 ===
#[no_mangle]
pub extern "C" fn string_length(s: *const c_char) -> c_int {
    if s.is_null() {
        return -1;
    }
    // SAFETY: 调用者保证 s 是有效的 C 字符串
    let c_str = unsafe { CStr::from_ptr(s) };
    c_str.to_bytes().len() as c_int
}

// === 处理数组/切片参数 ===
#[no_mangle]
pub extern "C" fn sum_array(data: *const c_int, len: c_int) -> c_int {
    if data.is_null() || len <= 0 {
        return 0;
    }
    // SAFETY: 调用者保证 data 指向 len 个有效的 c_int
    let slice = unsafe { slice::from_raw_parts(data, len as usize) };
    slice.iter().sum()
}

// === 通过指针返回结果 ===
#[repr(C)]
pub struct Result {
    value: c_int,
    error: c_int,  // 0 = 成功
}

#[no_mangle]
pub extern "C" fn safe_divide(a: c_int, b: c_int, result: *mut Result) -> c_int {
    if result.is_null() {
        return -1;
    }

    if b == 0 {
        // SAFETY: result 非空
        unsafe {
            (*result).value = 0;
            (*result).error = 1;
        }
        return -1;
    }

    // SAFETY: result 非空
    unsafe {
        (*result).value = a / b;
        (*result).error = 0;
    }
    0
}

// === 回调函数参数 ===
type Callback = extern "C" fn(c_int) -> c_int;

#[no_mangle]
pub extern "C" fn apply_callback(value: c_int, cb: Callback) -> c_int {
    cb(value)
}

// 一个用于测试的回调
extern "C" fn double_it(x: c_int) -> c_int {
    x * 2
}

fn main() {
    // 测试所有暴露的函数
    println!("=== 简单函数 ===");
    println!("add(3, 4) = {}", add(3, 4));

    println!("\n=== 字符串 ===");
    let s = std::ffi::CString::new("Hello").unwrap();
    println!("string_length(\"Hello\") = {}", string_length(s.as_ptr()));
    println!("string_length(null) = {}", string_length(std::ptr::null()));

    println!("\n=== 数组 ===");
    let data: Vec<c_int> = vec![1, 2, 3, 4, 5];
    println!("sum_array = {}", sum_array(data.as_ptr(), data.len() as c_int));

    println!("\n=== 指针返回 ===");
    let mut result = Result { value: 0, error: 0 };
    safe_divide(10, 3, &mut result);
    println!("10/3 = {}, error = {}", result.value, result.error);
    safe_divide(10, 0, &mut result);
    println!("10/0: error = {}", result.error);

    println!("\n=== 回调 ===");
    println!("apply_callback(5, double) = {}", apply_callback(5, double_it));
}

函数指针类型 ​

rust
use std::ffi::c_int;

// extern "C" 函数指针类型
type CFunc = extern "C" fn(c_int) -> c_int;
type CFuncVoid = extern "C" fn();
type CCompare = extern "C" fn(*const c_int, *const c_int) -> c_int;

// 可选的回调(可以为 null)
type OptionalCallback = Option<extern "C" fn(c_int)>;
// Option<extern "C" fn> 与 C 的函数指针大小相同(空指针优化)

extern "C" fn increment(x: c_int) -> c_int {
    x + 1
}

extern "C" fn decrement(x: c_int) -> c_int {
    x - 1
}

extern "C" fn print_value(x: c_int) {
    println!("  值: {}", x);
}

fn execute(f: CFunc, value: c_int) -> c_int {
    f(value)
}

fn maybe_call(cb: OptionalCallback, value: c_int) {
    match cb {
        Some(f) => f(value),
        None => println!("  没有回调"),
    }
}

fn main() {
    // 函数指针赋值
    let f: CFunc = increment;
    println!("increment(10) = {}", execute(f, 10));

    let f: CFunc = decrement;
    println!("decrement(10) = {}", execute(f, 10));

    // 可选回调
    let cb: OptionalCallback = Some(print_value);
    maybe_call(cb, 42);

    let cb: OptionalCallback = None;
    maybe_call(cb, 42);

    // 大小验证(空指针优化)
    println!("\n函数指针大小:");
    println!("  extern \"C\" fn: {} 字节", std::mem::size_of::<CFunc>());
    println!("  Option<extern \"C\" fn>: {} 字节",
        std::mem::size_of::<OptionalCallback>());
    // 两者大小相同
}

基本示例 ​

封装一套完整的 C 兼容 API:

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

// ===== 模拟的 C 兼容库 API =====

// 不透明类型(对 C 隐藏内部实现)
pub struct Calculator {
    history: Vec<(String, f64)>,
    result: f64,
}

// 创建实例(返回裸指针给 C)
#[no_mangle]
pub extern "C" fn calc_new() -> *mut Calculator {
    let calc = Box::new(Calculator {
        history: Vec::new(),
        result: 0.0,
    });
    Box::into_raw(calc)
}

// 释放实例
#[no_mangle]
pub extern "C" fn calc_free(calc: *mut Calculator) {
    if !calc.is_null() {
        // SAFETY: calc 来自 calc_new 的 Box::into_raw
        unsafe { drop(Box::from_raw(calc)); }
    }
}

// 加法
#[no_mangle]
pub extern "C" fn calc_add(calc: *mut Calculator, value: f64) -> c_int {
    if calc.is_null() { return -1; }
    // SAFETY: calc 非空,来自 calc_new
    let calc = unsafe { &mut *calc };
    calc.result += value;
    calc.history.push((format!("+ {}", value), calc.result));
    0
}

// 减法
#[no_mangle]
pub extern "C" fn calc_sub(calc: *mut Calculator, value: f64) -> c_int {
    if calc.is_null() { return -1; }
    let calc = unsafe { &mut *calc };
    calc.result -= value;
    calc.history.push((format!("- {}", value), calc.result));
    0
}

// 乘法
#[no_mangle]
pub extern "C" fn calc_mul(calc: *mut Calculator, value: f64) -> c_int {
    if calc.is_null() { return -1; }
    let calc = unsafe { &mut *calc };
    calc.result *= value;
    calc.history.push((format!("* {}", value), calc.result));
    0
}

// 获取当前结果
#[no_mangle]
pub extern "C" fn calc_result(calc: *const Calculator) -> f64 {
    if calc.is_null() { return 0.0; }
    // SAFETY: calc 非空
    unsafe { (*calc).result }
}

// 重置
#[no_mangle]
pub extern "C" fn calc_reset(calc: *mut Calculator) -> c_int {
    if calc.is_null() { return -1; }
    let calc = unsafe { &mut *calc };
    calc.result = 0.0;
    calc.history.push(("reset".to_string(), 0.0));
    0
}

// 获取历史记录数量
#[no_mangle]
pub extern "C" fn calc_history_count(calc: *const Calculator) -> c_int {
    if calc.is_null() { return 0; }
    let calc = unsafe { &*calc };
    calc.history.len() as c_int
}

fn main() {
    // 模拟 C 代码调用这套 API

    println!("=== Calculator API 测试 ===");

    // 创建
    let calc = calc_new();
    assert!(!calc.is_null());
    println!("创建计算器: {:p}", calc);

    // 运算
    calc_add(calc, 100.0);
    println!("+ 100 = {}", calc_result(calc));

    calc_sub(calc, 30.0);
    println!("- 30  = {}", calc_result(calc));

    calc_mul(calc, 2.0);
    println!("* 2   = {}", calc_result(calc));

    println!("历史记录: {} 条", calc_history_count(calc));

    // 重置
    calc_reset(calc);
    println!("重置后: {}", calc_result(calc));

    // 空指针安全
    println!("\n=== 空指针安全 ===");
    println!("null add: {}", calc_add(ptr::null_mut(), 1.0));
    println!("null result: {}", calc_result(ptr::null()));

    // 释放
    calc_free(calc);
    println!("\n计算器已释放");

    // 释放 null 不会出问题
    calc_free(ptr::null_mut());
    println!("释放 null 安全");
}

常见问题 ​

问题一:extern "C" 和不写 extern 有什么区别?

不写 extern 的函数使用 Rust 默认调用约定,该约定不稳定,可能随版本变化。extern "C" 使用 C 标准调用约定,跨语言兼容。在 FFI 中必须用 extern "C"。

问题二:#[no_mangle] 是必须的吗?

如果希望 C 代码能找到这个函数,就必须加 #[no_mangle]。Rust 默认会修饰(mangle)函数名称以支持泛型和模块系统,修饰后的名称 C 代码无法识别。#[no_mangle] 保持函数名不变。

问题三:extern "C" 函数可以使用泛型吗?

不能。C 没有泛型的概念,extern "C" 函数必须使用具体类型。如果需要支持多种类型,要为每种类型写一个单独的函数。

问题四:extern "C" 函数可以返回 Result 或 Option 吗?

不能直接返回——这些是 Rust 特有的类型,C 不认识。通常用返回错误码(c_int)表示成功/失败,或通过输出参数(*mut T)返回结果。Option<extern "C" fn> 可以安全地用于可选回调。

适用场景 ​

  • 调用 C 库:声明并调用已有的 C 函数
  • 暴露 Rust API:为 C/C++ 项目提供 Rust 实现的功能
  • 跨语言插件:编写可以被多种语言加载的动态库
  • 系统调用:调用操作系统的 C 接口

注意事项 ​

  • extern "C" 块中的函数签名必须与 C 中的完全匹配
  • 暴露给 C 的函数需要 #[no_mangle] 和 pub extern "C"
  • extern "C" 函数不能使用泛型
  • 返回值和参数必须使用 C 兼容类型
  • extern "system" 在 Windows 上使用 stdcall,其他平台等于 extern "C"
  • Option<extern "C" fn> 利用空指针优化,与 C 函数指针大小相同

总结 ​

extern "C" 指定 C 标准调用约定,是 Rust FFI 的核心语法。它有两个方向的用法:在 extern "C" { } 块中声明外部 C 函数(调用时需要 unsafe),在 Rust 函数前加 extern "C" 使其可被 C 调用(还需要 #[no_mangle])。Rust 支持多种调用约定("C"、"system"、"stdcall" 等),其中 "C" 是跨语言互操作最通用的选择。extern "C" 函数不能使用泛型,参数和返回值必须是 C 兼容类型。函数指针类型也包含调用约定信息(extern "C" fn(i32) -> i32),Option<extern "C" fn> 利用空指针优化与 C 函数指针大小相同。