Getting Started

Prerequisites

  • Rust toolchain (stable channel). Install via rustup.
  • Linux x86_64 (the primary supported platform).
  • A C compiler toolchain (gcc or clang) for linking the cdylib.

Build

Clone the repository and build the release library:

git clone https://github.com/t-cun/compatmalloc.git
cd compatmalloc
cargo build --release

The output shared library is at:

target/release/libcompatmalloc.so

Basic usage with LD_PRELOAD

Inject the library into any dynamically linked program:

LD_PRELOAD=./target/release/libcompatmalloc.so <your-program>

For example:

# Run bash with compatmalloc
LD_PRELOAD=./target/release/libcompatmalloc.so bash -c 'echo "hello from hardened malloc"'

# Run Python
LD_PRELOAD=./target/release/libcompatmalloc.so python3 -c 'print("works")'

# Run a server
LD_PRELOAD=./target/release/libcompatmalloc.so ./my-server

Verify it works

You can confirm that compatmalloc is intercepting allocations by checking that the library is loaded:

LD_PRELOAD=./target/release/libcompatmalloc.so \
  bash -c 'cat /proc/self/maps | grep compatmalloc'

This should show the library mapped into the process address space.

You can also check exported symbols:

nm -D target/release/libcompatmalloc.so | grep -E ' T (malloc|free|calloc|realloc)$'

Expected output:

0000000000xxxxxx T calloc
0000000000xxxxxx T free
0000000000xxxxxx T malloc
0000000000xxxxxx T realloc

Disable at runtime

If you need to bypass the hardened allocator without removing LD_PRELOAD, set the kill-switch environment variable:

COMPATMALLOC_DISABLE=1 LD_PRELOAD=./target/release/libcompatmalloc.so <your-program>

This makes all allocator calls pass through to glibc. See Configuration for all available options.

Run the test suite

cargo test --workspace

This runs unit tests for all internal modules (size classes, bitmap, metadata table, etc.).