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 .Nd give advice about use of memory
  42 .Sh SYNOPSIS
  43 .Fd #include <sys/types.h>
  44 .Fd #include <sys/mman.h>
  45 .Ft int
  46 .Fn madvise "caddr_t addr" "size_t len" "int behav"
  47 .Ft int
  48 .Fn posix_madvise "caddr_t addr" "size_t len" "int behav"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn madvise
  52 system call allows a process that has knowledge of its memory behavior to describe it to the system. The advice passed in may be used by the system to alter its virtual memory paging strategy. This advice may improve application and system performance. The behavior specified in
  53 .Fa behav
  54 can only be one of the following values:
  55 .Pp
  56 .Bl -tag -width MADV_SEQUENTIAL
  57 .It Dv  MADV_NORMAL
  58 Indicates that the application has no advice to give on its behavior in the specifed address range. This is the system default behavior. This is used with
  59 .Fn madvise
  60 system call.
  61 .It Dv POSIX_MADV_NORMAL
  62 Same as MADV_NORMAL but used with
  63 .Fn posix_madvise
  64 system call.
  65 .It Dv MADV_SEQUENTIAL
  66 Indicates that the application expects to access this address range in a sequential manner. This is used with
  67 .Fn madvise
  68 system call.
  69 .It Dv POSIX_MADV_SEQUENTIAL
  70 Same as MADV_SEQUENTIAL but used with
  71 .Fn posix_madvise
  72 system call.
  73 .It Dv MADV_RANDOM
  74 Indicates that the application expects to access this address range in a random manner. This is used with
  75 .Fn madvise
  76 system call.
  77 .It Dv POSIX_MADV_RANDOM
  78 Same as MADV_RANDOM but used with
  79 .Fn posix_madvise
  80 system call.
  81 .It Dv MADV_WILLNEED
  82 Indicates that the application expects to access this address range soon. This is used with
  83 .Fn madvise
  84 system call.
  85 .It Dv POSIX_MADV_WILLNEED
  86 Same as MADV_WILLNEED but used with
  87 .Fn posix_madvise
  88 system call.
  89 .It Dv MADV_DONTNEED
  90 Indicates that the application is not expecting to access this address range soon. This is used with
  91 .Fn madvise
  92 system call.
  93 .It Dv POSIX_MADV_DONTNEED
  94 Same as MADV_DONTNEED but used with
  95 .Fn posix_madvise
  96 system call.
  97 .It Dv MADV_FREE
  98 Indicates that the application will not need the information contained in this address range so the pages may be reused right away. The address range will remain valid. This is used with
  99 .Fn madvise
 100 system call.
 101 .El
 102 .Pp
 103 The
 104 .Fn posix_madvise
 105 behaves same as
 106 .Fn madvise
 107 except that it uses values with POSIX_ prefix for the
 108 .Fa behav
 109 system call argument.
 110 .Sh RETURN VALUES
 111 Upon successful completion,
 112 a value of 0 is returned.
 113 Otherwise, a value of -1 is returned and
 114 .Va errno
 115 is set to indicate the error.
 116 .Sh ERRORS
 117 .Fn madvise
 118 fails if one or more of the following are true:
 119 .Bl -tag -width Er
 120 .It Bq Er EINVAL
 121 The value of
 122 .Fa behav
 123 is incorrect.
 124 .It Bq Er ENOMEM
 125 The virtual address range specified by the
 126 .Fa addr
 127 and
 128 .Fa len
 129 are outside the range allowed for the address space.
 130 .It Bq Er EINVAL
 131 The address range includes unallocated regions.
 132 .El
 133 .Sh SEE ALSO
 134 .Xr mincore 2 ,
 135 .Xr minherit 2 ,
 136 .Xr mprotect 2 ,
 137 .Xr msync 2 ,
 138 .Xr munmap 2
 139 .Sh HISTORY
 140 The
 141 .Nm madvise
 142 function first appeared in 4.4BSD.
 143 The
 144 .Nm posix_madvise
 145 function is part of IEEE 1003.1-2001 and was first implemented in Mac OS X 10.2.