usr/src/man/man3c/madvise.3c

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Right Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH MADVISE 3C "Mar 28, 2016"
   7 .SH NAME
   8 madvise \- provide advice to VM system
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/mman.h>
  14
  15 \fBint\fR \fBmadvise\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIadvice\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .LP
  20 The \fBmadvise()\fR function advises the kernel that a region of user mapped
  21 memory in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) will be accessed
  22 following a type of pattern. The kernel uses this information to optimize the
  23 procedure for manipulating and maintaining the resources associated with the
  24 specified mapping range. In general (and true to the name of the function),
  25 the advice is merely advisory, and the only user-visible ramifications
  26 are in terms of performance, not semantics. Note that
  27 \fBMADV_PURGE\fR is an exception to this; see below for details.
  28 .sp
  29 .LP
  30 Values for \fIadvice\fR are defined in <\fBsys/mman.h\fR> as:
  31 .sp
  32 .in +2
  33 .nf
  34 #define MADV_NORMAL           0x0  /* No further special treatment */
  35 #define MADV_RANDOM           0x1  /* Expect random page references */
  36 #define MADV_SEQUENTIAL       0x2  /* Expect sequential page references */
  37 #define MADV_WILLNEED         0x3  /* Will need these pages */
  38 #define MADV_DONTNEED         0x4  /* Don't need these pages */
  39 #define MADV_FREE             0x5  /* Contents can be freed */
  40 #define MADV_ACCESS_DEFAULT   0x6  /* default access */
  41 #define MADV_ACCESS_LWP       0x7  /* next LWP to access heavily */
  42 #define MADV_ACCESS_MANY      0x8  /* many processes to access heavily */
  43 #define MADV_PURGE            0x9  /* contents will be purged */
  44 .fi
  45 .in -2
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fBMADV_NORMAL\fR\fR
  51 .ad
  52 .RS 23n
  53 This is the default system characteristic where accessing memory within the
  54 address range causes the system to read data from the mapped file. The kernel
  55 reads all data from files into pages which are retained for a period of time as
  56 a "cache." System pages can be a scarce resource, so the kernel steals pages
  57 from other mappings when needed. This is a likely occurrence, but adversely
  58 affects system performance only if a large amount of memory is accessed.
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBMADV_RANDOM\fR\fR
  65 .ad
  66 .RS 23n
  67 Tell the kernel to read in a minimum amount of data from a mapped file on any
  68 single particular access. If  \fBMADV_NORMAL\fR is in effect when an address of
  69 a mapped file is accessed, the system tries to read in as much data from the
  70 file as reasonable, in anticipation of other accesses within a certain
  71 locality.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBMADV_SEQUENTIAL\fR\fR
  78 .ad
  79 .RS 23n
  80 Tell the system that addresses in this range are likely to be accessed only
  81 once, so the system will free the resources mapping the address range as
  82 quickly as possible.
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBMADV_WILLNEED\fR\fR
  89 .ad
  90 .RS 23n
  91 Tell the system that a certain address range is definitely needed so the kernel
  92 will start reading the specified range into memory. This can benefit programs
  93 wanting to minimize the time needed to access memory the first time, as the
  94 kernel would need to read in from the file.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBMADV_DONTNEED\fR\fR
 101 .ad
 102 .RS 23n
 103 Tell the kernel that the specified address range is no longer needed, so the
 104 system starts to free the resources associated with the address range.
 105 While the semantics of \fBMADV_DONTNEED\fR are similar to other systems,
 106 they differ significantly from the semantics on Linux, where
 107 \fBMADV_DONTNEED\fR will actually synchronously purge the address range,
 108 and subsequent faults will load from either backing store or be
 109 zero-filled on demand. If the peculiar Linux semantics are
 110 desired, \fBMADV_PURGE\fR should be used in lieu of \fBMADV_DONTNEED\fR.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBMADV_FREE\fR\fR
 117 .ad
 118 .RS 23n
 119 Tell the kernel that contents in the specified address range are no longer
 120 important and the range will be overwritten. When there is demand for memory,
 121 the system will free pages associated with the specified address range. In this
 122 instance, the next time a page in the address range is referenced, it will
 123 contain all zeroes.  Otherwise, it will contain the data that was there prior
 124 to the \fBMADV_FREE\fR call. References made to the address range will not make
 125 the system read from backing store (swap space) until the page is modified
 126 again.
 127 .sp
 128 This value cannot be used on mappings that have underlying file objects.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBMADV_PURGE\fR\fR
 135 .ad
 136 .RS 23n
 137 Tell the kernel to purge the specified address range.  The mapping will
 138 be retained, but the pages themselves will be destroyed; subsequent
 139 faults on the range will result in the page being read from backing
 140 store (if file-backed) or being zero-filled on demand (if anonymous).  Note
 141 that these semantics are generally inferior to \fBMADV_FREE\fR, which gives the
 142 system more flexibility and results in better performance
 143 when pages are, in fact, reused by the caller. Indeed, \fBMADV_PURGE\fR only
 144 exists to provide an equivalent to the unfortunate
 145 \fBMADV_DONTNEED\fR semantics found in Linux, upon which some programs
 146 have (regrettably) come to depend. In de novo applications,
 147 \fBMADV_PURGE\fR should be avoided; \fBMADV_FREE\fR should always be
 148 preferred.
 149 .RE
 150
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBMADV_ACCESS_LWP\fR\fR
 155 .ad
 156 .RS 23n
 157 Tell the kernel that the next LWP to touch the specified address range will
 158 access it most heavily, so the kernel should try to allocate the memory and
 159 other resources for this range and the LWP accordingly.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBMADV_ACCESS_MANY\fR\fR
 166 .ad
 167 .RS 23n
 168 Tell the kernel that many processes and/or LWPs will access the specified
 169 address range randomly across the machine, so the kernel should try to allocate
 170 the memory and other resources for this range accordingly.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBMADV_ACCESS_DEFAULT\fR\fR
 177 .ad
 178 .RS 23n
 179 Reset the kernel's expectation for how the specified range will be accessed to
 180 the default.
 181 .RE
 182
 183 .sp
 184 .LP
 185 The \fBmadvise()\fR function should be used by applications with specific
 186 knowledge of their access patterns over a memory object, such as a mapped file,
 187 to increase system performance.
 188 .SH RETURN VALUES
 189 .LP
 190 Upon successful completion, \fBmadvise()\fR returns \fB0\fR; otherwise, it
 191 returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error.
 192 .SH ERRORS
 193 .ne 2
 194 .na
 195 \fB\fBEAGAIN\fR\fR
 196 .ad
 197 .RS 10n
 198 Some or all mappings  in the  address  range [\fIaddr\fR,  \fIaddr\fR  +
 199 \fIlen\fR) are locked for I/O.
 200 .RE
 201
 202 .sp
 203 .ne 2
 204 .na
 205 \fB\fBEBUSY\fR\fR
 206 .ad
 207 .RS 10n
 208 Some or all of the addresses in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR)
 209 are locked and \fBMS_SYNC\fR with the \fBMS_INVALIDATE\fR option is specified.
 210 .RE
 211
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBEFAULT\fR\fR
 216 .ad
 217 .RS 10n
 218 Some or all of the addresses in the specified range could not be read into
 219 memory from the underlying object when performing \fBMADV_WILLNEED\fR. The
 220 \fBmadvise()\fR function could return prior to this condition being detected,
 221 in which case \fBerrno\fR will not be set to \fBEFAULT\fR.
 222 .RE
 223
 224 .sp
 225 .ne 2
 226 .na
 227 \fB\fBEINVAL\fR\fR
 228 .ad
 229 .RS 10n
 230 The \fIaddr\fR argument is not a multiple of the page size as returned by
 231 \fBsysconf\fR(3C), the length of the specified address range is equal to 0, or
 232 the \fIadvice\fR argument was invalid.
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBEIO\fR\fR
 239 .ad
 240 .RS 10n
 241 An I/O error occurred while reading from or writing to the file system.
 242 .RE
 243
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBENOMEM\fR\fR
 248 .ad
 249 .RS 10n
 250 Addresses in the range [\fIaddr\fR, \fIaddr\fR + \fIlen\fR) are outside the
 251 valid range for the address space of a process, or specify one or more pages
 252 that are not mapped.
 253 .RE
 254
 255 .sp
 256 .ne 2
 257 .na
 258 \fB\fBESTALE\fR\fR
 259 .ad
 260 .RS 10n
 261 Stale \fBNFS\fR file handle.
 262 .RE
 263
 264 .SH ATTRIBUTES
 265 .LP
 266 See \fBattributes\fR(5) for descriptions of the following attributes:
 267 .sp
 268
 269 .sp
 270 .TS
 271 box;
 272 c | c
 273 l | l .
 274 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 275 _
 276 Interface Stability     Stable
 277 _
 278 MT-Level        MT-Safe
 279 .TE
 280
 281 .SH SEE ALSO
 282 .LP
 283 \fBmeminfo\fR(2), \fBmmap\fR(2), \fBsysconf\fR(3C), \fBattributes\fR(5)