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