# C ABI
Date: 2026-08-15
Release: 0.3.1
ABI version: 1
Platforms: x86-64 Windows and Linux
Bomalloc builds an `rlib`, dynamic library, and static library. The public C
declarations are in [`include/bomalloc.h`](../include/bomalloc.h). Every exported
name uses the `bo_` prefix; linking the library does not interpose the process C
runtime allocator.
## Build and link
```text
cargo build --release
```
Windows artifacts are `bomalloc.dll`, `bomalloc.dll.lib`, and `bomalloc.lib`.
Linux artifacts are `libbomalloc.so` and `libbomalloc.a`.
Linux dynamic linking:
```text
cc -std=c11 app.c -Iinclude -Ltarget/release -lbomalloc -o app
LD_LIBRARY_PATH=target/release ./app
```
Linux static linking:
```text
cc -std=c11 app.c -Iinclude target/release/libbomalloc.a \
-ldl -lpthread -lm -o app
```
MSVC dynamic linking from an x64 Developer Command Prompt:
```text
cl /std:c11 app.c /I include /link /LIBPATH:target\release bomalloc.dll.lib
```
Place `bomalloc.dll` beside the executable or on its DLL search path.
## Allocation API
```c
#include "bomalloc.h"
void *data = bo_calloc(1024, sizeof(unsigned));
if (data == NULL) {
/* allocation failure */
}
void *grown = bo_realloc(data, 16 * 1024);
if (grown != NULL) {
data = grown;
}
bo_free(data);
```
| `bo_malloc` | At least 16-byte alignment. A zero-size request returns a freeable non-null allocation after successful initialization. |
| `bo_calloc` | Checks multiplication overflow and zeros the requested payload. |
| `bo_aligned_alloc` | Alignment must be a power of two, at least pointer-sized; size must be divisible by alignment. |
| `bo_posix_memalign` | Uses POSIX alignment rules and leaves `*output` unchanged on failure. |
| `bo_realloc` | Preserves `min(old_size, new_size)` bytes. Null acts as malloc; zero frees and returns null. Failure leaves the old object live. |
| `bo_reallocarray` | Overflow-checked array reallocation. |
| `bo_free` | Accepts null and may run on a thread different from allocation. |
| `bo_malloc_usable_size` | Returns writable capacity, or zero for null. |
Every non-null input pointer must be a currently live allocation returned by this
C ABI. Mixing it with libc, the Windows heap, Rust `System`, another bomalloc
instance, or an already completed release is undefined behavior.
## Allocation metadata
The wrapper stores one 8-byte requested-size/alignment word before each returned
pointer. The backing base, prefix, and Rust `Layout` are derived from this word.
This permits sized Rust deallocation without exposing layouts to C callers.
Very small C allocations therefore have more internal fragmentation than direct
Rust allocation. `bo_stats_v1.c_header_bytes_per_allocation` reports the fixed
C header cost.
Core Rust live-byte counters include the wrapper header and alignment slack; they
are not an exact sum of C payload sizes. Exact C payload accounting would add a
shared atomic update to every C allocation and release.
## Initialization and errors
The allocation family is thread-safe and initializes lazily.
`bo_allocator_initialize()` requests eager initialization. Allocation failure
returns null and does not modify libc `errno`.
Management functions return one of:
- `BO_OK`;
- `BO_ENOMEM`;
- `BO_EINVAL`;
- `BO_EUNSUPPORTED`;
- `BO_EINVARIANT`;
- `BO_EPANIC`.
Invalid pointer use is a caller contract violation, not a recoverable validation
error.
## Management and versioning
`bo_allocator_abi_version()` returns `BO_ALLOCATOR_ABI_VERSION`. Versioned
statistics and trim structures contain both `abi_version` and `struct_size`:
```c
bo_stats_v1 stats = {0};
if (bo_allocator_stats_v1(&stats) == BO_OK) {
printf("committed=%llu\n", (unsigned long long)stats.committed_bytes);
}
bo_trim_stats_v1 trimmed = {0};
bo_allocator_trim_v1(BO_TRIM_EXCESS, &trimmed);
```
`BO_TRIM_AGGRESSIVE` advances the trim epoch and attempts to decommit or release
every safely free span. `bo_allocator_validate()` runs allocator invariant
checks.
ABI version 1 fixes the documented function signatures, enum values, and
structure prefixes for the 0.3.x line. A caller should initialize structures to
zero and respect `struct_size` so future versions can append fields.
## Verification and limitations
The release gate covers:
- Rust calls through the exported C calling convention;
- a real C smoke source at `tests/c_abi_smoke.c`;
- Windows and Linux Debug/Release allocator suites and Loom models;
- MSVC C11/C++17 dynamic linking;
- Linux C11 dynamic and static linking;
- packaged-crate tests, Clippy, and strict rustdoc on both operating systems.
The ABI does not provide unprefixed malloc interposition, `LD_PRELOAD`, a Windows
CRT shim, NUMA policy, or a production support guarantee. Current performance
evidence lives in [Mature allocator benchmark](mature-benchmark-results.md).