Rust 实战练习 - 7. FFI, 库, ABI, libc

FFI

FFI（Foreign Function Interface）是这样一种机制：用一种编程语言写的程序能调用另一种编程语言写的函数（routines）。

调用约定，类型表示和名称修饰这三者的统称，即是众所周知的应用二进制接口（ABI）。

如果所有的语言在调用时都能认识同样一套 ABI 规范，那么就能完全畅通的调用了。可惜，世界不会像我们人为想象的那样干净。

在计算机技术发展的过程中，出现了各种 ABI 规范：

• cdecl
• syscall
• optlink
• pascal
• register
• stdcall
• fastcall
• thiscall
• winapi
• Intel ABI
• System V

等。详情可参考：X86调用约定。

而 Rust 目前支持如下 ABI 约定：

• stdcall
• aapcs
• cdecl
• fastcall
• vectorcall
• Rust
• rust-intrinsic
• system
• C
• win64
• sysv64

目前我们 IT 工业的基石，绝大部分是由 C 语言写成。于是自然而然，绝大多数库都遵循 cdecl（或 C）规范。所以我们可以专注于 C 规范来讨论问题。

目前所知，能（较方便地）对其它语言提供 FFI 库支持的语言有：

• C
• C++（通过定义 C 接口）
• Rust（通过使用 C 约定）
• Ada
• Fortran

通用方案

在开发的过程中，要一个一个对大量的 C/C++ 库写绑定来进行 FFI，毕竟是一项费时费力的活儿。聪明的程序员们就开始构想一些“通用”的方案，实现批量快速绑定。

SWIG

以下定义来自 https://zh.wikipedia.org/wiki/SWIG：

简单包装界面产生器(SWIG)是一个开源软件工具，用来将C语言或C++写的计算机程序或函式库，连接脚本语言，例如Lua, Perl, PHP, Python, R, Ruby, Tcl, 和其它语言，例如C#, Java, JavaScript, Go, D, OCaml, Octave, Scilab以及Scheme. 也可以输出成XML格式。

也就是说，使用了 SWIG 这套工具和规范，就可以直接在上层语言（动态语言居多）中调用 C/C++ 库了，省却大量烦恼。但在实际使用中，还会有一些细节问题，往往需要人工调整。所以也不是那么完美。

Gnome 的 GI 规范

Gnome/Gtk 那一帮理想主义青年，发明了 GI（GObject Introspection）。用于对基于 glib/gobject 生态的众多软件（C 代码库）自动生成完整的接口描述文件（及 typelib），然后其它语言只要实现了对 Gir 这一个标准的支持，那么就可以无缝调用所有经过 Gir 化处理的 C 库。而不再需要单独为每一个 C 库做绑定了。这样就大大简化了 FFI 接口项目的编写工作。

目前这一杰出创意的重量级工作成果有 cairo, pango, gtk 等库。

更多信息请参考：https://gi.readthedocs.io/en/latest/。

另一种思路——基于字节码的平台级路线

语言间的相互调用，历史的发展提供了另一条路线：建立一个共同的字节码平台，这个平台之上的所有语言，皆可便捷地相互调用。

• JVM 平台语言之间的 FFI
• WASM 平台的 FFI

https://rustcc.cn/search?q=Rust%20FFI%20%E7%BC%96%E7%A8%8B

https://rustcc.cn/article?id=44a47b42-184c-4e2f-9318-be07ee5a516c

Rust 语言主要在关键字和标准库两个方面对 FFI 提供了支持，具体如下：

• 关键字 extern
  • 属性 #[no_mangle]
  • 外部块 ExternBlock 及其属性 link 和 link_name
• 标准库
  • std:os:raw 模块
  • std:ffi 模块

Rust编写lib给别人用

通过使用 ABI 字符串来指定具体的 ABI，其中有三个 ABI 字符串是跨平台的：

• extern "Rust"，默认的 ABI，在 Rust 代码中对任何普通函数fn foo()声明时都将使用该 ABI。
• extern "C"，指定使用 C-ABI，类似extern fn foo()，无论 C 编译器支持哪种默认设置。
• extern "system"，通常类似extern "C"，但在 Win32 平台上，它是"stdcall"，或用于链接到 Windows API。

crate-type: [bin|lib|rlib|dylib|cdylib|staticlib|proc-macro]

• bin 二进制可执行文件，main函数为入口。
• lib Rust Library的编译工具默认值，一般为rlib。由编译器推荐其值。
• rlib Rust Library的静态库，满足Rust API。 *.rlib 实现为一个 ar 归档文件。
• dylib Rust Library的动态库，在编译的时候，生成动态库（Linux 上为 .so, MacOS 上为 .dylib, Windows 上为 .dll）。
• cdylib 满足C调用规范的动态链接库。在编译的时候，生成动态库（Linux 上为 .so, MacOS 上为 .dylib, Windows 上为 .dll）。
• staticlib 满足C调用规范的静态链接库。编译会生成 .a 文件（在 Linux 和 MacOS 上），或 .lib 文件（在 Windows 上）。
• proc-macro 过程宏crate.

