NAME

mmap - map pages of memory

 SYNOPSIS

#include <sys/mman.h>

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

 DESCRIPTION

The mmap() function establishes a mapping between a process' address space and a file or shared memory object. The format of the call is as follows:

pa=mmap(addr, len, prot, flags, fildes, 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 implementation-dependent 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 will be legitimate for the possible (not necessarily current) address space of the process. The range of bytes starting at off and continuing for len bytes will be legitimate for the possible (not necessarily current) offsets in the file or shared memory object represented by fildes.

The mapping established by mmap() replaces any previous mappings for those whole pages containing any part of the address space of the process starting at pa and continuing for len bytes.

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 mmap() function is supported for regular files and shared memory objects. Support for any other type of file is unspecified.

The parameter prot determines whether read, write, execute, or some combination of accesses are permitted to the data being mapped. The prot should be either PROT_NONE or the bitwise inclusive OR of one or more of the other flags in the following table, defined in the header <sys/mman.h>.

Symbolic Constant	Description
PROT_READ	Data can be read.
PROT_WRITE	Data can be written.
PROT_EXEC	Data can be executed.
PROT_NONE	Data cannot be accessed.

If an implementation cannot support the combination of access types specified by prot, the call to mmap() fails. An implementation may permit accesses other than those specified by prot; however, the implementation will 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 implementation will support at least the following values of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the inclusive OR of PROT_READ and PROT_WRITE. The file descriptor fildes will have 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 as described below.

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, defined in <sys/mman.h>:

Symbolic Constant	Description
MAP_SHARED	Changes are shared.
MAP_PRIVATE	Changes are private.
MAP_FIXED	Interpret addr exactly.

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 will be visible only to the calling process and will not change the underlying object. It is unspecified whether modifications to the underlying object done after the MAP_PRIVATE mapping is established are 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().

When MAP_FIXED is set in the flags argument, the implementation is informed that the value of pa must be addr, exactly. If MAP_FIXED is set, mmap() may return MAP_FAILED and set errno to [EINVAL]. If a MAP_FIXED request is successful, the mapping established by mmap() replaces any previous mappings for the process' pages in the range [pa, pa + len).

When MAP_FIXED is not set, the implementation uses addr in an unspecified manner to arrive at pa. The pa so chosen will be an area of the address space that the implementation deems suitable for a mapping of len bytes to the file. All implementations interpret an addr value of 0 as granting the implementation complete freedom in selecting pa, subject to constraints described below. A non-zero value of addr is taken to be a suggestion of a process address near which the mapping should be placed. When the implementation selects a value for pa, it never places a mapping at address 0, nor does it replace any extant mapping.

The off argument is constrained to be aligned and sized according to the value returned by sysconf() when passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, the argument addr must also meet these constraints. The implementation performs mapping operations over whole pages. Thus, while the argument len need not meet a size or alignment constraint, the implementation will include, 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. References within the address range starting at pa and continuing for len bytes to whole pages following the end of an object result in delivery of a SIGBUS signal.

An implementation may deliver SIGBUS signals when a reference would cause an error in the mapped object, such as out-of-space condition.

The mmap() function adds an extra reference to the file associated with the file descriptor fildes which is not removed by a subsequent close() on that file descriptor. This reference is removed when there are no more mappings to the file.

The st_atime field of the mapped file may be marked for update at any time between the mmap() call and the corresponding munmap() call. The initial read or write reference to a mapped region will cause the file's st_atime field to be marked for update if it has not already been marked for update.

The st_ctime and st_mtime fields of a file that is mapped with MAP_SHARED and PROT_WRITE, will be marked for update at some point in the interval between a write reference to the mapped region and the next call to msync() with MS_ASYNC or MS_SYNC for that portion of the file by any process. If there is no such call, these fields may be marked for update at any time after a write reference if the underlying file is modified as a result.

There may be implementation-dependent limits on the number of memory regions that can be mapped (per process or per system). If such a limit is imposed, whether the number of memory regions that can be mapped by a process is decreased by the use of shmat() is implementation-dependent.

 RETURN VALUE

Upon successful completion, the mmap() function returns the address at which the mapping was placed (pa); otherwise, it returns a value of MAP_FAILED and sets errno to indicate the error. The symbol MAP_FAILED is defined in the header <sys/mman.h>. No successful return from mmap() will return the value MAP_FAILED.

If mmap() fails for reasons other than [EBADF], [EINVAL] or [ENOTSUP], some of the mappings in the address range starting at addr and continuing for len bytes may have been unmapped.

 ERRORS

The mmap() function will fail if:

[EACCES]

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.

[EAGAIN]

The mapping could not be locked in memory, if required by mlockall(), due to a lack of resources.

[EBADF]

The fildes argument is not a valid open file descriptor.

[EINVAL]

The addr argument (if MAP_FIXED was specified) or off is not a multiple of the page size as returned by sysconf(), or are considered invalid by the implementation.

[EINVAL]

The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).

[EMFILE]

The number of mapped regions would exceed an implementation-dependent limit (per process or per system).

[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 if MAP_FIXED was not specified and there is insufficient room in the address space to effect the mapping.

[ENOMEM]

The mapping could not be locked in memory, if required by mlockall(), because it would require more space than the system is able to supply.

[ENOTSUP]

The implementation 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 in flags 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.

 EXAMPLES

None.

 APPLICATION USAGE

Use of mmap() may reduce the amount of memory available to other memory allocation functions.

Use of MAP_FIXED may result in unspecified behaviour in further use of brk(), sbrk(), malloc() and shmat(). The use of MAP_FIXED is discouraged, as it may prevent an implementation from making the most effective use of resources.

The application must ensure correct synchronisation when using mmap() in conjunction with any other file access method, such as read() and write(), standard input/output, and shmat().

The mmap() function allows access to resources via address space manipulations, instead of read()/write(). Once a file is mapped, all a process has to do to access it is use the data at the address to which the file was mapped. So, using pseudo-code to illustrate the way in which an existing program might be changed to use mmap(), the following:

fildes = open(...)
lseek(fildes, some_offset)
read(fildes, buf, len)
/* use data in buf */

becomes:

fildes = open(...)
address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
/* use data at address */

The [EINVAL] error above is marked EX because it is defined as an optional error in the POSIX Realtime Extension.

 FUTURE DIRECTIONS

None.

 SEE ALSO

brk(), exec, fcntl(), fork(), lockf(), msync(), munmap(), mprotect(), sbrk(), shmat(), sysconf(), <sys/mman.h>.