mmap(), mmap64() -- map files or devices into memory

SYNOPSIS

#include <sys/mman.h>

void *mmap(void *addr, size_t len, int prot, int flags, int fildes, off_t off);

void *mmap64(void *addr, size_t len, int prot, int flags, int fildes, off64_t off);

The mmap() function establishes a mapping between the address space of the process at an address pa for len bytes to the memory object represented by the file descriptor fildes at offset off for len bytes. The value of pa is an address chosen by the system as a function of the parameter addr and the values of flags, further described below. A successful mmap() call returns pa as its result. The address range starting at pa and continuing for len bytes is legitimate for the possible (not necessarily current) address space of the process. The range of bytes starting at off and continuing for len bytes is legitimate for the possible (not necessarily current) offsets in the memory object represented by fildes.

If the size of the mapped file changes after the call to mmap() as a result of some other operation on the mapped file, the effect of references to portions of the mapped region that correspond to added or removed portions of the file is unspecified.

The mmap64() function is identical to the mmap() function except that it can be used to map memory from files that are larger than 2 gigabytes into the process memory. The mmap64() function is a part of the large file extensions.

The mmap() function is supported for regular files, the special file /dev/zero, and anonymous memory. mmap() on any another type of file returns an error with errno set to ENODEV.

The parameter prot determines whether read, write, execute, or some combination of accesses are permitted to the pages being mapped. The prot flag should be the bitwise inclusive OR of one or more of the following flags:

PROT_READ: Page can be read.
PROT_WRITE: Page can be written.
PROT_EXEC: Page can be executed.
PROT_NONE: Page can not be accessed.

The system does not permit a write to succeed where PROT_WRITE has not been set or permit any access where PROT_NONE alone has been set. The file descriptor fildes has been opened with read permission, regardless of the protection options specified. If PROT_WRITE is specified, the application must have opened the file descriptor fildes with write permission unless MAP_PRIVATE is specified in the flags parameter.

The parameter flags provides other information about the handling of the mapped data. The value of flags is the bitwise inclusive OR of these options:

MAP_SHARED: Modifications are shared between all processes mapping the same range of the same file, and changes to the memory region are reflected in the mapped file.
MAP_PRIVATE: Modifications are private to the process, and changes to the memory region are not reflected in the mapped file.
MAP_FIXED: Interpret addr exactly.
MAP_VARIABLE: Place memory mapped region at an system-computed address.
MAP_FILE: Map a regular file, or character special device file /dev/zero.
MAP_ANON: Map anonymous memory not associated with any specific file. The fildes parameter should be specified as -1 with this flag.

MAP_SHARED and MAP_PRIVATE describe the disposition of write references to the memory object. If MAP_SHARED is specified, write references change the underlying object. If MAP_PRIVATE is specified, modifications to the mapped data by the calling process s visible only to the calling process and does not change the underlying object. Modifications to the underlying object done after the MAP_PRIVATE mapping is established are not visible through the MAP_PRIVATE mapping. Either MAP_SHARED or MAP_PRIVATE can be specified, but not both. The mapping type is retained across fork().

MAP_FIXED and MAP_VARIABLE describe how the addr parameter should be interpreted. When MAP_FIXED is set in the flags argument, the system is informed that the value of pa must be addr, exactly. If MAP_FIXED is not set or MAP_VARIABLE is set, a non-zero value of addr is taken to be a suggestion of a process address near which the mapping should be placed. The pa so chosen is an area of the address space that the system deems suitable for a mapping of len bytes to the file. An addr value of 0 is interpreted as granting the system complete freedom in selecting pa, subject to constraints described below. When the system selects a value for pa, it never places a mapping at address 0. Either MAP_FIXED or MAP_VARIABLE can be specified, but not both.

The MAP_FILE and MAP_ANON flags control whether the region to be mapped is a mapped file region or an anonymous shared memory region. If neither MAP_ANON nor MAP_FILE is specified, MAP_FILE is used by default. Either MAP_FILE or MAP_ANON can be specified, but not both. If MAP_ANON is specified, the value of off is meaningless because there is no underlying file object for the memory region.

