madvise(2)                                                       madvise(2)




 NAME    [Toc]    [Back]
      madvise() - advise the system of a process's expected paging behavior

 SYNOPSIS    [Toc]    [Back]
      #include <sys/mman.h>

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

 DESCRIPTION    [Toc]    [Back]
      The madvise system call permits a process to advise the system about
      its expected future behavior in referencing a mapped file, an
      anonymous memory region, or a shared memory region.  Certain
      implementations can use this information to optimize the use of
      resources.

      addr and len specify the address and length in bytes of the region to
      which the advice refers.  For MADV_DONTNEED, the address and length
      must be contained within a successful call to mmap() (see mmap(2)) or
      a successful call to shmat() (see shmat(2)); otherwise, madvise()
      fails with an [EINVAL] error.

      The behav argument is one the following flags defined in the header
      <sys/mman.h>:

           MADV_NORMAL       Removes any previous advice and sets the
                             default behavior.  By default, the kernel
                             tracks access patterns on data objects and
                             performs I/Os based on process trends (that is,
                             sequential versus random).  Sequential trends
                             cause larger "read-ahead" I/Os, while random
                             accesses reduce the amount of I/O to avoid
                             unnecessary I/O.

           MADV_RANDOM       Informs the kernel that any objects mapped in
                             this range will be accessed in a random matter.
                             The kernel will read only the minimal amount of
                             data to satisfy the user fault.

           MADV_SEQUENTIAL   Informs the kernel that any objects mapped in
                             this range will be accessed in a sequential
                             matter.  The kernel will perform the maximum
                             read-ahead for every fault.  The kernel does
                             not pay attention to access patterns and
                             trends, but instead assumes sequentiality for
                             every access on the object.

           MADV_DONTNEED     Informs the kernel that the specified range is
                             no longer needed by the process.  This allows



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 madvise(2)                                                       madvise(2)




                             the kernel to release the physical pages
                             associated with an address range back to the
                             system for use by other processes.

                             MADV_DONTNEED is restricted to object ranges
                             created with calls to mmap() and shmat().
                             Attempting to use MADV_DONTNEED on an object
                             that was not created using a call to mmap() or
                             shmat() will result in [EINVAL] being returned
                             to the caller.

           MADV_WILLNEED     Will need these pages.

           MADV_SPACEAVAIL   Ensure that resources are reserved.

 WARNINGS    [Toc]    [Back]
      The current implementation of madvise() defines MADV_SPACEAVAIL and
      MADV_WILLNEED as null operations.

 RETURN VALUE    [Toc]    [Back]
      madvise() returns the following values:

            0   Successful completion.
           -1   Failure.  errno is set to indicate the error.

 ERRORS    [Toc]    [Back]
      If madvise() fails, errno is set to one of the following values.

           [EFAULT]       The range specified by (addr, addr+len) is invalid
                          for a process's address space, or permission was
                          incorrect on the object for the behav specified.

           [EINVAL]       behav contains an invalid value, or addr is not a
                          multiple of the page size as returned by the
                          system call sysconf(_SC_PAGE_SIZE).

           [EINVAL]       The address range specified by addr and len was
                          not created by a successful call to mmap() or
                          shmat().

 AUTHOR    [Toc]    [Back]
      madvise() was developed by HP and OSF.

 SEE ALSO    [Toc]    [Back]
      mmap(2), sysconf(2).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      madvise(): AES, SVID3


 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003