Document madvise(2) as it is in FreeBSD.

1 files changed, 40 insertions, 11 deletions

diff --git a/lib/libc/sys/madvise.2 b/lib/libc/sys/madvise.2
index 4326389..a100cb9 100644
--- a/lib/libc/sys/madvise.2
+++ b/lib/libc/sys/madvise.2
@@ -31,7 +31,7 @@
 .\"
 .\"	@(#)madvise.2	8.1 (Berkeley) 6/9/93
 .\"
-.Dd June 9, 1993
+.Dd Jul 19, 1996
 .Dt MADVISE 2
 .Os
 .Sh NAME
@@ -50,23 +50,52 @@ to describe it to the system.
 The known behaviors are given in
 .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_SPACEAVAIL	5	/* insure that resources are reserved */
+#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 */
 .Ed
+.sp
+MADV_NORMAL tells the system to revert to the default paging
+behavior.
+.sp
+MADV_RANDOM is a hint that pages will be accessed randomly, and prefetching
+is likely not advantageous.
+.sp
+MADV_SEQUENTIAL causes the VM system to depress the priority of
+pages immediately preceeding a given page when it is faulted in.
+.sp
+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.
+.sp
+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.
+.sp
+MADV_FREE gives the VM system the freedom to free pages,
+and and tells the system that information in the specified page range
+is no longer important.  This is an efficient way of allowing 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 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.
+
 .Sh SEE ALSO
 .Xr msync 2 ,
 .Xr munmap 2 ,
 .Xr mprotect 2 ,
 .Xr mincore 2 .
 
-.Sh BUGS
-.Nm madvise 
-is not yet implemented.
-
 .Sh HISTORY
 The
 .Nm madvise