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