lib/libc/sys/madvise.2

   1 .\"     $NetBSD: madvise.2,v 1.27 2011/03/29 18:54:54 jruoho 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. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)madvise.2   8.1 (Berkeley) 6/9/93
  31 .\"
  32 .Dd March 29, 2011
  33 .Dt MADVISE 2
  34 .Os
  35 .Sh NAME
  36 .Nm madvise
  37 .Nd give advice about use of memory
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/mman.h
  42 .Ft int
  43 .Fn madvise "void *addr" "size_t len" "int behav"
  44 .Ft int
  45 .Fn posix_madvise "void *addr" "size_t len" "int advice"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn madvise
  49 system call
  50 allows a process that has knowledge of its memory behavior
  51 to describe it to the system.
  52 The
  53 .Fn posix_madvise
  54 interface is identical and is provided for standards conformance.
  55 .Pp
  56 The known behaviors are:
  57 .Bl -tag -width MADV_SEQUENTIAL
  58 .It Dv MADV_NORMAL
  59 Tells the system to revert to the default paging
  60 behavior.
  61 .It Dv MADV_RANDOM
  62 Is a hint that pages will be accessed randomly, and prefetching
  63 is likely not advantageous.
  64 .It Dv MADV_SEQUENTIAL
  65 Is a hint that pages will be accessed sequentially, from the lower address to
  66 higher address.
  67 It might cause the VM system to depress the priority of
  68 pages immediately preceding a given page when it is faulted in.
  69 .It Dv MADV_WILLNEED
  70 Is a hint that pages will be accessed in the near future.
  71 It might cause the VM system to make pages that are in a given virtual
  72 address range to temporarily have higher priority, and if they are in
  73 memory, decrease the likelihood of them being freed.
  74 It might immediately map the pages that are already in memory into the
  75 process, thereby eliminating unnecessary overhead of going through
  76 the entire process of faulting the pages in.
  77 It might or might not fault pages in from backing store.
  78 .It Dv MADV_DONTNEED
  79 Is a hint that pages will not be accessed in the near future.
  80 It might allow the VM system to decrease the in-memory priority
  81 of pages in the specified range.
  82 .It Dv MADV_FREE
  83 Gives the VM system the freedom to free pages,
  84 and tells the system that information in the specified page range
  85 is no longer important.
  86 .El
  87 .Pp
  88 Portable programs that call the
  89 .Fn posix_madvise
  90 interface should use the aliases
  91 .Dv POSIX_MADV_NORMAL , POSIX_MADV_SEQUENTIAL ,
  92 .Dv POSIX_MADV_RANDOM , POSIX_MADV_WILLNEED ,
  93 and
  94 .Dv POSIX_MADV_DONTNEED
  95 rather than the flags described above.
  96 .Sh RETURN VALUES
  97 Upon successful completion,
  98 a value of 0 is returned.
  99 Otherwise, a value of \-1 is returned and
 100 .Va errno
 101 is set to indicate the error.
 102 .Sh ERRORS
 103 .Fn madvise
 104 will fail if:
 105 .Bl -tag -width Er
 106 .It Bq Er EINVAL
 107 Invalid parameters were provided.
 108 .El
 109 .Sh SEE ALSO
 110 .Xr mincore 2 ,
 111 .Xr mprotect 2 ,
 112 .Xr msync 2 ,
 113 .Xr munmap 2 ,
 114 .Xr posix_fadvise 2
 115 .Sh STANDARDS
 116 The
 117 .Fn posix_madvise
 118 system call is expected to conform to the
 119 .St -p1003.1-2001
 120 standard.
 121 .Sh HISTORY
 122 The
 123 .Nm madvise
 124 system call first appeared in
 125 .Bx 4.4 ,
 126 but until
 127 .Nx 1.5
 128 it did not perform any of the requests on, or change any behavior of the
 129 address range given.
 130 The
 131 .Fn posix_madvise
 132 was invented in
 133 .Nx 5.0 .