The full prototype of mmap() is:

#include <sys/mman.h>

void *mmap(void   *addr,    /* Hint for where to place mapping (NULL = let kernel decide) */
           size_t  length,  /* Size of the mapping in bytes                              */
           int     prot,    /* Memory protection flags                                   */
           int     flags,   /* Mapping type: MAP_PRIVATE or MAP_SHARED + optional flags  */
           int     fd,      /* File descriptor (or -1 for anonymous mapping)             */
           off_t   offset); /* Offset into the file (must be page-aligned)               */

/* Returns: starting address of mapping on success, MAP_FAILED on error */

Return value: On success, mmap() returns a pointer to the start of the mapped region. On failure it returns MAP_FAILED (which is (void *) -1), and sets errno. Always check for MAP_FAILED, not NULL.

/* Correct error check */
char *addr = mmap(NULL, length, PROT_READ, MAP_PRIVATE, fd, 0);
if (addr == MAP_FAILED) {   /* NOT: if (addr == NULL) */
    perror("mmap");
    exit(EXIT_FAILURE);
}

The flags argument controls the most important behaviour of a mapping. Exactly one of MAP_PRIVATE or MAP_SHARED must always be specified.

How MAP_PRIVATE Copy-on-Write (CoW) works:

Code example — MAP_PRIVATE (process-local changes):

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/mman.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>

int main(void)
{
    int fd;
    struct stat sb;
    char *addr;

    /* Open a file for reading */
    fd = open("testfile.txt", O_RDONLY);
    if (fd == -1) { perror("open"); exit(EXIT_FAILURE); }

    if (fstat(fd, &sb) == -1) { perror("fstat"); exit(EXIT_FAILURE); }

    /*
     * MAP_PRIVATE: any writes we make are NOT reflected in the file.
     * PROT_READ | PROT_WRITE: we can read and modify our private copy.
     */
    addr = mmap(NULL, sb.st_size,
                PROT_READ | PROT_WRITE,
                MAP_PRIVATE,
                fd, 0);
    if (addr == MAP_FAILED) { perror("mmap"); exit(EXIT_FAILURE); }

    close(fd);   /* Safe to close fd after mmap() succeeds */

    /* This modifies our private copy only - file on disk is unchanged */
    addr[0] = 'X';

    printf("First char in our mapping: %c\n", addr[0]);
    printf("File on disk is NOT changed.\n");

    munmap(addr, sb.st_size);
    return 0;
}

Code example — MAP_SHARED (changes reflected in file):

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/mman.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>

int main(void)
{
    int fd;
    char *addr;
    const size_t SIZE = 64;

    /*
     * For MAP_SHARED + PROT_WRITE, file must be opened O_RDWR.
     * Opening O_RDONLY and using MAP_SHARED + PROT_WRITE will fail with EACCES.
     */
    fd = open("shared_file.txt", O_RDWR | O_CREAT, 0644);
    if (fd == -1) { perror("open"); exit(EXIT_FAILURE); }

    /* File must be at least SIZE bytes - extend it if needed */
    if (ftruncate(fd, SIZE) == -1) { perror("ftruncate"); exit(EXIT_FAILURE); }

    addr = mmap(NULL, SIZE,
                PROT_READ | PROT_WRITE,
                MAP_SHARED,          /* Changes ARE written to the file */
                fd, 0);
    if (addr == MAP_FAILED) { perror("mmap"); exit(EXIT_FAILURE); }

    close(fd);

    /* This WILL be reflected in the file on disk */
    snprintf(addr, SIZE, "Hello from mmap MAP_SHARED!\n");

    printf("Written to file via mmap.\n");

    /* msync() ensures changes are flushed to disk before munmap */
    if (msync(addr, SIZE, MS_SYNC) == -1)
        perror("msync");

    munmap(addr, SIZE);
    return 0;
}

The prot argument controls what operations a process can perform on the mapped memory. It can be PROT_NONE, or a bitwise OR of one or more flags:

How protection violations are handled:

Code example — demonstrating memory protection:

#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <sys/mman.h>
#include <unistd.h>

void sigsegv_handler(int sig)
{
    printf("Caught SIGSEGV (%d): memory protection violation!\n", sig);
    /* In real code: log, cleanup, then exit */
    exit(EXIT_FAILURE);
}

int main(void)
{
    char *addr;
    size_t page_size = (size_t)sysconf(_SC_PAGESIZE);

    /* Install SIGSEGV handler to demonstrate protection */
    signal(SIGSEGV, sigsegv_handler);

    /*
     * Create anonymous private mapping with READ-ONLY protection.
     * MAP_ANONYMOUS: not backed by a file.
     * -1, 0 are fd and offset, ignored for anonymous mappings.
     */
    addr = mmap(NULL, page_size,
                PROT_READ,           /* Read only! */
                MAP_PRIVATE | MAP_ANONYMOUS,
                -1, 0);
    if (addr == MAP_FAILED) { perror("mmap"); exit(EXIT_FAILURE); }

    printf("Page size: %zu bytes\n", page_size);
    printf("Mapping at: %p\n", (void *)addr);
    printf("Trying to READ (allowed): first byte = %d\n", addr[0]);

    /* Attempting to WRITE will trigger SIGSEGV */
    printf("Attempting WRITE to PROT_READ region...\n");
    addr[0] = 'A';   /* This line triggers SIGSEGV */

    printf("This line will never print.\n");
    munmap(addr, page_size);
    return 0;
}

