Memory safety is one of Rust’s key selling points, but it becomes challenging when interfacing with languages like C or C++ through Foreign Function Interface (FFI). I’ve spent years working with these interfaces and discovered techniques that help maintain Rust’s safety guarantees while communicating with code that doesn’t enforce them.
Safe Wrappers Around Unsafe Code
The foundation of safe FFI is isolating unsafe code inside well-designed wrappers. When I first started with Rust FFI, I made the mistake of sprinkling unsafe blocks throughout my codebase. I quickly learned this approach multiplies the surface area for potential bugs.
Instead, I now create dedicated modules with clear boundaries:
// Low-level FFI declarations
mod ffi {
use std::os::raw::{c_char, c_int};
extern "C" {
pub fn sqlite3_open(filename: *const c_char, ppdb: *mut *mut sqlite3) -> c_int;
pub fn sqlite3_close(db: *mut sqlite3) -> c_int;
// Other SQLite functions
}
#[repr(C)]
pub struct sqlite3 {
_private: [u8; 0],
}
}
// Safe public API
pub struct Database {
db: *mut ffi::sqlite3,
}
impl Database {
pub fn open(path: &str) -> Result<Self, DatabaseError> {
let c_path = CString::new(path).map_err(|_| DatabaseError::InvalidPath)?;
let mut db_ptr: *mut ffi::sqlite3 = std::ptr::null_mut();
let result = unsafe {
ffi::sqlite3_open(c_path.as_ptr(), &mut db_ptr)
};
if result != 0 {
return Err(DatabaseError::OpenFailed(result));
}
if db_ptr.is_null() {
return Err(DatabaseError::NullDatabase);
}
Ok(Database { db: db_ptr })
}
}
impl Drop for Database {
fn drop(&mut self) {
if !self.db.is_null() {
unsafe { ffi::sqlite3_close(self.db) };
}
}
}
This pattern encapsulates all unsafe operations within carefully designed methods that maintain safety invariants. The public API exposes only safe functions with proper error handling.
Memory Ownership with Callback Functions
Callbacks present unique challenges in FFI. When a C library calls back into Rust, we must ensure data remains valid for the duration of the callback but is properly cleaned up afterward.
I’ve developed a pattern using context pointers that works reliably:
struct CallbackContext {
results: Vec<String>,
error: Option<String>,
}
extern "C" fn callback_handler(
context: *mut c_void,
result: *const c_char,
result_len: c_int
) -> c_int {
// Safety: We trust the C library to provide our pointer back
let context = unsafe { &mut *(context as *mut CallbackContext) };
if result.is_null() {
context.error = Some("Null result pointer".to_string());
return -1;
}
let result_slice = unsafe {
std::slice::from_raw_parts(
result as *const u8,
result_len as usize
)
};
match std::str::from_utf8(result_slice) {
Ok(s) => context.results.push(s.to_string()),
Err(_) => {
context.error = Some("Invalid UTF-8".to_string());
return -1;
}
}
0 // Success
}
pub fn process_with_callback() -> Result<Vec<String>, String> {
let mut context = CallbackContext {
results: Vec::new(),
error: None,
};
let result = unsafe {
ffi::library_process(
callback_handler,
&mut context as *mut _ as *mut c_void
)
};
if result != 0 {
return Err(format!("Processing failed with code: {}", result));
}
if let Some(error) = context.error {
return Err(error);
}
Ok(context.results)
}
This pattern works because the context is stack-allocated and outlives the C function call. The C library never takes ownership of our data.
Proper String Handling
String conversions are a common source of memory errors in FFI code. I’ve found these patterns particularly useful:
// Converting Rust strings to C strings
fn rust_to_c_string(s: &str) -> Result<CString, StringError> {
CString::new(s).map_err(|_| StringError::ContainsNulByte)
}
// Converting C strings to Rust strings (null-terminated)
fn c_to_rust_string(ptr: *const c_char) -> Result<String, StringError> {
if ptr.is_null() {
return Err(StringError::NullPointer);
}
let c_str = unsafe { CStr::from_ptr(ptr) };
c_str.to_str()
.map(|s| s.to_owned())
.map_err(|_| StringError::InvalidUtf8)
}
// Converting C string with explicit length to Rust string
fn c_str_with_len_to_rust(ptr: *const c_char, len: usize) -> Result<String, StringError> {
if ptr.is_null() {
return Err(StringError::NullPointer);
}
let slice = unsafe { std::slice::from_raw_parts(ptr as *const u8, len) };
String::from_utf8(slice.to_vec())
.map_err(|_| StringError::InvalidUtf8)
}
These functions handle common error cases like null pointers and invalid UTF-8, preventing many potential bugs.
Type-Safe Resource Management
Proper resource management is critical in FFI code. The pattern I use most often is implementing RAII (Resource Acquisition Is Initialization) through Rust’s Drop trait:
pub struct FileHandle {
handle: *mut ffi::FILE,
owned: bool,
}
impl FileHandle {
pub fn open(path: &str, mode: &str) -> Result<Self, FileError> {
let c_path = CString::new(path).map_err(|_| FileError::InvalidPath)?;
let c_mode = CString::new(mode).map_err(|_| FileError::InvalidMode)?;
let handle = unsafe { ffi::fopen(c_path.as_ptr(), c_mode.as_ptr()) };
if handle.is_null() {
return Err(FileError::OpenFailed);
}
Ok(FileHandle { handle, owned: true })
}
pub fn write(&mut self, data: &[u8]) -> Result<usize, FileError> {
if self.handle.is_null() {
return Err(FileError::InvalidHandle);
}
let written = unsafe {
ffi::fwrite(
data.as_ptr() as *const c_void,
1,
data.len(),
self.handle
)
};
if written < data.len() {
return Err(FileError::WriteFailed);
}
Ok(written)
}
// Takes ownership of an existing file handle
pub fn from_raw(handle: *mut ffi::FILE, owned: bool) -> Self {
FileHandle { handle, owned }
}
// Releases ownership of the handle
pub fn into_raw(mut self) -> *mut ffi::FILE {
self.owned = false;
self.handle
}
}
impl Drop for FileHandle {
fn drop(&mut self) {
if !self.handle.is_null() && self.owned {
unsafe { ffi::fclose(self.handle) };
}
}
}
This pattern provides clean resource management with proper ownership semantics. The owned flag allows for flexibility when working with resources created elsewhere.
Properly Aligned Data Structures
Memory layout compatibility is crucial when passing data structures between Rust and C. I always ensure proper alignment and representation:
#[repr(C)]
pub struct ImageInfo {
width: u32,
height: u32,
format: u32,
data: *mut u8,
data_size: usize,
}
#[repr(C)]
pub enum CompressionType {
None = 0,
LZ4 = 1,
Zstd = 2,
}
#[repr(C, packed)]
pub struct PackedHeader {
magic: [u8; 4],
version: u16,
flags: u16,
}
// Function to create C-compatible structures
pub fn create_image_info(image: &Image) -> ImageInfo {
ImageInfo {
width: image.width,
height: image.height,
format: image.format.to_c_format(),
data: image.raw_data.as_ptr() as *mut u8,
data_size: image.raw_data.len(),
}
}
I’ve learned to be particularly careful with:
- Using
#[repr(C)]to ensure C-compatible memory layout - Using
#[repr(C, packed)]when the C structure is packed - Ensuring enums have explicit values
- Being aware of alignment requirements for different platforms
Error Handling Across FFI Boundaries
Error handling across language boundaries requires careful design. I’ve found this approach works well:
#[derive(Debug)]
pub enum FfiError {
InvalidInput,
OutOfMemory,
IoError,
Unknown(i32),
}
// Convert C error codes to Rust errors
fn convert_error_code(code: i32) -> Result<(), FfiError> {
match code {
0 => Ok(()),
-1 => Err(FfiError::InvalidInput),
-2 => Err(FfiError::OutOfMemory),
-3 => Err(FfiError::IoError),
other => Err(FfiError::Unknown(other)),
}
}
// Implement conversion to C error codes for Rust errors
impl FfiError {
fn to_error_code(&self) -> i32 {
match self {
FfiError::InvalidInput => -1,
FfiError::OutOfMemory => -2,
FfiError::IoError => -3,
FfiError::Unknown(code) => *code,
}
}
}
// FFI-safe function that returns an error code
#[no_mangle]
pub extern "C" fn process_data(
data: *const u8,
len: usize,
output: *mut *mut u8,
output_len: *mut usize
) -> i32 {
let result = catch_unwind(|| {
if data.is_null() || output.is_null() || output_len.is_null() {
return Err(FfiError::InvalidInput);
}
let input_slice = unsafe { std::slice::from_raw_parts(data, len) };
// Process data...
let result_data = process_input(input_slice)?;
// Allocate memory for the result
let result_ptr = allocate_buffer(&result_data)?;
unsafe {
*output = result_ptr;
*output_len = result_data.len();
}
Ok(())
});
match result {
Ok(Ok(())) => 0, // Success
Ok(Err(e)) => e.to_error_code(),
Err(_) => -999, // Panic occurred
}
}
This pattern ensures Rust panics don’t propagate across the FFI boundary (which would lead to undefined behavior) and provides a clear mapping between Rust’s rich error types and C’s simple error codes.
Managing External Memory
When working with memory allocated by C libraries, proper management is essential:
pub struct ExternalBuffer {
ptr: *mut u8,
size: usize,
free_fn: unsafe extern "C" fn(*mut c_void),
}
impl ExternalBuffer {
// Create from externally allocated memory
pub unsafe fn from_raw_parts(
ptr: *mut u8,
size: usize,
free_fn: unsafe extern "C" fn(*mut c_void)
) -> Result<Self, BufferError> {
if ptr.is_null() {
return Err(BufferError::NullPointer);
}
Ok(ExternalBuffer { ptr, size, free_fn })
}
pub fn as_slice(&self) -> &[u8] {
unsafe { std::slice::from_raw_parts(self.ptr, self.size) }
}
pub fn as_mut_slice(&mut self) -> &mut [u8] {
unsafe { std::slice::from_raw_parts_mut(self.ptr, self.size) }
}
}
impl Drop for ExternalBuffer {
fn drop(&mut self) {
if !self.ptr.is_null() {
unsafe { (self.free_fn)(self.ptr as *mut c_void) };
self.ptr = std::ptr::null_mut();
}
}
}
This pattern allows safe interaction with memory allocated by external libraries while ensuring it’s properly freed.
Testing FFI Code
Testing FFI code requires special techniques. I’ve found these approaches effective:
#[cfg(test)]
mod tests {
use super::*;
use std::ffi::CString;
#[test]
fn test_string_conversion() {
let original = "Hello, world!";
let c_string = rust_to_c_string(original).unwrap();
let roundtrip = c_to_rust_string(c_string.as_ptr()).unwrap();
assert_eq!(original, roundtrip);
}
#[test]
fn test_null_pointer_handling() {
let result = c_to_rust_string(std::ptr::null());
assert!(matches!(result, Err(StringError::NullPointer)));
}
// Mock C functions for testing
mod mock {
use std::collections::HashMap;
use std::sync::Mutex;
lazy_static! {
static ref MOCK_FILES: Mutex<HashMap<String, Vec<u8>>> = Mutex::new(HashMap::new());
}
pub unsafe extern "C" fn mock_fopen(path: *const c_char, _mode: *const c_char) -> *mut FILE {
let c_str = CStr::from_ptr(path);
let path_str = c_str.to_str().unwrap().to_owned();
let mut files = MOCK_FILES.lock().unwrap();
files.insert(path_str.clone(), Vec::new());
path_str.as_ptr() as *mut FILE
}
// Other mock functions...
}
#[test]
fn test_file_operations() {
// Replace real FFI functions with mocks for testing
let original_fopen = ffi::fopen;
ffi::fopen = mock::mock_fopen;
// Test file operations...
// Restore original function
ffi::fopen = original_fopen;
}
}
By creating mock implementations of C functions, I can test FFI code without requiring the actual C libraries during testing.
Conclusion
Writing memory-safe FFI code in Rust requires discipline and careful design. The techniques I’ve shared come from years of experience building libraries that bridge Rust with C and C++. By following these patterns, you can safely extend Rust applications with native libraries while maintaining the safety guarantees that make Rust such a powerful language.
Remember that FFI is inherently unsafe, but with proper encapsulation, you can contain that unsafety to small, well-tested modules. This allows the rest of your codebase to benefit from Rust’s safety features even when interfacing with languages that don’t provide the same guarantees.
