vlibc/include/sys/mman.h

#ifndef VLIBC_SYS_MMAN_H
#define VLIBC_SYS_MMAN_H

/*
 * vlibc — <sys/mman.h>.
 *
 * Memory mapping, protection, and synchronization (POSIX.1-2008). Every
 * function here is an unbuffered pass-through to the kernel: failures are
 * reported as -1 (or MAP_FAILED for mmap) with errno set by the syscall
 * layer.
 *
 *   Level 1 (onlyposix): mmap, munmap, mprotect, msync, mlock, munlock,
 *                        mlockall, munlockall, posix_madvise.
 *   Level 2 (muslmimic): madvise (XSI — posix_madvise is the POSIX base
 *                        form), shm_open, shm_unlink.
 *
 * All constant values are Linux x86_64 kernel-UAPI facts (asm-generic/
 * mman-common.h and mman.h), transcribed, not invented. PROT_*, MAP_*,
 * MAP_FAILED, MS_* and MCL_* exist at level 1. The POSIX_MADV_* advice
 * values match the Linux MADV_* values for the same advice (0-4), which is
 * what lets posix_madvise pass its advice straight to SYS_madvise; the
 * Linux MADV_* names themselves are gated at level 2 with madvise, the only
 * function that takes them. MAP_ANONYMOUS is provided as a source
 * compatibility alias of the primary spelling MAP_ANON (the BSD/POSIX
 * draft name glibc also accepts).
 *
 * POSIX shared memory (shm_open/shm_unlink, level 2) is backed by a real
 * named file under /dev/shm (tmpfs), NOT by memfd_create: the object is a
 * path in the shared-memory filesystem, visible there and re-openable by
 * name until shm_unlink removes it, which matches POSIX's named-object
 * semantics. vlibc renders name as "/dev/shm/" + name and requires that
 * name contain no '/' — the object is a single directory entry, so a slash
 * would escape the namespace (EINVAL). This differs from the POSIX wording
 * that a name begin with a slash: vlibc names carry no leading slash and
 * the prefix is added internally. Otherwise shm_open behaves as open(2) on
 * the rendered path (the oflag access modes plus O_CREAT/O_EXCL/O_TRUNC and
 * mode bits are honored; O_WRONLY alone is undefined by POSIX and passed
 * through to the kernel) and shm_unlink as unlink(2) on it.
 *
 * None of these declarations carry an intent attribute: every function
 * changes the caller's address space or performs I/O with side effects and
 * reports failures through errno, so const/pure would be unsound (the same
 * rationale unistd.h documents for its I/O family).
 */

#include <vlibc/features.h>

#include <stddef.h>

#include <sys/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ---- memory protection ---- */

#define PROT_NONE 0x0  /* page cannot be accessed */
#define PROT_READ 0x1  /* page can be read */
#define PROT_WRITE 0x2 /* page can be written */
#define PROT_EXEC 0x4  /* page can be executed */

/* ---- mapping types and flags ---- */

#define MAP_SHARED 0x01        /* share changes with the file and other mappers */
#define MAP_PRIVATE 0x02       /* private copy-on-write mapping */
#define MAP_FIXED 0x10         /* interpret addr exactly; fail if it cannot be used */
#define MAP_ANON 0x20          /* anonymous mapping, not file-backed (primary name) */
#define MAP_ANONYMOUS MAP_ANON /* source-compatibility alias of MAP_ANON */

/* Value returned by mmap on failure (never a valid mapping address). */
#define MAP_FAILED ((void *)-1)

/* ---- msync synchronization flags ---- */

#define MS_ASYNC 0x1      /* return before the writes take effect */
#define MS_INVALIDATE 0x2 /* invalidate other mappings of the file */
#define MS_SYNC 0x4       /* perform synchronous writes */

/* ---- mlockall flags ---- */

#define MCL_CURRENT 0x1 /* lock all currently mapped pages */
#define MCL_FUTURE 0x2  /* lock all pages mapped in the future */

/* ---- posix_madvise advice (Linux MADV_* values, see the header note) ---- */

#define POSIX_MADV_NORMAL 0     /* no special treatment */
#define POSIX_MADV_RANDOM 1     /* pages will be accessed randomly */
#define POSIX_MADV_SEQUENTIAL 2 /* pages will be accessed sequentially */
#define POSIX_MADV_WILLNEED 3   /* pages will be needed soon */
#define POSIX_MADV_DONTNEED 4   /* pages are not needed soon */

/*
 * Map len bytes starting at offset off of the object open on fildes into
 * the process address space and return the mapping address, or MAP_FAILED
 * with errno set. addr is a hint for the placement (0 for "anywhere")
 * unless flags contains MAP_FIXED; prot is a combination of PROT_* (PROT_NONE
 * alone forbids all access). With MAP_ANON fildes is ignored and must be -1
 * and off 0; the mapping is zero-filled. The mapping is shared or private
 * per MAP_SHARED/MAP_PRIVATE. len is rounded up to whole pages.
 */
