madvise

title: madvise(2)

summary: give advice about use of memory

text:
# madvise(2)

## NAME
madvise - give advice about use of memory

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/mman.h>
```

```
int madvise(void addr[.length], size_t length, int advice);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

madvise():

```
    Since glibc 2.19:

        _DEFAULT_SOURCE

    Up to and including glibc 2.19:

        _BSD_SOURCE
```

## DESCRIPTION
The madvise() system call is used to give advice or directions to the kernel about the address range beginning at address addr and with size length. madvise() only operates on whole pages, therefore addr must be page-aligned. The value of length is rounded up to a multiple of page size. In most cases, the goal of such advice is to improve system or application performance.

Initially, the system call supported a set of "conventional" advice values, which are also available on several other implementations. (Note, though, that madvise() is not specified in POSIX.) Subsequently, a number of Linux-specific advice values have been added.

### Conventional advice values
The advice values listed below allow an application to tell the kernel how it expects to use some mapped or shared memory areas, so that the kernel can choose appropriate read-ahead and caching techniques. These advice values do not influence the semantics of the application (except in the case of MADV_DONTNEED), but may influence its performance. All of the advice values listed here have analogs in the POSIX-specified posix_madvise(3) function, and the values have the same meanings, with the exception of MADV_DONTNEED.

The advice is indicated in the advice argument, which is one of the following:

MADV_NORMAL

No special treatment. This is the default.

MADV_RANDOM

Expect page references in random order. (Hence, read ahead may be less useful than normally.)

MADV_SEQUENTIAL

Expect page references in sequential order. (Hence, pages in the given range can be aggressively read ahead, and may be freed soon after they are accessed.)

MADV_WILLNEED

Expect access in the near future. (Hence, it might be a good idea to read some pages ahead.)

MADV_DONTNEED

Do not expect access in the near future. (For the time being, the application is finished with the given range, so the kernel can free resources associated with it.)

After a successful MADV_DONTNEED operation, the semantics of memory access in the specified region are changed: subsequent accesses of pages in the range will succeed, but will result in either repopulating the memory contents from the up-to-date contents of the underlying mapped file (for shared file mappings, shared anonymous mappings, and shmem-based techniques such as System V shared memory segments) or zero-fill-on-demand pages for anonymous private mappings.

Note that, when applied to shared mappings, MADV_DONTNEED might not lead to immediate freeing of the pages in the range. The kernel is free to delay freeing the pages until an appropriate moment. The resident set size (RSS) of the calling process will be immediately reduced however.

MADV_DONTNEED cannot be applied to locked pages, or VM_PFNMAP pages. (Pages marked with the kernel-internal VM_PFNMAP flag are special memory areas that are not managed by the virtual memory subsystem. Such pages are typically created by device drivers that map the pages into user space.)

Support for Huge TLB pages was added in Linux v5.18. Addresses within a mapping backed by Huge TLB pages must be aligned to the underlying Huge TLB page size, and the range length is rounded up to a multiple of the underlying Huge TLB page size.

### Linux-specific advice values
The following Linux-specific advice values have no counterparts in the POSIX-specified posix_madvise(3), and may or may not have counterparts in the madvise() interface available on other implementations. Note that some of these operations change the semantics of memory accesses.

MADV_REMOVE (since Linux 2.6.16)

Free up a given range of pages and its associated backing store. This is equivalent to punching a hole in the corresponding range of the backing store (see fallocate(2)). Subsequent accesses in the specified address range will see data with a value of zero.

The specified address range must be mapped shared and writable. This flag cannot be applied to locked pages, or VM_PFNMAP pages.

In the initial implementation, only tmpfs(5) supported MADV_REMOVE; but since Linux 3.5, any filesystem which supports the fallocate(2) FALLOC_FL_PUNCH_HOLE mode also supports MADV_REMOVE. Filesystems which do not support MADV_REMOVE fail with the error EOPNOTSUPP.

Support for the Huge TLB filesystem was added in Linux v4.3.

MADV_DONTFORK (since Linux 2.6.16)

Do not make the pages in this range available to the child after a fork(2). This is useful to prevent copy-on-write semantics from changing the physical location of a page if the parent writes to it after a fork(2). (Such page relocations cause problems for hardware that DMAs into the page.)

MADV_DOFORK (since Linux 2.6.16)

Undo the effect of MADV_DONTFORK, restoring the default behavior, whereby a mapping is inherited across fork(2).

MADV_HWPOISON (since Linux 2.6.32)

Poison the pages in the range specified by addr and length and handle subsequent references to those pages like a hardware memory corruption. This operation is available only for privileged (CAP_SYS_ADMIN) processes. This operation may result in the calling process receiving a SIGBUS and the page being unmapped.

This feature is intended for testing of memory error-handling code; it is available only if the kernel was configured with CONFIG_MEMORY_FAILURE.

MADV_MERGEABLE (since Linux 2.6.32)

Enable Kernel Samepage Merging (KSM) for the pages in the range specified by addr and length. The kernel regularly scans those areas of user memory that have been marked as mergeable, looking for pages with identical content. These are replaced by a single write-protected page (which is automatically copied if a process later wants to update the content of the page). KSM merges only private anonymous pages (see mmap(2)).

The KSM feature is intended for applications that generate many instances of the same data (e.g., virtualization systems such as KVM). It can consume a lot of processing power; use with care. See the Linux kernel source file Documentation/admin-guide/mm/ksm.rst for more details.

The MADV_MERGEABLE and MADV_UNMERGEABLE operations are available only if the kernel was configured with CONFIG_KSM.

MADV_UNMERGEABLE (since Linux 2.6.32)

Undo the effect of an earlier MADV_MERGEABLE operation on the specified address range; KSM unmerges whatever pages it had merged in the address range specified by addr and length.

MADV_SOFT_OFFLINE (since Linux 2.6.33)

Soft offline the pages in the range specified by addr and length. The memory of each page in the specified range is preserved (i.e., when next accessed, the same content will be visible, but in a new physical page frame), and the original page is offlined (i.e., no longer used, and taken out of normal memory management). The effect of the MADV_SOFT_OFFLINE operation is invisible to (i.e., does not change the semantics of) the calling process.

This feature is intended for testing of memory error-handling code; it is available only if the kernel was configured with CONFIG_MEMORY_FAILURE.

MADV_HUGEPAGE (since Linux 2.6.38)

Enable Transparent Huge Pages (THP) for pages in the range specified by addr and length. The kernel will regularly scan the areas marked as huge page candidates to replace them with huge pages. The kernel will also allocate huge pages directly when the region is naturally aligned to the huge page size (see posix_memalign(2)).

This feature is primarily aimed at applications that use large mappings of data and access large regions of that memory at a time (e.g., virtualization systems such as QEMU). It can very easily waste memory (e.g., a 2 MB mapping that only ever accesses 1 byte will result in 2 MB of wired memory instead of one 4 KB page). See the Linux kernel source file Documentation/admin-guide/mm/transhuge.rst for more details.

Most common kernels configurations provide MADV_HUGEPAGE-style behavior by default, and thus MADV_HUGEPAGE is normally not necessary. It is mostly intended for embedded systems, where MADV_HUGEPAGE-style behavior may not be enabled by default in the kernel. On such systems, this flag can be used in order to selectively enable THP. Whenever MADV_HUGEPAGE is used, it should always be in regions of memory with an access pattern that the developer knows in advance won't risk to increase the memory footprint of the application when transparent hugepages are enabled.

Since Linux 5.4, automatic scan of eligible areas and replacement by huge pages works with private anonymous pages (see mmap(2)), shmem pages, and file-backed pages. For all memory types, memory may only be replaced by huge pages on hugepage-aligned boundaries. For file-mapped memory —including tmpfs (see tmpfs(2))— the mapping must also be naturally hugepage-aligned within the file. Additionally, for file-backed, non-tmpfs memory, the file must not be open for write and the mapping must be executable.

The VMA must not be marked VM_NOHUGEPAGE, VM_HUGETLB, VM_IO, VM_DONTEXPAND, VM_MIXEDMAP, or VM_PFNMAP, nor can it be stack memory or backed by a DAX-enabled device (unless the DAX device is hot-plugged as System RAM). The process must also not have PR_SET_THP_DISABLE set (see prctl(2)).

The MADV_HUGEPAGE, MADV_NOHUGEPAGE, and MADV_COLLAPSE operations are available only if the kernel was configured with CONFIG_TRANSPARENT_HUGEPAGE and file/shmem memory is only supported if the kernel was configured with CONFIG_READ_ONLY_THP_FOR_FS.

MADV_NOHUGEPAGE (since Linux 2.6.38)

Ensures that memory in the address range specified by addr and length will not be backed by transparent hugepages.

MADV_COLLAPSE (since Linux 6.1)

Perform a best-effort synchronous collapse of the native pages mapped by the memory range into Transparent Huge Pages (THPs). MADV_COLLAPSE operates on the current state of memory of the calling process and makes no persistent changes or guarantees on how pages will be mapped, constructed, or faulted in the future.

MADV_COLLAPSE supports private anonymous pages (see mmap(2)), shmem pages, and file-backed pages. See MADV_HUGEPAGE for general information on memory requirements for THP. If the range provided spans multiple VMAs, the semantics of the collapse over each VMA is independent from the others. If collapse of a given huge page-aligned/sized region fails, the operation may continue to attempt collapsing the remainder of the specified memory. MADV_COLLAPSE will automatically clamp the provided range to be hugepage-aligned.

All non-resident pages covered by the range will first be swapped/faulted-in, before being copied onto a freshly allocated hugepage. If the native pages compose the same PTE-mapped hugepage, and are suitably aligned, allocation of a new hugepage may be elided and collapse may happen in-place. Unmapped pages will have their data directly initialized to 0 in the new hugepage. However, for every eligible hugepage-aligned/sized region to be collapsed, at least one page must currently be backed by physical memory.

