mbox 0.3.0

malloc-based box. Supports wrapping pointers or null-terminated strings returned from malloc as a Rust type, which will be free'd on drop.
Documentation

mbox: malloc-based box

Travis (Linux and OS X) Build status AppVeyor (Windows) Build status Coverage Status crates.io MIT

This crate provides structures that wrap pointers returned from malloc as a Box, and automatically free them on drop. These types allow you to interact with pointers and null-terminated strings and arrays in a Rusty style.

Examples

extern crate libc;
extern crate mbox;

use libc::{c_char, malloc, strcpy};
use mbox::MString;

// Assume we have a C function that returns a malloc'ed string.
unsafe extern "C" fn create_str() -> *mut c_char {
    let ptr = malloc(12) as *mut c_char;
    strcpy(ptr, b"Hello world\0".as_ptr() as *const c_char);
    ptr
}

fn main() {
    // we wrap the null-terminated string into an MString.
    let string = unsafe { MString::from_raw_unchecked(create_str()) };

    // check the content is expected.
    assert_eq!(&*string, "Hello world");

    // the string will be dropped by `free` after the code is done.
}

Installation

Add this to your Cargo.toml:

[dependencies]
mbox = "0.3"

Usage

This crate provides three main types, all of which uses the system's malloc/free as the allocator.

  • MBox<T> — Similar to Box<T>.
  • MString — Similar to std::ffi::CString.
  • MArray<T> — A null-terminated array, which can be used to represent e.g. array of C strings terminated by a null pointer.

#![no_std]

You may compile mbox and disable the std feature to not link to std (it will still link to core.

[dependencies]
mbox = { version = "0.3", default-features = false }

When #![no_std] is activated, you cannot convert an MString into a std::ffi::CStr, as the type simply does not exist 🙂.

Migrating from other crates

Note that MBox does not support custom allocator. If the type requires custom allocation, MBox cannot serve you.

  • malloc_bufMallocBuffer<T> is equivalent to MBox<[T]>. Note however we will not check for null pointers.

  • cbox — When not using a custom DisposeRef, the CSemiBox<'static, T> type is equivalent to MBox<T>, and CBox<T> is equivalent to &'static T.

  • c_vec — When using free as the destructor, CVec<T> is equivalent to MBox<[T]> and CSlice<T> as [T].