MADVISE(E)          Linux Programmer's Manual          MADVISE(E)



NAME
       madvise - give advice about use of memory

SYNOPSIS
       #include <sys/mman.h>

       int madvise(void *start, size_t length, int advice);

DESCRIPTION
       The  madvise  system  call advises the kernel about how to
       handle paging input/output in the address range  beginning
       at  address start and with size length bytes. It allows an
       application to tell the kernel how it expects to use  some
       mapped  or  shared  memory  areas,  so that the kernel can
       choose  appropriate  read-ahead  and  caching  techniques.
       This call does not influence the semantics of the applica-
       tion, but may influence its  performance.  The  kernel  is
       free to ignore the advice.

       The  advice is indicated in the advice parameter which can
       be

       MADV_NORMAL
              No special treatment. This is the default.

       MADV_RANDOM
              Expect page references in  random  order.   (Hence,
              read ahead may be less useful than normally.)

       MADV_SEQUENTIAL
              Expect   page   references   in  sequential  order.
              (Hence, pages in the given  range  can  be  aggres-
              sively read ahead, and may be freed soon after they
              are accessed.)

       MADV_WILLNEED
              Expect access in the near future.  (Hence, it might
              be a good idea to read some pages ahead.)

       MADV_DONTNEED
              Do  not expect access in the near future.  (For the
              time being, the application is  finished  with  the
              given range, so the kernel can free resources asso-
              ciated with it.)

RETURN VALUE
       On success madvise returns zero. On error, it  returns  -1
       and errno is set appropiately.

ERRORS
       EINVAL the  value  len  is  negative,  start  is not page-
              aligned, advice is not a valid value, or the appli-
              cation  is  attempting  to release locked or shared
              pages (with MADV_DONTNEED).

       ENOMEM addresses in the specified range are not  currently
              mapped,  or  are  outside  the address space of the
              process.

       ENOMEM (for MADV_WILLNEED) Not enough memory -  paging  in
              failed.

       EIO    (for  MADV_WILLNEED)  Paging  in  this  area  would
              exceed the process's maximum resident set size.

       EBADF  the map exists, but the area  maps  something  that
              isn't a file.

       EAGAIN a kernel resource was temporarily unavailable.

LINUX NOTES
       The current Linux implementation (2.4.0) views this system
       call more as a command than as advice and hence may return
       an  error  when  it  cannot do what it usually would do in
       response to  this  advice.  (See  the  ERRORS  description
       above.)  This is nonstandard behaviour.

       The  Linux  implementation requires that the address start
       be page-aligned, and allows length to be  zero.  If  there
       are some parts of the specified address range that are not
       mapped, the Linux version  of  madvise  ignores  them  and
       applies  the call to the rest (but returns ENOMEM from the
       system call, as it should).

HISTORY
       The madvise function first appeared in 4.4BSD.

CONFORMING TO
       POSIX.1b   (POSIX.4).    POSIX    1003.1-2001    describes
       posix_madvise with constants POSIX_MADV_NORMAL, etc., with
       a behaviour close to that described here. There is a simi-
       lar posix_fadvise for file access.

SEE ALSO
       getrlimit(t),  mmap(p), mincore(e), mprotect(t), msync(c),
       munmap(p)



Linux 2.4.5                 2001-06-10                 MADVISE(E)