1MADVISE(2)                 Linux Programmer's Manual                MADVISE(2)
2
3
4

NAME

6       madvise - give advice about use of memory
7

SYNOPSIS

9       #include <sys/mman.h>
10
11       int madvise(void *addr, size_t length, int advice);
12
13   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
14
15       madvise():
16           Since glibc 2.19:
17               _DEFAULT_SOURCE
18           Up to and including glibc 2.19:
19               _BSD_SOURCE
20

DESCRIPTION

22       The  madvise()  system call is used to give advice or directions to the
23       kernel about the address range beginning at address addr and with  size
24       length  bytes In most cases, the goal of such advice is to improve sys‐
25       tem or application performance.
26
27       Initially, the system call supported a  set  of  "conventional"  advice
28       values,  which  are  also  available  on several other implementations.
29       (Note, though, that madvise()  is  not  specified  in  POSIX.)   Subse‐
30       quently, a number of Linux-specific advice values have been added.
31
32   Conventional advice values
33       The  advice values listed below allow an application to tell the kernel
34       how it expects to use some mapped or shared memory areas, so  that  the
35       kernel can choose appropriate read-ahead and caching techniques.  These
36       advice values do not influence the semantics of the application (except
37       in  the case of MADV_DONTNEED), but may influence its performance.  All
38       of the advice values listed here have analogs  in  the  POSIX-specified
39       posix_madvise(3)  function, and the values have the same meanings, with
40       the exception of MADV_DONTNEED.
41
42       The advice is indicated in the advice argument, which  is  one  of  the
43       following:
44
45       MADV_NORMAL
46              No special treatment.  This is the default.
47
48       MADV_RANDOM
49              Expect  page references in random order.  (Hence, read ahead may
50              be less useful than normally.)
51
52       MADV_SEQUENTIAL
53              Expect page references in sequential order.   (Hence,  pages  in
54              the given range can be aggressively read ahead, and may be freed
55              soon after they are accessed.)
56
57       MADV_WILLNEED
58              Expect access in the near future.  (Hence, it might  be  a  good
59              idea to read some pages ahead.)
60
61       MADV_DONTNEED
62              Do  not  expect access in the near future.  (For the time being,
63              the application is finished with the given range, so the  kernel
64              can free resources associated with it.)
65
66              After  a  successful  MADV_DONTNEED  operation, the semantics of
67              memory access in the specified region  are  changed:  subsequent
68              accesses  of pages in the range will succeed, but will result in
69              either repopulating the memory contents from the up-to-date con‐
70              tents  of  the underlying mapped file (for shared file mappings,
71              shared anonymous mappings, and shmem-based  techniques  such  as
72              System  V  shared  memory segments) or zero-fill-on-demand pages
73              for anonymous private mappings.
74
75              Note that, when applied to shared mappings, MADV_DONTNEED  might
76              not  lead  to  immediate freeing of the pages in the range.  The
77              kernel is free to delay freeing the pages until  an  appropriate
78              moment.  The resident set size (RSS) of the calling process will
79              be immediately reduced however.
80
81              MADV_DONTNEED cannot be applied to locked pages, Huge TLB pages,
82              or  VM_PFNMAP  pages.   (Pages  marked  with the kernel-internal
83              VM_PFNMAP flag are special memory areas that are not managed  by
84              the  virtual memory subsystem.  Such pages are typically created
85              by device drivers that map the pages into user space.)
86
87   Linux-specific advice values
88       The following Linux-specific advice values have no counterparts in  the
89       POSIX-specified  posix_madvise(3), and may or may not have counterparts
90       in the madvise() interface available on  other  implementations.   Note
91       that some of these operations change the semantics of memory accesses.
92
93       MADV_REMOVE (since Linux 2.6.16)
94              Free up a given range of pages and its associated backing store.
95              This is equivalent to punching a hole in the corresponding  byte
96              range  of  the  backing  store  (see  fallocate(2)).  Subsequent
97              accesses in the specified address range will see bytes  contain‐
98              ing zero.
99
100              The  specified address range must be mapped shared and writable.
101              This flag cannot be applied to locked pages, Huge TLB pages,  or
102              VM_PFNMAP pages.
103
104              In  the  initial  implementation,  only  tmpfs(5)  was supported
105              MADV_REMOVE; but since Linux 3.5, any filesystem which  supports
106              the   fallocate(2)   FALLOC_FL_PUNCH_HOLE   mode  also  supports
107              MADV_REMOVE.  Hugetlbfs fails with the error  EINVAL  and  other
108              filesystems fail with the error EOPNOTSUPP.
109
110       MADV_DONTFORK (since Linux 2.6.16)
111              Do not make the pages in this range available to the child after
112              a fork(2).  This is useful to  prevent  copy-on-write  semantics
113              from  changing  the  physical  location  of a page if the parent
114              writes to it after a  fork(2).   (Such  page  relocations  cause
115              problems for hardware that DMAs into the page.)
116
117       MADV_DOFORK (since Linux 2.6.16)
118              Undo  the  effect of MADV_DONTFORK, restoring the default behav‐
119              ior, whereby a mapping is inherited across fork(2).
120
121       MADV_HWPOISON (since Linux 2.6.32)
122              Poison the pages in the range specified by addr and  length  and
123              handle subsequent references to those pages like a hardware mem‐
124              ory corruption.  This operation is available only for privileged
125              (CAP_SYS_ADMIN)  processes.   This  operation  may result in the
126              calling process receiving a SIGBUS and the page being unmapped.
127
128              This feature is intended for testing  of  memory  error-handling
129              code;  it  is  available  only if the kernel was configured with
130              CONFIG_MEMORY_FAILURE.
131
132       MADV_MERGEABLE (since Linux 2.6.32)
133              Enable Kernel Samepage Merging (KSM) for the pages in the  range
134              specified  by addr and length.  The kernel regularly scans those
135              areas of user memory that have been marked as mergeable, looking
136              for  pages with identical content.  These are replaced by a sin‐
137              gle write-protected page (which is  automatically  copied  if  a
138              process  later  wants  to  update the content of the page).  KSM
139              merges only private anonymous pages (see mmap(2)).
140
141              The KSM feature is intended for applications that generate  many
142              instances of the same data (e.g., virtualization systems such as
143              KVM).  It can consume a lot of processing power; use with  care.
144              See   the   Linux   kernel   source   file  Documentation/admin-
145              guide/mm/ksm.rst for more details.
146
147              The MADV_MERGEABLE and MADV_UNMERGEABLE operations are available
148              only if the kernel was configured with CONFIG_KSM.
149
150       MADV_UNMERGEABLE (since Linux 2.6.32)
151              Undo  the  effect  of an earlier MADV_MERGEABLE operation on the
152              specified address range; KSM  unmerges  whatever  pages  it  had
153              merged in the address range specified by addr and length.
154
155       MADV_SOFT_OFFLINE (since Linux 2.6.33)
156              Soft  offline  the  pages  in  the  range  specified by addr and
157              length.  The memory of each page in the specified range is  pre‐
158              served (i.e., when next accessed, the same content will be visi‐
159              ble, but in a new physical page frame), and the original page is
160              offlined  (i.e.,  no longer used, and taken out of normal memory
161              management).  The effect of the MADV_SOFT_OFFLINE  operation  is
162              invisible  to (i.e., does not change the semantics of) the call‐
163              ing process.
164
165              This feature is intended for testing  of  memory  error-handling
166              code;  it  is  available  only if the kernel was configured with
167              CONFIG_MEMORY_FAILURE.
168
169       MADV_HUGEPAGE (since Linux 2.6.38)
170              Enable Transparent Huge Pages (THP) for pages in the range spec‐
171              ified  by  addr  and  length.  Currently, Transparent Huge Pages
172              work only with private anonymous pages (see mmap(2)).  The  ker‐
173              nel will regularly scan the areas marked as huge page candidates
174              to replace them with huge pages.  The kernel will also  allocate
175              huge  pages directly when the region is naturally aligned to the
176              huge page size (see posix_memalign(2)).
177
178              This feature is primarily aimed at applications that  use  large
179              mappings  of  data  and access large regions of that memory at a
180              time (e.g., virtualization systems such as QEMU).  It  can  very
181              easily  waste  memory  (e.g.,  a  2 MB  mapping  that  only ever
182              accesses 1 byte will result in 2 MB of wired memory  instead  of
183              one  4 KB  page).   See  the Linux kernel source file Documenta‐
184              tion/admin-guide/mm/transhuge.rst for more details.
185
186              The MADV_HUGEPAGE and MADV_NOHUGEPAGE operations  are  available
187              only   if   the  kernel  was  configured  with  CONFIG_TRANSPAR‐
188              ENT_HUGEPAGE.
189
190       MADV_NOHUGEPAGE (since Linux 2.6.38)
191              Ensures that memory in the address range specified by  addr  and
192              length will not be collapsed into huge pages.
193
194       MADV_DONTDUMP (since Linux 3.4)
195              Exclude  from  a core dump those pages in the range specified by
196              addr and length.  This is useful in applications that have large
197              areas  of memory that are known not to be useful in a core dump.
198              The effect of MADV_DONTDUMP takes precedence over the  bit  mask
199              that  is  set  via  the  /proc/[pid]/coredump_filter  file  (see
200              core(5)).
201
202       MADV_DODUMP (since Linux 3.4)
203              Undo the effect of an earlier MADV_DONTDUMP.
204
205       MADV_FREE (since Linux 4.5)
206              The application no longer requires the pages in the range speci‐
207              fied by addr and len.  The kernel can thus free these pages, but
208              the freeing could be delayed until memory pressure occurs.   For
209              each  of  the pages that has been marked to be freed but has not
210              yet been freed, the free operation will be canceled if the call‐
211              er  writes  into  the page.  After a successful MADV_FREE opera‐
212              tion, any stale data (i.e., dirty, unwritten pages) will be lost
213              when  the kernel frees the pages.  However, subsequent writes to
214              pages in the range will succeed  and  then  kernel  cannot  free
215              those  dirtied  pages,  so  that  the caller can always see just
216              written data.  If there is no subsequent write, the  kernel  can
217              free  the  pages at any time.  Once pages in the range have been
218              freed, the caller will see zero-fill-on-demand pages upon subse‐
219              quent page references.
220
221              The MADV_FREE operation can be applied only to private anonymous
222              pages (see mmap(2)).  In Linux before version 4.12, when freeing
223              pages  on  a  swapless  system, the pages in the given range are
224              freed instantly, regardless of memory pressure.
225
226       MADV_WIPEONFORK (since Linux 4.14)
227              Present the child process with zero-filled memory in this  range
228              after  a fork(2).  This is useful in forking servers in order to
229              ensure that sensitive per-process data (for example, PRNG seeds,
230              cryptographic  secrets,  and  so on) is not handed to child pro‐
231              cesses.
232
233              The MADV_WIPEONFORK operation can be  applied  only  to  private
234              anonymous pages (see mmap(2)).
235
236              Within the child created by fork(2), the MADV_WIPEONFORK setting
237              remains in place on the specified address range.   This  setting
238              is cleared during execve(2).
239
240       MADV_KEEPONFORK (since Linux 4.14)
241              Undo the effect of an earlier MADV_WIPEONFORK.
242

