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              Most common kernels configurations  provide  MADV_HUGEPAGE-style
187              behavior by default, and thus MADV_HUGEPAGE is normally not nec‐
188              essary.  It is  mostly  intended  for  embedded  systems,  where
189              MADV_HUGEPAGE-stye behavior may not be enabled by default in the
190              kernel.  On such systems, this flag can  be  used  in  order  to
191              selectively  enable  THP.   Whenever  MADV_HUGEPAGE  is used, it
192              should always be in regions of memory  with  an  access  pattern
193              that  the  developer knows in advance won't risk to increase the
194              memory footprint of the application when  transparent  hugepages
195              are enabled.
196
197              The  MADV_HUGEPAGE  and MADV_NOHUGEPAGE operations are available
198              only  if  the  kernel  was  configured   with   CONFIG_TRANSPAR‐
199              ENT_HUGEPAGE.
200
201       MADV_NOHUGEPAGE (since Linux 2.6.38)
202              Ensures  that  memory in the address range specified by addr and
203              length will not be backed by transparent hugepages.
204
205       MADV_DONTDUMP (since Linux 3.4)
206              Exclude from a core dump those pages in the range  specified  by
207              addr and length.  This is useful in applications that have large
208              areas of memory that are known not to be useful in a core  dump.
209              The  effect  of MADV_DONTDUMP takes precedence over the bit mask
210              that  is  set  via  the  /proc/[pid]/coredump_filter  file  (see
211              core(5)).
212
213       MADV_DODUMP (since Linux 3.4)
214              Undo the effect of an earlier MADV_DONTDUMP.
215
216       MADV_FREE (since Linux 4.5)
217              The application no longer requires the pages in the range speci‐
218              fied by addr and len.  The kernel can thus free these pages, but
219              the  freeing could be delayed until memory pressure occurs.  For
220              each of the pages that has been marked to be freed but  has  not
221              yet been freed, the free operation will be canceled if the call‐
222              er writes into the page.  After a  successful  MADV_FREE  opera‐
223              tion, any stale data (i.e., dirty, unwritten pages) will be lost
224              when the kernel frees the pages.  However, subsequent writes  to
225              pages  in  the  range  will  succeed and then kernel cannot free
226              those dirtied pages, so that the  caller  can  always  see  just
227              written  data.   If there is no subsequent write, the kernel can
228              free the pages at any time.  Once pages in the range  have  been
229              freed, the caller will see zero-fill-on-demand pages upon subse‐
230              quent page references.
231
232              The MADV_FREE operation can be applied only to private anonymous
233              pages (see mmap(2)).  In Linux before version 4.12, when freeing
234              pages on a swapless system, the pages in  the  given  range  are
235              freed instantly, regardless of memory pressure.
236
237       MADV_WIPEONFORK (since Linux 4.14)
238              Present  the child process with zero-filled memory in this range
239              after a fork(2).  This is useful in forking servers in order  to
240              ensure that sensitive per-process data (for example, PRNG seeds,
241              cryptographic secrets, and so on) is not handed  to  child  pro‐
242              cesses.
243
244              The  MADV_WIPEONFORK  operation  can  be applied only to private
245              anonymous pages (see mmap(2)).
246
247              Within the child created by fork(2), the MADV_WIPEONFORK setting
248              remains  in  place on the specified address range.  This setting
249              is cleared during execve(2).
250
251       MADV_KEEPONFORK (since Linux 4.14)
252              Undo the effect of an earlier MADV_WIPEONFORK.
253

RETURN VALUE

255       On success, madvise() returns zero.  On error, it returns -1 and  errno
256       is set appropriately.
257

ERRORS

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

VERSIONS

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

CONFORMING TO

295       madvise()  is  not specified by any standards.  Versions of this system
296       call, implementing a wide variety of advice values, exist on many other
297       implementations.   Other  implementations  typically implement at least
298       the flags listed above under Conventional  advice  flags,  albeit  with
299       some variation in semantics.
300
301       POSIX.1-2001  describes posix_madvise(3) with constants POSIX_MADV_NOR‐
302       MAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, POSIX_MADV_WILLNEED, and
303       POSIX_MADV_DONTNEED,  and  so  on, with behavior close to the similarly
304       named flags listed above.
305

NOTES

307   Linux notes
308       The Linux implementation  requires  that  the  address  addr  be  page-
309       aligned,  and allows length to be zero.  If there are some parts of the
310       specified address range that are not mapped, the Linux version of  mad‐
311       vise()  ignores  them  and  applies  the  call to the rest (but returns
312       ENOMEM from the system call, as it should).
313

SEE ALSO

315       getrlimit(2), mincore(2), mmap(2),  mprotect(2),  msync(2),  munmap(2),
316       prctl(2), posix_madvise(3), core(5)
317

COLOPHON

319       This  page  is  part of release 5.07 of the Linux man-pages project.  A
320       description of the project, information about reporting bugs,  and  the
321       latest     version     of     this    page,    can    be    found    at
322       https://www.kernel.org/doc/man-pages/.
323
324
325
326Linux                             2020-04-11                        MADVISE(2)
Impressum