msync(2)                                                           msync(2)




 NAME    [Toc]    [Back]
      msync - synchronize the memory of a mapped file with physical storage

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

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

 DESCRIPTION    [Toc]    [Back]
      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 references to the pages will be obtained by the
      system from their permanent storage locations.

      The flags argument is one of the following:

           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.

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

           +  It is unspecified whether writes to the same portion of the
              file prior to the call are visible by read references to the
              memory region.

           +  It is unspecified whether unmodified pages in the specified
              range are also written 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 operations are completed.

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

           +  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.

           +  It is unspecified whether write references prior to the call,
              by any process, to memory regions mapped to the same portion
              of the file using MAP_SHARED, are visible by read references
              to the region.




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






 msync(2)                                                           msync(2)




      addr and len specify the region to be synchronized.  If these are not
      the address and length of a region created by a previous successful
      call to mmap(), msync() returns an error.  The behavior of msync()
      upon a region created with the MAP_ANONYMOUS or MAP_PRIVATE flags is
      undefined.

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

    Performance Considerations    [Toc]    [Back]
      The following performance considerations only apply when using the
      MS_INVALIDATE option with msync().  These performance constraints do
      not apply when either MS_ASYNC or MS_SYNC are exclusively used with
      msync().

      Direct read/write references to portions of a mapped memory region
      currently undergoing an msync() operation (with MS_INVALIDATE
      specified), may be blocked until all scheduled write operations are
      completed.  This is especially true when performing an msync()
      operation across a relatively large address range that requires many
      individual write operations to be scheduled out to the underlying
      hardware.  HP-UX will schedule a separate write operation for each
      contiguous group of modified pages on disk.  As more write operations
      are queued out to the device, the overall suspension time of direct
      read/write references to the same portions of the memory region will
      generally increase.

      The suspension times of direct read/write references can be reduced by
      issuing msync() requests over smaller portions of the memory region,
      but issuing them more frequently than a corresponding larger
      synchronization request.  This will serve to more evenly distribute
      I/O activity across the mapped file, while reducing the number of
      write operations per msync().

 RETURN VALUE    [Toc]    [Back]
      Upon successful completion, msync() returns 0.  Otherwise, it returns
      -1 and sets errno to indicate the error.

 ERRORS    [Toc]    [Back]
      The msync() function will fail if:

           [EINVAL]          The addr argument is not a multiple of the page
                             size as returned by sysconf(_SC_PAGE_SIZE).

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

           [EIO]             An I/O error occurred while reading from or
                             writing to the file system.





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






 msync(2)                                                           msync(2)




           [ENOMEM]          Some or all the addresses in the range [addr,
                             addr+len] are invalid for the address space of
                             the process.  Or, pages that are not mapped are
                             specified.

 APPLICATION USAGE    [Toc]    [Back]
      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.

 AUTHOR    [Toc]    [Back]
      msync() was developed by HP, AT&T, and OSF.

 SEE ALSO    [Toc]    [Back]
      mmap(2), sysconf(2), <sys/mman.h>.

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

 CHANGE HISTORY    [Toc]    [Back]
      First released in Issue 4, Version 2.


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