extern "C" 声明
核心概念
extern "C" 是 Rust 中用于指定 C 调用约定(calling convention)的关键语法。调用约定决定了函数参数如何传递(通过寄存器还是栈)、返回值如何处理、栈由谁清理等底层细节。不同语言和平台有不同的调用约定,extern "C" 告诉 Rust 编译器使用 C 语言的标准调用约定,这是跨语言互操作最常用的约定。
extern "C" 在两个方向上使用:在 extern "C" { } 块中声明要调用的外部 C 函数;在 Rust 函数签名前加 extern "C" 使其可以被 C 代码调用。
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 支持多种调用约定,通过 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" | Windows | Win32 API |
extern "cdecl" | C 声明 | 与 extern "C" 类似 |
extern "C" 块的详细用法
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
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));
}函数指针类型
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:
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 函数指针大小相同。