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 ac‐
97              cesses in the specified address range will see bytes  containing
98              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/ad‐
145              min-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 ac‐
182              cesses 1 byte will result in 2 MB of wired memory instead of one
183              4 KB  page).  See the Linux kernel source file Documentation/ad‐
184              min-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-style  behavior  may  not be enabled by default in
190              the 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
222              caller writes into the page.  After a successful MADV_FREE oper‐
223              ation,  any  stale  data  (i.e., dirty, unwritten pages) will be
224              lost when the  kernel  frees  the  pages.   However,  subsequent
225              writes to pages in the range will succeed and then kernel cannot
226              free 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
254       MADV_COLD (since Linux 5.4)
255              Deactivate a given range of pages.  This will make the  pages  a
256              more  probable reclaim target should there be a memory pressure.
257              This is a nondestructive operation.  The advice might be ignored
258              for some pages in the range when it is not applicable.
259
260       MADV_PAGEOUT (since Linux 5.4)
261              Reclaim  a given range of pages.  This is done to free up memory
262              occupied by these pages.  If a page is  anonymous,  it  will  be
263              swapped  out.   If  a  page is file-backed and dirty, it will be
264              written back to the backing storage.  The advice  might  be  ig‐
265              nored for some pages in the range when it is not applicable.
266

RETURN VALUE

268       On  success, madvise() returns zero.  On error, it returns -1 and errno
269       is set to indicate the error.
270

ERRORS

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

VERSIONS

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

CONFORMING TO

308       madvise() is not specified by any standards.  Versions of  this  system
309       call, implementing a wide variety of advice values, exist on many other
310       implementations.  Other implementations typically  implement  at  least
311       the  flags  listed  above  under Conventional advice flags, albeit with
312       some variation in semantics.
313
314       POSIX.1-2001 describes posix_madvise(3) with constants  POSIX_MADV_NOR‐
315       MAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, POSIX_MADV_WILLNEED, and
316       POSIX_MADV_DONTNEED, and so on, with behavior close  to  the  similarly
317       named flags listed above.
318

NOTES

320   Linux notes
321       The  Linux  implementation  requires  that  the  address  addr be page-
322       aligned, and allows length to be zero.  If there are some parts of  the
323       specified  address range that are not mapped, the Linux version of mad‐
324       vise() ignores them and applies the  call  to  the  rest  (but  returns
325       ENOMEM from the system call, as it should).
326

SEE ALSO

328       getrlimit(2),  mincore(2),  mmap(2),  mprotect(2), msync(2), munmap(2),
329       prctl(2), process_madvise(2), posix_madvise(3), core(5)
330

COLOPHON

332       This page is part of release 5.13 of the Linux  man-pages  project.   A
333       description  of  the project, information about reporting bugs, and the
334       latest    version    of    this    page,    can     be     found     at
335       https://www.kernel.org/doc/man-pages/.
336
337
338
339Linux                             2021-03-22                        MADVISE(2)
Impressum