huschi.net

MSYNC(3P)                  POSIX Programmer's Manual                 MSYNC(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
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 shall write all modified data to permanent storage
       locations,  if  any,  in  those  whole pages containing any part of the
       address space of the process starting at address  addr  and  continuing
       for  len  bytes.  If  no such storage exists, msync() need not have any
       effect. If requested, the msync() function shall then invalidate cached
       copies of data.
       The  implementation  shall  require that addr be a multiple of the page
       size as returned by sysconf().
       For mappings to files, the msync() function shall ensure that all write
       operations are completed as defined for synchronized I/O data integrity
       completion. It is unspecified whether the  implementation  also  writes
       out  other  file  attributes.   When  the msync() function is called on
       MAP_PRIVATE mappings, any modified data shall not  be  written  to  the
       underlying  object  and shall not cause such data to be made visible to
       other processes.  It is unspecified whether data  in  MAP_PRIVATE  map-
       pings  has any permanent storage locations.  The effect of msync() on a
       shared memory object or a typed  memory  object  is  unspecified.   The
       behavior  of this function is unspecified if the mapping was not estab-
       lished by a call to mmap().
       The flags argument is constructed from the bitwise-inclusive OR of  one
       or more of the following flags defined in the <sys/mman.h> header:
                   Symbolic Constant  Description
                   MS_ASYNC           Perform asynchronous writes.
                   MS_SYNC            Perform synchronous writes.
                   MS_INVALIDATE      Invalidate cached data.
       When  MS_ASYNC  is specified, msync() shall return immediately once all
       the write operations  are  initiated  or  queued  for  servicing;  when
       MS_SYNC  is  specified, msync() shall not return until all write opera-
       tions are completed as defined for synchronized I/O data integrity com-
       pletion. Either MS_ASYNC or MS_SYNC is specified, but not both.
       When  MS_INVALIDATE  is  specified, msync() shall invalidate all cached
       copies of mapped data that are inconsistent with the permanent  storage
       locations  such  that  subsequent references shall obtain data that was
       consistent with the permanent storage locations  sometime  between  the
       call to msync() and the first subsequent memory reference to the data.
       If msync() causes any write to a file, the file's st_ctime and st_mtime
       fields shall be marked for update.
RETURN VALUE
       Upon successful completion, msync() shall return 0; otherwise, it shall
       return -1 and set errno to indicate the error.
ERRORS
       The msync() function shall fail if:
       EBUSY  Some  or  all of the addresses in the range starting at addr and
              continuing for len bytes are locked, and MS_INVALIDATE is speci-
              fied.
       EINVAL The value of flags is invalid.
       EINVAL The value of addr is not a multiple of the page size {PAGESIZE}.
       ENOMEM The  addresses  in the range starting at addr and continuing for
              len bytes are outside the range allowed for the address space of
              a process or specify one or more pages that are not mapped.

       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       The  msync()  function  is  only  supported  if the Memory Mapped Files
       option and the Synchronized Input and Output option are supported,  and
       thus need not be available on all implementations.
       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. There-
       fore, there are no guarantees that msync() is  the  only  control  over
       when pages are or are not written to disk.
RATIONALE
       The  msync()  function writes out data in a mapped region to the perma-
       nent storage for the underlying object. The  call  to  msync()  ensures
       data integrity of the file.
       After  the  data  is written out, any cached data may be invalidated if
       the MS_INVALIDATE flag was specified. This is useful on systems that do
       not support read/write consistency.
FUTURE DIRECTIONS
       None.
SEE ALSO
       mmap(), 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 .

IEEE/The Open Group                  2003                            MSYNC(3P)