Rust FFI 编程 - 手动绑定 C 库入门 02---MikeLoveRust

本篇是《手动绑定 C 库入门》的第二篇。了解第一篇后，我们知道在调用 C 库时，需要重新在 Rust 中对该 C 库中的数据类型和函数签名进行封装。这篇我们将实践涉及到诸如数组，结构体等类型时，如何进行手动绑定。

备注：有自动生成绑定的工具，比如，bindgen可以自动生成 C 库和某些C ++库的 Rust FFI 绑定。但这个章节不涉及这些。

本篇的主要内容有：

数组示例结构体示例repr属性结构体opaque 结构体1. 数组示例

假定我们现在有个 C 库 c_utils.so，其中有一个函数 int sum(const int* my_array, int length) ，给定一个整数数组，返回数组中所有元素的和。

// ffi/rust-call-c/src/c_utils.c int sum(const int* my_array, int length) { int total = 0; for(int i = 0; i < length; i++) { total += my_array[i]; } return total; }

在 Rust 中绑定 C 库中的 sum 函数，然后直接通过 unsafe 块中调用。

// ffi/rust-call-c/src/array.rs use std::os::raw::c_int; // 对 C 库中的 sum 函数进行 Rust 绑定： extern "C" { fn sum(my_array: *const c_int, length: c_int) -> c_int; } fn main() { let numbers: [c_int; 10] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; unsafe { let total = sum(numbers.as_ptr(), numbers.len() as c_int); println!("The total is {}", total); assert_eq!(total, numbers.iter().sum()); } }

编译，然后执行输出如下结果：

lyys-MacBook-Pro:src lyy$ rustc array.rs -o array -L. -lc_utils lyys-MacBook-Pro:src lyy$ ./array The total is 552. 结构体

结构体是由用户定义的一种复合类型，我们知道不同的语言使用不同的机制在计算机内存中布局数据，这样 Rust 编译器可能会执行某些优化而导致类型布局有所不同，无法和其他语言编写的程序正确交互。

类型布局（Type layout），是指类型在内存中的排列方式，是其数据在内存中的大小，对齐方式以及其字段的相对偏移量。当数据自然对齐时，CPU 可以最有效地执行内存读写。

2.1 repr属性

为了解决上述问题，Rust 引入了repr属性来指定类型的内存布局，该属性支持的值有：

#[repr(Rust)]，默认布局或不指定repr属性。#[repr(C)]，C 布局，这告诉编译器"像C那样对类型布局"，可使用在结构体，枚举和联合类型。#[repr(transparent)]，此布局仅可应用于结构体为：包含单个非零大小的字段（ newtype-like ），以及任意数量的大小为 0 且对齐方式为 1 的字段（例如PhantomData<T>）#[repr(u*)],#[repr(i*)]，原始整型的表示形式，如：u8，i32，isize等，仅可应用于枚举。

结构体的成员总是按照指定的顺序存放在内存中，由于各种类型的对齐要求，通常需要填充以确保成员以适当对齐的字节开始。对于 1 和 2 ，可以分别使用对齐修饰符align和packed来提高或降低其对齐方式。使用repr属性，只可以更改其字段之间的填充，但不能更改字段本身的内存布局。repr(packed)可能导致未定义的行为，不要轻易使用。

以下是repr属性的一些示例：

// ffi/rust-call-c/src/layout.rs use std::mem; // 默认布局，对齐方式降低到 1 #[repr(packed(1))] struct PackedStruct { first: i8, second: i16, third: i8 } // C 布局 #[repr(C)] struct CStruct { first: i8, second: i16, third: i8 } // C 布局, 对齐方式升高到 8 #[repr(C, align(8))] struct AlignedStruct { first: i8, second: i16, third: i8 } // 联合类型的大小等于其字段类型的最大值 #[repr(C)] union ExampleUnion { smaller: i8, larger: i16 } fn main() { assert_eq!(mem::size_of::<CStruct>(), 6); assert_eq!(mem::align_of::<CStruct>(), 2); assert_eq!(mem::align_of::<PackedStruct>(), 1); assert_eq!(mem::align_of::<AlignedStruct>(), 8); assert_eq!(mem::size_of::<ExampleUnion>(), 2); }2.2 结构体

为了说明在 Rust 中调用 C 库时，应该如何传递结构体？我试着找了一些 C 库，但由于有些库需要安装，最后决定通过标准库中的 time.h 来做示例。我们假定要在 Rust 程序中实现格式化日期格式的功能，可以通过调用这个标准库中的 strftime() 函数来完成。首先看头文件 time.h ，结构体及函数声明如下：