RETURN VALUE

244       On  success, madvise() returns zero.  On error, it returns -1 and errno
245       is set appropriately.
246

ERRORS

248       EACCES advice is MADV_REMOVE, but the specified address range is not  a
249              shared writable mapping.
250
251       EAGAIN A kernel resource was temporarily unavailable.
252
253       EBADF  The map exists, but the area maps something that isn't a file.
254
255       EINVAL addr is not page-aligned or length is negative.
256
257       EINVAL advice is not a valid.
258
259       EINVAL advice is MADV_DONTNEED or MADV_REMOVE and the specified address
260              range includes locked, Huge TLB pages, or VM_PFNMAP pages.
261
262       EINVAL advice is MADV_MERGEABLE or MADV_UNMERGEABLE, but the kernel was
263              not configured with CONFIG_KSM.
264
265       EINVAL advice is MADV_FREE or MADV_WIPEONFORK but the specified address
266              range includes file, Huge TLB, MAP_SHARED, or VM_PFNMAP ranges.
267
268       EIO    (for  MADV_WILLNEED)  Paging  in  this  area  would  exceed  the
269              process's maximum resident set size.
270
271       ENOMEM (for MADV_WILLNEED) Not enough memory: paging in failed.
272
273       ENOMEM Addresses  in  the  specified range are not currently mapped, or
274              are outside the address space of the process.
275
276       EPERM  advice is MADV_HWPOISON,  but  the  caller  does  not  have  the
277              CAP_SYS_ADMIN capability.
278

