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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)madvise.2 8.1 (Berkeley) 6/9/93 29.\" $FreeBSD: stable/12/lib/libc/sys/madvise.2 314436 2017-02-28 23:42:47Z imp $ 30.\" 31.Dd July 12, 2015 32.Dt MADVISE 2 33.Os 34.Sh NAME 35.Nm madvise , posix_madvise 36.Nd give advice about use of memory 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In sys/mman.h 41.Ft int 42.Fn madvise "void *addr" "size_t len" "int behav" 43.Ft int 44.Fn posix_madvise "void *addr" "size_t len" "int behav" 45.Sh DESCRIPTION 46The 47.Fn madvise 48system call 49allows a process that has knowledge of its memory behavior 50to describe it to the system. 51The 52.Fn posix_madvise 53interface is identical, except it returns an error number on error and does 54not modify 55.Va errno , 56and is provided for standards conformance. 57.Pp 58The known behaviors are: 59.Bl -tag -width MADV_SEQUENTIAL 60.It Dv MADV_NORMAL 61Tells the system to revert to the default paging 62behavior. 63.It Dv MADV_RANDOM 64Is a hint that pages will be accessed randomly, and prefetching 65is likely not advantageous. 66.It Dv MADV_SEQUENTIAL 67Causes the VM system to depress the priority of 68pages immediately preceding a given page when it is faulted in. 69.It Dv MADV_WILLNEED 70Causes pages that are in a given virtual address range 71to temporarily have higher priority, and if they are in 72memory, decrease the likelihood of them being freed. 73Additionally, 74the pages that are already in memory will be immediately mapped into 75the process, thereby eliminating unnecessary overhead of going through 76the entire process of faulting the pages in. 77This WILL NOT fault 78pages in from backing store, but quickly map the pages already in memory 79into the calling process. 80.It Dv MADV_DONTNEED 81Allows the VM system to decrease the in-memory priority 82of pages in the specified address range. 83Consequently, future references to this address range are more likely 84to incur a page fault. 85.It Dv MADV_FREE 86Gives the VM system the freedom to free pages, 87and tells the system that information in the specified page range 88is no longer important. 89This is an efficient way of allowing 90.Xr malloc 3 91to free pages anywhere in the address space, while keeping the address space 92valid. 93The next time that the page is referenced, the page might be demand 94zeroed, or might contain the data that was there before the 95.Dv MADV_FREE 96call. 97References made to that address space range will not make the VM system 98page the information back in from backing store until the page is 99modified again. 100.It Dv MADV_NOSYNC 101Request that the system not flush the data associated with this map to 102physical backing store unless it needs to. 103Typically this prevents the 104file system update daemon from gratuitously writing pages dirtied 105by the VM system to physical disk. 106Note that VM/file system coherency is 107always maintained, this feature simply ensures that the mapped data is 108only flush when it needs to be, usually by the system pager. 109.Pp 110This feature is typically used when you want to use a file-backed shared 111memory area to communicate between processes (IPC) and do not particularly 112need the data being stored in that area to be physically written to disk. 113With this feature you get the equivalent performance with mmap that you 114would expect to get with SysV shared memory calls, but in a more controllable 115and less restrictive manner. 116However, note that this feature is not portable 117across UNIX platforms (though some may do the right thing by default). 118For more information see the MAP_NOSYNC section of 119.Xr mmap 2 120.It Dv MADV_AUTOSYNC 121Undoes the effects of MADV_NOSYNC for any future pages dirtied within the 122address range. 123The effect on pages already dirtied is indeterminate - they 124may or may not be reverted. 125You can guarantee reversion by using the 126.Xr msync 2 127or 128.Xr fsync 2 129system calls. 130.It Dv MADV_NOCORE 131Region is not included in a core file. 132.It Dv MADV_CORE 133Include region in a core file. 134.It Dv MADV_PROTECT 135Informs the VM system this process should not be killed when the 136swap space is exhausted. 137The process must have superuser privileges. 138This should be used judiciously in processes that must remain running 139for the system to properly function. 140.El 141.Pp 142Portable programs that call the 143.Fn posix_madvise 144interface should use the aliases 145.Dv POSIX_MADV_NORMAL , POSIX_MADV_SEQUENTIAL , 146.Dv POSIX_MADV_RANDOM , POSIX_MADV_WILLNEED , 147and 148.Dv POSIX_MADV_DONTNEED 149rather than the flags described above. 150.Sh RETURN VALUES 151.Rv -std madvise 152.Sh ERRORS 153The 154.Fn madvise 155system call will fail if: 156.Bl -tag -width Er 157.It Bq Er EINVAL 158The 159.Fa behav 160argument is not valid. 161.It Bq Er ENOMEM 162The virtual address range specified by the 163.Fa addr 164and 165.Fa len 166arguments is not valid. 167.It Bq Er EPERM 168.Dv MADV_PROTECT 169was specified and the process does not have superuser privileges. 170.El 171.Sh SEE ALSO 172.Xr mincore 2 , 173.Xr mprotect 2 , 174.Xr msync 2 , 175.Xr munmap 2 , 176.Xr posix_fadvise 2 177.Sh STANDARDS 178The 179.Fn posix_madvise 180interface conforms to 181.St -p1003.1-2001 . 182.Sh HISTORY 183The 184.Fn madvise 185system call first appeared in 186.Bx 4.4 . 187