msync()--Synchronize Modified Data with Mapped File

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

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

The msync() function can be used to write modified data from a shared mapping (created using the mmap() function) to non-volatile storage or invalidate privately mapped pages. The data located through mapping address addr for a length of len are either written to disk, or invalidated, depending on the value of flags and the private or shared nature of the mapping.

Parameters

addr

The starting address of the memory region to be synchronized to permanent storage. The specified address must be a multiple of the page size.

len

The number of bytes affected. The length must not be zero. If the length is not a multiple of the page size the system will round this value to the next page boundary.

flags

The desired synchronization.

The following table shows the symbolic constants allowed for the flags parameter.

Symbolic Constant	Decimal Value	Description
MS_ASYNC	1	Perform asynchronous writes.
MS_SYNC	2	Perform synchronous writes.
MS_INVALIDATE	4	Invalidate privately cached data

The MS_SYNC and MS_ASYNC options are mutually exclusive. The MS_SYNC and MS_ASYNC options are ignored if the memory map was created with the MAP_PRIVATE option.

The MS_INVALIDATE option is used to discard changes made to a memory map created with the MAP_PRIVATE option. The private memory map is synchronized with the current data in the file. Any reference subsequent to the execution of the msync() function that invalidates a page will result in a reference to the current value of the file. The first modification of a page after the privately mapped page is invalidated results in the creation of a fresh private copy of that page. Subsequent modifications of this page prior to the next execution of an msync that invalidates the page will result in modifications to the same private copy of the page.

The MS_INVALIDATE value is ignored if the memory map was created with the MAP_SHARED option.

Authorities

No authorization is required.

Return Value

Upon successful completion, the msync() function returns 0.

Error Conditions

When the msync() function fails, it returns -1 and sets errno as follows.

Error Messages

The following messages may be sent from this function.

Usage Notes

1. The msync() function must be used to write changed pages of a shared mapping to disk. If a system crash occurs before the msync() function completes, some data may not be preserved.

   Process termination does not automatically write changed pages to disk. Some or all pages may be eventually written by the paging subsystem, but no guarantee is given. Therefore, if the data must be preserved the msync() function must be used to ensure changes made through a shared memory map are written to disk.

2. The address pointer that was returned by mmap() can only be used with the V4R4M0 or later versions of the following languages:
   • ILE COBOL
   • ILE RPG
   • ILE C if the TERASPACE parameter is used when compiling the program.
   
   
3. The application cannot write or store any data via the memory mapping which includes any tagged (16-byte) pointers because the pointer attribute will be lost. Some examples of tagged pointers include space pointers, system pointers, invocation pointers etc..

   If the DTAMDL(*LLP64) parameter is used when compiling an ILE C program, this limitation does not apply as the pointers will be 8 byte pointers, and their pointer attribute will be preserved.

Related Information

• open()--Open File
• open64()--Open File (Large File Enabled)
• mmap()--Memory Map a Stream File
• munmap()--Remove Memory Mapping
• mprotect()--Change Access Protection for Memory Mapping

Example

See Code disclaimer information for information pertaining to code examples.

The following example creates a file, creates a memory map, stores data into the file, and writes the data to disk using the msync() function.

#include <errno.h >
#include <fcntl.h >
#include <unistd.h >
#include <stdio.h >
#include <stdlib.h >
#include <string.h >
#include <sys/types.h >
#include <sys/mman.h >

main(void) {

  size_t bytesWritten =0;
  int fd;
  int PageSize;
  const char   textÝ = "This is a test";

 if ( (PageSize = sysconf(_SC_PAGE_SIZE)) < 0) {
    perror("sysconf() Error=");
    return -1;
 }

 fd = open("/tmp/mmsyncTest",
             (O_CREAT | O_TRUNC | O_RDWR),
             (S_IRWXU | S_IRWXG | S_IRWXO) );
  if ( fd < 0 ) {
    perror("open() error");
    return fd;
  }

  off_t lastoffset = lseek( fd, PageSize, SEEK_SET);
  bytesWritten = write(fd, " ", 1 );
  if (bytesWritten != 1 ) {
    perror("write error. ");
    return -1;
  }


      /* mmap the file. */
  void *address;
  int len;
   off_t my_offset = 0;
   len = PageSize;   /* Map one page */
   address =
        mmap(NULL, len, PROT_WRITE, MAP_SHARED, fd, my_offset);

   if ( address == MAP_FAILED ) {
       perror("mmap error. " );
       return -1;
     }
       /* Move some data into the file using memory map. */
     (void) strcpy( (char*) address, text);
       /* use msync to write changes to disk. */
     if ( msync( address, PageSize , MS_SYNC ) < 0 ) {
          perror("msync failed with error:");
          return -1;
      }
      else (void) printf("%s","msync completed successfully.");

    close(fd);
    unlink("/tmp/msyncTest");
}

Output:

This is a test.