man2/madvise.2

   1 .\" Copyright (C) 2001 David Gómez <davidge@jazzfree.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Based on comments from mm/filemap.c. Last modified on 10-06-2001
   6 .\" Modified, 25 Feb 2002, Michael Kerrisk, <mtk.manpages@gmail.com>
   7 .\"     Added notes on MADV_DONTNEED
   8 .\" 2010-06-19, mtk, Added documentation of MADV_MERGEABLE and
   9 .\"     MADV_UNMERGEABLE
  10 .\" 2010-06-15, Andi Kleen, Add documentation of MADV_HWPOISON.
  11 .\" 2010-06-19, Andi Kleen, Add documentation of MADV_SOFT_OFFLINE.
  12 .\" 2011-09-18, Doug Goldstein <cardoe@cardoe.com>
  13 .\"     Document MADV_HUGEPAGE and MADV_NOHUGEPAGE
  14 .\"
  15 .TH MADVISE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  16 .SH NAME
  17 madvise \- give advice about use of memory
  18 .SH LIBRARY
  19 Standard C library
  20 .RI ( libc ", " \-lc )
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <sys/mman.h>
  24 .PP
  25 .BI "int madvise(void *" addr ", size_t " length ", int " advice );
  26 .fi
  27 .PP
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 .BR madvise ():
  34 .nf
  35     Since glibc 2.19:
  36         _DEFAULT_SOURCE
  37     Up to and including glibc 2.19:
  38         _BSD_SOURCE
  39 .fi
  40 .SH DESCRIPTION
  41 The
  42 .BR madvise ()
  43 system call is used to give advice or directions to the kernel
  44 about the address range beginning at address
  45 .I addr
  46 and with size
  47 .I length
  48 bytes.
  49 In most cases,
  50 the goal of such advice is to improve system or application performance.
  51 .PP
  52 Initially, the system call supported a set of "conventional"
  53 .I advice
  54 values, which are also available on several other implementations.
  55 (Note, though, that
  56 .BR madvise ()
  57 is not specified in POSIX.)
  58 Subsequently, a number of Linux-specific
  59 .IR advice
  60 values have been added.
  61 .\"
  62 .\" ======================================================================
  63 .\"
  64 .SS Conventional advice values
  65 The
  66 .I advice
  67 values listed below
  68 allow an application to tell the kernel how it expects to use
  69 some mapped or shared memory areas, so that the kernel can choose
  70 appropriate read-ahead and caching techniques.
  71 These
  72 .I advice
  73 values do not influence the semantics of the application
  74 (except in the case of
  75 .BR MADV_DONTNEED ),
  76 but may influence its performance.
  77 All of the
  78 .I advice
  79 values listed here have analogs in the POSIX-specified
  80 .BR posix_madvise (3)
  81 function, and the values have the same meanings, with the exception of
  82 .BR MADV_DONTNEED .
  83 .PP
  84 The advice is indicated in the
  85 .I advice
  86 argument, which is one of the following:
  87 .TP
  88 .B MADV_NORMAL
  89 No special treatment.
  90 This is the default.
  91 .TP
  92 .B MADV_RANDOM
  93 Expect page references in random order.
  94 (Hence, read ahead may be less useful than normally.)
  95 .TP
  96 .B MADV_SEQUENTIAL
  97 Expect page references in sequential order.
  98 (Hence, pages in the given range can be aggressively read ahead,
  99 and may be freed soon after they are accessed.)
 100 .TP
 101 .B MADV_WILLNEED
 102 Expect access in the near future.
 103 (Hence, it might be a good idea to read some pages ahead.)
 104 .TP
 105 .B MADV_DONTNEED
 106 Do not expect access in the near future.
 107 (For the time being, the application is finished with the given range,
 108 so the kernel can free resources associated with it.)
 109 .IP
 110 After a successful
 111 .B MADV_DONTNEED
 112 operation,
 113 the semantics of memory access in the specified region are changed:
 114 subsequent accesses of pages in the range will succeed, but will result
 115 in either repopulating the memory contents from the
 116 up-to-date contents of the underlying mapped file
 117 (for shared file mappings, shared anonymous mappings,
 118 and shmem-based techniques such as System V shared memory segments)
 119 or zero-fill-on-demand pages for anonymous private mappings.
 120 .IP
 121 Note that, when applied to shared mappings,
 122 .BR MADV_DONTNEED
 123 might not lead to immediate freeing of the pages in the range.
 124 The kernel is free to delay freeing the pages until an appropriate moment.
 125 The resident set size (RSS) of the calling process will be immediately
 126 reduced however.
 127 .IP
 128 .B MADV_DONTNEED
 129 cannot be applied to locked pages, Huge TLB pages, or
 130 .BR VM_PFNMAP
 131 pages.
 132 (Pages marked with the kernel-internal
 133 .B VM_PFNMAP
 134 .\" http://lwn.net/Articles/162860/
 135 flag are special memory areas that are not managed
 136 by the virtual memory subsystem.
 137 Such pages are typically created by device drivers that
 138 map the pages into user space.)
 139 .\"
 140 .\" ======================================================================
 141 .\"
 142 .SS Linux-specific advice values
 143 The following Linux-specific
 144 .I advice
 145 values have no counterparts in the POSIX-specified
 146 .BR posix_madvise (3),
 147 and may or may not have counterparts in the
 148 .BR madvise ()
 149 interface available on other implementations.
 150 Note that some of these operations change the semantics of memory accesses.
 151 .TP
 152 .BR MADV_REMOVE " (since Linux 2.6.16)"
 153 .\" commit f6b3ec238d12c8cc6cc71490c6e3127988460349
 154 Free up a given range of pages
 155 and its associated backing store.
 156 This is equivalent to punching a hole in the corresponding byte
 157 range of the backing store (see
 158 .BR fallocate (2)).
 159 Subsequent accesses in the specified address range will see
 160 bytes containing zero.
 161 .\" Databases want to use this feature to drop a section of their
 162 .\" bufferpool (shared memory segments) - without writing back to
 163 .\" disk/swap space.  This feature is also useful for supporting
 164 .\" hot-plug memory on UML.
 165 .IP
 166 The specified address range must be mapped shared and writable.
 167 This flag cannot be applied to locked pages, Huge TLB pages, or
 168 .BR VM_PFNMAP
 169 pages.
 170 .IP
 171 In the initial implementation, only
 172 .BR tmpfs (5)
 173 was supported
 174 .BR MADV_REMOVE ;
 175 but since Linux 3.5,
 176 .\" commit 3f31d07571eeea18a7d34db9af21d2285b807a17
 177 any filesystem which supports the
 178 .BR fallocate (2)
 179 .BR FALLOC_FL_PUNCH_HOLE
 180 mode also supports
 181 .BR MADV_REMOVE .
 182 Hugetlbfs fails with the error
 183 .BR EINVAL
 184 and other filesystems fail with the error
 185 .BR EOPNOTSUPP .
 186 .TP
 187 .BR MADV_DONTFORK " (since Linux 2.6.16)"
 188 .\" commit f822566165dd46ff5de9bf895cfa6c51f53bb0c4
 189 .\" See http://lwn.net/Articles/171941/
 190 Do not make the pages in this range available to the child after a
 191 .BR fork (2).
 192 This is useful to prevent copy-on-write semantics from changing
 193 the physical location of a page if the parent writes to it after a
 194 .BR fork (2).
 195 (Such page relocations cause problems for hardware that
 196 DMAs into the page.)
 197 .\" [PATCH] madvise MADV_DONTFORK/MADV_DOFORK
 198 .\" Currently, copy-on-write may change the physical address of
 199 .\" a page even if the user requested that the page is pinned in
 200 .\" memory (either by mlock or by get_user_pages).  This happens
 201 .\" if the process forks meanwhile, and the parent writes to that
 202 .\" page.  As a result, the page is orphaned: in case of
 203 .\" get_user_pages, the application will never see any data hardware
 204 .\" DMA's into this page after the COW.  In case of mlock'd memory,
 205 .\" the parent is not getting the realtime/security benefits of mlock.
 206 .\"
 207 .\" In particular, this affects the Infiniband modules which do DMA from
 208 .\" and into user pages all the time.
 209 .\"
 210 .\" This patch adds madvise options to control whether memory range is
 211 .\" inherited across fork. Useful e.g. for when hardware is doing DMA
 212 .\" from/into these pages.  Could also be useful to an application
 213 .\" wanting to speed up its forks by cutting large areas out of
 214 .\" consideration.
 215 .\"
 216 .\" SEE ALSO: http://lwn.net/Articles/171941/
 217 .\" "Tweaks to madvise() and posix_fadvise()", 14 Feb 2006
 218 .TP
 219 .BR MADV_DOFORK " (since Linux 2.6.16)"
 220 Undo the effect of
 221 .BR MADV_DONTFORK ,
 222 restoring the default behavior, whereby a mapping is inherited across
 223 .BR fork (2).
 224 .TP
 225 .BR MADV_HWPOISON " (since Linux 2.6.32)"
 226 .\" commit 9893e49d64a4874ea67849ee2cfbf3f3d6817573
 227 Poison the pages in the range specified by
 228 .I addr
 229 and
 230 .IR length
 231 and handle subsequent references to those pages
 232 like a hardware memory corruption.
 233 This operation is available only for privileged
 234 .RB ( CAP_SYS_ADMIN )
 235 processes.
 236 This operation may result in the calling process receiving a
 237 .B SIGBUS
 238 and the page being unmapped.
 239 .IP
 240 This feature is intended for testing of memory error-handling code;
 241 it is available only if the kernel was configured with
 242 .BR CONFIG_MEMORY_FAILURE .
 243 .TP
 244 .BR MADV_MERGEABLE " (since Linux 2.6.32)"
 245 .\" commit f8af4da3b4c14e7267c4ffb952079af3912c51c5
 246 Enable Kernel Samepage Merging (KSM) for the pages in the range specified by
 247 .I addr
 248 and
 249 .IR length .
 250 The kernel regularly scans those areas of user memory that have
 251 been marked as mergeable,
 252 looking for pages with identical content.
 253 These are replaced by a single write-protected page (which is automatically
 254 copied if a process later wants to update the content of the page).
 255 KSM merges only private anonymous pages (see
 256 .BR mmap (2)).
 257 .IP
 258 The KSM feature is intended for applications that generate many
 259 instances of the same data (e.g., virtualization systems such as KVM).
 260 It can consume a lot of processing power; use with care.
 261 See the Linux kernel source file
 262 .I Documentation/admin\-guide/mm/ksm.rst
 263 for more details.
 264 .IP
 265 The
 266 .BR MADV_MERGEABLE
 267 and
 268 .BR MADV_UNMERGEABLE
 269 operations are available only if the kernel was configured with
 270 .BR CONFIG_KSM .
 271 .TP
 272 .BR MADV_UNMERGEABLE " (since Linux 2.6.32)"
 273 Undo the effect of an earlier
 274 .BR MADV_MERGEABLE
 275 operation on the specified address range;
 276 KSM unmerges whatever pages it had merged in the address range specified by
 277 .IR addr
 278 and
 279 .IR length .
 280 .TP
 281 .BR MADV_SOFT_OFFLINE " (since Linux 2.6.33)"
 282 .\" commit afcf938ee0aac4ef95b1a23bac704c6fbeb26de6
 283 Soft offline the pages in the range specified by
 284 .I addr
 285 and
 286 .IR length .
 287 The memory of each page in the specified range is preserved
 288 (i.e., when next accessed, the same content will be visible,
 289 but in a new physical page frame),
 290 and the original page is offlined
 291 (i.e., no longer used, and taken out of normal memory management).
 292 The effect of the
 293 .B MADV_SOFT_OFFLINE
 294 operation is invisible to (i.e., does not change the semantics of)
 295 the calling process.
 296 .IP
 297 This feature is intended for testing of memory error-handling code;
 298 it is available only if the kernel was configured with
 299 .BR CONFIG_MEMORY_FAILURE .
 300 .TP
 301 .BR MADV_HUGEPAGE " (since Linux 2.6.38)"
 302 .\" commit 0af4e98b6b095c74588af04872f83d333c958c32
 303 .\" http://lwn.net/Articles/358904/
 304 .\" https://lwn.net/Articles/423584/
 305 Enable Transparent Huge Pages (THP) for pages in the range specified by
 306 .I addr
 307 and
 308 .IR length .
 309 Currently, Transparent Huge Pages work only with private anonymous pages (see
 310 .BR mmap (2)).
 311 The kernel will regularly scan the areas marked as huge page candidates
 312 to replace them with huge pages.
 313 The kernel will also allocate huge pages directly when the region is
 314 naturally aligned to the huge page size (see
 315 .BR posix_memalign (2)).
 316 .IP
 317 This feature is primarily aimed at applications that use large mappings of
 318 data and access large regions of that memory at a time (e.g., virtualization
 319 systems such as QEMU).
 320 It can very easily waste memory (e.g., a 2\ MB mapping that only ever accesses
 321 1 byte will result in 2\ MB of wired memory instead of one 4\ KB page).
 322 See the Linux kernel source file
 323 .I Documentation/admin\-guide/mm/transhuge.rst
 324 for more details.
 325 .IP
 326 Most common kernels configurations provide
 327 .BR MADV_HUGEPAGE -style
 328 behavior by default, and thus
 329 .BR MADV_HUGEPAGE
 330 is normally not necessary.
 331 It is mostly intended for embedded systems, where
 332 .BR MADV_HUGEPAGE -style
 333 behavior may not be enabled by default in the kernel.
 334 On such systems,
 335 this flag can be used in order to selectively enable THP.
 336 Whenever
 337 .BR MADV_HUGEPAGE
 338 is used, it should always be in regions of memory with
 339 an access pattern that the developer knows in advance won't risk
 340 to increase the memory footprint of the application when transparent
 341 hugepages are enabled.
 342 .IP
 343 The
 344 .BR MADV_HUGEPAGE
 345 and
 346 .BR MADV_NOHUGEPAGE
 347 operations are available only if the kernel was configured with
 348 .BR CONFIG_TRANSPARENT_HUGEPAGE .
 349 .TP
 350 .BR MADV_NOHUGEPAGE " (since Linux 2.6.38)"
 351 Ensures that memory in the address range specified by
 352 .IR addr
 353 and
 354 .IR length
 355 will not be backed by transparent hugepages.
 356 .TP
 357 .BR MADV_DONTDUMP " (since Linux 3.4)"
 358 .\" commit 909af768e88867016f427264ae39d27a57b6a8ed
 359 .\" commit accb61fe7bb0f5c2a4102239e4981650f9048519
 360 Exclude from a core dump those pages in the range specified by
 361 .I addr
 362 and
 363 .IR length .
 364 This is useful in applications that have large areas of memory
 365 that are known not to be useful in a core dump.
 366 The effect of
 367 .BR MADV_DONTDUMP
 368 takes precedence over the bit mask that is set via the
 369 .I /proc/[pid]/coredump_filter
 370 file (see
 371 .BR core (5)).
 372 .TP
 373 .BR MADV_DODUMP " (since Linux 3.4)"
 374 Undo the effect of an earlier
 375 .BR MADV_DONTDUMP .
 376 .TP
 377 .BR MADV_FREE " (since Linux 4.5)"
 378 The application no longer requires the pages in the range specified by
 379 .IR addr
 380 and
 381 .IR len .
 382 The kernel can thus free these pages,
 383 but the freeing could be delayed until memory pressure occurs.
 384 For each of the pages that has been marked to be freed
 385 but has not yet been freed,
 386 the free operation will be canceled if the caller writes into the page.
 387 After a successful
 388 .B MADV_FREE
 389 operation, any stale data (i.e., dirty, unwritten pages) will be lost
 390 when the kernel frees the pages.
 391 However, subsequent writes to pages in the range will succeed
 392 and then kernel cannot free those dirtied pages,
 393 so that the caller can always see just written data.
 394 If there is no subsequent write,
 395 the kernel can free the pages at any time.
 396 Once pages in the range have been freed, the caller will
 397 see zero-fill-on-demand pages upon subsequent page references.
 398 .IP
 399 The
 400 .B MADV_FREE
 401 operation
 402 can be applied only to private anonymous pages (see
 403 .BR mmap (2)).
 404 In Linux before version 4.12,
 405 .\" commit 93e06c7a645343d222c9a838834a51042eebbbf7
 406 when freeing pages on a swapless system,
 407 the pages in the given range are freed instantly,
 408 regardless of memory pressure.
 409 .TP
 410 .BR MADV_WIPEONFORK " (since Linux 4.14)"
 411 .\" commit d2cd9ede6e193dd7d88b6d27399e96229a551b19
 412 Present the child process with zero-filled memory in this range after a
 413 .BR fork (2).
 414 This is useful in forking servers in order to ensure
 415 that sensitive per-process data
 416 (for example, PRNG seeds, cryptographic secrets, and so on)
 417 is not handed to child processes.
 418 .IP
 419 The
 420 .B MADV_WIPEONFORK
 421 operation can be applied only to private anonymous pages (see
 422 .BR mmap (2)).
 423 .IP
 424 Within the child created by
 425 .BR fork (2),
 426 the
 427 .B MADV_WIPEONFORK
 428 setting remains in place on the specified address range.
 429 This setting is cleared during
 430 .BR execve (2).
 431 .TP
 432 .BR MADV_KEEPONFORK " (since Linux 4.14)"
 433 .\" commit d2cd9ede6e193dd7d88b6d27399e96229a551b19
 434 Undo the effect of an earlier
 435 .BR MADV_WIPEONFORK .
 436 .TP
 437 .BR MADV_COLD " (since Linux 5.4)"
 438 .\" commit 9c276cc65a58faf98be8e56962745ec99ab87636
 439 Deactivate a given range of pages.
 440 This will make the pages a more probable
 441 reclaim target should there be a memory pressure.
 442 This is a nondestructive operation.
 443 The advice might be ignored for some pages in the range when it is not
 444 applicable.
 445 .TP
 446 .BR MADV_PAGEOUT " (since Linux 5.4)"
 447 .\" commit 1a4e58cce84ee88129d5d49c064bd2852b481357
 448 Reclaim a given range of pages.
 449 This is done to free up memory occupied by these pages.
 450 If a page is anonymous, it will be swapped out.
 451 If a page is file-backed and dirty, it will be written back to the backing
 452 storage.
 453 The advice might be ignored for some pages in the range when it is not
 454 applicable.
 455 .TP
 456 .BR MADV_POPULATE_READ " (since Linux 5.14)"
 457 "Populate (prefault) page tables readable,
 458 faulting in all pages in the range just as if manually reading from each page;
 459 however,
 460 avoid the actual memory access that would have been performed after handling
 461 the fault.
 462 .IP
 463 In contrast to
 464 .BR MAP_POPULATE ,
 465 .B MADV_POPULATE_READ
 466 does not hide errors,
 467 can be applied to (parts of) existing mappings and will always populate
 468 (prefault) page tables readable.
 469 One example use case is prefaulting a file mapping,
 470 reading all file content from disk;
 471 however,
 472 pages won't be dirtied and consequently won't have to be written back to disk
 473 when evicting the pages from memory.
 474 .IP
 475 Depending on the underlying mapping,
 476 map the shared zeropage,
 477 preallocate memory or read the underlying file;
 478 files with holes might or might not preallocate blocks.
 479 If populating fails,
 480 a
 481 .B SIGBUS
 482 signal is not generated; instead, an error is returned.
 483 .IP
 484 If
 485 .B MADV_POPULATE_READ
 486 succeeds,
 487 all page tables have been populated (prefaulted) readable once.
 488 If
 489 .B MADV_POPULATE_READ
 490 fails,
 491 some page tables might have been populated.
 492 .IP
 493 .B MADV_POPULATE_READ
 494 cannot be applied to mappings without read permissions
 495 and special mappings,
 496 for example,
 497 mappings marked with kernel-internal flags such as
 498 .B VM_PFNMAP
 499 or
 500 .BR VM_IO ,
 501 or secret memory regions created using
 502 .BR memfd_secret(2) .
 503 .IP
 504 Note that with
 505 .BR MADV_POPULATE_READ ,
 506 the process can be killed at any moment when the system runs out of memory.
 507 .TP
 508 .BR MADV_POPULATE_WRITE " (since Linux 5.14)"
 509 Populate (prefault) page tables writable,
 510 faulting in all pages in the range just as if manually writing to each
 511 each page;
 512 however,
 513 avoid the actual memory access that would have been performed after handling
 514 the fault.
 515 .IP
 516 In contrast to
 517 .BR MAP_POPULATE ,
 518 MADV_POPULATE_WRITE does not hide errors,
 519 can be applied to (parts of) existing mappings and will always populate
 520 (prefault) page tables writable.
 521 One example use case is preallocating memory,
 522 breaking any CoW (Copy on Write).
 523 .IP
 524 Depending on the underlying mapping,
 525 preallocate memory or read the underlying file;
 526 files with holes will preallocate blocks.
 527 If populating fails,
 528 a
 529 .B SIGBUS
 530 signal is not generated; instead, an error is returned.
 531 .IP
 532 If
 533 .B MADV_POPULATE_WRITE
 534 succeeds,
 535 all page tables have been populated (prefaulted) writable once.
 536 If
 537 .B MADV_POPULATE_WRITE
 538 fails,
 539 some page tables might have been populated.
 540 .IP
 541 .B MADV_POPULATE_WRITE
 542 cannot be applied to mappings without write permissions
 543 and special mappings,
 544 for example,
 545 mappings marked with kernel-internal flags such as
 546 .B VM_PFNMAP
 547 or
 548 .BR VM_IO ,
 549 or secret memory regions created using
 550 .BR memfd_secret(2) .
 551 .IP
 552 Note that with
 553 .BR MADV_POPULATE_WRITE ,
 554 the process can be killed at any moment when the system runs out of memory.
 555 .SH RETURN VALUE
 556 On success,
 557 .BR madvise ()
 558 returns zero.
 559 On error, it returns \-1 and
 560 .I errno
 561 is set to indicate the error.
 562 .SH ERRORS
 563 .TP
 564 .B EACCES
 565 .I advice
 566 is
 567 .BR MADV_REMOVE ,
 568 but the specified address range is not a shared writable mapping.
 569 .TP
 570 .B EAGAIN
 571 A kernel resource was temporarily unavailable.
 572 .TP
 573 .B EBADF
 574 The map exists, but the area maps something that isn't a file.
 575 .TP
 576 .B EFAULT
 577 .I advice
 578 is
 579 .B MADV_POPULATE_READ
 580 or
 581 .BR MADV_POPULATE_WRITE ,
 582 and populating (prefaulting) page tables failed because a
 583 .B SIGBUS
 584 would have been generated on actual memory access and the reason is not a
 585 HW poisoned page
 586 (HW poisoned pages can,
 587 for example,
 588 be created using the
 589 .B MADV_HWPOISON
 590 flag described elsewhere in this page).
 591 .TP
 592 .B EINVAL
 593 .I addr
 594 is not page-aligned or
 595 .I length
 596 is negative.
 597 .\" .I length
 598 .\" is zero,
 599 .TP
 600 .B EINVAL
 601 .I advice
 602 is not a valid.
 603 .TP
 604 .B EINVAL
 605 .I advice
 606 is
 607 .B MADV_COLD
 608 or
 609 .B MADV_PAGEOUT
 610 and the specified address range includes locked, Huge TLB pages, or
 611 .B VM_PFNMAP
 612 pages.
 613 .TP
 614 .B EINVAL
 615 .I advice
 616 is
 617 .B MADV_DONTNEED
 618 or
 619 .BR MADV_REMOVE
 620 and the specified address range includes locked, Huge TLB pages, or
 621 .B VM_PFNMAP
 622 pages.
 623 .TP
 624 .B EINVAL
 625 .I advice
 626 is
 627 .BR MADV_MERGEABLE
 628 or
 629 .BR MADV_UNMERGEABLE ,
 630 but the kernel was not configured with
 631 .BR CONFIG_KSM .
 632 .TP
 633 .B EINVAL
 634 .I advice
 635 is
 636 .BR MADV_FREE
 637 or
 638 .BR MADV_WIPEONFORK
 639 but the specified address range includes file, Huge TLB,
 640 .BR MAP_SHARED ,
 641 or
 642 .BR VM_PFNMAP
 643 ranges.
 644 .TP
 645 .B EINVAL
 646 .I advice
 647 is
 648 .B MADV_POPULATE_READ
 649 or
 650 .BR MADV_POPULATE_WRITE ,
 651 but the specified address range includes ranges with insufficient permissions
 652 or special mappings,
 653 for example,
 654 mappings marked with kernel-internal flags such a
 655 .B VM_IO
 656 or
 657 .BR VM_PFNMAP ,
 658 or secret memory regions created using
 659 .BR memfd_secret(2) .
 660 .TP
 661 .B EIO
 662 (for
 663 .BR MADV_WILLNEED )
 664 Paging in this area would exceed the process's
 665 maximum resident set size.
 666 .TP
 667 .B ENOMEM
 668 (for
 669 .BR MADV_WILLNEED )
 670 Not enough memory: paging in failed.
 671 .TP
 672 .B ENOMEM
 673 Addresses in the specified range are not currently
 674 mapped, or are outside the address space of the process.
 675 .TP
 676 .B ENOMEM
 677 .I advice
 678 is
 679 .B MADV_POPULATE_READ
 680 or
 681 .BR MADV_POPULATE_WRITE ,
 682 and populating (prefaulting) page tables failed because there was not enough
 683 memory.
 684 .TP
 685 .B EPERM
 686 .I advice
 687 is
 688 .BR MADV_HWPOISON ,
 689 but the caller does not have the
 690 .B CAP_SYS_ADMIN
 691 capability.
 692 .TP
 693 .B EHWPOISON
 694 .I advice
 695 is
 696 .B MADV_POPULATE_READ
 697 or
 698 .BR MADV_POPULATE_WRITE ,
 699 and populating (prefaulting) page tables failed because a HW poisoned page
 700 (HW poisoned pages can,
 701 for example,
 702 be created using the
 703 .B MADV_HWPOISON
 704 flag described elsewhere in this page)
 705 was encountered.
 706 .SH VERSIONS
 707 Since Linux 3.18,
 708 .\" commit d3ac21cacc24790eb45d735769f35753f5b56ceb
 709 support for this system call is optional,
 710 depending on the setting of the
 711 .B CONFIG_ADVISE_SYSCALLS
 712 configuration option.
 713 .SH CONFORMING TO
 714 .BR madvise ()
 715 is not specified by any standards.
 716 Versions of this system call, implementing a wide variety of
 717 .I advice
 718 values, exist on many other implementations.
 719 Other implementations typically implement at least the flags listed
 720 above under
 721 .IR "Conventional advice flags" ,
 722 albeit with some variation in semantics.
 723 .PP
 724 POSIX.1-2001 describes
 725 .BR posix_madvise (3)
 726 with constants
 727 .BR POSIX_MADV_NORMAL ,
 728 .BR POSIX_MADV_RANDOM ,
 729 .BR POSIX_MADV_SEQUENTIAL ,
 730 .BR POSIX_MADV_WILLNEED ,
 731 and
 732 .BR POSIX_MADV_DONTNEED ,
 733 and so on, with behavior close to the similarly named flags listed above.
 734 .SH NOTES
 735 .SS Linux notes
 736 The Linux implementation requires that the address
 737 .I addr
 738 be page-aligned, and allows
 739 .I length
 740 to be zero.
 741 If there are some parts of the specified address range
 742 that are not mapped, the Linux version of
 743 .BR madvise ()
 744 ignores them and applies the call to the rest (but returns
 745 .B ENOMEM
 746 from the system call, as it should).
 747 .\" .SH HISTORY
 748 .\" The
 749 .\" .BR madvise ()
 750 .\" function first appeared in 4.4BSD.
 751 .SH SEE ALSO
 752 .BR getrlimit (2),
 753 .BR memfd_secret(2),
 754 .BR mincore (2),
 755 .BR mmap (2),
 756 .BR mprotect (2),
 757 .BR msync (2),
 758 .BR munmap (2),
 759 .BR prctl (2),
 760 .BR process_madvise (2),
 761 .BR posix_madvise (3),
 762 .BR core (5)