[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

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 X/Open UNIX95 Specification 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.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]