NAME

msync - synchronise 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 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 then invalidates cached copies of data.

The implementation  will require that addr be a multiple of the page size as returned by sysconf().

For mappings to files, the msync() function ensures that all write operations are completed as defined for synchronised 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 will not be written to the underlying object and will not cause such data to be made visible to other processes. It is unspecified whether data in MAP_PRIVATE mappings has any permanent storage locations. The effect of msync() on shared memory objects is unspecified.

The flags argument is constructed from the bitwise inclusive OR of one or more of the following flags defined in the header <sys/mman.h>:

Symbolic Constant	Description
MS_ASYNC	Perform asynchronous writes.
MS_SYNC	Perform synchronous writes.
MS_INVALIDATE	Invalidate cached data.

When MS_ASYNC is specified, msync() returns immediately once all the write operations are initiated or queued for servicing; when MS_SYNC is specified, msync() will not return until all write operations are completed as defined for synchronised I/O data integrity completion. Either MS_ASYNC or MS_SYNC is specified, but not both.

When MS_INVALIDATE is specified, msync() invalidates all cached copies of mapped data that are inconsistent with the permanent storage locations such that subsequent references 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.

The behaviour of this function is unspecified if the mapping was not 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.

 RETURN VALUE

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 starting at addr and continuing for len bytes are locked, and MS_INVALIDATE is specified.

[EINVAL]

The value in 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.

 EXAMPLES

None.

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

The second form of [EINVAL] above is marked EX because it is defined as an optional error in the POSIX Realtime Extension.

 FUTURE DIRECTIONS

None.

 SEE ALSO

mmap(), sysconf(), <sys/mman.h>.