docs - refresh man pages

docs/man/malloc.html

@@ -111,60 +111,69 @@
 <pre><code><strong>NAME</strong>
     malloc, mfree, realloc - userspace heap allocation
 
+
 <strong>SYNOPSIS</strong>
-<strong>    void* montauk::malloc(uint64_t size);</strong>
-<strong>    void montauk::mfree(void* ptr);</strong>
-<strong>    void* montauk::realloc(void* ptr, uint64_t size);</strong>
+    <strong>void* montauk::malloc(uint64_t size);</strong>
+    <strong>void montauk::mfree(void* ptr);</strong>
+    <strong>void* montauk::realloc(void* ptr, uint64_t size);</strong>
+
 
 <strong>DESCRIPTION</strong>
     The userspace heap provides dynamic memory allocation on top of
-    the kernel's page-mapping syscall (SYS_ALLOC). Include the
-    header &lt;montauk/heap.h&gt; to use these functions.
+    anonymous virtual memory. The Montauk C++ API and libc's
+    malloc/free API use the same process-wide allocator.
+
 
    <strong>malloc</strong>
     Allocates 'size' bytes from the free list. Returns a 16-byte
     aligned pointer, or nullptr on failure. When the free list is
-    empty, it requests more pages from the kernel via SYS_ALLOC
-    (minimum 16 KiB growth, initial seed of 64 KiB).
+    empty, it reserves more pages from the kernel. Physical pages
+    are committed as they are first touched.
 
         char* buf = (char*)montauk::malloc(1024);
 
+
    <strong>mfree</strong>
-    Returns the block to the userspace free list. No syscall is
-    made -- the memory stays mapped and is immediately reusable.
+    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);
 
+
    <strong>realloc</strong>
-    Resizes the allocation to 'size' bytes. Allocates a new block,
-    copies the smaller of old/new sizes, and frees the old block.
+    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);
 
-<strong>IMPLEMENTATION</strong>
-    The allocator uses a linked free-list with first-fit search.
-    Blocks larger than needed are split. The allocation header is
-    16 bytes (magic + size). All allocations are 16-byte aligned.
 
-    The heap grows by requesting pages from the kernel via
-    SYS_ALLOC. These pages are never returned to the kernel (since
-    SYS_FREE is currently a no-op), but mfree makes them available
-    for future malloc calls within the process.
+<strong>IMPLEMENTATION</strong>
+    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.
+
 
 <strong>LOW-LEVEL PAGE API</strong>
     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 (no-op)
+        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.
 
-    alloc() maps zeroed pages starting at 0x40000000 and growing
-    upward. Size is rounded up to 4 KiB page boundaries.
 
 <strong>SEE ALSO</strong>
-    syscalls(2), file(2)</code></pre>
-
+    <a href="syscalls.html">syscalls(2)</a>, <a href="file.html">file(2)</a></code></pre>
 <hr>
 
 <div class="center">