mmap(S)

mmap -- map object to pages of memory

Syntax

cc . . . -lc

#include <sys/types.h>
#include <sys/mman.h>

caddr_t mmap(caddr_t addr, size_t len, int prot, int flags,/
    int fd, off_t off);

Description

The function mmap establishes a mapping between a process's address space and a virtual memory object. The format of the call is:

pa = mmap(addr, len, prot, flags, fd, off);

mmap establishes a mapping between the process's address space at an address pa for len bytes to the memory object represented by the file descriptor fd at offset off for len bytes. The value of pa is an implementation-dependent function of the parameter addr and values of flags, further described below. A successful mmap call returns pa as its result. The address ranges covered by [pa, pa + len] and [off, off + len] must be legitimate for the possible (not necessarily current) address space of a process and the object in question, respectively. mmap cannot grow a file (see ftruncate(S)).

The mapping established by mmap replaces any previous mappings for the process's pages in the range [pa, pa + len].

The parameter prot determines whether read, write, execute, or some combination of accesses are permitted to the pages being mapped. The protection options are defined in <sys/mman.h> as:

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

Not all implementations literally provide all possible combinations. PROT_WRITE is often implemented as PROT_READ|PROT_WRITE and PROT_EXEC as PROT_READ|PROT_EXEC. However, no implementation will permit a write to succeed where PROT_WRITE has not been set. The behavior of PROT_WRITE can be influenced by setting MAP_PRIVATE in the flags parameter, described below.

The parameter flags provides other information about the handling of the mapped pages. The options are defined in <sys/mman.h> as:

MAP_SHARED: share changes
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 will change the memory object. If MAP_PRIVATE is specified, the initial write reference will create a private copy of the memory object page and redirect the mapping to the copy. Either MAP_SHARED or MAP_PRIVATE must be specified, but not both. The mapping type is retained across a fork(S).

Note that the private copy is not created until the first write; until then, other users who have the object mapped MAP_SHARED can change the object.

MAP_FIXED informs the system that the value of pa must be addr, exactly. The use of MAP_FIXED is discouraged, as it may prevent an implementation from making the most effective use of system resources.

When MAP_FIXED is not set, the system uses addr in an implementation-defined manner to arrive at pa. The pa so chosen will be an area of the address space which the system deems suitable for a mapping of len bytes to the specified object. All implementations interpret an addr value of zero as granting the system 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 system selects a value for pa, it will never place a mapping at address 0, nor will it replace any extant mapping, nor map into areas considered part of the potential data or stack segments.

The parameter off is constrained to be aligned and sized according to the value returned by sysconf. When MAP_FIXED is specified, the parameter addr must also meet these constraints. The system performs mapping operations over whole pages. Thus, while the parameter len need not meet a size or alignment constraint, the system will include, in any mapping operation, any partial page specified by the range [pa, pa + len].

The system will always zero-fill any partial page at the end of an object. Further, the system will never write out any modified portions of the last page of an object which are beyond its end. References to whole pages following the end of an object will result in the delivery of a SIGBUS signal. SIGBUS signals may also be delivered on various filesystem conditions, including quota exceeded errors.

mmap adds an extra reference to the object associated with the file descriptor fd which is not removed by a subsequent close on that file descriptor. This reference is removed when the entire range is unmapped (explicitly or implicitly).

Return values

On success, mmap returns the address at which the mapping was placed (pa). On failure, mmap returns (caddr_t)-1 and sets errno to identify the error.

Diagnostics

In the following conditions mmap fails and sets errno to:

[EAGAIN]: the mapping could not be locked in memory.
[EBADF]: fd is not open.
[EACCES]: fd is not open for read, regardless of the protection specified, or fd is not open for write and PROT_WRITE was specified for a MAP_SHARED type mapping.
[ENXIO]: addresses in the range [off, off + len] are invalid for fd.
[EINVAL]: the arguments addr (if MAP_FIXED was specified) or off are not multiples of the page size as returned by sysconf.
[EINVAL]: the field in flags is invalid (for example neither MAP_PRIVATE or MAP_SHARED).
[ENODEV]: fd refers to an object for which mmap is meaningless, such as a terminal.
[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.
[EBUSY]: fd refers to a block device which is currently mounted or in use as a swap area.
[ETXTBSY]: fd refers to a file which is currently in use for writing, and PROT_EXEC was specified.

Examples

mmap allows access to resources via address space manipulations instead of the read/write interface. Once a file is mapped, all a process has to do to access it is use the data at the address to which the object was mapped. Consider the following pseudo-code:

   fd = open(...)
   lseek(fd, offset)
   read(fd, buf, len)
   /* use data in buf */

Here is a rewrite using mmap:

   fd = open(...)
   address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
                  MAP_PRIVATE, fd, offset)
   /* use data at address */

Files

/lib/libc.a: linking library

Standards conformance

mmap is conformant with:

AT&T SVID Issue 3;
IEEE POSIX Std 1003.4 1992 System Application Program Interface (API) Realtime Extension [C Language] (ISO/IEC 9945-1).