Bridging Worlds: Safe FFI Bindings for C Functions in Rust

You've been tasked with integrating a pre-existing C library into your Rust project. This C library exposes a set of utility functions, but Rust cannot directly call C code. Your challenge is to create safe and robust Foreign Function Interface (FFI) bindings in Rust to interact with these C functions. This is a fundamental skill for leveraging existing C codebases or system libraries within Rust applications.

Problem Description

Your goal is to create a Rust module that acts as an intermediary between your Rust code and a simple C library. This involves defining Rust equivalents for the C data types and functions, and then using these definitions to call the C functions from Rust. The primary focus is on ensuring memory safety and correctness when crossing the FFI boundary.

What needs to be achieved:

1. Define Rust representations for the C functions provided.
2. Call these C functions from Rust code.
3. Handle data type conversions between Rust and C safely.
4. Ensure proper memory management when passing data across the FFI boundary.

Key requirements:

• You must use the #[link] attribute to specify the C library.
• You must use extern "C" blocks to declare the C functions.
• You must use Rust's FFI-safe types (e.g., c_int, *const c_char, *mut c_void).
• You should provide Rust-idiomatic wrappers around the raw FFI calls to enhance safety and ease of use.

Expected behavior:

Your Rust code should successfully compile and run, demonstrating that it can call the C functions and receive their results correctly. The Rust wrappers should abstract away the raw FFI details, providing a safer interface for other Rust code.

Important edge cases to consider:

• Null pointers: How do you handle potentially null pointers passed from C or returned to C?
• String handling: C strings (char*) are null-terminated. How do you safely convert between Rust String or &str and C strings?
• Mutable data: How do you safely pass mutable data to C functions that modify it?

Examples

Let's assume you have a C library (which you'll need to create or simulate for this challenge) with the following functions:

C Library (mylib.c):

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

// Adds two integers
int add_integers(int a, int b) {
    return a + b;
}

// Reverses a string in place
void reverse_string(char* str) {
    if (!str) return;
    int len = strlen(str);
    for (int i = 0; i < len / 2; i++) {
        char temp = str[i];
        str[i] = str[len - i - 1];
        str[len - i - 1] = temp;
    }
}

// Allocates memory for a string, copies content, and returns it
char* create_greeting(const char* name) {
    if (!name) return NULL;
    const char* prefix = "Hello, ";
    size_t name_len = strlen(name);
    size_t prefix_len = strlen(prefix);
    char* greeting = (char*)malloc(prefix_len + name_len + 1); // +1 for null terminator
    if (!greeting) return NULL;
    strcpy(greeting, prefix);
    strcat(greeting, name);
    return greeting;
}

// Frees memory previously allocated by create_greeting
void free_string(char* str) {
    free(str);
}

Example 1:

Input:
Rust code calls `add_integers` with `a = 5`, `b = 10`.

Output:
The Rust code receives the integer `15`.

Explanation:
Rust calls the C function `add_integers` through its FFI bindings and prints the returned sum.

Example 2:

Input:
Rust code calls `reverse_string` with a mutable string buffer.

Rust `String`: "Rust"
C `char*` representation: A mutable buffer containing "Rust\0"

Output:
The Rust `String` is modified to "tsuR" after the C function call.

Explanation:
Rust passes a mutable pointer to its string data to the C function, which modifies it in place.

Example 3:

Input:
Rust code calls `create_greeting` with a Rust `&str` "World".
Rust code then calls `free_string` to deallocate the returned C string.

Output:
The Rust code receives a `String` "Hello, World" and memory is correctly deallocated.

Explanation:
Rust passes a C-string representation of "World" to `create_greeting`. The C function allocates memory and returns a `char*`. Rust receives this pointer, converts it to a Rust `String`, and then calls `free_string` to prevent memory leaks.

Constraints

• The C library functions (add_integers, reverse_string, create_greeting, free_string) are assumed to be available in a shared or static library named mylib.
• You must provide a Rust module that can be imported and used by other Rust code.
• The Rust wrappers should not panic on valid C inputs (e.g., null pointers where appropriate according to C function semantics).
• No unsafe code should be used in the Rust wrappers; all unsafe operations must be encapsulated within the extern "C" block or carefully handled.
• Memory allocated by C functions must be deallocated using the corresponding C deallocation function.

Notes

• You will likely need to create a simple C project (e.g., using gcc or clang) to compile the provided C code into a library that your Rust project can link against.
• Consider using crates like libc for C-compatible types and std::ffi for string conversion utilities.
• Think about how to represent C pointers and strings in Rust safely.
• The core challenge is to bridge the gap between Rust's ownership and borrowing system and C's manual memory management and pointer-based operations.