// Rust定义函数给外部使用
#[no_mangle]
pub extern "C" fn addtwo1(a: u32, b: u32) -> u32 {let c = a + b;println!("print in rust, sum is: {}", c);c
}#[no_mangle]
pub extern "C" fn sum_of_array(array: *const u32, len: usize) -> u32 {let array = unsafe {assert!(!array.is_null());slice::from_raw_parts(array, len)};array.iter().sum()
}// 在 Cargo.toml 中，加入如下两行
[lib]
crate-type = ["cdylib"]

C代码

#include <stdio.h>
#include <stdint.h>extern uint32_t addtwo1(uint32_t, uint32_t);
extern uint32_t sum_of_array(const uint32_t *numbers, size_t length);int main(void) {uint32_t sum = addtwo1(10, 20);printf("print in c, sum is: %d\n", sum);uint32_t numbers[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};unsigned int length = sizeof(numbers) / sizeof(*numbers);uint32_t sum = sum_of_array(numbers, length);printf("print in c, sum is: %d\n", sum);
}

build

编译 rust so：cargo build
编译 c binary：gcc -o ./ccode03 ./ccode03.c -L ./ -lrustffi3
运行：LD_LIBRARY_PATH=. ./ccode03

结构体导出

只有当#[repr(C)] / #[repr(C, packed)]属性应用于一个struct时，Rust 才能保证该结构的布局与平台的 C 语言表示兼容

#[repr(C)]
pub struct Foo {a: isize,b: isize
}// Struct的方法
impl Foo {// 成员函数，需要this指针pub fn method1(&self) -> isize{self.a+self.b}// 成员函数pub fn method2(&self, x: isize) -> isize {x + self.a + self.b}// 静态成员函数，不需要thispub fn method3(x: isize) -> isize {x*2}
}

对应的C代码大概是这样子

struct Foo {int a;int b;
}void foo_method1(Foo* foo);
int foo_method2(Foo* foo, int x);
int foo_method1(int x);

然而，这种映射是不能自动转换的（毕竟只是我们自己的约定），需要手动写出来。

#[no_mangle]
pub unsafe extern "C" fn foo_method1(foo: *mut Foo) {let foo = &*foo;foo.method1();
}#[no_mangle]
pub unsafe extern "C" fn foo_method2(foo: *const Foo, x: isize) -> isize {let foo = &*foo;foo.method2(x)
}#[no_mangle]
pub unsafe extern "C" fn foo_method3(x: isize) -> isize {Foo::method3(x)
}

编译cargo build --release, 得到

$ nm -D --defined-only libd7.so 
0000000000001100 T foo_method1
0000000000001110 T foo_method2
0000000000001120 T foo_method3

最后，C代码:

#include <stdio.h>struct Foo
{long a;long b;
};extern void foo_method1(struct Foo *f);
extern long foo_method2(struct Foo *f, long x);
extern long foo_method3(long x);int main(int argc, char* argv){struct Foo f;f.a = 10;f.b = 100;long val = -1;foo_method1(&f);val = foo_method2(&f, 2);printf("m2: %ld\r\n", val);val = foo_method3(3);printf("m3: %ld\r\n", val);return 0;
}// gcc -o ../target/release/c_ffi main.c -L ../target/release/ -ld7
// LD_LIBRARY_PATH=. ./c_ffi
m2: 112
m3: 6

完美!

Rust调用别人写好的C库

// Rust使用外部的库
#[cfg(all(target_os = "win32", target_arch = "x86"))]
#[link(name = "c_library"，kind="cdylib" )]
#[allow(non_snake_case)]
extern "C" {// 访问全局变量static rl_readline_version: libc::c_int; // 可以使用link_name映射外部函数名#[link_name = "c_function_name"]fn c_function(input: i32) -> i32;
}// 标准库<stdlib.h>内置的abs函数
extern "C" {#[link_name = "abs"]fn abs_in_rust(input: i32) -> i32;
}fn main() {unsafe {println!("abs(-1) is {}", abs_in_rust(-1));}
}

kind是一个可选值，通过它来指定原生库的类型，它有以下三种可选的值：

• dylib，表示为动态库。如果未指定kind，则它为默认值。
• static，表示为静态库。
• framework，表示 macOS 的框架，这仅对 macOS 目标有效。

对于互传递参数，Rust 标准库std::os::raw 和std::ffi 这两个模块提供了这方面的支持。

参考链接

[1] 外部块支持的 ABI 字符串，https://doc.rust-lang.org/reference/items/external-blocks.html

[2] 标准库 std::os::raw 模块，https://doc.rust-lang.org/stable/std/os/raw/index.html

[3] 标准库 std::ffi 模块，https://doc.rust-lang.org/std/ffi/index.html

[4] Rust 中 String 与 UTF-8 编码，https://mp.weixin.qq.com/s/ZX_0G6JcNMusLz6JJOkNSg

libc

libc 是对各平台的系统库的原始 FFI 绑定。其代码地址在：https://github.com/rust-lang/libc。可以看到，这是 Rust 官方维护的一个库。

