diff options
Diffstat (limited to 'lib/libc/sys/madvise.2')
| -rw-r--r-- | lib/libc/sys/madvise.2 | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/lib/libc/sys/madvise.2 b/lib/libc/sys/madvise.2 new file mode 100644 index 0000000..9a82782 --- /dev/null +++ b/lib/libc/sys/madvise.2 @@ -0,0 +1,154 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)madvise.2 8.1 (Berkeley) 6/9/93 +.\" $FreeBSD$ +.\" +.Dd Jul 19, 1996 +.Dt MADVISE 2 +.Os +.Sh NAME +.Nm madvise +.Nd give advice about use of memory +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/mman.h> +.Ft int +.Fn madvise "void *addr" "size_t len" "int behav" +.Sh DESCRIPTION +The +.Fn madvise +system call +allows a process that has knowledge of its memory behavior +to describe it to the system. +The known behaviors are given in +.Aq Pa sys/mman.h : +.Bd -literal +#define MADV_NORMAL 0 /* no further special treatment */ +#define MADV_RANDOM 1 /* expect random page references */ +#define MADV_SEQUENTIAL 2 /* expect sequential references */ +#define MADV_WILLNEED 3 /* will need these pages */ +#define MADV_DONTNEED 4 /* don't need these pages */ +#define MADV_FREE 5 /* data is now unimportant */ +#define MADV_NOSYNC 6 /* no explicit commit to physical backing store */ +#define MADV_AUTOSYNC 7 /* default commit method to physical backing store */ +.Ed +.Pp +.Bl -tag -width MADV_SEQUENTIAL +.It Dv MADV_NORMAL +Tells the system to revert to the default paging +behavior. +.It Dv MADV_RANDOM +Is a hint that pages will be accessed randomly, and prefetching +is likely not advantageous. +.It Dv MADV_SEQUENTIAL +Causes the VM system to depress the priority of +pages immediately preceding a given page when it is faulted in. +.It Dv MADV_WILLNEED +Causes pages that are in a given virtual address range +to temporarily have higher priority, and if they are in +memory, decrease the likelihood of them being freed. Additionally, +the pages that are already in memory will be immediately mapped into +the process, thereby eliminating unnecessary overhead of going through +the entire process of faulting the pages in. This WILL NOT fault +pages in from backing store, but quickly map the pages already in memory +into the calling process. +.It Dv MADV_DONTNEED +Allows the VM system to decrease the in-memory priority +of pages in the specified range. Additionally future references to +this address range will incur a page fault. +.It Dv MADV_FREE +Gives the VM system the freedom to free pages, +and tells the system that information in the specified page range +is no longer important. This is an efficient way of allowing +.Xr malloc 3 +to free pages anywhere in the address space, while keeping the address space +valid. The next time that the page is referenced, the page might be demand +zeroed, or might contain the data that was there before the +.Dv MADV_FREE +call. +References made to that address space range will not make the VM system +page the information back in from backing store until the page is +modified again. +.It Dv MADV_NOSYNC +Request that the system not flush the data associated with this map to +physical backing store unless it needs to. Typically this prevents the +filesystem update daemon from gratuitously writing pages dirtied +by the VM system to physical disk. Note that VM/filesystem coherency is +always maintained, this feature simply ensures that the mapped data is +only flush when it needs to be, usually by the system pager. +.Pp +This feature is typically used when you want to use a file-backed shared +memory area to communicate between processes (IPC) and do not particularly +need the data being stored in that area to be physically written to disk. +With this feature you get the equivalent performance with mmap that you +would expect to get with SysV shared memory calls, but in a more controllable +and less restrictive manner. However, note that this feature is not portable +across UNIX platforms (though some may do the right thing by default). +For more information see the MAP_NOSYNC section of +.Xr mmap 2 +.It Dv MADV_AUTOSYNC +Undoes the effects of MADV_NOSYNC for any future pages dirtied within the +address range. The effect on pages already dirtied is indeterminate - they +may or may not be reverted. You can guarentee reversion by using the +.Xr msync 2 +or +.Xr fsync 2 +system calls. +.El +.Sh RETURN VALUES +Upon successful completion, +.Fn madvise +returns 0. Otherwise a value of -1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn madvise +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The virtual address range specified by the +.Fa addr +and +.Fa len +arguments is not valid. +.El +.Sh SEE ALSO +.Xr mincore 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munmap 2 . +.Sh HISTORY +The +.Fn madvise +function first appeared in +.Bx 4.4 . |