VERSIONS

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

CONFORMING TO

284       madvise() is not specified by any standards.  Versions of  this  system
285       call, implementing a wide variety of advice values, exist on many other
286       implementations.  Other implementations typically  implement  at  least
287       the  flags  listed  above  under Conventional advice flags, albeit with
288       some variation in semantics.
289
290       POSIX.1-2001 describes posix_madvise(3) with constants  POSIX_MADV_NOR‐
291       MAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, POSIX_MADV_WILLNEED, and
292       POSIX_MADV_DONTNEED, and so on, with behavior close  to  the  similarly
293       named flags listed above.
294

NOTES

296   Linux notes
297       The  Linux  implementation  requires  that  the  address  addr be page-
298       aligned, and allows length to be zero.  If there are some parts of  the
299       specified  address range that are not mapped, the Linux version of mad‐
300       vise() ignores them and applies the  call  to  the  rest  (but  returns
301       ENOMEM from the system call, as it should).
302

SEE ALSO

304       getrlimit(2),  mincore(2),  mmap(2),  mprotect(2), msync(2), munmap(2),
305       prctl(2), posix_madvise(3), core(5)
306

COLOPHON

308       This page is part of release 5.02 of the Linux  man-pages  project.   A
309       description  of  the project, information about reporting bugs, and the
310       latest    version    of    this    page,    can     be     found     at
311       https://www.kernel.org/doc/man-pages/.
312
313
314
315Linux                             2019-03-06                        MADVISE(2)
Impressum