libc 提供了与 Rust 支持的各平台上的最基础系统 C 库打交道的所有必要设施。它导出了底层平台的类型、函数和常量。

libc 会导出底层 C 库的这些东西：

• C 类型，比如 typedefs, 原生类型，枚举，结构体等等
• C 常量，比如使用 #define 指令定义的那些常量
• C 静态变量
• C 函数（按它们的头文件中定义的函数签名来导出）
• C 宏，在 Rust 中会实现为 #[inline] 函数

另外，libc 中导出的所有 C struct 都已经实现了 Copy 和 Clone trait.

libc 的所有函数调用，都必须放进 unsafe 块中。因为它的所有调用都是 unsafe 的；

Rust 默认与libc和libm链接。

与C的库区别：

熟悉 linux 系统开发的同学都知道，linux 系统本身有个 libc 库，是几乎一切应用的基础库。基本上 linux 下 C 语言写的代码都要链接这个库才能运行。

而 Rust 的 libc crate，不完全等价于 C 的 libc 库的封装。具体区别如下：

• Linux （以及其它 unix-like 平台）下，导出的是 libc, libm, librt, libdl, libutil 和 libpthread 这几个库的符号。
• OSX 下，导出的是 libsystem_c, libsystem_m, libsystem_pthread, libsystem_malloc 和 libdyld 这几个库的符号。
• Windows 下，导出的是 VS CRT（VS C RunTime VS C 运行时库）中的符号。但是这些符号，比前两个平台的符号，数量上要少得多。因此，可以直接这样说，Rust libc crate 在 Windows 平台上的功能有限。在 Windows 平台上，建议使用 winapi 这个 crate 进行开发。

比如：Rust 标准库中没有提供创建子进程的设施，不过可以创建一个子线程。而libc 可以创建一个子进程。

libc 与 std::os:😗::raw 的关系？

细心的同学会发现，在标准库的 os 模块下面，有一些东西与 libc 的重复。

页面 https://doc.rust-lang.org/std/os/raw/index.html 包含了 c_char, c_double, c_float, c_int, c_long, c_longlong, c_schar, c_short, c_uchar, c_uint, c_ulong, c_ulonglong, c_ushort。

而 libc 中，对这些内容，也重新定义了一份（比如：https://docs.rs/libc/0.2.69/libc/type.c_char.html）。为什么呢？

std::os::raw 中这些定义，可以用于与一些简单的 C 代码进行交互，比如说不存在系统调用的 C 代码。这个时候，就不需要再引入 libc 库了。

而一旦产生了系统调用或者 Unix 环境编程，那么就得引入 libc 库来操作。

std 下面还有一些 std::os:😗::raw 的模块，这些模块现在已经被 Deprecated 了（比如：https://doc.rust-lang.org/std/os/unix/raw/index.html）。

nix库

nix 库 旨在提供对各种类 Unix 平台（Linux，Darwin等）API 的友好绑定（bindings），其代码地址在：https://github.com/nix-rust/nix。

它通过使用强制合法或安全的类型对 libc 库进行了一次封装，相对于 libc 库暴露的 unsafe API，它具有两个特点：

• 用户代码中尽量没有 unsafe
• Rust 风格的错误处理

不过尽管 nix 库尝试支持 libc 库支持的所有平台，但由于技术或人力限制，仅支持其中的某些平台。可能这也是一些底层库（比如：tokio项目中的mio）在版本v0.6.3之后 移除 对 nix 库依赖的一个原因吧。

nix 库中的模块大致如下：

• dir，相对标准库中的std::fs::ReadDir更底层的目录接口。
• errno， nix 库中处理各种类 Unix 系统的错误类型，对于 FreeBSD，IOS，MacOS 系统直接封装的 libc 库中的。
• fcntl， Unix 系统中文件 IO 的数据结构，以及对文件的各种操作接口。
• features，用于操作系统级功能的测试。
• ifaddrs，使用 Linux 或 BSD 中的函数getifaddrs获取网络接口及地址列表。
• kmod，包含加载和卸载内核模块的功能。
• mount，包含设备文件的挂载操作，mount和umount。
• mqueue， 对应 POSIX 规范中消息队列 API 的功能。
• net，涉及网络接口的功能。
• poll，在特点文件描述符上触发 wait 事件。
• pty，创建主从虚拟伪终端 PTYs。
• sched，提供 Linux 系统的调度接口。
• sys，这个模块包括各种系统相关的功能：POSIX 异步 I/O，文件系统事件的监控 API，Socket接口函数等。
• ucontext，提供协程上下文相关的借接口。
• unistd，在 libc 库unistd.h头文件中函数的 safe 封装。

Demo

use nix::unistd::*;fn main() {match fork() {Ok(ForkResult::Parent { child }) => {// 在父进程中println!("Hello, I am parent thread: {}", getpid());}Ok(ForkResult::Child) => {// 在子进程中println!("Hello, I am child thread: {}", getpid());println!("My parent thread: {}", getppid());            }Err(errno) => {// fork 创建子进程失败println!("Fork creation failed!");}}  
}