cstring-array

Safe, zero-copy wrapper for passing string arrays to C FFI (char**)

This crate provides CStringArray, a safe abstraction over C's null-terminated string arrays, commonly used for command-line arguments (argv) and similar purposes.

Features

• Memory-safe: RAII-based lifetime management prevents dangling pointers
• Zero-copy: When constructed from Vec<CString>, no re-allocation occurs
• C-compatible: Produces valid char** pointers with null termination
• Ergonomic: Multiple constructors and trait implementations for easy usage
• Well-tested: 98.5%+ test coverage for reliability
• Minimal dependencies: Pure Rust with no external dependencies
• Cross-platform: Works on Linux, macOS, Windows, and more

Quick Start

Add this to your Cargo.toml:

[dependencies]
cstring-array = "0.1"

Usage

Basic Example

use cstring_array::CStringArray;
use std::ffi::c_char;

let args = vec![
    "program".to_string(),
    "--verbose".to_string(),
    "file.txt".to_string(),
];
let array = CStringArray::new(args).unwrap();

// Safe to pass to C FFI functions expecting char**
let ptr: *const *const c_char = array.as_ptr();
assert_eq!(array.len(), 3);

Construction Methods

use cstring_array::CStringArray;
use std::ffi::CString;
use std::convert::TryFrom;

// From Vec<String>
let arr1 = CStringArray::new(vec!["foo".to_string(), "bar".to_string()]).unwrap();

// From Vec<CString> (zero-copy)
let cstrings = vec![CString::new("foo").unwrap(), CString::new("bar").unwrap()];
let arr2 = CStringArray::from_cstrings(cstrings).unwrap();

// Using TryFrom with Vec<&str>
let arr3 = CStringArray::try_from(vec!["foo", "bar"]).unwrap();

// Using TryFrom with arrays
let arr4 = CStringArray::try_from(["foo", "bar"]).unwrap();

Real-World Example: Calling C Function

use cstring_array::CStringArray;
use std::ffi::c_char;

extern "C" {
    fn execve(
        pathname: *const c_char,
        argv: *const *const c_char,
        envp: *const *const c_char,
    ) -> i32;
}

fn execute_program(path: &str, args: Vec<String>) -> Result<(), Box<dyn std::error::Error>> {
    let argv = CStringArray::new(args)?;
    let envp = CStringArray::new(vec![])?;  // Empty environment

    unsafe {
        execve(
            CString::new(path)?.as_ptr(),
            argv.as_ptr(),
            envp.as_ptr(),
        );
    }

    Ok(())
}

Error Handling

use cstring_array::{CStringArray, CStringArrayError};

// Interior null bytes are detected
let result = CStringArray::new(vec!["hello\0world".to_string()]);
assert!(matches!(result, Err(CStringArrayError::NulError(_))));

// Empty arrays are not allowed
let result = CStringArray::new(vec![]);
assert!(matches!(result, Err(CStringArrayError::EmptyArray)));

Safety Considerations

The pointer returned by CStringArray::as_ptr() is only valid for the lifetime of the CStringArray. Ensure the array outlives any C code using the pointer:

use cstring_array::CStringArray;
use std::ffi::c_char;

fn call_c_function(argv: *const *const c_char, argc: i32) {
    // ... FFI call ...
}

let array = CStringArray::new(vec!["arg1".to_string(), "arg2".to_string()]).unwrap();
let ptr = array.as_ptr();
call_c_function(ptr, array.len() as i32);
// array must not be dropped before call_c_function returns

Performance

CStringArray is designed for zero-cost abstractions:

• Zero-copy when constructed from Vec<CString>
• No re-allocation of strings, only pointer array management
• RAII cleanup without manual memory management

Benchmark Results

Last updated: 2025-10-18 23:46:35 UTC

Operations

Construction Comparison

From Cstrings Zero Copy

Large Strings

New From Strings

Sunburst Chart

The inner-most circle is the entire project, moving away from the center are folders then, finally, a single file. The size and color of each slice represents the number of statements and the coverage, respectively.

Grid Chart

Each block represents a single file in the project. The size and color of each block is represented by the number of statements and the coverage, respectively.

Icicle Chart

The top section represents the entire project, proceeding with folders and finally individual files. The size and color of each slice represents the number of statements and the coverage, respectively.

Minimum Supported Rust Version (MSRV)

This crate requires Rust 1.90 or later.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Developed by RAprogramm

Related Projects

• std::ffi::CString - Standard library C string type
• std::ffi::CStr - Borrowed C string slice