munmap()--Remove Memory Mapping
Syntax
#include <sys/types.h> #include <sys/mman.h> int munmap ( void *addr, size_t len );Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Yes
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 condition | Additional information |
---|---|
[EINVAL] |
For example, for munmap() this may mean that the address range from addr and continuing for a length of len is outside the valid range allowed for a process. This error may also indicate that the value for the addr parameter is not a multiple of the page size. A value of 0 for parameter len also will result in this error number. |
[ENOTAVAIL] | |
[EUNKNOWN] |
Error Messages
The following messages may be sent from this function.
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPFA0D4 E | File system error occurred. Error number &1. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- 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.
- 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
The following example creates a file, produces a memory mapping of the file using mmap(), and then removes the mapping using the munmap() function.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#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); } }
API introduced: V5R1