MADV_COLLAPSE is independent of any sysfs (see sysfs(5)) setting under /sys/kernel/mm/transparent_hugepage, both in terms of determining THP eligibility, and allocation semantics. See Linux kernel source file Documentation/admin-guide/mm/transhuge.rst for more information. MADV_COLLAPSE also ignores huge= tmpfs mount when operating on tmpfs files. Allocation for the new hugepage may enter direct reclaim and/or compaction, regardless of VMA flags (though VM_NOHUGEPAGE is still respected).

When the system has multiple NUMA nodes, the hugepage will be allocated from the node providing the most native pages.

If all hugepage-sized/aligned regions covered by the provided range were either successfully collapsed, or were already PMD-mapped THPs, this operation will be deemed successful. Note that this doesn't guarantee anything about other possible mappings of the memory. In the event multiple hugepage-aligned/sized areas fail to collapse, only the most-recently–failed code will be set in errno.

MADV_DONTDUMP (since Linux 3.4)

Exclude from a core dump those pages in the range specified by addr and length. This is useful in applications that have large areas of memory that are known not to be useful in a core dump. The effect of MADV_DONTDUMP takes precedence over the bit mask that is set via the /proc/pid/coredump_filter file (see core(5)).

MADV_DODUMP (since Linux 3.4)

Undo the effect of an earlier MADV_DONTDUMP.

MADV_FREE (since Linux 4.5)

The application no longer requires the pages in the range specified by addr and len. The kernel can thus free these pages, but the freeing could be delayed until memory pressure occurs. For each of the pages that has been marked to be freed but has not yet been freed, the free operation will be canceled if the caller writes into the page. After a successful MADV_FREE operation, any stale data (i.e., dirty, unwritten pages) will be lost when the kernel frees the pages. However, subsequent writes to pages in the range will succeed and then kernel cannot free those dirtied pages, so that the caller can always see just written data. If there is no subsequent write, the kernel can free the pages at any time. Once pages in the range have been freed, the caller will see zero-fill-on-demand pages upon subsequent page references.

The MADV_FREE operation can be applied only to private anonymous pages (see mmap(2)). Before Linux 4.12, when freeing pages on a swapless system, the pages in the given range are freed instantly, regardless of memory pressure.

MADV_WIPEONFORK (since Linux 4.14)

Present the child process with zero-filled memory in this range after a fork(2). This is useful in forking servers in order to ensure that sensitive per-process data (for example, PRNG seeds, cryptographic secrets, and so on) is not handed to child processes.

The MADV_WIPEONFORK operation can be applied only to private anonymous pages (see mmap(2)).

Within the child created by fork(2), the MADV_WIPEONFORK setting remains in place on the specified address range. This setting is cleared during execve(2).

MADV_KEEPONFORK (since Linux 4.14)

Undo the effect of an earlier MADV_WIPEONFORK.

MADV_COLD (since Linux 5.4)

Deactivate a given range of pages. This will make the pages a more probable reclaim target should there be a memory pressure. This is a nondestructive operation. The advice might be ignored for some pages in the range when it is not applicable.

MADV_PAGEOUT (since Linux 5.4)

Reclaim a given range of pages. This is done to free up memory occupied by these pages. If a page is anonymous, it will be swapped out. If a page is file-backed and dirty, it will be written back to the backing storage. The advice might be ignored for some pages in the range when it is not applicable.

MADV_POPULATE_READ (since Linux 5.14)

"Populate (prefault) page tables readable, faulting in all pages in the range just as if manually reading from each page; however, avoid the actual memory access that would have been performed after handling the fault.

In contrast to MAP_POPULATE, MADV_POPULATE_READ does not hide errors, can be applied to (parts of) existing mappings and will always populate (prefault) page tables readable. One example use case is prefaulting a file mapping, reading all file content from disk; however, pages won't be dirtied and consequently won't have to be written back to disk when evicting the pages from memory.

Depending on the underlying mapping, map the shared zeropage, preallocate memory or read the underlying file; files with holes might or might not preallocate blocks. If populating fails, a SIGBUS signal is not generated; instead, an error is returned.

If MADV_POPULATE_READ succeeds, all page tables have been populated (prefaulted) readable once. If MADV_POPULATE_READ fails, some page tables might have been populated.

MADV_POPULATE_READ cannot be applied to mappings without read permissions and special mappings, for example, mappings marked with kernel-internal flags such as VM_PFNMAP or VM_IO, or secret memory regions created using memfd_secret(2).

Note that with MADV_POPULATE_READ, the process can be killed at any moment when the system runs out of memory.

MADV_POPULATE_WRITE (since Linux 5.14)

Populate (prefault) page tables writable, faulting in all pages in the range just as if manually writing to each each page; however, avoid the actual memory access that would have been performed after handling the fault.

In contrast to MAP_POPULATE, MADV_POPULATE_WRITE does not hide errors, can be applied to (parts of) existing mappings and will always populate (prefault) page tables writable. One example use case is preallocating memory, breaking any CoW (Copy on Write).

Depending on the underlying mapping, preallocate memory or read the underlying file; files with holes will preallocate blocks. If populating fails, a SIGBUS signal is not generated; instead, an error is returned.

If MADV_POPULATE_WRITE succeeds, all page tables have been populated (prefaulted) writable once. If MADV_POPULATE_WRITE fails, some page tables might have been populated.

MADV_POPULATE_WRITE cannot be applied to mappings without write permissions and special mappings, for example, mappings marked with kernel-internal flags such as VM_PFNMAP or VM_IO, or secret memory regions created using memfd_secret(2).

Note that with MADV_POPULATE_WRITE, the process can be killed at any moment when the system runs out of memory.

## RETURN VALUE
On success, madvise() returns zero. On error, it returns -1 and errno is set to indicate the error.

## ERRORS
EACCES

advice is MADV_REMOVE, but the specified address range is not a shared writable mapping.

EAGAIN

A kernel resource was temporarily unavailable.

EBADF

The map exists, but the area maps something that isn't a file.

EBUSY

(for MADV_COLLAPSE) Could not charge hugepage to cgroup: cgroup limit exceeded.

EFAULT

advice is MADV_POPULATE_READ or MADV_POPULATE_WRITE, and populating (prefaulting) page tables failed because a SIGBUS would have been generated on actual memory access and the reason is not a HW poisoned page (HW poisoned pages can, for example, be created using the MADV_HWPOISON flag described elsewhere in this page).

EINVAL

addr is not page-aligned or length is negative.

EINVAL

advice is not a valid.

EINVAL

advice is MADV_COLD or MADV_PAGEOUT and the specified address range includes locked, Huge TLB pages, or VM_PFNMAP pages.

EINVAL

advice is MADV_DONTNEED or MADV_REMOVE and the specified address range includes locked, Huge TLB pages, or VM_PFNMAP pages.

EINVAL

advice is MADV_MERGEABLE or MADV_UNMERGEABLE, but the kernel was not configured with CONFIG_KSM.

EINVAL

advice is MADV_FREE or MADV_WIPEONFORK but the specified address range includes file, Huge TLB, MAP_SHARED, or VM_PFNMAP ranges.

EINVAL

advice is MADV_POPULATE_READ or MADV_POPULATE_WRITE, but the specified address range includes ranges with insufficient permissions or special mappings, for example, mappings marked with kernel-internal flags such a VM_IO or VM_PFNMAP, or secret memory regions created using memfd_secret(2).

EIO

(for MADV_WILLNEED) Paging in this area would exceed the process's maximum resident set size.

ENOMEM

(for MADV_WILLNEED) Not enough memory: paging in failed.

ENOMEM

(for MADV_COLLAPSE) Not enough memory: could not allocate hugepage.

ENOMEM

Addresses in the specified range are not currently mapped, or are outside the address space of the process.

ENOMEM

advice is MADV_POPULATE_READ or MADV_POPULATE_WRITE, and populating (prefaulting) page tables failed because there was not enough memory.

EPERM

advice is MADV_HWPOISON, but the caller does not have the CAP_SYS_ADMIN capability.

EHWPOISON

advice is MADV_POPULATE_READ or MADV_POPULATE_WRITE, and populating (prefaulting) page tables failed because a HW poisoned page (HW poisoned pages can, for example, be created using the MADV_HWPOISON flag described elsewhere in this page) was encountered.

## VERSIONS
Versions of this system call, implementing a wide variety of advice values, exist on many other implementations. Other implementations typically implement at least the flags listed above under Conventional advice flags, albeit with some variation in semantics.

POSIX.1-2001 describes posix_madvise(3) with constants POSIX_MADV_NORMAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, POSIX_MADV_WILLNEED, and POSIX_MADV_DONTNEED, and so on, with behavior close to the similarly named flags listed above.

### Linux
The Linux implementation requires that the address addr be page-aligned, and allows length to be zero. If there are some parts of the specified address range that are not mapped, the Linux version of madvise() ignores them and applies the call to the rest (but returns ENOMEM from the system call, as it should).

madvise(0, 0, advice) will return zero iff advice is supported by the kernel and can be relied on to probe for support.

## STANDARDS
None.

## HISTORY
First appeared in 4.4BSD.

Since Linux 3.18, support for this system call is optional, depending on the setting of the CONFIG_ADVISE_SYSCALLS configuration option.

## SEE ALSO
getrlimit(2), memfd_secret(2), mincore(2), mmap(2), mprotect(2), msync(2), munmap(2), prctl(2), process_madvise(2), posix_madvise(3), core(5)


mbind

package: man-pages

title: mbind(2)

summary: set memory policy for a memory range

text:
# mbind(2)

## NAME
mbind - set memory policy for a memory range

## LIBRARY
NUMA (Non-Uniform Memory Access) policy library (libnuma, -lnuma)

## SYNOPSIS

```
#include <numaif.h>
```

```
long mbind(void addr[.len], unsigned long len, int mode,
           const unsigned long nodemask[(.maxnode + ULONG_WIDTH - 1)
                                        / ULONG_WIDTH],
           unsigned long maxnode, unsigned int flags);
```

## DESCRIPTION
mbind() sets the NUMA memory policy, which consists of a policy mode and zero or more nodes, for the memory range starting with addr and continuing for len bytes. The memory policy defines from which node memory is allocated.

