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