.TH MALLOC 3
.SH NAME
    malloc, mfree, realloc - userspace heap allocation

.SH SYNOPSIS
.BI     void* montauk::malloc(uint64_t size);
.BI     void montauk::mfree(void* ptr);
.BI     void* montauk::realloc(void* ptr, uint64_t size);

.SH DESCRIPTION
    The userspace heap provides dynamic memory allocation on top of
    anonymous virtual memory. The Montauk C++ API and libc's
    malloc/free API use the same process-wide allocator.

.SS malloc
    Allocates 'size' bytes from the free list. Returns a 16-byte
    aligned pointer, or nullptr on failure. When the free list is
    empty, it reserves more pages from the kernel. Physical pages
    are committed as they are first touched.

        char* buf = (char*)montauk::malloc(1024);

.SS mfree
    Returns the block to the userspace allocator. Arena blocks are
    immediately reusable; large direct mappings are returned to the
    kernel, including their virtual address range.
    Passing nullptr is a safe no-op.

        montauk::mfree(buf);

.SS realloc
    Resizes the allocation to 'size' bytes. A block with sufficient
    capacity is retained; otherwise a new block is allocated, the
    smaller of old/new requested sizes is copied, and the old block
    is freed. Integer overflow fails without changing the old block.
    If ptr is nullptr, behaves like malloc.

        buf = (char*)montauk::realloc(buf, 2048);

.SH IMPLEMENTATION
    The allocator uses segregated size-class bins and a coalescing
    address-ordered overflow list. Headers retain both requested size
    and actual block extent. A process-wide lock serializes C and C++
    allocation calls. All returned pointers are 16-byte aligned.

    Allocations of 256 KiB or more use direct page mappings so they
    can be released promptly. Smaller allocations use growing arenas.

.SH LOW-LEVEL PAGE API
    For large allocations or when direct page control is needed:

        void* montauk::alloc(uint64_t size);  // SYS_ALLOC
        void  montauk::free(void* ptr);       // SYS_FREE

    alloc() reserves zero-filled, read/write, non-executable pages.
    Size is rounded up to 4 KiB. Freed ranges are reusable.

.SH SEE ALSO
    syscalls(2), file(2)