This section includes the following subroutine references:
“The mmap() subroutine” on page 461
“The mprotect() subroutine” on page 467
“The msync() subroutine” on page 469
“The munmap() subroutine” on page 471
Maps a file-system object into virtual memory.
Standard C library (libc.a)
#include <sys/types.h> #include <sys/mman.h> void *mmap(addr, len, prot, flags, filedes, offset) void * addr; size_t len; int prot, flags, filedes; off_t offset;
The mmap() subroutine creates a new mapped file or anonymous memory region by establishing a mapping between a process-address space and a file-system object. Care needs to be taken when using the mmap() subroutine if the program attempts to map itself. If the page containing executing instructions is currently referenced as data through an mmap mapping, the program will hang. Use the -H4096 binder option, and that will put the executable text on page boundaries. Then reset the file that contains the executable material, and view via an mmap mapping.
A region created by the mmap() subroutine cannot be used as the buffer for read or write operations that involve a device. Similarly, an mmap region cannot be used as the buffer for operations that require either a pin or xmattach operation on the buffer.
Modifications to a file-system object are seen consistently, whether accessed from a mapped file region or from the read or write subroutine.
Child processes inherit all mapped regions from the parent process when the fork subroutine is called. The child process also inherits the same sharing and protection attributes for these mapped regions. A successful call to any exec subroutine will unmap all mapped regions created with the mmap() subroutine.
The mmap64() subroutine is identical to the mmap subroutine() except that the starting offset for the file mapping is specified as a 64-bit value. This permits file mappings which start beyond OFF_MAX.
In the large file enabled programming environment, mmap() is redefined to be mmap64().
If the application has requested SPEC1170 compliant behavior, then the st_atime field of the mapped file is marked for update upon successful completion of the mmap() call.
If the application has requested SPEC1170 compliant behavior, then the st_ctime and st_mtime fields of a file that is mapped with MAP_SHARED and PROT_WRITE are marked for update at the next call to msync() subroutine or munmap() subroutine if the file has been modified.
Note
A file-system object should not be simultaneously mapped using both the mmap() and shmat() subroutines. Unexpected results may occur when references are made beyond the end of the object.
addr | Specifies the starting address of the memory region to be mapped. When the MAP_FIXED flag is specified, this address must be a multiple of the page size returned by the sysconf() subroutine using the _SC_PAGE_SIZE value. A region is never placed at address zero, or at an address where it would overlap an existing region. | |
len | Specifies the length, in bytes, of the memory region to be mapped. The system performs mapping operations over whole page only. If the len parameter is not a multiple of the page size, the system will include, in any mapping operation, the address range between the end of the region and the end of the page containing the end of the region. | |
prot | Specifies the access permission for the mapped region. The /usr/include/sys/mman.h file defines the following access options: | |
PROT_READ | Region can be read. | |
PROT_WRITE | Region can be written. | |
PROT_EXEC | Region can be executed. | |
PROT_NONE | Region cannot be accessed. | |
The prot parameter can be the PROT_NONE flag, or any combination of the other values logically ORed together. If the PROT_NONE flag is not specified, access permissions may be granted to the region in addition to those explicitly requested. However, write access will not be granted unless the PROT_WRITE flag is specified. |
Note
The operating system generates a SIGSEGV signal if a program attempts an access that exceeds the access permission given to a memory region. For example, if the PROT_WRITE flag is not specified and a program attempts a write access, a SIGSEGV signal results.
If the region is a mapped file that was mapped with the MAP_SHARED flag, the mmap() subroutine grants read or execute access permission only if the file descriptor used to map the file was opened for reading. It grants write access permission only if the file descriptor was opened for writing. If the region is a mapped file that was mapped with the MAP_PRIVATE flag, the mmap() subroutine grants read, write, or execute access permission only if the file descriptor used to map the file was opened for reading. If the region is an anonymous memory region, the mmap subroutine grants all requested access permissions. | |
filedes | Specifies the file descriptor of the file-system object to be mapped. If the MAP_ANONYMOUS flag is set, the filedes parameter must be -1. After the successful completion of the mmap() subroutine, the file specified by the filedes parameter may be closed without executing the mapped region or the contents of the mapped file. Each mapped region creates a file reference, similar to an open file descriptor, which prevents the file data from been deallocated. |
Note
The mmap() subroutine supports the mapping of regular files only. An mmap() call that specifies a file descriptor for a special file fails, returning the ENODEV error. An example of a file descriptor for a special file is one that might be used for mapping either I/O or device memory.
offset | Specifies the file byte offset at which the mapping starts. This offset must be a multiple of the page size returned by the sysconf() routine using the _SC_PAGE_SIZE value. |
flags | Specify attributes of the mapped region. Values for the flags parameter are constructed by a bitwise-inclusive ORing of values listed in Table C-4 on page 465, which lists symbolic names defined in the /usr/include/sys/mman.h file. |
Value | Description |
---|---|
MAP_FILE | Specifies the creation of a new mapped file region by mapping the file associated with the filedes file descriptor. The mapped region can extend beyond the end of the file, both at the time when the mmap() subroutine is called and while the mapping persists. This situation could occur if a file with no contents was created just before the call to the mmap() subroutine, or if a file was later truncated. However, references to whole pages following the end of the file result in the delivery of a SIGBUS signal. Only one of the MAP_FILE and MAP_ANONYMOUS flags must be specified with the mmap() subroutine. |
MAP_ANONYMOUS | Specifies the creation of a new, anonymous memory region that is initialized to all zeros. This memory region can be shared only with the descendants of the current process. When using this flag, the filedes parameter must be -1. Only one of the MAP_FILE and MAP_ANONYMOUS flags must be specified with the mmap() subroutine. |
MAP_VARIABLE | Specifies that the system select an address for the new memory region if the new memory region cannot be mapped at the address specified by the addr parameter, or if the addr parameter is NULL. Only one of the MAP_VARIABLE and MAP_FIXED flags must be specified with the mmap() subroutine. |
MAP_FIXED | Specifies that the mapped region be placed exactly at the address specified by the addr parameter. If the application has requested SPEC1170 complaint behavior and the mmap() request is successful, the mapping replaces any previous mappings for the process’s pages in the specified range. If the application has not requested SEPC170 compliant behavior and a previous mapping exists in the range, then the request fails. Only one of the MAP_VARIABLE and MAP_FIXED flags must be specified with the mmap() subroutine. |
MAP_SHARED | When the MAP_SHARED flag is set, modifications to the mapped memory region will be visible to other processes that have mapped the same region using this flag. If the region is a mapped file region, modifications to the region will be written to the file. You can specify only one of the MAP_SHARED or MAP_PRIVATE flags with the mmap() subroutine. MAP_PRIVATE is the default setting when neither flag is specified unless you request SPEC1170compliant behavior. In this case, you must choose either MAP_SHARED or MAP_PRIVATE. |
MAP_PRIVATE | When the MAP_PRIVATE flag is set, modifications to the mapped region by the calling process are not visible to other processes that have mapped the same region. If the region is a mapped file region, modifications to the region are not written to the file.
If this flag is specified, the initial write reference to an object page creates a private copy of that page and redirects the mapping to the copy. Until then, modifications to the page by processes that have mapped the same region with the MAP_SHARED flag are visible. You can specify only one of the MAP_SHARED or MAP_PRIVATE flags with the mmap() subroutine. MAP_PRIVATE is the default setting when neither flag is specified unless you request SPEC1170compliant behavior. In this case, you must choose either MAP_SHARED or MAP_PRIVATE. |
If successful, the mmap() subroutine returns the address at which the mapping was placed. Otherwise, it returns -1 and sets the errno global variable to indicate the error.
Under the following conditions, the mmap subroutine fails and sets the errno global variable to:
EACCES | The file referred to by the fildes parameter is not open for read access, or the file is not open for write access and the PROT_WRITE flag was specified for a MAP_SHARED mapping operation, or the file to be mapped has enforced locking enabled and the file is currently locked. |
EBADF | The fildes parameter is not a valid file descriptor, or the MAP_ANONYMOUS flag was set and the fildes parameter is not -1. |
EFBIG | The mapping requested extends beyond the maximum file size associated with fildes. |
EINVAL | The flags or prot parameter is invalid, or the addr parameter or off parameter is not a multiple of the page size returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter. |
EINVAL | The application has requested SPEC1170 compliant behavior and the value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set). |
EMFILE | The application has requested SPEC1170 compliant behavior and the number of mapped regions would exceed an implementation-dependent limit (per process or per system). |
ENODEV | The fildes parameter refers to an object that cannot be mapped, such as a terminal. |
ENOMEM | There is not enough address space to map len bytes or the application has not requested Single UNIX Specification Version 2 compliant behavior, and the MAP_FIXED flag was set and part of the address-space range (addr, addr+len) is already allocated. |
ENXIO | The addresses specified by the range (off, off+len) are invalid for the fildes parameter. |
EOVERFLOW | The mapping requested extends beyond the offset maximum for the file description associated with fildes. |
Modifies access protections for memory mapping.
Standard C library (libc.a)
#include <sys/types.h> #include <sys/mman.h> int mprotect ( addr, len, prot) void *addr; size_t len; int prot;
The mprotect() subroutine modifies the access protection of a mapped file region or anonymous memory region created by the mmap() subroutine. The behavior of this function is unspecified if the mapping was not established by a call to the mmap() subroutine.
addr | Specifies the address of the region to be modified. 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 modified. 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 will be rounded off to the next multiple of the page size. | |
prot | Specifies the new access permissions for the mapped region. Legitimate values for the prot parameter are the same as those permitted for the mmap (mmap or mmap64()) subroutine, as follows: | |
PROT_READ | Region can be read. | |
PROT_WRITE | Region can be written. | |
PROT_EXEC | Region can be executed. | |
PROT_NONE | Region cannot be accessed. |
When successful, the mprotect() subroutine returns 0. Otherwise, it returns -1 and sets the errno global variable to indicate the error.
Note
The return value for mprotect() is 0 if it fails, because the region given was not created by mmap() unless XPG 1170 behavior is requested by setting the environment variable XPG_SUS_ENV to ON.
Attention
If the mprotect() subroutine is unsuccessful because of a condition other than that specified by the EINVAL error code, the access protection for some pages in the (addr, addr + len) range may have been changed.
If the mprotect() subroutine is unsuccessful, the errno global variable may be set to one of the following values:
EACCES | The prot parameter specifies a protection that conflicts with the access permission set for the underlying file. |
EINVAL | The prot parameter is not valid, or the addr parameter is not a multiple of the page size as returned by the sysconf() subroutine using the_SC_PAGE_SIZE value for the Name parameter. |
ENOMEM | The application has requested Single UNIX Specification Version 2 compliant behavior, and addresses in the range are invalid for the address space of the process or specify one or more pages which are not mapped. |
Synchronizes a mapped file.
Standard C library (libc.a).
#include <sys/types.h> #include <sys/mman.h> int msync ( addr, len, flags) void *addr; size_t len; int flags;
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.
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 symbolic constants listed in Table C-5 that determine the way caching operations are performed. |
Value | Description |
---|---|
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. |
When successful, the msync() subroutine returns 0. Otherwise, it returns -1 and sets the errno global variable to indicate the error.
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. |
Unmaps a mapped region.
Standard C library (libc.a)
#include <sys/types.h> #include <sys/mman.h> int munmap ( addr, len) void *addr; size_t len;
The munmap() subroutine unmaps a mapped file region or anonymous memory region. The munmap() subroutine unmaps regions created from calls to the mmap() subroutine only.
If an address lies in a region that is unmapped by the munmap subroutine and that region is not subsequently mapped again, any reference to that address will result in the delivery of a SIGSEGV signal to the process.
addr | Specifies the address of the region to be unmapped. 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 unmapped. 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. |
When successful, the munmap() subroutine returns 0. Otherwise, it returns -1 and sets the errno global variable to indicate the error.
If the munmap() subroutine is unsuccessful, the errno global variable is set to the following value:
EINVAL | The addr parameter is not a multiple of the page size, as returned by the sysconf() subroutine using the _SC_PAGE_SIZE value for the Name parameter. |
EINVAL | The application has requested Single UNIX Specification Version 2 compliant behavior and the len argument is 0. |