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 58The 59.Fn madvise 60system call allows a process that has knowledge of its memory behavior 61to describe it to the system. 62The advice passed in may be used by the system 63to alter its virtual memory paging strategy. 64This advice may improve application and system performance. 65The behavior specified in 66.Fa advice 67can only be one of the following values: 68.Pp 69.Bl -tag -width MADV_SEQUENTIAL 70.It Dv MADV_NORMAL 71Indicates that the application has no advice to give on its behavior 72in the specified address range. 73This is the system default behavior. 74This is used with 75.Fn madvise 76system call. 77.It Dv POSIX_MADV_NORMAL 78Same as MADV_NORMAL but used with 79.Fn posix_madvise 80system call. 81.It Dv MADV_SEQUENTIAL 82Indicates that the application expects to access this address range 83in a sequential manner. 84This is used with 85.Fn madvise 86system call. 87.It Dv POSIX_MADV_SEQUENTIAL 88Same as MADV_SEQUENTIAL but used with 89.Fn posix_madvise 90system call. 91.It Dv MADV_RANDOM 92Indicates that the application expects to access this address range 93in a random manner. 94This is used with 95.Fn madvise 96system call. 97.It Dv POSIX_MADV_RANDOM 98Same as MADV_RANDOM but used with 99.Fn posix_madvise 100system call. 101.It Dv MADV_WILLNEED 102Indicates that the application expects to access this address range soon. 103This is used with 104.Fn madvise 105system call. 106.It Dv POSIX_MADV_WILLNEED 107Same as MADV_WILLNEED but used with 108.Fn posix_madvise 109system call. 110.It Dv MADV_DONTNEED 111Indicates that the application is not expecting 112to access this address range soon. 113This is used with 114.Fn madvise 115system call. 116.It Dv POSIX_MADV_DONTNEED 117Same as MADV_DONTNEED but used with 118.Fn posix_madvise 119system call. 120.It Dv MADV_FREE 121Indicates that the application will not need the information contained 122in this address range, so the pages may be reused right away. 123The address range will remain valid. 124This is used with 125.Fn madvise 126system call. 127.It Dv MADV_ZERO_WIRED_PAGES 128Indicates that the application would like the wired pages in this address 129range to be zeroed out if the address range is deallocated without first 130unwiring the pages (i.e. a munmap(2) without a preceding munlock(2) or the application 131quits). 132This is used with 133.Fn madvise 134system call. 135.It Dv MADV_ZERO 136Indicates that the application would like this address range effectively 137zeroed without causing unnecessary memory accesses. This could return ENOTSUP 138in some situations, in which case the caller should fall back to zeroing the 139range themselves. 140This is used with 141.Fn madvise 142system call. 143.El 144.Pp 145The 146.Fn posix_madvise 147behaves same as 148.Fn madvise 149except that it uses values with POSIX_ prefix for the 150.Fa advice 151system call argument. 152.Sh RETURN VALUES 153Upon successful completion, 154a value of 0 is returned. 155Otherwise, a value of -1 is returned and 156.Va errno 157is set to indicate the error. 158.Sh ERRORS 159.Fn madvise 160fails if one or more of the following are true: 161.Bl -tag -width Er 162.\" ========== 163.It Bq Er EINVAL 164The value of 165.Fa advice 166is incorrect. 167.\" ========== 168.It Bq Er EINVAL 169The address range includes unallocated regions. 170.\" ========== 171.It Bq Er ENOMEM 172The virtual address range specified by the 173.Fa addr 174and 175.Fa len 176are outside the range allowed for the address space. 177.\" ========== 178.It Bq Er EPERM 179The operation isn't allowed on a part (or whole) of the address range due to 180restrictions. 181.\" ========== 182.It Bq Er ENOTSUP 183The operation is not supported. 184.El 185.Sh LEGACY SYNOPSIS 186.Fd #include <sys/types.h> 187.Fd #include <sys/mman.h> 188.Pp 189.Ft int 190.br 191.Fo madvise 192.Fa "caddr_t addr" 193.Fa "size_t len" 194.Fa "int advice" 195.Fc ; 196.Pp 197.Ft int 198.br 199.Fo posix_madvise 200.Fa "caddr_t addr" 201.Fa "size_t len" 202.Fa "int advice" 203.Fc ; 204.Pp 205The include file 206.In sys/types.h 207is necessary. 208The type of 209.Fa addr 210has changed. 211.Sh SEE ALSO 212.Xr mincore 2 , 213.Xr minherit 2 , 214.Xr mprotect 2 , 215.Xr msync 2 , 216.Xr munmap 2 , 217.Xr compat 5 218.Sh HISTORY 219The 220.Nm madvise 221function first appeared in 4.4BSD. 222The 223.Nm posix_madvise 224function is part of IEEE 1003.1-2001 225and was first implemented in Mac OS X 10.2. 226