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 memory 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

Is a hint that pages will be accessed sequentially, from the lower address to higher address. It might cause the VM system to depress the priority of pages immediately preceding a given page when it is faulted in.

MADV_WILLNEED

Is a hint that pages will be accessed in the near future. It might cause the VM system to make 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. It might immediately map the pages that are already in memory into the process, thereby eliminating unnecessary overhead of going through the entire process of faulting the pages in. It might or might not fault pages in from backing store.

MADV_DONTNEED

Is a hint that pages will not be accessed in the near future. It might allow the VM system to decrease the in-memory priority of pages in the specified range.

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.