If the memory range specified by the addr and len arguments includes an "anonymous" region of memory—that is a region of memory created using the mmap(2) system call with the MAP_ANONYMOUS—or a memory-mapped file, mapped using the mmap(2) system call with the MAP_PRIVATE flag, pages will be allocated only according to the specified policy when the application writes (stores) to the page. For anonymous regions, an initial read access will use a shared page in the kernel containing all zeros. For a file mapped with MAP_PRIVATE, an initial read access will allocate pages according to the memory policy of the thread that causes the page to be allocated. This may not be the thread that called mbind().

The specified policy will be ignored for any MAP_SHARED mappings in the specified memory range. Rather the pages will be allocated according to the memory policy of the thread that caused the page to be allocated. Again, this may not be the thread that called mbind().

If the specified memory range includes a shared memory region created using the shmget(2) system call and attached using the shmat(2) system call, pages allocated for the anonymous or shared memory region will be allocated according to the policy specified, regardless of which process attached to the shared memory segment causes the allocation. If, however, the shared memory region was created with the SHM_HUGETLB flag, the huge pages will be allocated according to the policy specified only if the page allocation is caused by the process that calls mbind() for that region.

By default, mbind() has an effect only for new allocations; if the pages inside the range have been already touched before setting the policy, then the policy has no effect. This default behavior may be overridden by the MPOL_MF_MOVE and MPOL_MF_MOVE_ALL flags described below.

The mode argument must specify one of MPOL_DEFAULT, MPOL_BIND, MPOL_INTERLEAVE, MPOL_PREFERRED, or MPOL_LOCAL (which are described in detail below). All policy modes except MPOL_DEFAULT require the caller to specify the node or nodes to which the mode applies, via the nodemask argument.

The mode argument may also include an optional mode flag. The supported mode flags are:

MPOL_F_STATIC_NODES (since Linux-2.6.26)

A nonempty nodemask specifies physical node IDs. Linux does not remap the nodemask when the thread moves to a different cpuset context, nor when the set of nodes allowed by the thread's current cpuset context changes.

MPOL_F_RELATIVE_NODES (since Linux-2.6.26)

A nonempty nodemask specifies node IDs that are relative to the set of node IDs allowed by the thread's current cpuset.

nodemask points to a bit mask of nodes containing up to maxnode bits. The bit mask size is rounded to the next multiple of sizeof(unsigned long), but the kernel will use bits only up to maxnode. A NULL value of nodemask or a maxnode value of zero specifies the empty set of nodes. If the value of maxnode is zero, the nodemask argument is ignored. Where a nodemask is required, it must contain at least one node that is on-line, allowed by the thread's current cpuset context (unless the MPOL_F_STATIC_NODES mode flag is specified), and contains memory.

The mode argument must include one of the following values:

MPOL_DEFAULT

This mode requests that any nondefault policy be removed, restoring default behavior. When applied to a range of memory via mbind(), this means to use the thread memory policy, which may have been set with set_mempolicy(2). If the mode of the thread memory policy is also MPOL_DEFAULT, the system-wide default policy will be used. The system-wide default policy allocates pages on the node of the CPU that triggers the allocation. For MPOL_DEFAULT, the nodemask and maxnode arguments must be specify the empty set of nodes.

MPOL_BIND

This mode specifies a strict policy that restricts memory allocation to the nodes specified in nodemask. If nodemask specifies more than one node, page allocations will come from the node with sufficient free memory that is closest to the node where the allocation takes place. Pages will not be allocated from any node not specified in the IR nodemask . (Before Linux 2.6.26, page allocations came from the node with the lowest numeric node ID first, until that node contained no free memory. Allocations then came from the node with the next highest node ID specified in nodemask and so forth, until none of the specified nodes contained free memory.)

MPOL_INTERLEAVE

This mode specifies that page allocations be interleaved across the set of nodes specified in nodemask. This optimizes for bandwidth instead of latency by spreading out pages and memory accesses to those pages across multiple nodes. To be effective the memory area should be fairly large, at least 1 MB or bigger with a fairly uniform access pattern. Accesses to a single page of the area will still be limited to the memory bandwidth of a single node.

MPOL_PREFERRED

This mode sets the preferred node for allocation. The kernel will try to allocate pages from this node first and fall back to other nodes if the preferred nodes is low on free memory. If nodemask specifies more than one node ID, the first node in the mask will be selected as the preferred node. If the nodemask and maxnode arguments specify the empty set, then the memory is allocated on the node of the CPU that triggered the allocation.

MPOL_LOCAL (since Linux 3.8)

This mode specifies "local allocation"; the memory is allocated on the node of the CPU that triggered the allocation (the "local node"). The nodemask and maxnode arguments must specify the empty set. If the "local node" is low on free memory, the kernel will try to allocate memory from other nodes. The kernel will allocate memory from the "local node" whenever memory for this node is available. If the "local node" is not allowed by the thread's current cpuset context, the kernel will try to allocate memory from other nodes. The kernel will allocate memory from the "local node" whenever it becomes allowed by the thread's current cpuset context. By contrast, MPOL_DEFAULT reverts to the memory policy of the thread (which may be set via set_mempolicy(2)); that policy may be something other than "local allocation".

If MPOL_MF_STRICT is passed in flags and mode is not MPOL_DEFAULT, then the call fails with the error EIO if the existing pages in the memory range don't follow the policy.

If MPOL_MF_MOVE is specified in flags, then the kernel will attempt to move all the existing pages in the memory range so that they follow the policy. Pages that are shared with other processes will not be moved. If MPOL_MF_STRICT is also specified, then the call fails with the error EIO if some pages could not be moved. If the MPOL_INTERLEAVE policy was specified, pages already residing on the specified nodes will not be moved such that they are interleaved.

If MPOL_MF_MOVE_ALL is passed in flags, then the kernel will attempt to move all existing pages in the memory range regardless of whether other processes use the pages. The calling thread must be privileged (CAP_SYS_NICE) to use this flag. If MPOL_MF_STRICT is also specified, then the call fails with the error EIO if some pages could not be moved. If the MPOL_INTERLEAVE policy was specified, pages already residing on the specified nodes will not be moved such that they are interleaved.

## RETURN VALUE
On success, mbind() returns 0; on error, -1 is returned and errno is set to indicate the error.

## ERRORS
EFAULT

Part or all of the memory range specified by nodemask and maxnode points outside your accessible address space. Or, there was an unmapped hole in the specified memory range specified by addr and len.

EINVAL

An invalid value was specified for flags or mode; or addr + len was less than addr; or addr is not a multiple of the system page size. Or, mode is MPOL_DEFAULT and nodemask specified a nonempty set; or mode is MPOL_BIND or MPOL_INTERLEAVE and nodemask is empty. Or, maxnode exceeds a kernel-imposed limit. Or, nodemask specifies one or more node IDs that are greater than the maximum supported node ID. Or, none of the node IDs specified by nodemask are on-line and allowed by the thread's current cpuset context, or none of the specified nodes contain memory. Or, the mode argument specified both MPOL_F_STATIC_NODES and MPOL_F_RELATIVE_NODES.

EIO

MPOL_MF_STRICT was specified and an existing page was already on a node that does not follow the policy; or MPOL_MF_MOVE or MPOL_MF_MOVE_ALL was specified and the kernel was unable to move all existing pages in the range.

ENOMEM

Insufficient kernel memory was available.

EPERM

The flags argument included the MPOL_MF_MOVE_ALL flag and the caller does not have the CAP_SYS_NICE privilege.

## STANDARDS
Linux.

## HISTORY
Linux 2.6.7.

Support for huge page policy was added with Linux 2.6.16. For interleave policy to be effective on huge page mappings the policied memory needs to be tens of megabytes or larger.

Before Linux 5.7. MPOL_MF_STRICT was ignored on huge page mappings.

MPOL_MF_MOVE and MPOL_MF_MOVE_ALL are available only on Linux 2.6.16 and later.

## NOTES
For information on library support, see numa(7).

NUMA policy is not supported on a memory-mapped file range that was mapped with the MAP_SHARED flag.

The MPOL_DEFAULT mode can have different effects for mbind() and set_mempolicy(2). When MPOL_DEFAULT is specified for set_mempolicy(2), the thread's memory policy reverts to the system default policy or local allocation. When MPOL_DEFAULT is specified for a range of memory using mbind(), any pages subsequently allocated for that range will use the thread's memory policy, as set by set_mempolicy(2). This effectively removes the explicit policy from the specified range, "falling back" to a possibly nondefault policy. To select explicit "local allocation" for a memory range, specify a mode of MPOL_LOCAL or MPOL_PREFERRED with an empty set of nodes. This method will work for set_mempolicy(2), as well.

## SEE ALSO
get_mempolicy(2), getcpu(2), mmap(2), set_mempolicy(2), shmat(2), shmget(2), numa(3), cpuset(7), numa(7), numactl(8)


membarrier

title: membarrier(2)

text:
# membarrier(2)