Code example — changing protection at runtime with mprotect():

#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <unistd.h>

int main(void)
{
    size_t page_size = (size_t)sysconf(_SC_PAGESIZE);
    char *addr;

    /* Start with read-only mapping */
    addr = mmap(NULL, page_size,
                PROT_READ,
                MAP_PRIVATE | MAP_ANONYMOUS,
                -1, 0);
    if (addr == MAP_FAILED) { perror("mmap"); exit(EXIT_FAILURE); }

    printf("Initial protection: PROT_READ\n");

    /* Upgrade protection to read+write using mprotect() */
    if (mprotect(addr, page_size, PROT_READ | PROT_WRITE) == -1) {
        perror("mprotect");
        munmap(addr, page_size);
        exit(EXIT_FAILURE);
    }

    printf("After mprotect: PROT_READ | PROT_WRITE\n");

    /* Now write is allowed */
    addr[0] = 'Z';
    printf("Write succeeded: addr[0] = '%c'\n", addr[0]);

    /* Downgrade back to read-only */
    if (mprotect(addr, page_size, PROT_READ) == -1) {
        perror("mprotect");
    }
    printf("Protection downgraded back to PROT_READ\n");

    munmap(addr, page_size);
    return 0;
}

A guard page is a page mapped with PROT_NONE placed intentionally at the start or end of a memory region. If the program accidentally reads or writes into the guard page, the kernel delivers SIGSEGV immediately, making bugs easy to detect. This is used by memory allocators, thread stacks, and custom arena allocators.

#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <unistd.h>

/*
 * Allocate a memory region with guard pages on both sides.
 * Total allocation = page + usable_size + page
 */
void *alloc_with_guards(size_t usable_size)
{
    size_t page = (size_t)sysconf(_SC_PAGESIZE);
    size_t total;
    char *base;

    /* Round up usable_size to page boundary */
    usable_size = (usable_size + page - 1) & ~(page - 1);
    total = page + usable_size + page;

    /* Map the entire region as PROT_NONE first */
    base = mmap(NULL, total,
                PROT_NONE,
                MAP_PRIVATE | MAP_ANONYMOUS,
                -1, 0);
    if (base == MAP_FAILED) return NULL;

    /* Make the usable middle region read+write */
    if (mprotect(base + page, usable_size, PROT_READ | PROT_WRITE) == -1) {
        munmap(base, total);
        return NULL;
    }

    /* Return pointer to usable region (after the first guard page) */
    return base + page;
}

int main(void)
{
    size_t page = (size_t)sysconf(_SC_PAGESIZE);
    char *buf;

    buf = alloc_with_guards(1024);
    if (!buf) { fprintf(stderr, "alloc failed\n"); exit(EXIT_FAILURE); }

    printf("Usable buffer at: %p\n", (void *)buf);

    /* Safe: within usable region */
    buf[0]    = 'H';
    buf[1023] = 'i';
    printf("Write successful: buf[0]=%c, buf[1023]=%c\n", buf[0], buf[1023]);

    /*
     * Accessing buf[-1] (before) or buf[page] (after) would hit
     * a PROT_NONE guard page and trigger SIGSEGV immediately.
     */

    /* Cleanup: unmap including guard pages */
    munmap(buf - page, page + 1024 + page);
    return 0;
}

mmap() arguments have specific alignment requirements that differ between standards (SUSv3 vs SUSv4) and Linux. This is a common interview topic because misalignment causes EINVAL errors that are hard to debug.

#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <unistd.h>

int main(void)
{
    long page_size = sysconf(_SC_PAGESIZE);
    printf("System page size: %ld bytes\n", page_size);

    /* CORRECT: offset = 0 (always page-aligned) */
    int fd = open("testfile.txt", O_RDONLY);
    if (fd != -1) {
        void *addr = mmap(NULL, 4096, PROT_READ, MAP_PRIVATE, fd, 0);
        if (addr != MAP_FAILED) {
            printf("mmap with offset=0: OK\n");
            munmap(addr, 4096);
        }
        close(fd);
    }

    /* CORRECT: offset = 1 * page_size (multiple of page size) */
    /*   mmap(NULL, 4096, PROT_READ, MAP_PRIVATE, fd, 1 * page_size); */

    /* WRONG: offset = 100 (not a multiple of page size) */
    /*   mmap(NULL, 4096, PROT_READ, MAP_PRIVATE, fd, 100);
     *   This returns MAP_FAILED with errno = EINVAL               */

    /* How to compute a page-aligned offset from an arbitrary byte offset */
    off_t byte_offset = 5000;
    off_t aligned_offset = (byte_offset / page_size) * page_size;
    size_t extra = (size_t)(byte_offset - aligned_offset); /* bytes before target */

    printf("Byte offset: %ld\n", (long)byte_offset);
    printf("Aligned offset to pass to mmap: %ld\n", (long)aligned_offset);
    printf("Add %zu bytes to returned pointer to reach target\n", extra);

    return 0;
}