munmap()--Remove Memory Mapping

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

 int  munmap ( void *addr,
                size_t  len );    

The munmap() function removes addressability to a range of memory mapped pages of a process's address space. All pages starting with addr and continuing for a length of len bytes are removed.

The address range specified must begin on a page boundary. Portions of the specified address range which are not mapped, or were not established by the mmap() function, are not affected by the munmap() function.

If the mapping was created MAP_PRIVATE then any private altered pages are discarded and the system storage associated with the copies are returned to the system free space.

When the mapping is removed, the reference associated with the pages mapped over the file is removed. If the file has no references other than those due to memory mapping and the remaining memory mappings are removed by the munmap() function, then the file becomes unreferenced. If the file becomes unreferenced due to an munmap() function call and the file is no longer linked, then the file will be deleted.

Parameters

addr

The starting address of the memory region being removed.

The addr parameter must be a multiple of the page size. The value zero or NULL is not a valid starting address. The sysconf() function may be used to determine the system page size.

len

(Input) The length of the address range. All whole pages beginning with addr for a length of len are included in the address range.

Authorities

No authorization is required.

Return Value

Upon successful completion, the munmap() function returns 0. Upon failure, -1 is returned and errno is set to the appropriate error number.

Error Conditions

When the munmap() 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 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.
   
   
2. 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
• mprotect()--Change Access Protection for Memory Mapping
• msync()--Synchronize Modified Data with Mapped File

Example

See Code disclaimer information for information pertaining to code examples.

The following example creates a file, produces a memory mapping of the file using mmap(), and then removes the mapping using the munmap() function.

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

main() {
  char fn[]="creat.file";
  char  text[]="This is a test";
  int fd;
  int PageSize;

  if ((fd =
       open(fn, O_CREAT | O_RDWR | O_APPEND,S_IRWXU)  < 0)
    perror("open() error");
  else if (write(fd, text, strlen(text)) < 0;
       error("write() error=");
    else if ( (PageSize=sysconf(_SC_PAGESIZE)) < 0 )
         error("sysconf() Error=");
    else {
    off_t lastoffset = lseek( fd, PageSize-1, SEEK_SET);
    write(fd, " ", 1);   /* grow file to 1 page. */
      /* mmap the file. */
    void *address;
    int len;
     my_offset = 0;

     len = 4096;   /* Map one page */
     address =
         mmap(NULL, len, PROT_READ, MAP_SHARED, fd, my_offset)
     if ( address != MAP_FAILED ) {
       if ( munmap( address, len ) ) == -1) {
          error("munmap failed with error:");
       }
     }

    close(fd);
    unlink(fn);
  }
}