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, fildes, off)
void * addr;
int prot, flags, fildes;
Note: The mmap64 subroutine applies to AIX 4.2 and later releases.
Note: The mmap64 subroutine applies to AIX 4.2 and later releases.
Attention: 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.
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.
|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 for the Name parameter. 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 pages 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 permissions for the mapped region. The
sys/mman.h file defines the following access options:
The prot parameter can be the PROT_NONE flag, or any combination of the PROT_READ flag, PROT_WRITE flag, and PROT_EXEC flag 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.
|fildes||Specifies the file descriptor of the file-system object to be
mapped. If the MAP_ANONYMOUS flag is set, the
fildes parameter must be -1. After the successful completion
of the mmap subroutine, the file specified by the fildes
parameter may be closed without effecting 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 being
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.
|off||Specifies the file byte offset at which the mapping starts. This offset must be a multiple of the page size returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter.|
|flags||Specifies attributes of the mapped region. Values for the
flags parameter are constructed by a bitwise-inclusive ORing of
values from the following list of symbolic names defined in the
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
|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 excedd and 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 X/Open UNIX95 Specification 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.|
This subroutine is part of Base Operating System (BOS) Runtime.
The exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutine, fork (fork, f_fork, or vfork Subroutine) subroutine, munmap (munmap Subroutine) subroutine, read subroutine, shmat subroutine, sysconf subroutine, write subroutine.
The pin kernel service, xmattach kernel service.
List of Memory Manipulation Services, List of Memory Mapping Services, Understanding Memory Mapping in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.