1MADVISE(2) Linux Programmer's Manual MADVISE(2)
2
6 madvise - give advice about use of memory
7
9 #include <sys/mman.h>
10 int madvise(void *addr, size_t length, int advice);
12 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
14 madvise(): _BSD_SOURCE
16
18 The madvise() system call advises the kernel about how to handle paging
19 input/output in the address range beginning at address addr and with
20 size length bytes. It allows an application to tell the kernel how it
21 expects to use some mapped or shared memory areas, so that the kernel
22 can choose appropriate read-ahead and caching techniques. This call
23 does not influence the semantics of the application (except in the case
24 of MADV_DONTNEED), but may influence its performance. The kernel is
25 free to ignore the advice.
26 The advice is indicated in the advice argument which can be
28 MADV_NORMAL
30 No special treatment. This is the default.
31 MADV_RANDOM
33 Expect page references in random order. (Hence, read ahead may
34 be less useful than normally.)
35 MADV_SEQUENTIAL
37 Expect page references in sequential order. (Hence, pages in
38 the given range can be aggressively read ahead, and may be freed
39 soon after they are accessed.)
40 MADV_WILLNEED
42 Expect access in the near future. (Hence, it might be a good
43 idea to read some pages ahead.)
44 MADV_DONTNEED
46 Do not expect access in the near future. (For the time being,
47 the application is finished with the given range, so the kernel
48 can free resources associated with it.) Subsequent accesses of
49 pages in this range will succeed, but will result either in
50 reloading of the memory contents from the underlying mapped file
51 (see mmap(2)) or zero-fill-on-demand pages for mappings without
52 an underlying file.
53 MADV_REMOVE (Since Linux 2.6.16)
55 Free up a given range of pages and its associated backing store.
56 Currently, only shmfs/tmpfs supports this; other file systems
57 return with the error ENOSYS.
58 MADV_DONTFORK (Since Linux 2.6.16)
60 Do not make the pages in this range available to the child after
61 a fork(2). This is useful to prevent copy-on-write semantics
62 from changing the physical location of a page(s) if the parent
63 writes to it after a fork(2). (Such page relocations cause
64 problems for hardware that DMAs into the page(s).)
65 MADV_DOFORK (Since Linux 2.6.16)
67 Undo the effect of MADV_DONTFORK, restoring the default behav‐
68 ior, whereby a mapping is inherited across fork(2).
69 MADV_HWPOISON (Since Linux 2.6.32)
71 Poison a page and handle it like a hardware memory corruption.
72 This operation is only available for privileged (CAP_SYS_ADMIN)
73 processes. This operation may result in the calling process
74 receiving a SIGBUS and the page being unmapped. This feature is
75 intended for testing of memory error-handling code; it is only
76 available if the kernel was configured with CONFIG_MEMORY_FAIL‐
77 URE.
78 MADV_SOFT_OFFLINE (Since Linux 2.6.33)
80 Soft offline the pages in the range specified by addr and
81 length. The memory of each page in the specified range is
82 copied to a new page, and the original page is offlined (i.e.,
83 no longer used, and taken out of normal memory management). The
84 effect of the MADV_SOFT_OFFLINE operation is normally invisible
85 to (i.e., does not change the semantics of) the calling process.
86 This feature is intended for testing of memory error-handling
87 code; it is only available if the kernel was configured with
88 CONFIG_MEMORY_FAILURE.
89 MADV_MERGEABLE (since Linux 2.6.32)
91 Enable Kernel Samepage Merging (KSM) for the pages in the range
92 specified by addr and length. The kernel regularly scans those
93 areas of user memory that have been marked as mergeable, looking
94 for pages with identical content. These are replaced by a sin‐
95 gle write-protected page (which is automatically copied if a
96 process later wants to update the content of the page). KSM
97 only merges private anonymous pages (see mmap(2)). The KSM fea‐
98 ture is intended for applications that generate many instances
99 of the same data (e.g., virtualization systems such as KVM). It
100 can consume a lot of processing power; use with care. See the
101 kernel source file Documentation/vm/ksm.txt for more details.
102 The MADV_MERGEABLE and MADV_UNMERGEABLE operations are only
103 available if the kernel was configured with CONFIG_KSM.
104 MADV_UNMERGEABLE (since Linux 2.6.32)
106 Undo the effect of an earlier MADV_MERGEABLE operation on the
107 specified address range; KSM unmerges whatever pages it had
108 merged in the address range specified by addr and length.
109
111 On success madvise() returns zero. On error, it returns -1 and errno
112 is set appropriately.
113
115 EAGAIN A kernel resource was temporarily unavailable.
116 EBADF The map exists, but the area maps something that isn't a file.
118 EINVAL This error can occur for the following reasons:
120 * The value len is negative.
122 * addr is not page-aligned.
124 * advice is not a valid value
126 * The application is attempting to release locked or shared
128 pages (with MADV_DONTNEED).
129 * MADV_MERGEABLE or MADV_UNMERGEABLE was specified in advice,
131 but the kernel was not configured with CONFIG_KSM.
132 EIO (for MADV_WILLNEED) Paging in this area would exceed the
134 process's maximum resident set size.
135 ENOMEM (for MADV_WILLNEED) Not enough memory: paging in failed.
137 ENOMEM Addresses in the specified range are not currently mapped, or
139 are outside the address space of the process.
140
142 POSIX.1b. POSIX.1-2001 describes posix_madvise(3) with constants
143 POSIX_MADV_NORMAL, etc., with a behavior close to that described here.
144 There is a similar posix_fadvise(2) for file access.
145 MADV_REMOVE, MADV_DONTFORK, MADV_DOFORK, MADV_HWPOISON, MADV_MERGEABLE,
147 and MADV_UNMERGEABLE are Linux-specific.
148
150 Linux Notes
151 The current Linux implementation (2.4.0) views this system call more as
152 a command than as advice and hence may return an error when it cannot
153 do what it usually would do in response to this advice. (See the
154 ERRORS description above.) This is nonstandard behavior.
155 The Linux implementation requires that the address addr be page-
157 aligned, and allows length to be zero. If there are some parts of the
158 specified address range that are not mapped, the Linux version of mad‐
159 vise() ignores them and applies the call to the rest (but returns
160 ENOMEM from the system call, as it should).
161
163 getrlimit(2), mincore(2), mmap(2), mprotect(2), msync(2), munmap(2)
164
166 This page is part of release 3.25 of the Linux man-pages project. A
167 description of the project, and information about reporting bugs, can
168 be found at http://www.kernel.org/doc/man-pages/.
169Linux 2010-06-20 MADVISE(2)