1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)madvise.2 8.1 (Berkeley) 6/9/93 33.\" $FreeBSD: src/lib/libc/sys/madvise.2,v 1.17.2.8 2003/01/06 23:33:59 trhodes Exp $ 34.\" $DragonFly: src/lib/libc/sys/madvise.2,v 1.2 2003/06/17 04:26:47 dillon Exp $ 35.\" 36.Dd July 19, 1996 37.Dt MADVISE 2 38.Os 39.Sh NAME 40.Nm madvise 41.Nd give advice about use of memory 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/types.h 46.In sys/mman.h 47.Ft int 48.Fn madvise "void *addr" "size_t len" "int behav" 49.Sh DESCRIPTION 50The 51.Fn madvise 52system call 53allows a process that has knowledge of its memory behavior 54to describe it to the system. 55.Pp 56The known behaviors are: 57.Bl -tag -width MADV_SEQUENTIAL 58.It Dv MADV_NORMAL 59Tells the system to revert to the default paging 60behavior. 61.It Dv MADV_RANDOM 62Is a hint that pages will be accessed randomly, and prefetching 63is likely not advantageous. 64.It Dv MADV_SEQUENTIAL 65Causes the VM system to depress the priority of 66pages immediately preceding a given page when it is faulted in. 67.It Dv MADV_WILLNEED 68Causes pages that are in a given virtual address range 69to temporarily have higher priority, and if they are in 70memory, decrease the likelihood of them being freed. Additionally, 71the pages that are already in memory will be immediately mapped into 72the process, thereby eliminating unnecessary overhead of going through 73the entire process of faulting the pages in. This WILL NOT fault 74pages in from backing store, but quickly map the pages already in memory 75into the calling process. 76.It Dv MADV_DONTNEED 77Allows the VM system to decrease the in-memory priority 78of pages in the specified range. Additionally future references to 79this address range will incur a page fault. 80.It Dv MADV_FREE 81Gives the VM system the freedom to free pages, 82and tells the system that information in the specified page range 83is no longer important. This is an efficient way of allowing 84.Xr malloc 3 85to free pages anywhere in the address space, while keeping the address space 86valid. The next time that the page is referenced, the page might be demand 87zeroed, or might contain the data that was there before the 88.Dv MADV_FREE 89call. 90References made to that address space range will not make the VM system 91page the information back in from backing store until the page is 92modified again. 93.It Dv MADV_NOSYNC 94Request that the system not flush the data associated with this map to 95physical backing store unless it needs to. Typically this prevents the 96filesystem update daemon from gratuitously writing pages dirtied 97by the VM system to physical disk. Note that VM/filesystem coherency is 98always maintained, this feature simply ensures that the mapped data is 99only flush when it needs to be, usually by the system pager. 100.Pp 101This feature is typically used when you want to use a file-backed shared 102memory area to communicate between processes (IPC) and do not particularly 103need the data being stored in that area to be physically written to disk. 104With this feature you get the equivalent performance with mmap that you 105would expect to get with SysV shared memory calls, but in a more controllable 106and less restrictive manner. However, note that this feature is not portable 107across UNIX platforms (though some may do the right thing by default). 108For more information see the MAP_NOSYNC section of 109.Xr mmap 2 110.It Dv MADV_AUTOSYNC 111Undoes the effects of MADV_NOSYNC for any future pages dirtied within the 112address range. The effect on pages already dirtied is indeterminate - they 113may or may not be reverted. You can guarantee reversion by using the 114.Xr msync 2 115or 116.Xr fsync 2 117system calls. 118.It Dv MADV_NOCORE 119Region is not included in a core file. 120.It Dv MADV_CORE 121Include region in a core file. 122.El 123.Sh RETURN VALUES 124.Rv -std madvise 125.Sh ERRORS 126The 127.Fn madvise 128function will fail if: 129.Bl -tag -width Er 130.It Bq Er EINVAL 131The virtual address range specified by the 132.Fa addr 133and 134.Fa len 135arguments is not valid. 136.El 137.Sh SEE ALSO 138.Xr mincore 2 , 139.Xr mprotect 2 , 140.Xr msync 2 , 141.Xr munmap 2 142.Sh HISTORY 143The 144.Fn madvise 145function first appeared in 146.Bx 4.4 . 147