## NAME
membarrier - issue memory barriers on a set of threads

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <linux/membarrier.h> /* Definition of MEMBARRIER_* constants */
#include <sys/syscall.h>      /* Definition of SYS_* constants */
#include <unistd.h>
```

```
int syscall(SYS_membarrier, int cmd, unsigned int flags, int cpu_id);
```

Note: glibc provides no wrapper for membarrier(), necessitating the use of syscall(2).

## DESCRIPTION
The membarrier() system call helps reducing the overhead of the memory barrier instructions required to order memory accesses on multi-core systems. However, this system call is heavier than a memory barrier, so using it effectively is not as simple as replacing memory barriers with this system call, but requires understanding of the details below.

Use of memory barriers needs to be done taking into account that a memory barrier always needs to be either matched with its memory barrier counterparts, or that the architecture's memory model doesn't require the matching barriers.

There are cases where one side of the matching barriers (which we will refer to as "fast side") is executed much more often than the other (which we will refer to as "slow side"). This is a prime target for the use of membarrier(). The key idea is to replace, for these matching barriers, the fast-side memory barriers by simple compiler barriers, for example:

```
asm volatile ("" : : : "memory")
```

and replace the slow-side memory barriers by calls to membarrier().

This will add overhead to the slow side, and remove overhead from the fast side, thus resulting in an overall performance increase as long as the slow side is infrequent enough that the overhead of the membarrier() calls does not outweigh the performance gain on the fast side.

The cmd argument is one of the following:

MEMBARRIER_CMD_QUERY (since Linux 4.3)

Query the set of supported commands. The return value of the call is a bit mask of supported commands. MEMBARRIER_CMD_QUERY, which has the value 0, is not itself included in this bit mask. This command is always supported (on kernels where membarrier() is provided).

MEMBARRIER_CMD_GLOBAL (since Linux 4.16)

Ensure that all threads from all processes on the system pass through a state where all memory accesses to user-space addresses match program order between entry to and return from the membarrier() system call. All threads on the system are targeted by this command.

MEMBARRIER_CMD_GLOBAL_EXPEDITED (since Linux 4.16)

Execute a memory barrier on all running threads of all processes that previously registered with MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED.

Upon return from the system call, the calling thread has a guarantee that all running threads have passed through a state where all memory accesses to user-space addresses match program order between entry to and return from the system call (non-running threads are de facto in such a state). This guarantee is provided only for the threads of processes that previously registered with MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED.

Given that registration is about the intent to receive the barriers, it is valid to invoke MEMBARRIER_CMD_GLOBAL_EXPEDITED from a process that has not employed MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED.

The "expedited" commands complete faster than the non-expedited ones; they never block, but have the downside of causing extra overhead.

MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED (since Linux 4.16)

Register the process's intent to receive MEMBARRIER_CMD_GLOBAL_EXPEDITED memory barriers.

MEMBARRIER_CMD_PRIVATE_EXPEDITED (since Linux 4.14)

Execute a memory barrier on each running thread belonging to the same process as the calling thread.

Upon return from the system call, the calling thread has a guarantee that all its running thread siblings have passed through a state where all memory accesses to user-space addresses match program order between entry to and return from the system call (non-running threads are de facto in such a state). This guarantee is provided only for threads in the same process as the calling thread.

The "expedited" commands complete faster than the non-expedited ones; they never block, but have the downside of causing extra overhead.

A process must register its intent to use the private expedited command prior to using it.

MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED (since Linux 4.14)

Register the process's intent to use MEMBARRIER_CMD_PRIVATE_EXPEDITED.

MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE (since Linux 4.16)

In addition to providing the memory ordering guarantees described in MEMBARRIER_CMD_PRIVATE_EXPEDITED, upon return from system call the calling thread has a guarantee that all its running thread siblings have executed a core serializing instruction. This guarantee is provided only for threads in the same process as the calling thread.

The "expedited" commands complete faster than the non-expedited ones, they never block, but have the downside of causing extra overhead.

A process must register its intent to use the private expedited sync core command prior to using it.

MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE (since Linux 4.16)

Register the process's intent to use MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE.

MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ (since Linux 5.10)

Ensure the caller thread, upon return from system call, that all its running thread siblings have any currently running rseq critical sections restarted if flags parameter is 0; if flags parameter is MEMBARRIER_CMD_FLAG_CPU, then this operation is performed only on CPU indicated by cpu_id. This guarantee is provided only for threads in the same process as the calling thread.

RSEQ membarrier is only available in the "private expedited" form.

A process must register its intent to use the private expedited rseq command prior to using it.

MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_RSEQ (since Linux 5.10)

Register the process's intent to use MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ.

MEMBARRIER_CMD_SHARED (since Linux 4.3)

This is an alias for MEMBARRIER_CMD_GLOBAL that exists for header backward compatibility.

The flags argument must be specified as 0 unless the command is MEMBARRIER_CMD_PRIVATE_EXPEDITED_RSEQ, in which case flags can be either 0 or MEMBARRIER_CMD_FLAG_CPU.

The cpu_id argument is ignored unless flags is MEMBARRIER_CMD_FLAG_CPU, in which case it must specify the CPU targeted by this membarrier command.

All memory accesses performed in program order from each targeted thread are guaranteed to be ordered with respect to membarrier().

If we use the semantic barrier() to represent a compiler barrier forcing memory accesses to be performed in program order across the barrier, and smp_mb() to represent explicit memory barriers forcing full memory ordering across the barrier, we have the following ordering table for each pairing of barrier(), membarrier(), and smp_mb(). The pair ordering is detailed as (O: ordered, X: not ordered):

barrier()

smp_mb()

membarrier()

barrier()

X

X

O

smp_mb()

X

O

O

membarrier()

O

O

O

## RETURN VALUE
On success, the MEMBARRIER_CMD_QUERY operation returns a bit mask of supported commands, and the MEMBARRIER_CMD_GLOBAL, MEMBARRIER_CMD_GLOBAL_EXPEDITED, MEMBARRIER_CMD_REGISTER_GLOBAL_EXPEDITED, MEMBARRIER_CMD_PRIVATE_EXPEDITED, MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED, MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE, and MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE operations return zero. On error, -1 is returned, and errno is set to indicate the error.

For a given command, with flags set to 0, this system call is guaranteed to always return the same value until reboot. Further calls with the same arguments will lead to the same result. Therefore, with flags set to 0, error handling is required only for the first call to membarrier().

## ERRORS
EINVAL

cmd is invalid, or flags is nonzero, or the MEMBARRIER_CMD_GLOBAL command is disabled because the nohz_full CPU parameter has been set, or the MEMBARRIER_CMD_PRIVATE_EXPEDITED_SYNC_CORE and MEMBARRIER_CMD_REGISTER_PRIVATE_EXPEDITED_SYNC_CORE commands are not implemented by the architecture.

ENOSYS

The membarrier() system call is not implemented by this kernel.

EPERM

The current process was not registered prior to using private expedited commands.

## STANDARDS
Linux.

## HISTORY
Linux 4.3.

Before Linux 5.10, the prototype was:

```
int membarrier(int cmd, int flags);
```

## NOTES
A memory barrier instruction is part of the instruction set of architectures with weakly ordered memory models. It orders memory accesses prior to the barrier and after the barrier with respect to matching barriers on other cores. For instance, a load fence can order loads prior to and following that fence with respect to stores ordered by store fences.

Program order is the order in which instructions are ordered in the program assembly code.

Examples where membarrier() can be useful include implementations of Read-Copy-Update libraries and garbage collectors.

## EXAMPLES
Assuming a multithreaded application where "fast_path()" is executed very frequently, and where "slow_path()" is executed infrequently, the following code (x86) can be transformed using membarrier():

```
#include <stdlib.h>
static volatile int a, b;
static void
fast_path(int *read_b)
{

    a = 1;

    asm volatile ("mfence" : : : "memory");

    *read_b = b;
}
static void
slow_path(int *read_a)
{

    b = 1;

    asm volatile ("mfence" : : : "memory");

    *read_a = a;
}
int
main(void)
{

    int read_a, read_b;

    /*

     * Real applications would call fast_path() and slow_path()

     * from different threads. Call those from main() to keep

     * this example short.

     */

    slow_path(&read_a);

    fast_path(&read_b);

    /*

     * read_b == 0 implies read_a == 1 and

     * read_a == 0 implies read_b == 1.

     */

    if (read_b == 0 && read_a == 0)

        abort();

    exit(EXIT_SUCCESS);
}
```

The code above transformed to use membarrier() becomes:

```
#define _GNU_SOURCE
#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>
#include <sys/syscall.h>
#include <linux/membarrier.h>
static volatile int a, b;
static int
membarrier(int cmd, unsigned int flags, int cpu_id)
{

    return syscall(__NR_membarrier, cmd, flags, cpu_id);
}
static int
init_membarrier(void)
{

    int ret;

    /* Check that membarrier() is supported. */

    ret = membarrier(MEMBARRIER_CMD_QUERY, 0, 0);

    if (ret < 0) {

        perror("membarrier");

        return -1;

    }

    if (!(ret & MEMBARRIER_CMD_GLOBAL)) {

        fprintf(stderr,

            "membarrier does not support MEMBARRIER_CMD_GLOBAL\n");

        return -1;

    }

    return 0;
}
static void
fast_path(int *read_b)
{

    a = 1;

    asm volatile ("" : : : "memory");

    *read_b = b;
}
static void
slow_path(int *read_a)
{

    b = 1;

    membarrier(MEMBARRIER_CMD_GLOBAL, 0, 0);

    *read_a = a;
}
int
main(int argc, char *argv[])
{

    int read_a, read_b;

    if (init_membarrier())

        exit(EXIT_FAILURE);

    /*

     * Real applications would call fast_path() and slow_path()

     * from different threads. Call those from main() to keep

     * this example short.

     */

    slow_path(&read_a);

    fast_path(&read_b);

    /*

     * read_b == 0 implies read_a == 1 and

     * read_a == 0 implies read_b == 1.

     */

    if (read_b == 0 && read_a == 0)

        abort();

    exit(EXIT_SUCCESS);
}
```


title: memfd_create(2)

summary: create an anonymous file

text:
# memfd_create(2)

## NAME
memfd_create - create an anonymous file

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#define _GNU_SOURCE         /* See feature_test_macros(7) */
#include <sys/mman.h>
```

```
int memfd_create(const char *name, unsigned int flags);
```

## DESCRIPTION
memfd_create() creates an anonymous file and returns a file descriptor that refers to it. The file behaves like a regular file, and so can be modified, truncated, memory-mapped, and so on. However, unlike a regular file, it lives in RAM and has a volatile backing storage. Once all references to the file are dropped, it is automatically released. Anonymous memory is used for all backing pages of the file. Therefore, files created by memfd_create() have the same semantics as other anonymous memory allocations such as those allocated using mmap(2) with the MAP_ANONYMOUS flag.

The initial size of the file is set to 0. Following the call, the file size should be set using ftruncate(2). (Alternatively, the file may be populated by calls to write(2) or similar.)

The name supplied in name is used as a filename and will be displayed as the target of the corresponding symbolic link in the directory /proc/self/fd/. The displayed name is always prefixed with memfd: and serves only for debugging purposes. Names do not affect the behavior of the file descriptor, and as such multiple files can have the same name without any side effects.

The following values may be bitwise ORed in flags to change the behavior of memfd_create():

MFD_CLOEXEC