void *
mmap(void *addr, size_t len, int prot, int flags, int fildes, off_t off);

/*
 * Remove the mapping at addr (a page boundary) covering len bytes; return
 * 0, or -1 with errno set. The address range becomes invalid.
 */
int
munmap(void *addr, size_t len);

/*
 * Change the protection of the mapped pages at addr covering len bytes to
 * prot; return 0, or -1 with errno set. addr must be page-aligned.
 */
int
mprotect(void *addr, size_t len, int prot);

/*
 * Flush the mapped pages at addr covering len bytes of a MAP_SHARED mapping
 * to (or invalidate them from) the underlying object per flags (MS_ASYNC,
 * MS_SYNC, MS_INVALIDATE); return 0, or -1 with errno set.
 */
int
msync(void *addr, size_t len, int flags);

/*
 * Lock the pages at addr covering len bytes into memory so they are never
 * paged out; return 0, or -1 with errno set. munlock unlocks them again.
 */
int
mlock(const void *addr, size_t len);

int
munlock(const void *addr, size_t len);

/*
 * Lock all pages mapped by the process into memory per flags (MCL_CURRENT,
 * MCL_FUTURE); return 0, or -1 with errno set. munlockall unlocks them.
 */
int
mlockall(int flags);

int
munlockall(void);

/*
 * Give the kernel advice (one of the POSIX_MADV_* values) about how the
 * pages at addr covering len bytes will be used; return 0, or -1 with errno
 * set. The advice may be ignored; the mapping is unchanged.
 */
int
posix_madvise(void *addr, size_t len, int advice);

#if VLIBC_LEVEL_GE(2)
/* Level 2 (muslmimic): XSI + POSIX shared memory. */

/* ---- madvise advice (Linux x86_64 kernel-UAPI values) ---- */

#define MADV_NORMAL 0           /* no special treatment */
#define MADV_RANDOM 1           /* pages will be accessed randomly */
#define MADV_SEQUENTIAL 2       /* pages will be accessed sequentially */
#define MADV_WILLNEED 3         /* pages will be needed soon */
#define MADV_DONTNEED 4         /* pages are not needed soon; free them */
#define MADV_FREE 8             /* free pages; contents lost on later write */
#define MADV_REMOVE 9           /* free the pages and punch a hole in the file */
#define MADV_DONTFORK 10        /* do not inherit the pages across fork */
#define MADV_DOFORK 11          /* revert MADV_DONTFORK */
#define MADV_MERGEABLE 12       /* enable KSM merging of the pages */
#define MADV_UNMERGEABLE 13     /* revert MADV_MERGEABLE */
#define MADV_HUGEPAGE 14        /* prefer transparent huge pages */
#define MADV_NOHUGEPAGE 15      /* revert MADV_HUGEPAGE */
#define MADV_DONTDUMP 16        /* exclude the pages from core dumps */
#define MADV_DODUMP 17          /* revert MADV_DONTDUMP */
#define MADV_WIPEONFORK 18      /* zero the pages in the child after fork */
#define MADV_KEEPONFORK 19      /* revert MADV_WIPEONFORK */
#define MADV_COLD 20            /* pages will be accessed less soon */
#define MADV_PAGEOUT 21         /* reclaim the pages immediately */
#define MADV_POPULATE_READ 22   /* fault the pages in for reading */
#define MADV_POPULATE_WRITE 23  /* fault the pages in for writing */
#define MADV_DONTNEED_LOCKED 24 /* like MADV_DONTNEED on locked pages */
#define MADV_COLLAPSE 25        /* collapse the range into a THP */

/*
 * Linux madvise: give the kernel advice (one of the MADV_* values above)
 * about the pages at addr covering len bytes; return 0, or -1 with errno
 * set. XSI — posix_madvise (level 1) is the POSIX base form; this is the
 * raw Linux interface exposing the full MADV_* set.
 */
int
madvise(void *addr, size_t len, int advice);

/*
 * Open (creating with mode if oflag contains O_CREAT) the POSIX shared
 * memory object name and return a descriptor, or -1 with errno set. The
 * object is a file under /dev/shm; name must not contain '/', and the
 * object persists (re-openable by name) until shm_unlink removes it. See
 * the header note on the naming deviation. oflag behaves as for open(2).
 */
int
shm_open(const char *name, int oflag, mode_t mode);

/*
 * Remove the shared memory object name from /dev/shm; return 0, or -1 with
 * errno set. Open descriptors of the object stay valid until closed. See
 * the header note on the naming deviation.
 */
int
shm_unlink(const char *name);
#endif /* VLIBC_LEVEL_GE(2) */

#ifdef __cplusplus
}
#endif

#endif /* VLIBC_SYS_MMAN_H */