msync(3C)

NAME

     msync - synchronize memory with physical storage

SYNOPSIS

     #include <sys/mman.h>

     int msync(void *addr, size_t len, int flags);

DESCRIPTION

     The  msync() function writes all modified  copies  of  pages
     over  the  range  [addr,  addr  +  len)  to  the  underlying
     hardware, or invalidates any copies so that  further  refer-
     ences to the pages will be obtained by the system from their
     permanent storage locations. The  permanent  storage  for  a
     modified  MAP_SHARED  mapping is the file the page is mapped
     to; the permanent storage for a modified MAP_PRIVATE mapping
     is its swap area.

     The flags argument is a bit pattern built from the following
     values:

     MS_ASYNC
           perform asynchronous writes

     MS_SYNC
           perform synchronous writes

     MS_INVALIDATE
           invalidate mappings

     If flags is MS_ASYNC or MS_SYNC, the  function  synchronizes
     the  file  contents  to  match  the  current contents of the
     memory region.

        o  All write references to the memory region  made  prior
           to  the call are visible by subsequent read operations
           on the file.

        o  All writes to the same portion of the  file  prior  to
           the  call may or may not be visible by read references
           to the memory region.

        o  Unmodified pages in the specified range are not  writ-
           ten to the underlying hardware.

     If flags is MS_ASYNC, the function  may  return  immediately
     once  all  write  operations  are  scheduled;  if  flags  is
     MS_SYNC, the function does not return until all write opera-
     tions are completed.

     If flags is MS_INVALIDATE,  the  function  synchronizes  the
     contents  of  the  memory  region  to match the current file
     contents.

        o  All writes to the mapped  portion  of  the  file  made
           prior  to  the  call  are  visible  by subsequent read
           references to the mapped memory region.

        o  All write references prior to the call,  by  any  pro-
           cess,  to memory regions mapped to the same portion of
           the file using MAP_SHARED, are visible by read  refer-
           ences to the region.

     If msync() causes any write to the  file,  then  the  file's
     st_ctime and st_mtime fields are marked for update.

RETURN VALUES

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

ERRORS

     The msync() function will fail if:

     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.

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

     EINVAL
           The addr argument is not a multiple of the  page  size
           as returned by sysconf(3C).

           The flags argument is not some combination of MS_ASYNC
           and MS_INVALIDATE.

     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.

     EPERM MS_INVALIDATE was specified and one  or  more  of  the
           pages is locked in memory.

USAGE

     The msync() function should be used by programs that require
     a  memory  object  to  be  in  a known state, for example in
     building transaction facilities.

     Normal system activity can cause  pages  to  be  written  to
     disk.   Therefore,  there  are no guarantees that msync() is
     the only control over when pages are or are not  written  to
     disk.

ATTRIBUTES

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

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

SEE ALSO

     memcntl(2),  mmap(2),  sysconf(3C),   attributes(5),   stan-
     dards(5)