7a:T4ea,Every programmer begins their journey with the traditional I/O model: open a file, read bytes into a buffer, process them, write bytes back, and close. This model is conceptually clean, universally understood, and taught in every introductory programming course. But beneath this simplicity lies a profound inefficiency that becomes painfully apparent at scale. **Consider what happens during a traditional read() call:** 1. Your application executes `read(fd, buffer, n)`, triggering a context switch to kernel mode 2. The kernel checks if the requested data exists in its **page cache** (buffer cache) 3. If not present, the kernel issues a disk I/O operation and blocks your process 4. When data arrives, it's first copied into the kernel's page cache 5. The kernel then copies the data **again** from page cache to your user-space buffer 6. Control returns to your application with another context switch This double-copy architecture—from disk to kernel buffer, then from kernel buffer to user buffer—was the accepted paradigm for decades. But what if we could eliminate that second copy entirely? What if your application could access file contents *directly* through memory operations, as if the file were simply an array in your address space?7b:T631,#include #include #include #include #include #include int main(int argc, char *argv[]) { if (argc != 2) { fprintf(stderr, "Usage: %s ", argv[0]); exit(EXIT_FAILURE); } // Step 1: Open the file int fd = open(argv[1], O_RDONLY); if (fd == -1) { perror("open"); exit(EXIT_FAILURE); } // Step 2: Get file size using fstat struct stat sb; if (fstat(fd, &sb) == -1) { perror("fstat"); close(fd); exit(EXIT_FAILURE); } // Step 3: Memory-map the file void *mapped = mmap( NULL, // addr: let kernel choose the address sb.st_size, // length: map entire file PROT_READ, // prot: read-only access MAP_PRIVATE, // flags: changes won't affect file fd, // fd: file descriptor to map 0 // offset: start from beginning of file ); if (mapped == MAP_FAILED) { perror("mmap"); close(fd); exit(EXIT_FAILURE); } // Step 4: File descriptor can be closed after mapping // The mapping remains valid close(fd); // Step 5: Access file contents through memory // Write first 100 bytes (or less) to stdout write(STDOUT_FILENO, mapped, sb.st_size < 100 ? sb.st_size : 100); // Step 6: Unmap when done if (munmap(mapped, sb.st_size) == -1) { perror("munmap"); exit(EXIT_FAILURE); } return 0; }7c:T55e,The first parameter, `addr`, specifies where in your process's virtual address space you want the mapping to appear. This parameter's behavior depends critically on whether you include MAP_FIXED in the flags. **When addr is NULL:** The kernel has complete freedom to choose an appropriate location. This is the most common and **recommended** usage. The kernel's memory manager will find a suitable hole in your virtual address space, taking into account: - Existing mappings (avoiding conflicts) - Architecture-specific constraints (alignment, special regions) - Address Space Layout Randomization (ASLR) security requirements - Optimal placement for memory allocator efficiency **When addr is non-NULL without MAP_FIXED:** The address is treated as a *hint*. The kernel attempts to create the mapping at the specified address, but if that location is unavailable (already mapped, or otherwise unsuitable), it will choose a different address. Your code must always use the returned pointer, never assume the hint was honored. **When addr is non-NULL with MAP_FIXED:** This is a **hard requirement**. The kernel must place the mapping exactly at the specified address, or fail entirely. If an existing mapping overlaps with the requested region, **that existing mapping is silently unmapped**—replaced by the new mapping. This behavior is intentional but dangerous.7d:T40a,**Modern Alternative: MAP_FIXED_NOREPLACE (Linux 4.17+):** Recognizing the dangers of MAP_FIXED, Linux introduced MAP_FIXED_NOREPLACE. This flag requests exact address placement but *fails* rather than replacing an existing mapping: ```c // Safe fixed-address mapping void *ptr = mmap( desired_addr, length, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS | MAP_FIXED_NOREPLACE, -1, 0 ); if (ptr == MAP_FAILED) { if (errno == EEXIST) { // Address already mapped - handle gracefully } } ``` **Page Alignment Requirements:** Whether specified as a hint or requirement, the addr parameter (when non-NULL) must be page-aligned. If you specify an address that doesn't fall on a page boundary, the kernel typically rounds down to the nearest page (behavior may vary by implementation). For explicit control, calculate page-aligned addresses: ```c long page_size = sysconf(_SC_PAGESIZE); // 4096 on most systems void *aligned_addr = (void *)((uintptr_t)desired_addr & ~(page_size - 1)); ```7e:T460,**The SIGBUS Trap:** One of the most confusing aspects of memory-mapped files is the SIGBUS signal. When you access a mapped region that corresponds to bytes beyond the end of the underlying file, the kernel delivers SIGBUS (Bus Error), not SIGSEGV (Segmentation Fault). Consider this dangerous pattern: ```c int fd = open("small_file.txt", O_RDONLY); // File is 100 bytes void *map = mmap(NULL, 4096, PROT_READ, MAP_PRIVATE, fd, 0); // This works fine: char first_byte = ((char *)map)[0]; // This causes SIGBUS, not SIGSEGV: char byte_1000 = ((char *)map)[1000]; // File only has 100 bytes! ``` **Why SIGBUS Instead of SIGSEGV?** The distinction is architecturally significant: - **SIGSEGV** indicates you accessed an address outside any valid mapping—there's no page table entry at all - **SIGBUS** indicates the mapping exists (page table entry present), but the underlying physical resource is invalid—you're accessing a page that's mapped but has no backing store When the accessed offset exceeds the file size, there's no corresponding block on disk. The page is mapped but empty, leading to SIGBUS.7f:T4f3,**PROT_EXEC and W^X (Write XOR Execute) Policy:** Modern security practices enforce W^X: memory should be either writable OR executable, but never both simultaneously. This prevents code injection attacks where an attacker writes malicious code to a buffer and then executes it. Many operating systems now enforce W^X by default: - **OpenBSD**: Strict W^X enforcement, PROT_WRITE | PROT_EXEC fails - **macOS**: Requires special entitlements for simultaneous W+X - **Linux**: Configurable via SELinux, some distros enforce it - **Windows**: DEP (Data Execution Prevention) provides similar protection **For JIT Compilers:** Just-In-Time compilers must work around W^X by: 1. Mapping memory initially as PROT_READ | PROT_WRITE 2. Writing generated code into the pages 3. Using mprotect() to change protection to PROT_READ | PROT_EXEC 4. Then executing the code ```c // JIT compilation pattern void *code_buffer = mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); generate_machine_code(code_buffer); // Write code bytes mprotect(code_buffer, size, PROT_READ | PROT_EXEC); // Make executable typedef int (*func_t)(void); func_t jit_function = (func_t)code_buffer; int result = jit_function(); // Execute generated code ```80:T44c,**PROT_NONE: Guard Pages and Address Reservation:** Although PROT_NONE creates pages that cannot be accessed at all, this has important uses: **Guard Pages:** Protect against buffer overflows and stack overflow. Place PROT_NONE pages at the boundaries of buffers or around the stack. Any overflow that touches the guard page immediately triggers SIGSEGV, catching the bug early. ```c // Create a buffer with guard pages size_t page_size = sysconf(_SC_PAGESIZE); size_t protected_size = buffer_size + 2 * page_size; void *region = mmap(NULL, protected_size, PROT_NONE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); // Make middle portion accessible void *buffer = (char *)region + page_size; mprotect(buffer, buffer_size, PROT_READ | PROT_WRITE); // Now 'buffer' is guarded on both ends ``` **Address Reservation:** Reserve a large contiguous virtual address region without consuming physical memory. Later, use mprotect() to make portions accessible as needed. This technique is used by custom allocators and garbage collectors to ensure memory growth doesn't require copying data to new locations.81:T65a,The `fd` (file descriptor) and `offset` parameters together specify which file and which portion of that file to map. **The File Descriptor:** For file-backed mappings, fd must be an open file descriptor with appropriate access rights: ```c int fd = open("data.bin", O_RDWR); // For MAP_SHARED with PROT_WRITE int fd = open("data.bin", O_RDONLY); // Sufficient for MAP_PRIVATE even with PROT_WRITE ``` **File Descriptor Lifecycle:** A commonly misunderstood point: **the file descriptor can be closed immediately after mmap() returns**. The mapping maintains its own reference to the underlying file (technically, to the struct file in kernel space). This means: ```c int fd = open("file.txt", O_RDONLY); void *map = mmap(NULL, size, PROT_READ, MAP_PRIVATE, fd, 0); close(fd); // Perfectly safe! Mapping remains valid. // Continue using 'map' for as long as needed printf("%s", (char *)map); munmap(map, size); // Clean up when done ``` This behavior enables cleaner code—you don't need to track file descriptors for the lifetime of mappings. **For Anonymous Mappings:** When using MAP_ANONYMOUS, the fd parameter should be -1. Some older Unix systems require fd to be -1; others ignore it. For maximum portability, always pass -1. **The offset Parameter:** The offset specifies where within the file the mapping should begin. Two critical requirements: 1. **Must be page-aligned:** The offset must be a multiple of the system page size. Non-page-aligned offsets cause mmap() to fail with EINVAL. 2. **Affects file positioning:** The mapping begins at file position `offset` and extends for `length` bytes.82:T591,#include #include #include #include #include // Map a section of a file, starting at a given offset // Returns NULL on failure void *map_file_section(const char *path, off_t offset, size_t length) { long page_size = sysconf(_SC_PAGESIZE); // Calculate page-aligned offset off_t aligned_offset = offset & ~(page_size - 1); size_t offset_diff = offset - aligned_offset; // Adjust length to include bytes before the requested offset size_t adjusted_length = length + offset_diff; int fd = open(path, O_RDONLY); if (fd == -1) { perror("open"); return NULL; } void *map = mmap(NULL, adjusted_length, PROT_READ, MAP_PRIVATE, fd, aligned_offset); close(fd); if (map == MAP_FAILED) { perror("mmap"); return NULL; } // Return pointer to the actual requested offset // Caller must remember to unmap starting at (ptr - offset_diff) // and using adjusted_length return (char *)map + offset_diff; } /* * Usage note: This function demonstrates the page-alignment * complexity. A production version would need to return * additional metadata for proper cleanup. * * Better approach: Create a struct containing: * - Pointer to user-requested offset * - Pointer to actual mapping start * - Actual mapping length */83:T76f,#include #include #include #include typedef struct { void *address; // Mapped address (NULL on failure) size_t length; // Actual mapped length int error_code; // errno value on failure const char *error_msg; // Human-readable error } MmapResult; MmapResult safe_mmap(size_t length, int prot, int flags, int fd, off_t offset) { MmapResult result = {0}; // Pre-validate obvious errors if (length == 0) { result.error_code = EINVAL; result.error_msg = "Length cannot be zero"; return result; } // Check page alignment of offset long page_size = sysconf(_SC_PAGESIZE); if (offset % page_size != 0) { result.error_code = EINVAL; result.error_msg = "Offset must be page-aligned"; return result; } void *map = mmap(NULL, length, prot, flags, fd, offset); if (map == MAP_FAILED) { result.error_code = errno; // Provide detailed error messages switch (errno) { case EACCES: result.error_msg = "Protection incompatible with file access mode"; break; case ENOMEM: result.error_msg = "Insufficient memory or address space"; break; case ENODEV: result.error_msg = "Filesystem does not support memory mapping"; break; default: result.error_msg = strerror(errno); } return result; } result.address = map; result.length = length; result.error_code = 0; result.error_msg = NULL; return result; } // Usage example: // MmapResult r = safe_mmap(file_size, PROT_READ, MAP_PRIVATE, fd, 0); // if (r.address == NULL) { // fprintf(stderr, "mmap failed: %s ", r.error_msg); // }84:T454,Understanding what happens inside the kernel during an mmap() call illuminates why certain behaviors exist and helps predict performance characteristics. **The Virtual Memory Area (VMA):** When mmap() succeeds, the kernel creates a **Virtual Memory Area (VMA)** structure that describes the mapping. In Linux, this is `struct vm_area_struct`. Each VMA contains: - Start and end addresses of the mapping - Protection flags (translated to architecture-specific page table bits) - Flags (shared/private, etc.) - Pointer to the mapped file (if file-backed) - Offset within the file - Operations table (for handling page faults, etc.) **What mmap() Does NOT Do:** Critically, mmap() typically does **not**: 1. **Allocate physical RAM:** No physical pages are allocated for the mapping (unless MAP_POPULATE is specified) 2. **Read file contents:** No I/O occurs to fetch file data 3. **Create page table entries:** Pages are not mapped in hardware page tables Mmap() merely creates the VMA—a promise that "if you access addresses in this range, the kernel knows what to do." The heavy lifting is deferred.85:T54e,**Page Fault Handling:** The deferred nature means that actual I/O happens during **page faults**: 1. Application accesses address within the mapped region 2. CPU consults page table—no entry exists (or entry is marked not-present) 3. CPU raises a page fault exception 4. Kernel's page fault handler runs: - Finds the VMA containing the faulting address - Determines this is a valid access (not a bug/attack) - For file-backed: checks page cache for this file+offset - If not cached: allocates physical page, issues disk I/O - Creates page table entry mapping virtual → physical 5. Returns from exception; CPU retries the faulting instruction 6. Access now succeeds This demand-paging approach means: - Starting a process is fast (don't need to load entire executable) - Memory is allocated only when actually used - Unused portions of mapped files consume zero RAM **Page Cache Sharing:** The page cache is the key to mmap efficiency. When multiple processes map the same file: - The kernel recognizes they're mapping the same file (via inode) - All maps share the same physical pages in the page cache - Only one copy exists in RAM, regardless of how many processes use it This is why shared libraries (.so/.dll files) are so efficient—the code pages exist once in physical memory, mapped into potentially thousands of processes.72:{"json":{"id":"seed_ae3a1d32601e92e36d2eecf238854ea6","slug":"memory-mapped-files","category":"Operating Systems","topic":"Virtual Memory","title":"Memory-Mapped Files","description":"Master the powerful mechanism of memory-mapped files, understanding how operating systems enable direct memory access to file contents through virtual memory, eliminating explicit read/write system calls and enabling efficient inter-process communication.","difficulty":"ADVANCED","estimatedMinutes":90,"pages":[{"id":"seed_f34e1a06b3cb77352d3d128a17173942","title":"mmap() System Call","order":0,"content":[{"id":"opening-hook","title":"The Bridge Between Files and Memory","content":[{"data":{"content":"$7a"},"type":"text"},{"data":{"icon":"Target","title":"What You Will Master","content":"By the end of this page, you will have comprehensive understanding of the mmap() system call—its complete signature, every parameter's purpose, all flags and their interactions, return value semantics, error conditions, and the kernel mechanisms that make memory mapping possible. You'll understand not just *how* to use mmap(), but *why* each design decision was made.","variant":"info"},"type":"callout"}]},{"id":"mmap-interface","title":"The mmap() System Call Interface","content":[{"data":{"content":"The `mmap()` system call is the POSIX interface for creating memory mappings. Its signature reveals the rich flexibility of the mechanism:\n\n```c\n#include \n\nvoid *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);\n```\n\nAt first glance, this six-parameter signature appears daunting. But each parameter addresses a specific aspect of the mapping contract between your application and the operating system. Let's dissect them systematically."},"type":"text"},{"data":{"rows":[["addr","void *","Hint for where to place the mapping in virtual address space","NULL (let kernel choose), or specific address"],["length","size_t","Size of the mapping in bytes","File size, page-multiple sizes"],["prot","int","Memory protection flags (access permissions)","PROT_READ, PROT_WRITE, PROT_EXEC"],["flags","int","Mapping behavior flags","MAP_SHARED, MAP_PRIVATE, MAP_ANONYMOUS"],["fd","int","File descriptor of the file to map","Valid fd, or -1 for anonymous mappings"],["offset","off_t","Offset within the file where mapping begins","0, or page-aligned offset"]],"caption":"mmap() Parameter Overview","headers":["Parameter","Type","Purpose","Common Values"]},"type":"table"},{"data":{"content":"**Return Value Semantics:**\n\nOn success, `mmap()` returns a pointer to the mapped region—the starting virtual address of the new mapping. On failure, it returns **MAP_FAILED** (which is `(void *) -1`) and sets `errno` to indicate the specific error.\n\n**Critical Implementation Detail:** Unlike many system calls that return -1 on error, mmap() returns `MAP_FAILED`. This distinction matters because a NULL return could theoretically be a valid mapping address (though mapping at address 0 is typically prevented by modern kernels for security reasons)."},"type":"text"},{"data":{"fileName":"basic_mmap_usage.c","languages":[{"code":"$7b","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":1},{"id":"addr-parameter","title":"The addr Parameter: Address Hint or Requirement","content":[{"data":{"content":"$7c"},"type":"text"},{"data":{"icon":"AlertCircle","title":"MAP_FIXED Danger Zone","content":"Using MAP_FIXED with an arbitrary address can corrupt your process's address space. If you accidentally specify an address that overlaps your stack, heap, or code segment, mmap() will silently replace those critical regions with your new mapping, causing immediate and mysterious crashes. Use MAP_FIXED only when you have precise knowledge of your address space layout—typically in specialized scenarios like implementing custom allocators or runtime loaders.","variant":"warning"},"type":"callout"},{"data":{"content":"$7d"},"type":"text"}],"titleType":"number","titleNumber":2},{"id":"length-parameter","title":"The length Parameter: Mapping Extent","content":[{"data":{"content":"The `length` parameter specifies the size of the mapping in bytes. The relationship between length and page boundaries is subtle but critical for correct usage.\n\n**Automatic Page Rounding:**\n\nInternally, the kernel rounds the length up to the nearest page boundary. If you request a 100-byte mapping, you'll actually get at least one full page (typically 4096 bytes). However, **accessing bytes beyond your specified length but within the mapped pages is undefined behavior**—the kernel may or may not fault on such accesses, leading to non-portable code.\n\n**Relationship to File Size:**\n\nWhen mapping files, the interplay between length and file size creates several scenarios:"},"type":"text"},{"data":{"rows":[["length == file_size","Perfect fit—entire file mapped","Optimal case, common usage pattern"],["length < file_size","Partial mapping—only specified bytes mapped","Valid for processing file sections"],["length > file_size","Mapped region extends beyond EOF","Accessing bytes beyond EOF causes SIGBUS"],["length = 0","Mapping fails with EINVAL","Zero-length mappings are prohibited"]],"caption":"length vs. File Size Scenarios","headers":["Scenario","Behavior","Implications"]},"type":"table"},{"data":{"content":"$7e"},"type":"text"},{"data":{"icon":"Lightbulb","title":"Safe Length Calculation","content":"Always use fstat() to get the exact file size, and use that size (or less) as your length parameter. Never map beyond the file's current size unless you've explicitly extended the file (using ftruncate() or write operations) beforehand.","variant":"tip"},"type":"callout"},{"data":{"fileName":"safe_length_handling.c","languages":[{"code":"#include \n#include \n#include \n#include \n#include \n\nvoid *safe_mmap_file(const char *path, size_t *out_size) {\n int fd = open(path, O_RDONLY);\n if (fd == -1) return NULL;\n \n struct stat sb;\n if (fstat(fd, &sb) == -1) {\n close(fd);\n return NULL;\n }\n \n // Handle empty files specially\n if (sb.st_size == 0) {\n close(fd);\n *out_size = 0;\n return NULL; // Can't map empty files\n }\n \n // Map exactly the file size - no more, no less\n void *map = mmap(NULL, sb.st_size, PROT_READ, MAP_PRIVATE, fd, 0);\n close(fd); // Safe to close after mapping\n \n if (map == MAP_FAILED) return NULL;\n \n *out_size = sb.st_size;\n return map;\n}\n\n// Usage:\n// size_t size;\n// void *data = safe_mmap_file(\"config.txt\", &size);\n// // Now 'size' contains exact number of accessible bytes","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":3},{"id":"prot-parameter","title":"The prot Parameter: Protection Flags","content":[{"data":{"content":"The `prot` parameter specifies the memory protection for the mapped region. These flags are combined using bitwise OR and determine what operations the CPU will permit on the mapped pages."},"type":"text"},{"data":{"rows":[["PROT_NONE","0x0","Pages cannot be accessed at all","Any access triggers SIGSEGV"],["PROT_READ","0x1","Pages can be read","Read operations permitted"],["PROT_WRITE","0x2","Pages can be written","Write operations permitted"],["PROT_EXEC","0x4","Pages can contain executable code","CPU can fetch instructions from these pages"]],"caption":"Memory Protection Flags","headers":["Flag","Value (typical)","Meaning","CPU Enforcement"]},"type":"table"},{"data":{"content":"**Common Combinations:**\n\n```c\nPROT_READ // Read-only mapping (data files)\nPROT_READ | PROT_WRITE // Read-write mapping (modifiable data)\nPROT_READ | PROT_EXEC // Executable code (shared libraries)\nPROT_READ | PROT_WRITE | PROT_EXEC // JIT compilation buffers\nPROT_NONE // Guard pages, reserved address space\n```\n\n**Interaction with File Permissions:**\n\nThe protection flags must be compatible with how the file was opened:\n\n- `PROT_READ` requires the file to be opened with `O_RDONLY` or `O_RDWR`\n- `PROT_WRITE` with `MAP_SHARED` requires `O_RDWR` (writes go to file)\n- `PROT_WRITE` with `MAP_PRIVATE` only requires `O_RDONLY` (writes are private, COW)\n- `PROT_EXEC` may have additional restrictions (see below)\n\nIf you request protections incompatible with the file descriptor's mode, mmap() fails with `EACCES`."},"type":"text"},{"data":{"icon":"Info","title":"Hardware Protection Granularity","content":"Protection is enforced at page granularity by the CPU's Memory Management Unit (MMU). You cannot have different protections for different bytes within the same page. The page table entry contains protection bits that the MMU checks on every memory access. Violations trigger processor exceptions that the kernel converts to signals.","variant":"note"},"type":"callout"},{"data":{"content":"$7f"},"type":"text"},{"data":{"content":"$80"},"type":"text"}],"titleType":"number","titleNumber":4},{"id":"flags-parameter","title":"The flags Parameter: Mapping Behavior","content":[{"data":{"content":"The `flags` parameter controls the fundamental characteristics of the mapping—whether changes are visible to other processes, whether the mapping backs a file or anonymous memory, and various behavioral modifiers. This is the most complex parameter, with flags organized into categories:\n\n**Mandatory Flags (exactly one required):**"},"type":"text"},{"data":{"rows":[["MAP_SHARED","Changes shared with other mappings and written to file","Writes update the file (eventually)","Other processes see changes"],["MAP_PRIVATE","Copy-on-write private mapping","Writes create private copies","Changes invisible to others"]],"caption":"Primary Mapping Type Flags","headers":["Flag","Description","Write Behavior","Visibility"]},"type":"table"},{"data":{"content":"You must specify exactly one of MAP_SHARED or MAP_PRIVATE. Omitting both, or specifying both, results in undefined behavior (though most implementations treat it as an error).\n\n**Optional Modifier Flags:**"},"type":"text"},{"data":{"rows":[["MAP_ANONYMOUS","Mapping not backed by any file","Allocating memory, shared memory without files"],["MAP_FIXED","Interpret addr exactly, not as hint","Replacing existing mappings, custom loaders"],["MAP_FIXED_NOREPLACE","Like MAP_FIXED but fail if address in use","Safe fixed placement (Linux 4.17+)"],["MAP_NORESERVE","Don't reserve swap space upfront","Sparse mappings, overcommit-aware allocation"],["MAP_POPULATE","Pre-fault all pages immediately","Avoid page faults on first access"],["MAP_LOCKED","Lock pages in RAM (like mlock)","Real-time applications, cryptographic keys"],["MAP_HUGETLB","Use huge pages for this mapping","Large working sets, TLB efficiency"],["MAP_STACK","Hint that this is stack memory","Stack allocation (used by threading libraries)"]],"caption":"Optional Mapping Modifier Flags","headers":["Flag","Description","Typical Use Case"]},"type":"table"},{"data":{"content":"**MAP_ANONYMOUS Deep Dive:**\n\nAnonymous mappings don't correspond to any file. Instead, they're backed by the system's swap space (if any) and are initialized to zero. This is actually how most modern memory allocators (malloc implementations) obtain memory from the operating system for large allocations.\n\n```c\n// Anonymous private mapping - like malloc() for large blocks\nvoid *heap_block = mmap(NULL, 1024 * 1024,\n PROT_READ | PROT_WRITE,\n MAP_PRIVATE | MAP_ANONYMOUS,\n -1, // fd must be -1 (or ignored, depending on implementation)\n 0 // offset must be 0 (or ignored)\n);\n```\n\nAdvantages of anonymous mmap over malloc for large allocations:\n- Guaranteed page-aligned addresses\n- Memory automatically zero-initialized by kernel\n- munmap() immediately returns memory to OS (no memory pool fragmentation)\n- Explicit control over mapping characteristics"},"type":"text"},{"data":{"icon":"Zap","title":"MAP_POPULATE for Performance","content":"When you know you'll access the entire mapping immediately, use MAP_POPULATE. This causes the kernel to read all file pages into memory during the mmap() call itself, rather than faulting them in one-by-one on first access. The mmap() call takes longer, but subsequent access patterns become predictable with no page faults interrupting your computation.","variant":"tip"},"type":"callout"}],"titleType":"number","titleNumber":5},{"id":"fd-offset-parameters","title":"The fd and offset Parameters: File Binding","content":[{"data":{"content":"$81"},"type":"text"},{"data":{"fileName":"partial_file_mapping.c","languages":[{"code":"$82","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"},{"data":{"content":"**Mapping Beyond File End:**\n\nIf offset + length exceeds the file size at the time of mmap(), the behavior depends on how far beyond:\n\n- **Within the last mapped page:** The kernel zero-fills bytes between EOF and the page boundary. Accessing these zeros is safe (reads return zero, writes to MAP_PRIVATE work but are discarded on munmap, writes to MAP_SHARED may extend the file).\n\n- **Beyond the last mapped page:** Accessing these addresses triggers SIGBUS.\n\n**Windows Comparison:**\n\nOn Windows, the equivalent is `CreateFileMapping()` + `MapViewOfFile()`. While the concepts are similar, Windows uses a two-step process and has different parameter semantics. Cross-platform code must abstract these differences."},"type":"text"}],"titleType":"number","titleNumber":6},{"id":"error-handling","title":"Comprehensive Error Handling","content":[{"data":{"content":"When mmap() fails, it returns MAP_FAILED and sets `errno` to indicate the specific error. Understanding these errors is essential for robust code:"},"type":"text"},{"data":{"rows":[["EACCES","Protection flags incompatible with file open mode","Open file with correct mode (O_RDWR for MAP_SHARED writes)"],["EAGAIN","File is locked, or too much memory locked","Release locks, reduce mlock usage, increase RLIMIT_MEMLOCK"],["EBADF","fd is not a valid open file descriptor","Check open() succeeded, file not already closed"],["EINVAL","Invalid arguments (length=0, offset not aligned, etc.)","Validate all parameters before calling"],["ENFILE","System-wide limit on open files reached","System administration issue - reduce open files"],["ENODEV","File system doesn't support mmap","Use traditional read/write instead"],["ENOMEM","Not enough memory, or address space limit reached","Reduce mapping size, free other mappings"],["EOVERFLOW","offset + length overflows off_t","Use 64-bit off_t (compile with _FILE_OFFSET_BITS=64)"],["EPERM","Operation not permitted (MAP_FIXED on special page, etc.)","Check permissions, avoid protected addresses"]],"caption":"mmap() Error Codes","headers":["errno","Cause","Resolution"]},"type":"table"},{"data":{"fileName":"robust_mmap_wrapper.c","languages":[{"code":"$83","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":7},{"id":"kernel-mechanics","title":"Under the Hood: Kernel Mechanics","content":[{"data":{"content":"$84"},"type":"text"},{"data":{"height":"500px","mermaidSyntax":"flowchart TD\n A[\"Application calls mmap()\"] --> B[\"Kernel validates parameters\"]\n B --> C{\"Parameters valid?\"}\n C -->|No| D[\"Return MAP_FAILED\"]\n C -->|Yes| E[\"Find free virtual address range\"]\n E --> F[\"Create VMA structure\"]\n F --> G[\"Insert VMA into process's mm_struct\"]\n G --> H[\"Return virtual address\"]\n H --> I[\"Application accesses address\"]\n I --> J[\"MMU: No page table entry!\"]\n J --> K[\"Page fault trap to kernel\"]\n K --> L[\"Kernel finds VMA for address\"]\n L --> M{\"Page in page cache?\"}\n M -->|Yes| N[\"Map existing page\"]\n M -->|No| O[\"Allocate page, read from disk\"]\n O --> N\n N --> P[\"Create page table entry\"]\n P --> Q[\"Return from fault, instruction retries\"]\n Q --> R[\"Access succeeds\"]"},"type":"mermaid-excalidraw"},{"data":{"content":"$85"},"type":"text"},{"data":{"icon":"Sparkles","title":"Key Insight","content":"The mmap() system call is fundamentally lightweight—it manipulates kernel data structures representing the mapping but defers all actual work (RAM allocation, disk I/O, page table modification) until the mapped addresses are accessed. This lazy approach is the cornerstone of efficient memory management in modern operating systems.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":8},{"id":"munmap-cleanup","title":"munmap(): Releasing Memory Mappings","content":[{"data":{"content":"Every mmap() should eventually be matched with a munmap() to release the mapping. The signature is straightforward:\n\n```c\n#include \n\nint munmap(void *addr, size_t length);\n```\n\n**Parameters:**\n- **addr**: Starting address of the mapping (as returned by mmap())\n- **length**: Size of the region to unmap\n\n**Return Value:**\n- Returns 0 on success\n- Returns -1 on failure, with errno set\n\n**Important Considerations:**"},"type":"text"},{"data":{"items":["**Partial unmapping is allowed:** You can unmap a portion of a larger mapping, creating a 'hole.' The kernel adjusts VMAs accordingly.","**Page alignment required:** Both addr and length should be page-aligned. Non-aligned values are handled (length rounded up, addr rounded down) but best practice is explicit alignment.","**For MAP_SHARED:** Dirty pages are not guaranteed to be written to disk. Use msync() before munmap() if you need durability.","**Accessing freed addresses:** After munmap(), accessing those addresses causes SIGSEGV. Ensure no threads are still using the mapping.","**Memory not immediately reclaimed:** The kernel may retain pages in the page cache for potential future use. True physical memory freeing is asynchronous.","**Doesn't close file descriptors:** If you haven't closed the fd, it remains open. The mapping and fd have independent lifecycles."],"title":{"icon":"Target","text":"munmap() Behaviors and Gotchas","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"fileName":"proper_cleanup.c","languages":[{"code":"#include \n#include \n\nvoid cleanup_mapping(void *map, size_t length, int is_shared_writeable) {\n if (map == NULL || map == MAP_FAILED) {\n return; // Nothing to clean up\n }\n \n if (is_shared_writeable) {\n // Ensure changes are persisted to disk\n if (msync(map, length, MS_SYNC) == -1) {\n perror(\"msync failed - data may not be persisted\");\n // Continue with munmap anyway\n }\n }\n \n if (munmap(map, length) == -1) {\n perror(\"munmap failed\");\n // On failure, memory may leak until process exit\n // There's no good recovery option\n }\n}\n\n// Note: For mapping sizes retrieved from struct stat,\n// length should be the exact value used in mmap().\n// Common bug: using different length values for mmap/munmap.","label":"C","value":"c"}],"showLineNumbers":true},"type":"code"}],"titleType":"number","titleNumber":9},{"id":"summary","title":"Summary: The mmap() Foundation","content":[{"data":{"content":"We've comprehensively examined the mmap() system call—the fundamental interface for memory-mapped files and anonymous memory allocation. Let's consolidate the key points:"},"type":"text"},{"data":{"type":"ordered","items":["**Six parameters** define the mapping: addr (placement), length (size), prot (protection), flags (behavior), fd (file), and offset (position)","**MAP_SHARED vs MAP_PRIVATE** is the fundamental choice—shared visibility and file updates vs private copy-on-write isolation","**Protection flags** (PROT_READ, PROT_WRITE, PROT_EXEC) are hardware-enforced at page granularity","**Offset must be page-aligned**—this is a firm kernel requirement, not a suggestion","**mmap() is lazy**—it creates kernel data structures but defers physical memory allocation and I/O to page faults","**File descriptors can be closed** after mapping—the mapping maintains its own reference","**Error handling** requires checking for MAP_FAILED (not NULL) and consulting errno","**munmap()** releases the mapping but doesn't guarantee disk synchronization—use msync() first for durability"],"title":{"icon":"CheckCircle","text":"Key Takeaways","type":"icon","color":"primary","variant":"outline-circle"},"variant":"accent"},"type":"list"},{"data":{"content":"**What's Next:**\n\nWith the mmap() interface mastered, we'll explore how memory-mapped files transform file access patterns. The next page examines the \"File as Memory\" paradigm—how treating files as byte arrays eliminates the read/write system call overhead and enables elegant solutions to complex problems."},"type":"text"},{"data":{"icon":"CheckCircle","title":"Page Complete","content":"You now have expert-level understanding of the mmap() system call interface. You know what each parameter does, how they interact, what errors can occur, and what happens inside the kernel. This foundation is essential for the deeper exploration of memory-mapped I/O patterns that follows.","variant":"success"},"type":"callout"}],"titleType":"number","titleNumber":10}],"isLocked":false},{"id":"seed_027f5004b2503d6c63613ae64a754bf2","title":"File as Memory","order":1,"content":null,"isLocked":true},{"id":"seed_a3722a59e58feb9060b4917e9d4c1b3a","title":"Lazy Loading","order":2,"content":null,"isLocked":true},{"id":"seed_7898bc340b651df5f085be4f1a2f0c72","title":"Shared Mappings","order":3,"content":null,"isLocked":true},{"id":"seed_759c3fa26cb3ffa52eb80b96e8d9f7b9","title":"Private Mappings","order":4,"content":null,"isLocked":true}]}}