Set the close-on-exec (FD_CLOEXEC) flag on the new file descriptor. See the description of the O_CLOEXEC flag in open(2) for reasons why this may be useful.

MFD_ALLOW_SEALING

Allow sealing operations on this file. See the discussion of the F_ADD_SEALS and F_GET_SEALS operations in fcntl(2), and also NOTES, below. The initial set of seals is empty. If this flag is not set, the initial set of seals will be F_SEAL_SEAL, meaning that no other seals can be set on the file.

MFD_HUGETLB (since Linux 4.14)

The anonymous file will be created in the hugetlbfs filesystem using huge pages. See the Linux kernel source file Documentation/admin-guide/mm/hugetlbpage.rst for more information about hugetlbfs. Specifying both MFD_HUGETLB and MFD_ALLOW_SEALING in flags is supported since Linux 4.16.

MFD_HUGE_2MB, MFD_HUGE_1GB, ...

Used in conjunction with MFD_HUGETLB to select alternative hugetlb page sizes (respectively, 2 MB, 1 GB, ...) on systems that support multiple hugetlb page sizes. Definitions for known huge page sizes are included in the header file <linux/memfd.h>.

For details on encoding huge page sizes not included in the header file, see the discussion of the similarly named constants in mmap(2).

Unused bits in flags must be 0.

As its return value, memfd_create() returns a new file descriptor that can be used to refer to the file. This file descriptor is opened for both reading and writing (O_RDWR) and O_LARGEFILE is set for the file descriptor.

With respect to fork(2) and execve(2), the usual semantics apply for the file descriptor created by memfd_create(). A copy of the file descriptor is inherited by the child produced by fork(2) and refers to the same file. The file descriptor is preserved across execve(2), unless the close-on-exec flag has been set.

## RETURN VALUE
On success, memfd_create() returns a new file descriptor. On error, -1 is returned and errno is set to indicate the error.

## ERRORS
EFAULT

The address in name points to invalid memory.

EINVAL

flags included unknown bits.

EINVAL

name was too long. (The limit is 249 bytes, excluding the terminating null byte.)

EINVAL

Both MFD_HUGETLB and MFD_ALLOW_SEALING were specified in flags.

EMFILE

The per-process limit on the number of open file descriptors has been reached.

ENFILE

The system-wide limit on the total number of open files has been reached.

ENOMEM

There was insufficient memory to create a new anonymous file.

EPERM

The MFD_HUGETLB flag was specified, but the caller was not privileged (did not have the CAP_IPC_LOCK capability) and is not a member of the sysctl_hugetlb_shm_group group; see the description of /proc/sys/vm/sysctl_hugetlb_shm_group in proc(5).

## STANDARDS
Linux.

## HISTORY
Linux 3.17, glibc 2.27.

## NOTES
The memfd_create() system call provides a simple alternative to manually mounting a tmpfs(5) filesystem and creating and opening a file in that filesystem. The primary purpose of memfd_create() is to create files and associated file descriptors that are used with the file-sealing APIs provided by fcntl(2).

The memfd_create() system call also has uses without file sealing (which is why file-sealing is disabled, unless explicitly requested with the MFD_ALLOW_SEALING flag). In particular, it can be used as an alternative to creating files in tmp or as an alternative to using the open(2) O_TMPFILE in cases where there is no intention to actually link the resulting file into the filesystem.

### File sealing
In the absence of file sealing, processes that communicate via shared memory must either trust each other, or take measures to deal with the possibility that an untrusted peer may manipulate the shared memory region in problematic ways. For example, an untrusted peer might modify the contents of the shared memory at any time, or shrink the shared memory region. The former possibility leaves the local process vulnerable to time-of-check-to-time-of-use race conditions (typically dealt with by copying data from the shared memory region before checking and using it). The latter possibility leaves the local process vulnerable to SIGBUS signals when an attempt is made to access a now-nonexistent location in the shared memory region. (Dealing with this possibility necessitates the use of a handler for the SIGBUS signal.)

Dealing with untrusted peers imposes extra complexity on code that employs shared memory. Memory sealing enables that extra complexity to be eliminated, by allowing a process to operate secure in the knowledge that its peer can't modify the shared memory in an undesired fashion.

An example of the usage of the sealing mechanism is as follows:

(1)

The first process creates a tmpfs(5) file using memfd_create(). The call yields a file descriptor used in subsequent steps.

(2)

The first process sizes the file created in the previous step using ftruncate(2), maps it using mmap(2), and populates the shared memory with the desired data.

(3)

The first process uses the fcntl(2) F_ADD_SEALS operation to place one or more seals on the file, in order to restrict further modifications on the file. (If placing the seal F_SEAL_WRITE, then it will be necessary to first unmap the shared writable mapping created in the previous step. Otherwise, behavior similar to F_SEAL_WRITE can be achieved by using F_SEAL_FUTURE_WRITE, which will prevent future writes via mmap(2) and write(2) from succeeding while keeping existing shared writable mappings).

(4)

A second process obtains a file descriptor for the tmpfs(5) file and maps it. Among the possible ways in which this could happen are the following:

•

The process that called memfd_create() could transfer the resulting file descriptor to the second process via a UNIX domain socket (see unix(7) and cmsg(3)). The second process then maps the file using mmap(2).

•

The second process is created via fork(2) and thus automatically inherits the file descriptor and mapping. (Note that in this case and the next, there is a natural trust relationship between the two processes, since they are running under the same user ID. Therefore, file sealing would not normally be necessary.)

•

The second process opens the file /proc/pid/fd/fd, where <pid> is the PID of the first process (the one that called memfd_create()), and <fd> is the number of the file descriptor returned by the call to memfd_create() in that process. The second process then maps the file using mmap(2).

(5)

The second process uses the fcntl(2) F_GET_SEALS operation to retrieve the bit mask of seals that has been applied to the file. This bit mask can be inspected in order to determine what kinds of restrictions have been placed on file modifications. If desired, the second process can apply further seals to impose additional restrictions (so long as the F_SEAL_SEAL seal has not yet been applied).

## EXAMPLES
Below are shown two example programs that demonstrate the use of memfd_create() and the file sealing API.

The first program, t_memfd_create.c, creates a tmpfs(5) file using memfd_create(), sets a size for the file, maps it into memory, and optionally places some seals on the file. The program accepts up to three command-line arguments, of which the first two are required. The first argument is the name to associate with the file, the second argument is the size to be set for the file, and the optional third argument is a string of characters that specify seals to be set on the file.

The second program, t_get_seals.c, can be used to open an existing file that was created via memfd_create() and inspect the set of seals that have been applied to that file.

The following shell session demonstrates the use of these programs. First we create a tmpfs(5) file and set some seals on it:

```
$ ./t_memfd_create my_memfd_file 4096 sw &
[1] 11775
PID: 11775; fd: 3; /proc/11775/fd/3
```

At this point, the t_memfd_create program continues to run in the background. From another program, we can obtain a file descriptor for the file created by memfd_create() by opening the /proc/pid/fd file that corresponds to the file descriptor opened by memfd_create(). Using that pathname, we inspect the content of the /proc/pid/fd symbolic link, and use our t_get_seals program to view the seals that have been placed on the file:

```
$ readlink /proc/11775/fd/3
/memfd:my_memfd_file (deleted)
$ ./t_get_seals /proc/11775/fd/3
Existing seals: WRITE SHRINK
```

### Program source: t_memfd_create.c

```
#define _GNU_SOURCE
#include <err.h>
#include <fcntl.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/mman.h>
#include <unistd.h>
int
main(int argc, char *argv[])
{

    int           fd;

    char          *name, *seals_arg;

    ssize_t       len;

    unsigned int  seals;

    if (argc < 3) {

        fprintf(stderr, "%s name size [seals]\n", argv[0]);

        fprintf(stderr, "\t'seals' can contain any of the "

                "following characters:\n");

        fprintf(stderr, "\t\tg - F_SEAL_GROW\n");

        fprintf(stderr, "\t\ts - F_SEAL_SHRINK\n");

        fprintf(stderr, "\t\tw - F_SEAL_WRITE\n");

        fprintf(stderr, "\t\tW - F_SEAL_FUTURE_WRITE\n");

        fprintf(stderr, "\t\tS - F_SEAL_SEAL\n");

        exit(EXIT_FAILURE);

    }

    name = argv[1];

    len = atoi(argv[2]);

    seals_arg = argv[3];

    /* Create an anonymous file in tmpfs; allow seals to be

       placed on the file. */

    fd = memfd_create(name, MFD_ALLOW_SEALING);

    if (fd == -1)

        err(EXIT_FAILURE, "memfd_create");

    /* Size the file as specified on the command line. */

    if (ftruncate(fd, len) == -1)

        err(EXIT_FAILURE, "truncate");

    printf("PID: %jd; fd: %d; /proc/%jd/fd/%d\n",

           (intmax_t) getpid(), fd, (intmax_t) getpid(), fd);

    /* Code to map the file and populate the mapping with data

       omitted. */

    /* If a 'seals' command-line argument was supplied, set some

       seals on the file. */

    if (seals_arg != NULL) {

        seals = 0;

        if (strchr(seals_arg, 'g') != NULL)

            seals |= F_SEAL_GROW;

        if (strchr(seals_arg, 's') != NULL)

            seals |= F_SEAL_SHRINK;

        if (strchr(seals_arg, 'w') != NULL)

            seals |= F_SEAL_WRITE;

        if (strchr(seals_arg, 'W') != NULL)

            seals |= F_SEAL_FUTURE_WRITE;

        if (strchr(seals_arg, 'S') != NULL)

            seals |= F_SEAL_SEAL;

        if (fcntl(fd, F_ADD_SEALS, seals) == -1)

            err(EXIT_FAILURE, "fcntl");

    }

    /* Keep running, so that the file created by memfd_create()

       continues to exist. */

    pause();

    exit(EXIT_SUCCESS);
}
```

### Program source: t_get_seals.c

