bsd/man/man2/madvise.2

   1 .\"     $NetBSD: madvise.2,v 1.7 1995/12/27 21:17:02 jtc Exp $
   2 .\"
   3 .\" Copyright (c) 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)madvise.2   8.1 (Berkeley) 6/9/93
  35 .\"
  36 .Dd June 9, 1993
  37 .Dt MADVISE 2
  38 .Os
  39 .Sh NAME
  40 .Nm madvise ,
  41 .Nm posix_madvise
  42 .Nd give advice about use of memory
  43 .Sh SYNOPSIS
  44 .Fd #include <sys/mman.h>
  45 .Ft int
  46 .Fo madvise
  47 .Fa "void *addr"
  48 .Fa "size_t len"
  49 .Fa "int advice"
  50 .Fc
  51 .Ft int
  52 .Fo posix_madvise
  53 .Fa "void *addr"
  54 .Fa "size_t len"
  55 .Fa "int advice"
  56 .Fc
  57 .Sh DESCRIPTION
  58 The
  59 .Fn madvise
  60 system call allows a process that has knowledge of its memory behavior
  61 to describe it to the system.
  62 The advice passed in may be used by the system
  63 to alter its virtual memory paging strategy.
  64 This advice may improve application and system performance.
  65 The behavior specified in
  66 .Fa advice
  67 can only be one of the following values:
  68 .Pp
  69 .Bl -tag -width MADV_SEQUENTIAL
  70 .It Dv  MADV_NORMAL
  71 Indicates that the application has no advice to give on its behavior
  72 in the specified address range.
  73 This is the system default behavior.
  74 This is used with
  75 .Fn madvise
  76 system call.
  77 .It Dv POSIX_MADV_NORMAL
  78 Same as MADV_NORMAL but used with
  79 .Fn posix_madvise
  80 system call.
  81 .It Dv MADV_SEQUENTIAL
  82 Indicates that the application expects to access this address range
  83 in a sequential manner.
  84 This is used with
  85 .Fn madvise
  86 system call.
  87 .It Dv POSIX_MADV_SEQUENTIAL
  88 Same as MADV_SEQUENTIAL but used with
  89 .Fn posix_madvise
  90 system call.
  91 .It Dv MADV_RANDOM
  92 Indicates that the application expects to access this address range
  93 in a random manner.
  94 This is used with
  95 .Fn madvise
  96 system call.
  97 .It Dv POSIX_MADV_RANDOM
  98 Same as MADV_RANDOM but used with
  99 .Fn posix_madvise
 100 system call.
 101 .It Dv MADV_WILLNEED
 102 Indicates that the application expects to access this address range soon.
 103 This is used with
 104 .Fn madvise
 105 system call.
 106 .It Dv POSIX_MADV_WILLNEED
 107 Same as MADV_WILLNEED but used with
 108 .Fn posix_madvise
 109 system call.
 110 .It Dv MADV_DONTNEED
 111 Indicates that the application is not expecting
 112 to access this address range soon.
 113 This is used with
 114 .Fn madvise
 115 system call.
 116 .It Dv POSIX_MADV_DONTNEED
 117 Same as MADV_DONTNEED but used with
 118 .Fn posix_madvise
 119 system call.
 120 .It Dv MADV_FREE
 121 Indicates that the application will not need the information contained
 122 in this address range, so the pages may be reused right away.
 123 The address range will remain valid.
 124 This is used with
 125 .Fn madvise
 126 system call.
 127 .It Dv MADV_ZERO_WIRED_PAGES
 128 Indicates that the application would like the wired pages in this address
 129 range to be zeroed out if the address range is deallocated without first
 130 unwiring the pages (i.e. a munmap(2) without a preceding munlock(2) or the application
 131 quits).
 132 This is used with
 133 .Fn madvise
 134 system call.
 135 .El
 136 .Pp
 137 The
 138 .Fn posix_madvise
 139 behaves same as
 140 .Fn madvise
 141 except that it uses values with POSIX_ prefix for the
 142 .Fa advice
 143 system call argument.
 144 .Sh RETURN VALUES
 145 Upon successful completion,
 146 a value of 0 is returned.
 147 Otherwise, a value of -1 is returned and
 148 .Va errno
 149 is set to indicate the error.
 150 .Sh ERRORS
 151 .Fn madvise
 152 fails if one or more of the following are true:
 153 .Bl -tag -width Er
 154 .\" ==========
 155 .It Bq Er EINVAL
 156 The value of
 157 .Fa advice
 158 is incorrect.
 159 .\" ==========
 160 .It Bq Er EINVAL
 161 The address range includes unallocated regions.
 162 .\" ==========
 163 .It Bq Er ENOMEM
 164 The virtual address range specified by the
 165 .Fa addr
 166 and
 167 .Fa len
 168 are outside the range allowed for the address space.
 169 .El
 170 .Sh LEGACY SYNOPSIS
 171 .Fd #include <sys/types.h>
 172 .Fd #include <sys/mman.h>
 173 .Pp
 174 .Ft int
 175 .br
 176 .Fo madvise
 177 .Fa "caddr_t addr"
 178 .Fa "size_t len"
 179 .Fa "int advice"
 180 .Fc ;
 181 .Pp
 182 .Ft int
 183 .br
 184 .Fo posix_madvise
 185 .Fa "caddr_t addr"
 186 .Fa "size_t len"
 187 .Fa "int advice"
 188 .Fc ;
 189 .Pp
 190 The include file
 191 .In sys/types.h
 192 is necessary.
 193 The type of
 194 .Fa addr
 195 has changed.
 196 .Sh SEE ALSO
 197 .Xr mincore 2 ,
 198 .Xr minherit 2 ,
 199 .Xr mprotect 2 ,
 200 .Xr msync 2 ,
 201 .Xr munmap 2 ,
 202 .Xr compat 5
 203 .Sh HISTORY
 204 The
 205 .Nm madvise
 206 function first appeared in 4.4BSD.
 207 The
 208 .Nm posix_madvise
 209 function is part of IEEE 1003.1-2001
 210 and was first implemented in Mac OS X 10.2.