msync()

Synchronize memory with physical storage

Synopsis:

#include <sys/mman.h>

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

Arguments:

addr
The beginning of the range of addresses that you want to synchronize.
len
The length of the range of addresses, in bytes.
flags
A bitwise inclusive OR of one or more of the following flags:

Note: You can specify at most one of MS_ASYNC and MS_SYNC, not both.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The msync() function writes 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. The msync() function is used with memory mapped files. If no such storage exists, msync() need not have any effect. If requested, the msync() function then invalidates cached copies of data.

For mappings to files, this function ensures that all write operations are completed as defined for synchronized I/O data integrity completion.


Note: Mappings to files aren't implemented on all filesystems.

When the msync() function is called on MAP_PRIVATE mappings, any modified data won't be written to the underlying object and won't cause such data to be made visible to other processes.

The behavior of msync() is unspecified if the mapping wasn't established by a call to mmap().

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

For POSIX support of memory-mapped files, the msync() function performs its intended operation of flushing (MS_SYNC or MS_ASYNC), invalidating (MS_INVALIDATE) the data cache or invalidating (MS_INVALIDATE_ICACHE) the instruction cache. This is regardless of the underlying object that is used for the mapping (for example, shared memory object, memory-mapped file, anonymous memory, etc). This POSIX behavior of syncing/invalidating to the underlying permanent locations only takes place with memory-mapped file.

Returns:

0
Success
-1
An error occurred (errno is set).

Errors:

EBUSY
Some or all of the addresses in the range starting at addr and continuing for len bytes are locked, and MS_INVALIDATE is specified.
EINVAL
Invalid flags value.
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 aren't mapped.

Classification:

POSIX 1003.1 MF SIO

Safety:
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes

Caveats:

MS_INVALIDATE_ICACHE is a QNX Neutrino extension.

MS_CACHE_ONLY flag ensures that the QNX extension behavior takes place, but not the POSIX standard behavior. This flag performs data cache operation in conjunction with MS_SYNC, MS_ASYNC, or MS_INVALIDATE.

See also:

mmap(), sysconf()