```
#define _GNU_SOURCE
#include <err.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{

    int           fd;

    unsigned int  seals;

    if (argc != 2) {

        fprintf(stderr, "%s /proc/PID/fd/FD\n", argv[0]);

        exit(EXIT_FAILURE);

    }

    fd = open(argv[1], O_RDWR);

    if (fd == -1)

        err(EXIT_FAILURE, "open");

    seals = fcntl(fd, F_GET_SEALS);

    if (seals == -1)

        err(EXIT_FAILURE, "fcntl");

    printf("Existing seals:");

    if (seals & F_SEAL_SEAL)

        printf(" SEAL");

    if (seals & F_SEAL_GROW)

        printf(" GROW");

    if (seals & F_SEAL_WRITE)

        printf(" WRITE");

    if (seals & F_SEAL_FUTURE_WRITE)

        printf(" FUTURE_WRITE");

    if (seals & F_SEAL_SHRINK)

        printf(" SHRINK");

    printf("\n");

    /* Code to map the file and access the contents of the

       resulting mapping omitted. */

    exit(EXIT_SUCCESS);
}
```

## SEE ALSO
fcntl(2), ftruncate(2), memfd_secret(2), mmap(2), shmget(2), shm_open(3)


title: memfd_secret(2)

summary: create an anonymous RAM-based file

text:
# memfd_secret(2)

## NAME
memfd_secret - create an anonymous RAM-based file to access secret memory regions

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/syscall.h>      /* Definition of SYS_* constants */
#include <unistd.h>
```

```
int syscall(SYS_memfd_secret, unsigned int flags);
```

Note: glibc provides no wrapper for memfd_secret(), necessitating the use of syscall(2).

## DESCRIPTION
memfd_secret() creates an anonymous RAM-based file and returns a file descriptor that refers to it. The file provides a way to create and access memory regions with stronger protection than usual RAM-based files and anonymous memory mappings. Once all open references to the file are closed, it is automatically released. The initial size of the file is set to 0. Following the call, the file size should be set using ftruncate(2).

The memory areas backing the file created with memfd_secret(2) are visible only to the processes that have access to the file descriptor. The memory region is removed from the kernel page tables and only the page tables of the processes holding the file descriptor map the corresponding physical memory. (Thus, the pages in the region can't be accessed by the kernel itself, so that, for example, pointers to the region can't be passed to system calls.)

The following values may be bitwise ORed in flags to control the behavior of memfd_secret():

FD_CLOEXEC

Set the close-on-exec flag on the new file descriptor, which causes the region to be removed from the process on execve(2). See the description of the O_CLOEXEC flag in open(2)

As its return value, memfd_secret() returns a new file descriptor that refers to an anonymous file. This file descriptor is opened for both reading and writing (O_RDWR) and O_LARGEFILE is set for the file descriptor.

With respect to fork(2) and execve(2), the usual semantics apply for the file descriptor created by memfd_secret(). A copy of the file descriptor is inherited by the child produced by fork(2) and refers to the same file. The file descriptor is preserved across execve(2), unless the close-on-exec flag has been set.

The memory region is locked into memory in the same way as with mlock(2), so that it will never be written into swap, and hibernation is inhibited for as long as any memfd_secret() descriptions exist. However the implementation of memfd_secret() will not try to populate the whole range during the mmap(2) call that attaches the region into the process's address space; instead, the pages are only actually allocated as they are faulted in. The amount of memory allowed for memory mappings of the file descriptor obeys the same rules as mlock(2) and cannot exceed RLIMIT_MEMLOCK.

## RETURN VALUE
On success, memfd_secret() returns a new file descriptor. On error, -1 is returned and errno is set to indicate the error.

## ERRORS
EINVAL

flags included unknown bits.

EMFILE

The per-process limit on the number of open file descriptors has been reached.

EMFILE

The system-wide limit on the total number of open files has been reached.

ENOMEM

There was insufficient memory to create a new anonymous file.

ENOSYS

memfd_secret() is not implemented on this architecture, or has not been enabled on the kernel command-line with secretmem_enable=1.

## STANDARDS
Linux.

## HISTORY
Linux 5.14.

## NOTES
The memfd_secret() system call is designed to allow a user-space process to create a range of memory that is inaccessible to anybody else - kernel included. There is no 100% guarantee that kernel won't be able to access memory ranges backed by memfd_secret() in any circumstances, but nevertheless, it is much harder to exfiltrate data from these regions.

memfd_secret() provides the following protections:

•

Enhanced protection (in conjunction with all the other in-kernel attack prevention systems) against ROP attacks. Absence of any in-kernel primitive for accessing memory backed by memfd_secret() means that one-gadget ROP attack can't work to perform data exfiltration. The attacker would need to find enough ROP gadgets to reconstruct the missing page table entries, which significantly increases difficulty of the attack, especially when other protections like the kernel stack size limit and address space layout randomization are in place.

•

Prevent cross-process user-space memory exposures. Once a region for a memfd_secret() memory mapping is allocated, the user can't accidentally pass it into the kernel to be transmitted somewhere. The memory pages in this region cannot be accessed via the direct map and they are disallowed in get_user_pages.

•

Harden against exploited kernel flaws. In order to access memory areas backed by memfd_secret(), a kernel-side attack would need to either walk the page tables and create new ones, or spawn a new privileged user-space process to perform secrets exfiltration using ptrace(2).

The way memfd_secret() allocates and locks the memory may impact overall system performance, therefore the system call is disabled by default and only available if the system administrator turned it on using "secretmem.enable=y" kernel parameter.

To prevent potential data leaks of memory regions backed by memfd_secret() from a hybernation image, hybernation is prevented when there are active memfd_secret() users.

## SEE ALSO
fcntl(2), ftruncate(2), mlock(2), memfd_create(2), mmap(2), setrlimit(2)


title: migrate_pages(2)

text:
# migrate_pages(2)

## NAME
migrate_pages - move all pages in a process to another set of nodes

## LIBRARY
NUMA (Non-Uniform Memory Access) policy library (libnuma, -lnuma)

## SYNOPSIS

```
#include <numaif.h>
```

```
long migrate_pages(int pid, unsigned long maxnode,
                   const unsigned long *old_nodes,
                   const unsigned long *new_nodes);
```

## DESCRIPTION
migrate_pages() attempts to move all pages of the process pid that are in memory nodes old_nodes to the memory nodes in new_nodes. Pages not located in any node in old_nodes will not be migrated. As far as possible, the kernel maintains the relative topology relationship inside old_nodes during the migration to new_nodes.

The old_nodes and new_nodes arguments are pointers to bit masks of node numbers, with up to maxnode bits in each mask. These masks are maintained as arrays of unsigned long integers (in the last long integer, the bits beyond those specified by maxnode are ignored). The maxnode argument is the maximum node number in the bit mask plus one (this is the same as in mbind(2), but different from select(2)).

The pid argument is the ID of the process whose pages are to be moved. To move pages in another process, the caller must be privileged (CAP_SYS_NICE) or the real or effective user ID of the calling process must match the real or saved-set user ID of the target process. If pid is 0, then migrate_pages() moves pages of the calling process.

Pages shared with another process will be moved only if the initiating process has the CAP_SYS_NICE privilege.

## RETURN VALUE
On success migrate_pages() returns the number of pages that could not be moved (i.e., a return of zero means that all pages were successfully moved). On error, it returns -1, and sets errno to indicate the error.

## ERRORS
EFAULT

Part or all of the memory range specified by old_nodes/new_nodes and maxnode points outside your accessible address space.

EINVAL

The value specified by maxnode exceeds a kernel-imposed limit. Or, old_nodes or new_nodes specifies one or more node IDs that are greater than the maximum supported node ID. Or, none of the node IDs specified by new_nodes are on-line and allowed by the process's current cpuset context, or none of the specified nodes contain memory.

EPERM

Insufficient privilege (CAP_SYS_NICE) to move pages of the process specified by pid, or insufficient privilege (CAP_SYS_NICE) to access the specified target nodes.

ESRCH

No process matching pid could be found.

## STANDARDS
Linux.

## HISTORY
Linux 2.6.16.

## NOTES
For information on library support, see numa(7).

Use get_mempolicy(2) with the MPOL_F_MEMS_ALLOWED flag to obtain the set of nodes that are allowed by the calling process's cpuset. Note that this information is subject to change at any time by manual or automatic reconfiguration of the cpuset.

Use of migrate_pages() may result in pages whose location (node) violates the memory policy established for the specified addresses (see mbind(2)) and/or the specified process (see set_mempolicy(2)). That is, memory policy does not constrain the destination nodes used by migrate_pages().

The <numaif.h> header is not included with glibc, but requires installing libnuma-devel or a similar package.

## SEE ALSO
get_mempolicy(2), mbind(2), set_mempolicy(2), numa(3), numa_maps(5), cpuset(7), numa(7), migratepages(8), numastat(8)

Documentation/vm/page_migration.rst in the Linux kernel source tree


mincore

title: mincore(2)

text:
# mincore(2)

## NAME
mincore - determine whether pages are resident in memory

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/mman.h>
```

```
int mincore(void addr[.length], size_t length, unsigned char *vec);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

mincore():

```
    Since glibc 2.19:

        _DEFAULT_SOURCE

    glibc 2.19 and earlier:

        _BSD_SOURCE || _SVID_SOURCE
