Crate mbox [] [src]

malloc-based box.

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.
}

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 using the no-std feature to not link to std (it will still link to core.

[dependencies]
mbox = { version = "0.1.3", features = ["no-std"] }

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].

Reexports

pub use mbox::MBox;
pub use sentinel::{MArray, MString};
pub use placer::MALLOC;

Modules

free

Trait to instruct how to properly drop and free pointers.

mbox

malloc-based Box.

placer

Placement-new support.

sentinel

Sentinel-terminated types.