#malloc #free #ffi #box #cstr

mbox

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

13 releases

Uses old Rust 2015

0.6.0 Mar 31, 2021
0.5.0 Apr 10, 2018
0.4.4 May 17, 2018
0.4.3 Feb 5, 2018
0.1.2 Jul 5, 2016

#560 in Rust patterns

Download history 1486/week @ 2022-11-28 1335/week @ 2022-12-05 1248/week @ 2022-12-12 1168/week @ 2022-12-19 345/week @ 2022-12-26 933/week @ 2023-01-02 1321/week @ 2023-01-09 1221/week @ 2023-01-16 1635/week @ 2023-01-23 1897/week @ 2023-01-30 1280/week @ 2023-02-06 1287/week @ 2023-02-13 1355/week @ 2023-02-20 1765/week @ 2023-02-27 1396/week @ 2023-03-06 1846/week @ 2023-03-13

6,416 downloads per month
Used in 9 crates (2 directly)

MIT license

56KB
1.5K SLoC

mbox: malloc-based box

Crates.io docs.rs Build status 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.6"

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.6", 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].

Dependencies

~205KB