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