Tribblix: manual page: madvise.3c

MADVISE(3C) Standard C Library Functions MADVISE(3C)

NAME

madvise - provide advice to VM system

SYNOPSIS

#include <sys/types.h>
#include <sys/mman.h>

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

DESCRIPTION

The madvise() function advises the kernel that a region of user mapped
memory in the range [addr, addr + len) will be accessed following a
type of pattern. The kernel uses this information to optimize the
procedure for manipulating and maintaining the resources associated
with the specified mapping range. In general (and true to the name of
the function), the advice is merely advisory, and the only user-visible
ramifications are in terms of performance, not semantics. Note that
MADV_PURGE is an exception to this; see below for details.

Values for advice are defined in <sys/mman.h> as:

#define MADV_NORMAL 0x0 /* No further special treatment */
#define MADV_RANDOM 0x1 /* Expect random page references */
#define MADV_SEQUENTIAL 0x2 /* Expect sequential page references */
#define MADV_WILLNEED 0x3 /* Will need these pages */
#define MADV_DONTNEED 0x4 /* Don't need these pages */
#define MADV_FREE 0x5 /* Contents can be freed */
#define MADV_ACCESS_DEFAULT 0x6 /* default access */
#define MADV_ACCESS_LWP 0x7 /* next LWP to access heavily */
#define MADV_ACCESS_MANY 0x8 /* many processes to access heavily */
#define MADV_PURGE 0x9 /* contents will be purged */

MADV_NORMAL
This is the default system characteristic where accessing
memory within the address range causes the system to read data
from the mapped file. The kernel reads all data from files
into pages which are retained for a period of time as a
"cache". System pages can be a scarce resource, so the kernel
steals pages from other mappings when needed. This is a likely
occurrence, but adversely affects system performance only if a
large amount of memory is accessed.

MADV_RANDOM
Tell the kernel to read in a minimum amount of data from a
mapped file on any single particular access. If MADV_NORMAL is
in effect when an address of a mapped file is accessed, the
system tries to read in as much data from the file as
reasonable, in anticipation of other accesses within a certain
locality.

MADV_SEQUENTIAL
Tell the system that addresses in this range are likely to be
accessed only once, so the system will free the resources
mapping the address range as quickly as possible.

MADV_WILLNEED
Tell the system that a certain address range is definitely
needed so the kernel will start reading the specified range
into memory. This can benefit programs wanting to minimize the
time needed to access memory the first time, as the kernel
would need to read in from the file.

MADV_DONTNEED
Tell the kernel that the specified address range is no longer
needed, so the system starts to free the resources associated
with the address range. While the semantics of MADV_DONTNEED
are similar to other systems, they differ significantly from
the semantics on Linux, where MADV_DONTNEED will actually
synchronously purge the address range, and subsequent faults
will load from either backing store or be zero-filled on
demand. If the peculiar Linux semantics are desired,
MADV_PURGE should be used in lieu of MADV_DONTNEED.

MADV_FREE
Tell the kernel that contents in the specified address range
are no longer important and the range will be overwritten.
When there is demand for memory, the system will free pages
associated with the specified address range. In this instance,
the next time a page in the address range is referenced, it
will contain all zeroes. Otherwise, it will contain the data
that was there prior to the MADV_FREE call. References made to
the address range will not make the system read from backing
store (swap space) until the page is modified again.

This value cannot be used on mappings that have underlying file
objects.

MADV_PURGE
Tell the kernel to purge the specified address range. The
mapping will be retained, but the pages themselves will be
destroyed; subsequent faults on the range will result in the
page being read from backing store (if file-backed) or being
zero-filled on demand (if anonymous). Note that these
semantics are generally inferior to MADV_FREE, which gives the
system more flexibility and results in better performance when
pages are, in fact, reused by the caller. Indeed, MADV_PURGE
only exists to provide an equivalent to the unfortunate
MADV_DONTNEED semantics found in Linux, upon which some
programs have (regrettably) come to depend. In de novo
applications, MADV_PURGE should be avoided; MADV_FREE should
always be preferred.

MADV_ACCESS_LWP
Tell the kernel that the next LWP to touch the specified
address range will access it most heavily, so the kernel should
try to allocate the memory and other resources for this range
and the LWP accordingly.

MADV_ACCESS_MANY
Tell the kernel that many processes and/or LWPs will access the
specified address range randomly across the machine, so the
kernel should try to allocate the memory and other resources
for this range accordingly.

MADV_ACCESS_DEFAULT
Reset the kernel's expectation for how the specified range will
be accessed to the default.

The madvise() function should be used by applications with specific
knowledge of their access patterns over a memory object, such as a
mapped file, to increase system performance.

RETURN VALUES

Upon successful completion, madvise() returns 0; otherwise, it returns
-1 and sets errno to indicate the error.

ERRORS

EAGAIN Some or all mappings in the address range [addr,
addr + len) are locked for I/O.

EBUSY Some or all of the addresses in the range [addr,
addr + len) are locked and MS_SYNC with the
MS_INVALIDATE option is specified.

EFAULT Some or all of the addresses in the specified range
could not be read into memory from the underlying
object when performing MADV_WILLNEED. The madvise()
function could return prior to this condition being
detected, in which case errno will not be set to
EFAULT.

EINVAL The addr argument is not a multiple of the page size
as returned by sysconf(3C), the length of the
specified address range is equal to 0, or the advice
argument was invalid.

EIO An I/O error occurred while reading from or writing
to the file system.

ENOMEM Addresses in the range [addr, addr + len) are
outside the valid range for the address space of a
process, or specify one or more pages that are not
mapped.

ESTALE Stale NFS file handle.

INTERFACE STABILITY