From 7de95ddd662b52c803d307b6028fd90a1aa71892 Mon Sep 17 00:00:00 2001
From: Thomas Vanbesien <tvanbesi@proton.me>
Date: Fri, 27 Feb 2026 10:31:39 +0100
Subject: Add zone allocation, internal data structures, and README

Implement mmap-based zone allocation for TINY (<=128B) and SMALL
(<=1024B) categories. malloc now creates zones on demand and
returns a pointer to the first chunk.
---
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 README.md

(limited to 'README.md')

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ef21ed7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+# ft_malloc
+
+Custom dynamic memory allocator implementing `malloc`, `free`, and `realloc` as a shared library (`libft_malloc_$HOSTTYPE.so`).
+
+42 School project.
+
+## Build
+
+```bash
+make        # build lib/libft_malloc_$HOSTTYPE.so + symlink
+make test   # build & run tests
+make clean  # remove object files
+make fclean # full clean (library, Libft, tests)
+make re     # fclean + all
+```
+
+## Usage
+
+The library is loaded at runtime via `LD_PRELOAD`, which instructs the Linux
+dynamic linker to load the specified shared library **before** any other,
+including libc. Any symbols it exports (such as `malloc`, `free`, `realloc`)
+override the default ones. This makes it a drop-in replacement with no
+recompilation needed:
+
+```bash
+LD_PRELOAD=./lib/libft_malloc.so ./my_program
+```
+
+Every call to `malloc`, `free`, or `realloc` inside `my_program` (and any
+library it uses) will go through `ft_malloc` instead of the system allocator.
+
+## API
+
+| Function | Description |
+|---|---|
+| `void *malloc(size_t size)` | Allocate `size` bytes |
+| `void free(void *ptr)` | Release a previously allocated block |
+| `void *realloc(void *ptr, size_t size)` | Resize a block to `size` bytes |
+| `void show_alloc_mem(void)` | Print all zones and allocations to stdout |
+
+## Architecture
+
+Allocations are divided into three categories:
+
+| Category | Size range | Strategy |
+|---|---|---|
+| TINY | 1 -- 128 bytes | Pre-allocated zone (fits 100+ allocations) |
+| SMALL | 129 -- 1024 bytes | Pre-allocated zone (fits 100+ allocations) |
+| LARGE | 1025+ bytes | Individual `mmap` per allocation |
+
+TINY and SMALL zones are page-aligned regions obtained via `mmap`. New zones
+are allocated on demand when the current one is full. LARGE allocations each
+get their own `mmap` region and are released individually via `munmap`.
+
+All returned pointers are 16-byte aligned.
-- 
cgit v1.2.3