```

## DESCRIPTION
mincore() returns a vector that indicates whether pages of the calling process's virtual memory are resident in core (RAM), and so will not cause a disk access (page fault) if referenced. The kernel returns residency information about the pages starting at the address addr, and continuing for length bytes.

The addr argument must be a multiple of the system page size. The length argument need not be a multiple of the page size, but since residency information is returned for whole pages, length is effectively rounded up to the next multiple of the page size. One may obtain the page size (PAGE_SIZE) using sysconf(_SC_PAGESIZE).

The vec argument must point to an array containing at least (length+PAGE_SIZE-1) / PAGE_SIZE bytes. On return, the least significant bit of each byte will be set if the corresponding page is currently resident in memory, and be clear otherwise. (The settings of the other bits in each byte are undefined; these bits are reserved for possible later use.) Of course the information returned in vec is only a snapshot: pages that are not locked in memory can come and go at any moment, and the contents of vec may already be stale by the time this call returns.

## RETURN VALUE
On success, mincore() returns zero. On error, -1 is returned, and errno is set to indicate the error.

## ERRORS
EAGAIN kernel is temporarily out of resources.

EFAULT

vec points to an invalid address.

EINVAL

addr is not a multiple of the page size.

ENOMEM

length is greater than (TASK_SIZE - addr). (This could occur if a negative value is specified for length, since that value will be interpreted as a large unsigned integer.) In Linux 2.6.11 and earlier, the error EINVAL was returned for this condition.

ENOMEM

addr to addr + length contained unmapped memory.

## STANDARDS
None.

## HISTORY
Linux 2.3.99pre1, glibc 2.2.

First appeared in 4.4BSD.

NetBSD, FreeBSD, OpenBSD, Solaris 8, AIX 5.1, SunOS 4.1.

## BUGS
Before Linux 2.6.21, mincore() did not return correct information for MAP_PRIVATE mappings, or for nonlinear mappings (established using remap_file_pages(2)).

## SEE ALSO
fincore(1), madvise(2), mlock(2), mmap(2), posix_fadvise(2), posix_madvise(3)


mkdir

title: mkdir(2)

summary: create a directory

text:
# mkdir(2)

## NAME
mkdir, mkdirat - create a directory

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/stat.h>
```

```
int mkdir(const char *pathname, mode_t mode);
```

```
#include <fcntl.h>           /* Definition of AT_* constants */
#include <sys/stat.h>
```

```
int mkdirat(int dirfd, const char *pathname, mode_t mode);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

mkdirat():

```
    Since glibc 2.10:

        _POSIX_C_SOURCE >= 200809L

    Before glibc 2.10:

        _ATFILE_SOURCE
```

## DESCRIPTION
mkdir() attempts to create a directory named pathname.

The argument mode specifies the mode for the new directory (see inode(7)). It is modified by the process's umask in the usual way: in the absence of a default ACL, the mode of the created directory is (mode & ~umask & 0777). Whether other mode bits are honored for the created directory depends on the operating system. For Linux, see NOTES below.

The newly created directory will be owned by the effective user ID of the process. If the directory containing the file has the set-group-ID bit set, or if the filesystem is mounted with BSD group semantics (mount -o bsdgroups or, synonymously mount -o grpid), the new directory will inherit the group ownership from its parent; otherwise it will be owned by the effective group ID of the process.

If the parent directory has the set-group-ID bit set, then so will the newly created directory.

### mkdirat()
The mkdirat() system call operates in exactly the same way as mkdir(), except for the differences described here.

If the pathname given in pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor dirfd (rather than relative to the current working directory of the calling process, as is done by mkdir() for a relative pathname).

If pathname is relative and dirfd is the special value AT_FDCWD, then pathname is interpreted relative to the current working directory of the calling process (like mkdir()).

If pathname is absolute, then dirfd is ignored.

See openat(2) for an explanation of the need for mkdirat().

## RETURN VALUE
mkdir() and mkdirat() return zero on success. On error, -1 is returned and errno is set to indicate the error.

## ERRORS
EACCES

The parent directory does not allow write permission to the process, or one of the directories in pathname did not allow search permission. (See also path_resolution(7).)

EBADF

(mkdirat()) pathname is relative but dirfd is neither AT_FDCWD nor a valid file descriptor.

EDQUOT

The user's quota of disk blocks or inodes on the filesystem has been exhausted.

EEXIST

pathname already exists (not necessarily as a directory). This includes the case where pathname is a symbolic link, dangling or not.

EFAULT

pathname points outside your accessible address space.

EINVAL

The final component ("basename") of the new directory's pathname is invalid (e.g., it contains characters not permitted by the underlying filesystem).

ELOOP

Too many symbolic links were encountered in resolving pathname.

EMLINK

The number of links to the parent directory would exceed LINK_MAX.

ENAMETOOLONG

pathname was too long.

ENOENT

A directory component in pathname does not exist or is a dangling symbolic link.

ENOMEM

Insufficient kernel memory was available.

ENOSPC

The device containing pathname has no room for the new directory.

ENOSPC

The new directory cannot be created because the user's disk quota is exhausted.

ENOTDIR

A component used as a directory in pathname is not, in fact, a directory.

ENOTDIR

(mkdirat()) pathname is relative and dirfd is a file descriptor referring to a file other than a directory.

EPERM

The filesystem containing pathname does not support the creation of directories.

EROFS

pathname refers to a file on a read-only filesystem.

## VERSIONS
Under Linux, apart from the permission bits, the S_ISVTX mode bit is also honored.

### glibc notes
On older kernels where mkdirat() is unavailable, the glibc wrapper function falls back to the use of mkdir(). When pathname is a relative pathname, glibc constructs a pathname based on the symbolic link in /proc/self/fd that corresponds to the dirfd argument.

## STANDARDS
POSIX.1-2008.

## HISTORY
mkdir()

SVr4, BSD, POSIX.1-2001.

mkdirat()

Linux 2.6.16, glibc 2.4.

## NOTES
There are many infelicities in the protocol underlying NFS. Some of these affect mkdir().

## SEE ALSO
mkdir(1), chmod(2), chown(2), mknod(2), mount(2), rmdir(2), stat(2), umask(2), unlink(2), acl(5), path_resolution(7)


mknod

title: mknod(2)

summary: create a special or ordinary file

text:
# mknod(2)

## NAME
mknod, mknodat - create a special or ordinary file

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/stat.h>
```

```
int mknod(const char *pathname, mode_t mode, dev_t dev);
```

```
#include <fcntl.h>           /* Definition of AT_* constants */
#include <sys/stat.h>
```

```
int mknodat(int dirfd, const char *pathname, mode_t mode, dev_t dev);
```

Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

mknod():

```
    _XOPEN_SOURCE >= 500

        || /* Since glibc 2.19: */ _DEFAULT_SOURCE

        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
```

## DESCRIPTION
The system call mknod() creates a filesystem node (file, device special file, or named pipe) named pathname, with attributes specified by mode and dev.

The mode argument specifies both the file mode to use and the type of node to be created. It should be a combination (using bitwise OR) of one of the file types listed below and zero or more of the file mode bits listed in inode(7).

The file mode is modified by the process's umask in the usual way: in the absence of a default ACL, the permissions of the created node are (mode & ~umask).

The file type must be one of S_IFREG, S_IFCHR, S_IFBLK, S_IFIFO, or S_IFSOCK to specify a regular file (which will be created empty), character special file, block special file, FIFO (named pipe), or UNIX domain socket, respectively. (Zero file type is equivalent to type S_IFREG.)

If the file type is S_IFCHR or S_IFBLK, then dev specifies the major and minor numbers of the newly created device special file (makedev(3) may be useful to build the value for dev); otherwise it is ignored.

If pathname already exists, or is a symbolic link, this call fails with an EEXIST error.

The newly created node will be owned by the effective user ID of the process. If the directory containing the node has the set-group-ID bit set, or if the filesystem is mounted with BSD group semantics, the new node will inherit the group ownership from its parent directory; otherwise it will be owned by the effective group ID of the process.

### mknodat()
The mknodat() system call operates in exactly the same way as mknod(), except for the differences described here.

If the pathname given in pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor dirfd (rather than relative to the current working directory of the calling process, as is done by mknod() for a relative pathname).

If pathname is relative and dirfd is the special value AT_FDCWD, then pathname is interpreted relative to the current working directory of the calling process (like mknod()).

If pathname is absolute, then dirfd is ignored.

See openat(2) for an explanation of the need for mknodat().

## RETURN VALUE
mknod() and mknodat() return zero on success. On error, -1 is returned and errno is set to indicate the error.

## ERRORS
EACCES

The parent directory does not allow write permission to the process, or one of the directories in the path prefix of pathname did not allow search permission. (See also path_resolution(7).)

EBADF

(mknodat()) pathname is relative but dirfd is neither AT_FDCWD nor a valid file descriptor.

EDQUOT

The user's quota of disk blocks or inodes on the filesystem has been exhausted.

EEXIST

pathname already exists. This includes the case where pathname is a symbolic link, dangling or not.

EFAULT

pathname points outside your accessible address space.

EINVAL

mode requested creation of something other than a regular file, device special file, FIFO or socket.

ELOOP

Too many symbolic links were encountered in resolving pathname.

ENAMETOOLONG

pathname was too long.

ENOENT

A directory component in pathname does not exist or is a dangling symbolic link.

ENOMEM

Insufficient kernel memory was available.

ENOSPC

The device containing pathname has no room for the new node.

ENOTDIR

A component used as a directory in pathname is not, in fact, a directory.

ENOTDIR

(mknodat()) pathname is relative and dirfd is a file descriptor referring to a file other than a directory.

EPERM

mode requested creation of something other than a regular file, FIFO (named pipe), or UNIX domain socket, and the caller is not privileged (Linux: does not have the CAP_MKNOD capability); also returned if the filesystem containing pathname does not support the type of node requested.

EROFS

pathname refers to a file on a read-only filesystem.

## VERSIONS
POSIX.1-2001 says: "The only portable use of mknod() is to create a FIFO-special file. If mode is not S_IFIFO or dev is not 0, the behavior of mknod() is unspecified." However, nowadays one should never use mknod() for this purpose; one should use mkfifo(3), a function especially defined for this purpose.

Under Linux, mknod() cannot be used to create directories. One should make directories with mkdir(2).

## STANDARDS
POSIX.1-2008.

## HISTORY
mknod()

SVr4, 4.4BSD, POSIX.1-2001 (but see VERSIONS).

mknodat()

Linux 2.6.16, glibc 2.4. POSIX.1-2008.

## NOTES
There are many infelicities in the protocol underlying NFS. Some of these affect mknod() and mknodat().

## SEE ALSO
mknod(1), chmod(2), chown(2), fcntl(2), mkdir(2), mount(2), socket(2), stat(2), umask(2), unlink(2), makedev(3), mkfifo(3), acl(5), path_resolution(7)


mlock

title: mlock(2)

summary: lock and unlock memory

text:
# mlock(2)

## NAME
mlock, mlock2, munlock, mlockall, munlockall - lock and unlock memory

## LIBRARY
Standard C library (libc, -lc)