The off argument is constrained to be a multiple of allocation granularity as returned by sysconf(_SC_NUTC_OS_ALLOCGRANULARITY). When MAP_FIXED is specified, the argument addr must also meet these constraints. While the argument len need not meet a size or alignment constraint, the system includes, in any mapping operation, any partial page specified by the range [pa, pa + len].

The system always zero-fills any partial page at the end of an object. Further, the system never writes out any modified portions of the last page of an object that are beyond its end.

PARAMETERS

addr: Is the desired starting address of the memory mapped region.
len: Is the number of bytes to map.
prot: Is the Desired protection of the memory mapped region. This parameter is specified as a bitwise inclusive OR of one or more of PROT_NONE, PROT_READ, PROT_WRITE, and PROT_EXEC.
flags: Specifies attributes of the mapped region as the results of a bitwise inclusive OR of any combination of MAP_FILE, MAP_ANON (or MAP_ANONYMOUS), MAP_VARIABLE, MAP_FIXED, MAP_SHARED, or MAP_PRIVATE.
fildes: Is the file descriptor specifying the file that is to be mapped. This parameter should be -1 if mapping anonymous memory.
off: Offset from where file should be mapped. This parameter has no meaning if mapping anonymous memory.

RETURN VALUES

If successful, the mmap() and mmap64() functions return the address at which the mapping was placed (pa); otherwise, they return MAP_FAILED and set errno to one of the following values:

EACCES: Either the fildes argument is not open for read, regardless of the protection specified, or fildes is not open for write and PROT_WRITE was specified for a MAP_SHARED type mapping.
EBADF: The fildes argument is not a valid open file descriptor.
EINVAL: off is not a multiple of allocation granularity as returned by sysconf() or MAP_FIXED was specified and addr is not a multiple of allocation granularity as returned by sysconf().
EINVAL: The value of flags is invalid.
EINVAL: MAP_ANON was specified and fildes is not -1.
EMFILE: The number of mapped regions would exceed a system limit.
ENODEV: The fildes argument refers to a file whose type is not supported by mmap().
ENOMEM: MAP_FIXED was specified, and the range [addr, addr + len] exceeds that allowed for the address space of a process or MAP_FIXED was not specified and there is insufficient room in the address space to effect the mapping.
ENOTSUP: The system does not support the combination of accesses requested in the prot argument.
ENXIO: Addresses in the range [off, off + len] are invalid for the object specified by fildes.
ENXIO: MAP_FIXED was specified and the combination of addr, len and off is invalid for the object specified by fildes.
EOVERFLOW: The file is a regular file and the value of off plus len exceeds the offset maximum established in the open file description associated with fildes.

CONFORMANCE

UNIX 98, with exceptions.

mmap64(): Large File Specification, revision 1.5.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

Windows does not allow overlapping memory ranges to be created with mmap(). Attempts to map with MAP_FIXED at an address already in use in the process address space fails. In addition, Windows interprets the address 0 as a request for the system to pick a mapping address. Hence mapping with MAP_FIXED at address 0 is not possible.

Windows requires that attached memory mapped regions and the offset passed to mmap() be a multiple of allocation granularity as returned by sysconf(_SC_NUTC_OS_ALLOCGRANULARITY). If you use the MAP_FIXED flag and/or specify offset to be something other than 0, you must ensure that this address and/or offset is a multiple of allocation granularity as returned by sysconf().

The PROT_WRITE flag is implemented as PROT_READ|PROT_WRITE and the PROT_EXEC flag is implemented as PROT_READ|PROT_EXEC. On Windows 9x, the PROT_EXEC flag is not supported, nor is PROT_NONE in combination with MAP_SHARED.

Windows recommends the mapped file be open as long as the mapping exists to prevent nonsharing processes from reading and writing to the file so that coherence can be maintained. Windows does not maintain coherence for networked files.

On Windows 9x, mmap() for regular files may fail if the system can not find a region large enough to map the entire file, irrespective of the size of the map requested. Also, multiple mmap() calls for the same file using MAP_SHARED all return the same address, as long as the region remains mapped in any process.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

mmap(), mmap64()
map files or devices into memory

Function