MADVISE(2)                NetBSD System Calls Manual                MADVISE(2)

NAME
     madvise -- give advice about use of memory

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/mman.h>

     int
     madvise(void *addr, size_t len, int behav);

     int
     posix_madvise(void *addr, size_t len, int advice);

DESCRIPTION
     The madvise() system call allows a process that has knowledge of its mem-
     ory behavior to describe it to the system.  The posix_madvise() interface
     is identical and is provided for standards conformance.

     The known behaviors are:

     MADV_NORMAL  Tells the system to revert to the default paging behavior.

     MADV_RANDOM  Is a hint that pages will be accessed randomly, and
                  prefetching is likely not advantageous.

     MADV_SEQUENTIAL
                  Causes the VM system to depress the priority of pages imme-
                  diately preceding a given page when it is faulted in.

     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.

     MADV_DONTNEED
                  Allows the VM system to decrease the in-memory priority of
                  pages in the specified range.  Additionally future refer-
                  ences to this address range will incur a page fault.

     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.

     Portable programs that call the posix_madvise() interface should use the
     aliases POSIX_MADV_NORMAL, POSIX_MADV_SEQUENTIAL, POSIX_MADV_RANDOM,
     POSIX_MADV_WILLNEED, and POSIX_MADV_DONTNEED rather than the flags
     described above.

RETURN VALUES
     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.

ERRORS
     madvise() will fail if:

     [EINVAL]           Invalid parameters were provided.

SEE ALSO
     mincore(2), mprotect(2), msync(2), munmap(2), posix_fadvise(2)

STANDARDS
     The posix_madvise() system call is expected to conform to the IEEE Std
     1003.1-2001 (``POSIX.1'') standard.

HISTORY
     The madvise system call first appeared in 4.4BSD, but until NetBSD 1.5 it
     did not perform any of the requests on, or change any behavior of the
     address range given.  The posix_madvise() was invented in NetBSD 5.0.

NetBSD 5.0_STABLE               April 19, 2008               NetBSD 5.0_STABLE
