Technical Reference: Base Operating System and Extensions, Volume 1

msync Subroutine

Purpose

Synchronizes a mapped file.

Library

Standard C Library (libc.a).

Syntax

#include <sys/types.h>
#include <sys/mman.h>

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

Description

The msync subroutine controls the caching operations of a mapped file region. Use the msync subroutine to transfer modified pages in the region to the underlying file storage device.

If the application has requested Single UNIX Specification, Version 2 compliant behavior then the st_ctime and st_mtime fields of the mapped file are marked for update upon successful completion of the msync subroutine call if the file has been modified.

Parameters

addr	Specifies the address of the region to be synchronized. Must be a multiple of the page size returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter.
len	Specifies the length, in bytes, of the region to be synchronized. If the len parameter is not a multiple of the page size returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter, the length of the region is rounded up to the next multiple of the page size.
flags	Specifies one or more of the following symbolic constants that determine the way caching operations are performed: MS_SYNC Specifies synchronous cache flush. The msync subroutine does not return until the system completes all I/O operations. This flag is invalid when the MAP_PRIVATE flag is used with the mmap subroutine. MAP_PRIVATE is the default privacy setting. When the MS_SYNC and MAP_PRIVATE flags both are used, the msync subroutine returns an errno value of EINVAL. MS_ASYNC Specifies an asynchronous cache flush. The msync subroutine returns after the system schedules all I/O operations. This flag is invalid when the MAP_PRIVATE flag is used with the mmap subroutine. MAP_PRIVATE is the default privacy setting. When the MS_SYNC and MAP_PRIVATE flags both are used, the msync subroutine returns an errno value of EINVAL. MS_INVALIDATE Specifies that the msync subroutine invalidates all cached copies of the pages. New copies of the pages must then be obtained from the file system the next time they are referenced.

Return Values

When successful, the msync subroutine returns 0. Otherwise, it returns -1 and sets the errno global variable to indicate the error.

Error Codes

If the msync subroutine is unsuccessful, the errno global variable is set to one of the following values:

EIO	An I/O error occurred while reading from or writing to the file system.
ENOMEM	The range specified by (addr, addr + len) is invalid for a process' address space, or the range specifies one or more unmapped pages.
EINVAL	The addr argument is not a multiple of the page size as returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter, or the flags parameter is invalid. The address of the region is within the process' inheritable address space.