original/man2/madvise.2

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