NAME

       posix_madvise - memory advisory information and alignment control (ADVANCED REALTIME)

SYNOPSIS

       #include <sys/mman.h>

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

DESCRIPTION

       The  posix_madvise()  function need only be supported if either the Memory Mapped Files or
       the Shared Memory Objects options are supported.

       The posix_madvise() function shall advise the implementation on the expected  behavior  of
       the  application  with  respect  to  the  data in the memory starting at address addr, and
       continuing for len bytes. The implementation may use this information to optimize handling
       of  the specified data. The posix_madvise() function shall have no effect on the semantics
       of access to memory in the specified range, although it  may  affect  the  performance  of
       access.

       The  implementation  may  require  that  addr be a multiple of the page size, which is the
       value returned by sysconf() when the name value _SC_PAGESIZE is used.

       The advice to be applied to the memory range is specified by the advice parameter and  may
       be one of the following values:

       POSIX_MADV_NORMAL

              Specifies  that  the application has no advice to give on its behavior with respect
              to the specified range. It is the default characteristic if no advice is given  for
              a range of memory.

       POSIX_MADV_SEQUENTIAL

              Specifies  that  the application expects to access the specified range sequentially
              from lower addresses to higher addresses.

       POSIX_MADV_RANDOM

              Specifies that the application expects to access the specified range  in  a  random
              order.

       POSIX_MADV_WILLNEED

              Specifies  that  the  application expects to access the specified range in the near
              future.

       POSIX_MADV_DONTNEED

              Specifies that the application expects that it will not access the specified  range
              in the near future.

       These values are defined in the <sys/mman.h> header.

RETURN VALUE

       Upon  successful completion, posix_madvise() shall return zero; otherwise, an error number
       shall be returned to indicate the error.

ERRORS

       The posix_madvise() function shall fail if:

       EINVAL The value of advice is invalid.

       ENOMEM Addresses in the range starting at addr and continuing for len bytes are partly  or
              completely outside the range allowed for the address space of the calling process.

       The posix_madvise() function may fail if:

       EINVAL The  value  of  addr  is not a multiple of the value returned by sysconf() when the
              name value _SC_PAGESIZE is used.

       EINVAL The value of len is zero.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The posix_madvise() function is part of the Advisory Information option and  need  not  be
       provided on all implementations.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       mmap()    ,   posix_fadvise()   ,   sysconf()   ,   the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, <sys/mman.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .