madvise(3C)
NAME
madvise - provide advice to VM system
SYNOPSIS
#include <sys/types.h>
#include <sys/mman.h>
int madvise(caddr_t 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 map-
ping range.
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 */
MADV_NORMAL
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
Tells 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
Tells 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. This is used in the cat(1) and
cp(1) utilities.
MADV_WILLNEED
Tells 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
Tells the kernel that the specified address range is
no longer needed, so the system starts to free the
resources associated with the address range.
MADV_FREE
Tells 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 speci-
fied address range. In this instance, the next time a
page in the address range is referenced, it will con-
tail 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 under-
lying file objects.
MADV_ACCESS_LWP
Tells the kernel that the next LWP to touch the speci-
fied 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
Tells 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
Resets 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 perfor-
mance.
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.
EINVAL
The addr argument is not a multiple of the page size
as returned by sysconf(3C), the length of the speci-
fied address range is equal to 0, or the advice argu-
ment 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.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Stable |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
cat(1), cp(1), meminfo(2), mmap(2), sysconf(3C), attri-
butes(5)
Man(1) output converted with
man2html