madvise - provide advice to VM system

---

SYNOPSIS

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

int madvise(addr, len, advice)
caddr_t addr;
size_t len;
int advice;

DESCRIPTION

madvise() 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.

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 */

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 only adversely affects system performance 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 when doing any single particular access. Normally 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 only be accessed once, so the system will free the resources used to map the address range as quickly as possible. This is used in the cat.1v and cp.1 utilities.

MADV_WILLNEED

Tells the system that a certain address range is definitely needed, so the kernel will read the specified range into memory immediately. This might be beneficial to programs who want to minimize the time it takes to access memory the first time since 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 immediately frees the resources associated with the address range.

madvise() should be used by programs that have specific knowledge of their access patterns over a memory object (for example, a mapped file) and wish to increase system performance.

RETURN VALUES

madvise() returns:

0

on success.

-1

on failure and sets errno to indicate the error.

ERRORS

EINVAL

addr is not a multiple of the page size as returned by getpagesize.2

The length of the specified address range is less than or equal to 0.

advice 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.

SEE ALSO

Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97