madvise(3C)




NAME

     madvise - provide advice to VM system


SYNOPSIS

     #include <sys/types.h>
     #include <sys/mman.h>

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


DESCRIPTION

     The madvise() function 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 manipulating and
     maintaining the resources associated with the specified map-
     ping range.

     Values for advice are defined in <sys/mman.h> 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 */
     #define MADV_FREE             0x5   /* Contents can be freed */
     #define MADV_ACCESS_DEFAULT   0x6   /* default access */
     #define MADV_ACCESS_LWP       0x7   /* next LWP to access heavily */
     #define MADV_ACCESS_MANY      0x8   /* many processes to access heavily */

     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
           mappings when needed. This is a likely occurrence, but
           adversely  affects  system performance only 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 on any single particular access. If
           MADV_NORMAL is in effect when an address of  a  mapped
           file  is accessed, the system tries to read in as much
           data from the file as reasonable, in  anticipation  of
           other accesses within a certain locality.

     MADV_SEQUENTIAL
           Tells the system that  addresses  in  this  range  are
           likely  to  be  accessed only once, so the system will
           free  the  resources  mapping  the  address  range  as
           quickly  as  possible.  This is used in the cat(1) and
           cp(1) utilities.

     MADV_WILLNEED
           Tells the system  that  a  certain  address  range  is
           definitely needed so the kernel will start reading the
           specified range into memory. This can benefit programs
           wanting  to  minimize the time needed to access memory
           the first time, as 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 starts to free the
           resources associated with the address range.

     MADV_FREE
           Tells  the  kernel  that  contents  in  the  specified
           address  range  are  no longer important and the range
           will be overwritten. When there is demand for  memory,
           the  system will free pages associated with the speci-
           fied address range. In this instance, the next time  a
           page  in the address range is referenced, it will con-
           tail all zeroes.  Otherwise, it will contain the  data
           that was there prior to the MADV_FREE call. References
           made to the address range will  not  make  the  system
           read from backing store (swap space) until the page is
           modified again.

           This value cannot be used on mappings that have under-
           lying file objects.

     MADV_ACCESS_LWP
           Tells the kernel that the next LWP to touch the speci-
           fied address range will access it most heavily, so the
           kernel should try to allocate  the  memory  and  other
           resources for this range and the LWP accordingly.

     MADV_ACCESS_MANY
           Tells the kernel that many processes and/or LWPs  will
           access the specified address range randomly across the
           machine, so the kernel  should  try  to  allocate  the
           memory and other resources for this range accordingly.

     MADV_ACCESS_DEFAULT
           Resets the kernel's expectation for how the  specified
           range will be accessed to the default.

     The madvise() function should be used by  applications  with
     specific  knowledge  of  their access patterns over a memory
     object, such as a mapped file, to  increase  system  perfor-
     mance.


RETURN VALUES

     Upon successful completion, madvise() returns 0;  otherwise,
     it returns -1 and sets errno to indicate the error.


ERRORS

     EAGAIN
           Some or all mappings  in the   address   range  [addr,
           addr  +  len) are locked for I/O.

     EBUSY Some or all of the addresses in the range [addr,  addr
           +  len)  are locked and MS_SYNC with the MS_INVALIDATE
           option is specified.

     EFAULT
           Some or all of the addresses in  the  specified  range
           could  not  be  read  into  memory from the underlying
           object when performing MADV_WILLNEED.

     EINVAL
           The addr argument is not a multiple of the  page  size
           as  returned  by sysconf(3C), the length of the speci-
           fied address range is equal to 0, or the advice  argu-
           ment 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.

     ESTALE
           Stale NFS file handle.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Stable                      |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|


SEE ALSO

     cat(1),  cp(1),  meminfo(2),  mmap(2),  sysconf(3C),  attri-
     butes(5)


Man(1) output converted with man2html