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/vm/ksm.txt for
145              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/vm/transhuge.txt 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)).  On a swapless system, freeing pages  in  a
223              given range happens instantly, regardless of memory pressure.
224
225       MADV_WIPEONFORK (since Linux 4.14)
226              Present  the child process with zero-filled memory in this range
227              after a fork(2).  This is useful in forking servers in order  to
228              ensure that sensitive per-process data (for example, PRNG seeds,
229              cryptographic secrets, and so on) is not handed  to  child  pro‐
230              cesses.
231
232              The  MADV_WIPEONFORK  operation  can  be applied only to private
233              anonymous pages (see mmap(2)).
234
235              Within the child created by fork(2), the MADV_WIPEONFORK setting
236              remains  in  place on the specified address range.  This setting
237              is cleared during execve(2).
238
239       MADV_KEEPONFORK (since Linux 4.14)
240              Undo the effect of an earlier MADV_WIPEONFORK.
241

RETURN VALUE

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

ERRORS

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

VERSIONS

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

CONFORMING TO

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

NOTES

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

SEE ALSO

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

COLOPHON

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