struct tm { int tm_sec; /* 秒，范围从 0 到 59 */ int tm_min; /* 分，范围从 0 到 59 */ int tm_hour; /* 小时，范围从 0 到 23 */ int tm_mday; /* 一月中的第几天，范围从 1 到 31 */ int tm_mon; /* 月份，范围从 0 到 11 */ int tm_year; /* 自 1900 起的年数 */ int tm_wday; /* 一周中的第几天，范围从 0 到 6 */ int tm_yday; /* 一年中的第几天，范围从 0 到 365 */ int tm_isdst; /* 夏令时 */ }; size_t strftime(char *str, size_t maxsize, const char *format, const struct tm *timeptr)

该函数根据 format 中定义的格式化规则，格式化结构体 timeptr 表示的时间，并把它存储在 str 中。这个函数使用了指向 C 结构体 tm 的指针，该结构体也必须在 Rust 中重新声明，通过类型布局小节，我们知道可以使用repr属性#[repr(C)]来确保在 Rust 中，该结构体的内存布局与在 C 中相同。

以下是对 strftime() 函数的 Rust FFI 手动绑定示例：

use libc::{c_int, size_t}; #[repr(C)] pub struct tm { pub tm_sec: c_int, pub tm_min: c_int, pub tm_hour: c_int, pub tm_mday: c_int, pub tm_mon: c_int, pub tm_year: c_int, pub tm_wday: c_int, pub tm_yday: c_int, pub tm_isdst: c_int, } extern { // 标准库<time.h> strftime函数的 Rust FFI 绑定 #[link_name = "strftime"] pub fn strftime_in_rust(stra: *mut u8, maxsize: size_t, format: *const u8, timeptr: *mut tm) -> size_t; }

接下来我们编写 Rust 程序，调用这个 C 库函数实现日期格式化功能，代码如下：

use std::str; mod time; fn main() { // 初始化 let mut v: Vec<u8> = vec![0; 80]; // 初始化结构体 let mut t = time::tm { tm_sec: 15, tm_min: 09, tm_hour: 18, tm_mday: 14, tm_mon: 04, tm_year: 120, tm_wday: 4, tm_yday: 135, tm_isdst: 0, }; // 期望的日期格式 let format = b"%Y-%m-%d %H:%M:%S".as_ptr(); unsafe { // 调用 time::strftime_in_rust(v.as_mut_ptr(), 80, format, &mut t); let s = match str::from_utf8(v.as_slice()) { Ok(r) => r, Err(e) => panic!("Invalid UTF-8 sequence: {}", e), }; println!("result: {}", s); } }2.3 Opaque 结构体

一些 C 库的 API 通常是在不透明指针指向的结构体上运行的一系列的函数。比如有以下 C 代码：

struct object; struct object* init(void); void free_object(struct object*); int get_info(const struct object*); void set_info(struct object*, int);

目前在 Rust 中，比较推荐的一种做法是，通过使用一个拥有私有字段的结构体来声明这种类型。

#[repr(C)] pub struct OpaqueObject { _private: [u8; 0], }

同样的，对该 C 库中的函数进行 Rust FFI 手动绑定，示例如下：

extern "C" { pub fn free_object(obj: *mut OpaqueObject); pub fn init() -> *mut OpaqueObject; pub fn get_info(obj: *const OpaqueObject) -> c_int; pub fn set_info(obj: *mut OpaqueObject, info: c_int); }

接下来我们调用这些函数，代码如下：

// ffi/rust-call-c/src/opaque.rs fn main() { unsafe { let obj = init(); println!("Original value: {}", get_info(obj)); set_info(obj, 521); println!("New value: {}", get_info(obj)); } }

编译，然后执行输出如下结果：

lyys-MacBook-Pro:src lyy$ rustc opaque.rs -o opaque -L. -lffi_test lyys-MacBook-Pro:src lyy$ ./opaque Original value: 0 New value: 521

注意：有一个 RFC 1861 （ 链接：https://github.com/canndrew/rfcs/blob/extern-types/text/1861-extern-types.md）用于引入extern type语法，但目前还未稳定。

总结

在 Rust 中调用 C 库，进行 Rust FFI 绑定：

传递结构体类型的参数时，可以使用repr属性#[repr(C)]确保有一致的内存布局。对于 C 库中的 Opaque 结构体类型的参数，在 Rust 中可以使用一个拥有私有字段的结构体来表示。 ---来自腾讯云社区的---MikeLoveRust