original/man2/madvise.2

   1 .\" Copyright (C) 2001 David Gómez <davidge@jazzfree.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Based on comments from mm/filemap.c. Last modified on 10-06-2001
  26 .\" Modified, 25 Feb 2002, Michael Kerrisk, <mtk.manpages@gmail.com>
  27 .\"     Added notes on MADV_DONTNEED
  28 .\" 2010-06-19, mtk, Added documentation of MADV_MERGEABLE and
  29 .\"     MADV_UNMERGEABLE
  30 .\" 2010-06-15, Andi Kleen, Add documentation of MADV_HWPOISON.
  31 .\" 2010-06-19, Andi Kleen, Add documentation of MADV_SOFT_OFFLINE.
  32 .\" 2011-09-18, Doug Goldstein <cardoe@cardoe.com>
  33 .\"     Document MADV_HUGEPAGE and MADV_NOHUGEPAGE
  34 .\"
  35 .TH MADVISE 2 2014-12-31 "Linux" "Linux Programmer's Manual"
  36 .SH NAME
  37 madvise \- give advice about use of memory
  38 .SH SYNOPSIS
  39 .B #include <sys/mman.h>
  40 .sp
  41 .BI "int madvise(void *" addr ", size_t " length ", int " advice );
  42 .sp
  43 .in -4n
  44 Feature Test Macro Requirements for glibc (see
  45 .BR feature_test_macros (7)):
  46 .in
  47 .sp
  48 .BR madvise ():
  49 _BSD_SOURCE
  50 .SH DESCRIPTION
  51 The
  52 .BR madvise ()
  53 system call advises the kernel about how to handle paging input/output in
  54 the address range beginning at address
  55 .I addr
  56 and with size
  57 .I length
  58 bytes.
  59 It allows an application to tell the kernel how it expects to use
  60 some mapped or shared memory areas, so that the kernel can choose
  61 appropriate read-ahead and caching techniques.
  62 This call does not influence the semantics of the application
  63 (except in the case of
  64 .BR MADV_DONTNEED ),
  65 but
  66 may influence its performance.
  67 The kernel is free to ignore the advice.
  68 .LP
  69 The advice is indicated in the
  70 .I advice
  71 argument which can be
  72 .TP
  73 .B MADV_NORMAL
  74 No special treatment.
  75 This is the default.
  76 .TP
  77 .B MADV_RANDOM
  78 Expect page references in random order.
  79 (Hence, read ahead may be less useful than normally.)
  80 .TP
  81 .B MADV_SEQUENTIAL
  82 Expect page references in sequential order.
  83 (Hence, pages in the given range can be aggressively read ahead,
  84 and may be freed soon after they are accessed.)
  85 .TP
  86 .B MADV_WILLNEED
  87 Expect access in the near future.
  88 (Hence, it might be a good idea to read some pages ahead.)
  89 .TP
  90 .B MADV_DONTNEED
  91 Do not expect access in the near future.
  92 (For the time being, the application is finished with the given range,
  93 so the kernel can free resources associated with it.)
  94 Subsequent accesses of pages in this range will succeed, but will result
  95 either in reloading of the memory contents from the underlying mapped file
  96 (see
  97 .BR mmap (2))
  98 or zero-fill-on-demand pages for mappings
  99 without an underlying file.
 100 .TP
 101 .BR MADV_REMOVE " (since Linux 2.6.16)"
 102 Free up a given range of pages
 103 and its associated backing store.
 104 Currently,
 105 .\" 2.6.18-rc5
 106 only shmfs/tmpfs supports this; other filesystems return with the
 107 error
 108 .BR ENOSYS .
 109 .\" Databases want to use this feature to drop a section of their
 110 .\" bufferpool (shared memory segments) - without writing back to
 111 .\" disk/swap space.  This feature is also useful for supporting
 112 .\" hot-plug memory on UML.
 113 .TP
 114 .BR MADV_DONTFORK " (since Linux 2.6.16)"
 115 .\" See http://lwn.net/Articles/171941/
 116 Do not make the pages in this range available to the child after a
 117 .BR fork (2).
 118 This is useful to prevent copy-on-write semantics from changing
 119 the physical location of a page(s) if the parent writes to it after a
 120 .BR fork (2).
 121 (Such page relocations cause problems for hardware that
 122 DMAs into the page(s).)
 123 .\" [PATCH] madvise MADV_DONTFORK/MADV_DOFORK
 124 .\" Currently, copy-on-write may change the physical address of
 125 .\" a page even if the user requested that the page is pinned in
 126 .\" memory (either by mlock or by get_user_pages).  This happens
 127 .\" if the process forks meanwhile, and the parent writes to that
 128 .\" page.  As a result, the page is orphaned: in case of
 129 .\" get_user_pages, the application will never see any data hardware
 130 .\" DMA's into this page after the COW.  In case of mlock'd memory,
 131 .\" the parent is not getting the realtime/security benefits of mlock.
 132 .\"
 133 .\" In particular, this affects the Infiniband modules which do DMA from
 134 .\" and into user pages all the time.
 135 .\"
 136 .\" This patch adds madvise options to control whether memory range is
 137 .\" inherited across fork. Useful e.g. for when hardware is doing DMA
 138 .\" from/into these pages.  Could also be useful to an application
 139 .\" wanting to speed up its forks by cutting large areas out of
 140 .\" consideration.
 141 .\"
 142 .\" SEE ALSO: http://lwn.net/Articles/171941/
 143 .\" "Tweaks to madvise() and posix_fadvise()", 14 Feb 2006
 144 .TP
 145 .BR MADV_DOFORK " (since Linux 2.6.16)"
 146 Undo the effect of
 147 .BR MADV_DONTFORK ,
 148 restoring the default behavior, whereby a mapping is inherited across
 149 .BR fork (2).
 150 .TP
 151 .BR MADV_HWPOISON " (since Linux 2.6.32)
 152 Poison a page and handle it like a hardware memory corruption.
 153 This operation is available only for privileged
 154 .RB ( CAP_SYS_ADMIN )
 155 processes.
 156 This operation may result in the calling process receiving a
 157 .B SIGBUS
 158 and the page being unmapped.
 159 This feature is intended for testing of memory error-handling code;
 160 it is available only if the kernel was configured with
 161 .BR CONFIG_MEMORY_FAILURE .
 162 .TP
 163 .BR MADV_SOFT_OFFLINE " (since Linux 2.6.33)
 164 Soft offline the pages in the range specified by
 165 .I addr
 166 and
 167 .IR length .
 168 The memory of each page in the specified range is preserved
 169 (i.e., when next accessed, the same content will be visible,
 170 but in a new physical page frame),
 171 and the original page is offlined
 172 (i.e., no longer used, and taken out of normal memory management).
 173 The effect of the
 174 .B MADV_SOFT_OFFLINE
 175 operation is invisible to (i.e., does not change the semantics of)
 176 the calling process.
 177 This feature is intended for testing of memory error-handling code;
 178 it is available only if the kernel was configured with
 179 .BR CONFIG_MEMORY_FAILURE .
 180 .TP
 181 .BR MADV_MERGEABLE " (since Linux 2.6.32)"
 182 Enable Kernel Samepage Merging (KSM) for the pages in the range specified by
 183 .I addr
 184 and
 185 .IR length .
 186 The kernel regularly scans those areas of user memory that have
 187 been marked as mergeable,
 188 looking for pages with identical content.
 189 These are replaced by a single write-protected page (which is automatically
 190 copied if a process later wants to update the content of the page).
 191 KSM merges only private anonymous pages (see
 192 .BR mmap (2)).
 193 The KSM feature is intended for applications that generate many
 194 instances of the same data (e.g., virtualization systems such as KVM).
 195 It can consume a lot of processing power; use with care.
 196 See the Linux kernel source file
 197 .I Documentation/vm/ksm.txt
 198 for more details.
 199 The
 200 .BR MADV_MERGEABLE
 201 and
 202 .BR MADV_UNMERGEABLE
 203 operations are available only if the kernel was configured with
 204 .BR CONFIG_KSM .
 205 .TP
 206 .BR MADV_UNMERGEABLE " (since Linux 2.6.32)"
 207 Undo the effect of an earlier
 208 .BR MADV_MERGEABLE
 209 operation on the specified address range;
 210 KSM unmerges whatever pages it had merged in the address range specified by
 211 .IR addr
 212 and
 213 .IR length .
 214 .TP
 215 .BR MADV_HUGEPAGE " (since Linux 2.6.38)"
 216 .\" http://lwn.net/Articles/358904/
 217 .\" https://lwn.net/Articles/423584/
 218 Enables Transparent Huge Pages (THP) for pages in the range specified by
 219 .I addr
 220 and
 221 .IR length .
 222 Currently, Transparent Huge Pages work only with private anonymous pages (see
 223 .BR mmap (2)).
 224 The kernel will regularly scan the areas marked as huge page candidates
 225 to replace them with huge pages.
 226 The kernel will also allocate huge pages directly when the region is
 227 naturally aligned to the huge page size (see
 228 .BR posix_memalign (2)).
 229 This feature is primarily aimed at applications that use large mappings of
 230 data and access large regions of that memory at a time (e.g., virtualization
 231 systems such as QEMU).
 232 It can very easily waste memory (e.g., a 2MB mapping that only ever accesses
 233 1 byte will result in 2MB of wired memory instead of one 4KB page).
 234 See the Linux kernel source file
 235 .I Documentation/vm/transhuge.txt
 236 for more details.
 237 The
 238 .BR MADV_HUGEPAGE
 239 and
 240 .BR MADV_NOHUGEPAGE
 241 operations are available only if the kernel was configured with
 242 .BR CONFIG_TRANSPARENT_HUGEPAGE .
 243 .TP
 244 .BR MADV_NOHUGEPAGE " (since Linux 2.6.38)"
 245 Ensures that memory in the address range specified by
 246 .IR addr
 247 and
 248 .IR length
 249 will not be collapsed into huge pages.
 250 .TP
 251 .BR MADV_DONTDUMP " (since Linux 3.4)"
 252 Exclude from a core dump those pages in the range specified by
 253 .I addr
 254 and
 255 .IR length .
 256 This is useful in applications that have large areas of memory
 257 that are known not to be useful in a core dump.
 258 The effect of
 259 .BR MADV_DONTDUMP
 260 takes precedence over the bit mask that is set via the
 261 .I /proc/PID/coredump_filter
 262 file (see
 263 .BR core (5)).
 264 .TP
 265 .BR MADV_DODUMP " (since Linux 3.4)"
 266 Undo the effect of an earlier
 267 .BR MADV_DONTDUMP .
 268 .SH RETURN VALUE
 269 On success
 270 .BR madvise ()
 271 returns zero.
 272 On error, it returns \-1 and
 273 .I errno
 274 is set appropriately.
 275 .SH ERRORS
 276 .TP
 277 .B EAGAIN
 278 A kernel resource was temporarily unavailable.
 279 .TP
 280 .B EBADF
 281 The map exists, but the area maps something that isn't a file.
 282 .TP
 283 .B EINVAL
 284 This error can occur for the following reasons:
 285 .RS
 286 .IP * 3
 287 The value
 288 .I len
 289 is negative.
 290 .\" .I len
 291 .\" is zero,
 292 .IP *
 293 .I addr
 294 is not page-aligned.
 295 .IP *
 296 .I advice
 297 is not a valid value
 298 .IP *
 299 The application is attempting to release locked or shared pages (with
 300 .BR MADV_DONTNEED ).
 301 .IP *
 302 .BR MADV_MERGEABLE
 303 or
 304 .BR MADV_UNMERGEABLE
 305 was specified in
 306 .IR advice ,
 307 but the kernel was not configured with
 308 .BR CONFIG_KSM .
 309 .RE
 310 .TP
 311 .B EIO
 312 (for
 313 .BR MADV_WILLNEED )
 314 Paging in this area would exceed the process's
 315 maximum resident set size.
 316 .TP
 317 .B ENOMEM
 318 (for
 319 .BR MADV_WILLNEED )
 320 Not enough memory: paging in failed.
 321 .TP
 322 .B ENOMEM
 323 Addresses in the specified range are not currently
 324 mapped, or are outside the address space of the process.
 325 .SH VERSIONS
 326 Since Linux 3.18,
 327 .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb
 328 support for this system call is optional,
 329 depending on the setting of the
 330 .B CONFIG_ADVISE_SYSCALLS
 331 configuration option.
 332 .SH CONFORMING TO
 333 POSIX.1b.
 334 POSIX.1-2001 describes
 335 .BR posix_madvise (3)
 336 .\" FIXME . Write a posix_madvise(3) page.
 337 with constants
 338 .BR POSIX_MADV_NORMAL ,
 339 .BR POSIX_MADV_RANDOM ,
 340 and so on,
 341 with a behavior close to that described here.
 342 There is a similar
 343 .BR posix_fadvise (2)
 344 for file access.
 345
 346 .BR MADV_REMOVE ,
 347 .BR MADV_DONTFORK ,
 348 .BR MADV_DOFORK ,
 349 .BR MADV_HWPOISON ,
 350 .BR MADV_MERGEABLE ,
 351 and
 352 .BR MADV_UNMERGEABLE
 353 are Linux-specific.
 354 .SH NOTES
 355 .SS Linux notes
 356 .LP
 357 The current Linux implementation (2.4.0) views this system call
 358 more as a command than as advice and hence may return an error
 359 when it cannot do what it usually would do in response to this
 360 advice.
 361 (See the ERRORS description above.)
 362 This is nonstandard behavior.
 363 .LP
 364 The Linux implementation requires that the address
 365 .I addr
 366 be page-aligned, and allows
 367 .I length
 368 to be zero.
 369 If there are some parts of the specified address range
 370 that are not mapped, the Linux version of
 371 .BR madvise ()
 372 ignores them and applies the call to the rest (but returns
 373 .B ENOMEM
 374 from the system call, as it should).
 375 .\" .SH HISTORY
 376 .\" The
 377 .\" .BR madvise ()
 378 .\" function first appeared in 4.4BSD.
 379 .SH SEE ALSO
 380 .BR getrlimit (2),
 381 .BR mincore (2),
 382 .BR mmap (2),
 383 .BR mprotect (2),
 384 .BR msync (2),
 385 .BR munmap (2),
 386 .BR prctl (2),
 387 .BR core (5)
 388 .SH COLOPHON
 389 This page is part of release 3.79 of the Linux
 390 .I man-pages
 391 project.
 392 A description of the project,
 393 information about reporting bugs,
 394 and the latest version of this page,
 395 can be found at
 396 \%http://www.kernel.org/doc/man\-pages/.