## SYNOPSIS

```
#include <sys/mman.h>
```

```
int mlock(const void addr[.len], size_t len);
int mlock2(const void addr[.len], size_t len, unsigned int flags);
int munlock(const void addr[.len], size_t len);
```

```
int mlockall(int flags);
int munlockall(void);
```

## DESCRIPTION
mlock(), mlock2(), and mlockall() lock part or all of the calling process's virtual address space into RAM, preventing that memory from being paged to the swap area.

munlock() and munlockall() perform the converse operation, unlocking part or all of the calling process's virtual address space, so that pages in the specified virtual address range can be swapped out again if required by the kernel memory manager.

Memory locking and unlocking are performed in units of whole pages.

### mlock(), mlock2(), and munlock()
mlock() locks pages in the address range starting at addr and continuing for len bytes. All pages that contain a part of the specified address range are guaranteed to be resident in RAM when the call returns successfully; the pages are guaranteed to stay in RAM until later unlocked.

mlock2() also locks pages in the specified range starting at addr and continuing for len bytes. However, the state of the pages contained in that range after the call returns successfully will depend on the value in the flags argument.

The flags argument can be either 0 or the following constant:

MLOCK_ONFAULT

Lock pages that are currently resident and mark the entire range so that the remaining nonresident pages are locked when they are populated by a page fault.

If flags is 0, mlock2() behaves exactly the same as mlock().

munlock() unlocks pages in the address range starting at addr and continuing for len bytes. After this call, all pages that contain a part of the specified memory range can be moved to external swap space again by the kernel.

### mlockall() and munlockall()
mlockall() locks all pages mapped into the address space of the calling process. This includes the pages of the code, data, and stack segment, as well as shared libraries, user space kernel data, shared memory, and memory-mapped files. All mapped pages are guaranteed to be resident in RAM when the call returns successfully; the pages are guaranteed to stay in RAM until later unlocked.

The flags argument is constructed as the bitwise OR of one or more of the following constants:

MCL_CURRENT

Lock all pages which are currently mapped into the address space of the process.

MCL_FUTURE

Lock all pages which will become mapped into the address space of the process in the future. These could be, for instance, new pages required by a growing heap and stack as well as new memory-mapped files or shared memory regions.

MCL_ONFAULT (since Linux 4.4)

Used together with MCL_CURRENT, MCL_FUTURE, or both. Mark all current (with MCL_CURRENT) or future (with MCL_FUTURE) mappings to lock pages when they are faulted in. When used with MCL_CURRENT, all present pages are locked, but mlockall() will not fault in non-present pages. When used with MCL_FUTURE, all future mappings will be marked to lock pages when they are faulted in, but they will not be populated by the lock when the mapping is created. MCL_ONFAULT must be used with either MCL_CURRENT or MCL_FUTURE or both.

If MCL_FUTURE has been specified, then a later system call (e.g., mmap(2), sbrk(2), malloc(3)), may fail if it would cause the number of locked bytes to exceed the permitted maximum (see below). In the same circumstances, stack growth may likewise fail: the kernel will deny stack expansion and deliver a SIGSEGV signal to the process.

munlockall() unlocks all pages mapped into the address space of the calling process.

## RETURN VALUE
On success, these system calls return 0. On error, -1 is returned, errno is set to indicate the error, and no changes are made to any locks in the address space of the process.

## ERRORS
EAGAIN

(mlock(), mlock2(), and munlock()) Some or all of the specified address range could not be locked.

EINVAL

(mlock(), mlock2(), and munlock()) The result of the addition addr+len was less than addr (e.g., the addition may have resulted in an overflow).

EINVAL

(mlock2()) Unknown flags were specified.

EINVAL

(mlockall()) Unknown flags were specified or MCL_ONFAULT was specified without either MCL_FUTURE or MCL_CURRENT.

EINVAL

(Not on Linux) addr was not a multiple of the page size.

ENOMEM

(mlock(), mlock2(), and munlock()) Some of the specified address range does not correspond to mapped pages in the address space of the process.

ENOMEM

(mlock(), mlock2(), and munlock()) Locking or unlocking a region would result in the total number of mappings with distinct attributes (e.g., locked versus unlocked) exceeding the allowed maximum. (For example, unlocking a range in the middle of a currently locked mapping would result in three mappings: two locked mappings at each end and an unlocked mapping in the middle.)

ENOMEM

(Linux 2.6.9 and later) the caller had a nonzero RLIMIT_MEMLOCK soft resource limit, but tried to lock more memory than the limit permitted. This limit is not enforced if the process is privileged (CAP_IPC_LOCK).

ENOMEM

(Linux 2.4 and earlier) the calling process tried to lock more than half of RAM.

EPERM

The caller is not privileged, but needs privilege (CAP_IPC_LOCK) to perform the requested operation.

EPERM

(munlockall()) (Linux 2.6.8 and earlier) The caller was not privileged (CAP_IPC_LOCK).

## VERSIONS

### Linux
Under Linux, mlock(), mlock2(), and munlock() automatically round addr down to the nearest page boundary. However, the POSIX.1 specification of mlock() and munlock() allows an implementation to require that addr is page aligned, so portable applications should ensure this.

The VmLck field of the Linux-specific /proc/pid/status file shows how many kilobytes of memory the process with ID PID has locked using mlock(), mlock2(), mlockall(), and mmap(2) MAP_LOCKED.

## STANDARDS
mlock()

munlock()

mlockall()

munlockall()

POSIX.1-2008.

mlock2()

Linux.

On POSIX systems on which mlock() and munlock() are available, _POSIX_MEMLOCK_RANGE is defined in <unistd.h> and the number of bytes in a page can be determined from the constant PAGESIZE (if defined) in <limits.h> or by calling sysconf(_SC_PAGESIZE).

On POSIX systems on which mlockall() and munlockall() are available, _POSIX_MEMLOCK is defined in <unistd.h> to a value greater than 0. (See also sysconf(3).)

## HISTORY
mlock()

munlock()

mlockall()

munlockall()

POSIX.1-2001, POSIX.1-2008, SVr4.

mlock2()

Linux 4.4, glibc 2.27.

## NOTES
Memory locking has two main applications: real-time algorithms and high-security data processing. Real-time applications require deterministic timing, and, like scheduling, paging is one major cause of unexpected program execution delays. Real-time applications will usually also switch to a real-time scheduler with sched_setscheduler(2). Cryptographic security software often handles critical bytes like passwords or secret keys as data structures. As a result of paging, these secrets could be transferred onto a persistent swap store medium, where they might be accessible to the enemy long after the security software has erased the secrets in RAM and terminated. (But be aware that the suspend mode on laptops and some desktop computers will save a copy of the system's RAM to disk, regardless of memory locks.)

Real-time processes that are using mlockall() to prevent delays on page faults should reserve enough locked stack pages before entering the time-critical section, so that no page fault can be caused by function calls. This can be achieved by calling a function that allocates a sufficiently large automatic variable (an array) and writes to the memory occupied by this array in order to touch these stack pages. This way, enough pages will be mapped for the stack and can be locked into RAM. The dummy writes ensure that not even copy-on-write page faults can occur in the critical section.

Memory locks are not inherited by a child created via fork(2) and are automatically removed (unlocked) during an execve(2) or when the process terminates. The mlockall() MCL_FUTURE and MCL_FUTURE | MCL_ONFAULT settings are not inherited by a child created via fork(2) and are cleared during an execve(2).

Note that fork(2) will prepare the address space for a copy-on-write operation. The consequence is that any write access that follows will cause a page fault that in turn may cause high latencies for a real-time process. Therefore, it is crucial not to invoke fork(2) after an mlockall() or mlock() operation—not even from a thread which runs at a low priority within a process which also has a thread running at elevated priority.

The memory lock on an address range is automatically removed if the address range is unmapped via munmap(2).

Memory locks do not stack, that is, pages which have been locked several times by calls to mlock(), mlock2(), or mlockall() will be unlocked by a single call to munlock() for the corresponding range or by munlockall(). Pages which are mapped to several locations or by several processes stay locked into RAM as long as they are locked at least at one location or by at least one process.

If a call to mlockall() which uses the MCL_FUTURE flag is followed by another call that does not specify this flag, the changes made by the MCL_FUTURE call will be lost.

The mlock2() MLOCK_ONFAULT flag and the mlockall() MCL_ONFAULT flag allow efficient memory locking for applications that deal with large mappings where only a (small) portion of pages in the mapping are touched. In such cases, locking all of the pages in a mapping would incur a significant penalty for memory locking.

### Limits and permissions
In Linux 2.6.8 and earlier, a process must be privileged (CAP_IPC_LOCK) in order to lock memory and the RLIMIT_MEMLOCK soft resource limit defines a limit on how much memory the process may lock.

Since Linux 2.6.9, no limits are placed on the amount of memory that a privileged process can lock and the RLIMIT_MEMLOCK soft resource limit instead defines a limit on how much memory an unprivileged process may lock.

## BUGS
In Linux 4.8 and earlier, a bug in the kernel's accounting of locked memory for unprivileged processes (i.e., without CAP_IPC_LOCK) meant that if the region specified by addr and len overlapped an existing lock, then the already locked bytes in the overlapping region were counted twice when checking against the limit. Such double accounting could incorrectly calculate a "total locked memory" value for the process that exceeded the RLIMIT_MEMLOCK limit, with the result that mlock() and mlock2() would fail on requests that should have succeeded. This bug was fixed in Linux 4.9.

In Linux 2.4 series of kernels up to and including Linux 2.4.17, a bug caused the mlockall() MCL_FUTURE flag to be inherited across a fork(2). This was rectified in Linux 2.4.18.

Since Linux 2.6.9, if a privileged process calls mlockall(MCL_FUTURE) and later drops privileges (loses the CAP_IPC_LOCK capability by, for example, setting its effective UID to a nonzero value), then subsequent memory allocations (e.g., mmap(2), brk(2)) will fail if the RLIMIT_MEMLOCK resource limit is encountered.

## SEE ALSO
mincore(2), mmap(2), setrlimit(2), shmctl(2), sysconf(3), proc(5), capabilities(7)