unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

MADVISE(3)                 Library Functions Manual                 MADVISE(3)



NAME
       madvise - provide advice to VM system

SYNOPSIS
       #include <&lt;sys/types.h>&gt;
       #include <&lt;sys/mman.h>&gt;

       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 manipu-
       lating and maintaining the resources associated with the specified map-
       ping range.

       Values for advice are defined in <&lt;sys/mman.h>&gt; 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 map-
              pings 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 antici-
              pation 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
       mctl(2), mmap(2)



                                21 January 1990                     MADVISE(3)