NAME [Toc] [Back]
msync - synchronize the memory of a mapped file with physical storage
SYNOPSIS [Toc] [Back]
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
+ 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
+ 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
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
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
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
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
[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
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
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 [ Back ]