MADVISE(2) | System Calls Manual | MADVISE(2)

# NAME

`madvise`, `posix_madvise` — give advice about use of memory

# SYNOPSIS

`#include <sys/mman.h>`

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

int
`posix_madvise`(void *addr, size_t len, int behav);

# 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 has the same effect, but returns the error value instead of only setting errno.

The possible behaviors are:

`MADV_NORMAL`
  No further special treatment needed.
`MADV_RANDOM`
  Expect random page access patterns.
`MADV_SEQUENTIAL`
  Expect sequential page references.
`MADV_WILLNEED`
  The pages will be referenced soon.
`MADV_DONTNEED`
  The pages will not be referenced soon.
`MADV_SPACEAVAIL`
  Ensure that resources are reserved.
`MADV_FREE`
  The pages don't contain any useful data and can be recycled.

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

# RETURN VALUES

The `madvise`() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

If successful, the `posix_madvise`() function will return zero. Otherwise an error number will be returned to indicate the error.

# ERRORS

`madvise`() will fail if:

[`EINVAL`]
  The specified behav argument was invalid.
[`EINVAL`]
  The addr parameter was not page aligned or addr and size specify a region that would extend beyond the end of the address space.
[`EPERM`]
  The addr and len parameters specify a region which contains at least one page marked immutable.

# SEE ALSO

mimmutable(2), minherit(2), mprotect(2), msync(2), munmap(2)

# STANDARDS

The `posix_madvise`() system call conforms to IEEE Std 1003.1-2008 (“POSIX.1”).

The `EPERM` failure conditions described are an extension to this specification.

# HISTORY

The `madvise`() function first appeared in SunOS 4.0 and has been available since OpenBSD 2.7. The `posix_madvise`() function first appeared in OpenBSD 4.8.

# BUGS

The `MADV_WILLNEED` behavior is ignored. The `MADV_SPACEAVAIL` behavior is not implemented and will always fail.

January 21, 2024 | Debian