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 .El
 128 .Pp
 129 The
 130 .Fn posix_madvise
 131 behaves same as
 132 .Fn madvise
 133 except that it uses values with POSIX_ prefix for the
 134 .Fa advice
 135 system call argument.
 136 .Sh RETURN VALUES
 137 Upon successful completion,
 138 a value of 0 is returned.
 139 Otherwise, a value of -1 is returned and
 140 .Va errno
 141 is set to indicate the error.
 142 .Sh ERRORS
 143 .Fn madvise
 144 fails if one or more of the following are true:
 145 .Bl -tag -width Er
 146 .\" ==========
 147 .It Bq Er EINVAL
 148 The value of
 149 .Fa advice
 150 is incorrect.
 151 .\" ==========
 152 .It Bq Er EINVAL
 153 The address range includes unallocated regions.
 154 .\" ==========
 155 .It Bq Er ENOMEM
 156 The virtual address range specified by the
 157 .Fa addr
 158 and
 159 .Fa len
 160 are outside the range allowed for the address space.
 161 .El
 162 .Sh LEGACY SYNOPSIS
 163 .Fd #include <sys/types.h>
 164 .Fd #include <sys/mman.h>
 165 .Pp
 166 .Ft int
 167 .br
 168 .Fo madvise
 169 .Fa "caddr_t addr"
 170 .Fa "size_t len"
 171 .Fa "int advice"
 172 .Fc ;
 173 .Pp
 174 .Ft int
 175 .br
 176 .Fo posix_madvise
 177 .Fa "caddr_t addr"
 178 .Fa "size_t len"
 179 .Fa "int advice"
 180 .Fc ;
 181 .Pp
 182 The include file
 183 .In sys/types.h
 184 is necessary.
 185 The type of
 186 .Fa addr
 187 has changed.
 188 .Sh SEE ALSO
 189 .Xr mincore 2 ,
 190 .Xr minherit 2 ,
 191 .Xr mprotect 2 ,
 192 .Xr msync 2 ,
 193 .Xr munmap 2 ,
 194 .Xr compat 5
 195 .Sh HISTORY
 196 The
 197 .Nm madvise
 198 function first appeared in 4.4BSD.
 199 The
 200 .Nm posix_madvise
 201 function is part of IEEE 1003.1-2001
 202 and was first implemented in Mac OS X 10.2.