mmap - map pages of memory

---

SYNOPSIS

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

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

DESCRIPTION

mmap() establishes a mapping between the process's address space at an address pa for len bytes to the memory object represented by fd at 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.

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

close.2v does not unmap pages of the object referred to by a descriptor. Use munmap.2 to remove a mapping.

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:

#define PROT_READ	0x1	/* page can be read */
#define PROT_WRITE	0x2	/* page can be written */
#define PROT_EXEC	0x4	/* page can be executed */
#define PROT_NONE	0x0	/* 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:

#define MAP_SHARED	1	/* Share changes */
#define MAP_PRIVATE	2	/* Changes are private */
#define MAP_TYPE	0xf	/* Mask for type of mapping */
#define MAP_FIXED	0x10	/* 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. The mapping type is retained across a fork.2v

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 as a hint 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 getpagesize (2). 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).

mmap() allows [pa, pa + len) to extend beyond the end of the object, both at the time of the mmap() and while the mapping persists, for example if the file was created just prior to the mmap() and has no contents, or if the file is truncated. Any reference to addresses beyond the end of the object, however, will result in the delivery of a SIGBUS signal.

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 a SIGBUS signal. SIGBUS may also be delivered on various filesystem conditions, including quota exceeded errors.

If the process calls mlockall.3 with the MCL_FUTURE flag, the pages mapped by all future calls to mmap() will be locked in memory. In this case, if not enough memory could be locked, mmap() fails and sets errno to EAGAIN.

RETURN VALUES

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

ERRORS

EACCES

fd was not open for read and PROT_READ or PROT_EXEC were specified.

fd was not open for write and PROT_WRITE was specified for a MAP_SHARED type mapping.

EAGAIN

Some or all of the mapping could not be locked in memory.

EBADF

fd was not open.

EINVAL

The arguments addr (if MAP_FIXED was specified) and off were not multiples of the page size as returned by getpagesize (2).

The MAP_TYPE field in flags was invalid (neither MAP_PRIVATE nor MAP_SHARED).

ENODEV

fd refered to an object for which mmap() is meaningless, such as a terminal.

ENOMEM

MAP_FIXED was specified, and the range [addr, addr + len) exceeded that allowed for the address space of a process.

MAP_FIXED was not specified and there was insufficient room in the address space to effect the mapping.

ENXIO

Addresses in the range [off, off + len) are invalid for fd.

SEE ALSO

Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97