NAME

mmap − map process addresses to a memory object

SYNOPSIS

#include <sys/mman.h>

caddr_t mmap(addr, len, prot, flags, fildes, off)

caddr_t addr;

size_t len;

int prot;

int flags;

int fildes;

off_t off;

DESCRIPTION

The mmap function establishes a mapping between the process’s address space and a memory object.  mmap returns a pointer to the start of the mapped memory object which is represented by the file descriptor fildes.  This file descriptor must have previously been returned by a call to shm_open(3P4).  Multiple programs can create shared memory regions by mapping the same memory object into their respective address spaces. 

The current implementation of mmap can be used only to map an entire memory object; that is, the value of len must be equal to the size, in bytes, of the memory object.  The size of a memory object can be changed via ftruncate(2) before the memory object is mapped by a process.  Once the memory object is mapped by any process, the size of the memory object cannot be changed. 

The parameter prot determines whether read, write, execute, or some combination of accesses is permitted to the data being mapped.  The argument is constructed from the bitwise inclusive OR of one or more of the following flags, which are defined in the header sys/mman.h:

PROT_READ

Data can be read. 

PROT_WRITE

Data can be written. 

PROT_EXEC

Data can be executed. 

PROT_NONE

Data cannot be accessed. 

Only the PROT_WRITE bit has significance in the current implementation.  If PROT_WRITE is not set, no write access is allowed to the memory object.  The PROT_NONE option is not supported.  Specifying PROT_NONE will cause an error to be returned.  Other protection bits are ignored.  Note that these bits will have significance in future implementations. 

The parameter flags provides other information about the handling of the mapped data.  The options are defined as:

MAP_SHARED

Share changes. 

MAP_PRIVATE

Changes are private (not supported)

MAP_FIXED

Interpret addr exactly. 

In the current implementation, MAP_SHARED must be specified.  The MAP_PRIVATE option is not supported.  When MAP_SHARED is specified, write references change the underlying object, that is, the memory object will be modified for all processes that have mapped the memory object. 

MAP_FIXED informs the system that the memory object should be mapped into the process’s address space at the location specified by addr.  When MAP_FIXED is not set, the value of addr is ignored, and the system will select an appropriate address for the mapping.  The user is not allowed to select an address that would conflict with an existing mapping.  To map a memory object on top of a previous mapping, the first mapping must first be removed via munmap(3P4).

When MAP_FIXED is specified, the parameter addr is constrained to be segment-aligned (the address must be a multiple of SHMLBA, which is defined in /usr/include/sys/shm.h).  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 len bytes. 

In the current implementation, the parameter off must be specified as zero. 
 

RETURN VALUE

Upon successful completion, the mmap function returns the address at which the mapping begins; otherwise, it returns a value of -1 and sets errno to indicate the error.  Possible errors are:

[EACCES] The file descriptor fildes is not open for read, regardless of the protection specified.  The file descriptor fildes is not open for write and PROT_WRITE was specified. 

[EAGAIN] The mapping could not be locked in memory, if required by mlockall(3P4) (because MCL_FUTURE was set), due to a lack of resources. 

[EBADF] The fildes argument is not a valid open file descriptor. 

[EINVAL] The argument addr (if MAP_FIXED was specified) is not segment-aligned.  MAP_FIXED was specified, and the address specified already holds a mapped object or is not an address in the process’s data region. The value of off is not zero.  The value in flags is invalid (e.g., MAP_SHARED must be specified).  The value of len is less than or equal to zero.  The value of prot is not a valid combination of the allowed flags. 

[ENODEV] The fildes argument does not refer to a memory object (memory objects are attached via shm_open(3P4)). 

[ENOMEM] MAP_FIXED was specified, and the address range starting at addr and continuing for len bytes exceeds that allowed for the address space of a process.  MAP_FIXED was not specified, and there is insufficient room in the address space to effect the mapping. The mapping could not be locked in memory, if required by mlockall(3P4) (because MCL_FUTURE was set), because it would require more space than the system is able to supply. 

[ENOTSUP] MAP_PRIVATE was specified in the flags argument and is not supported.  PROT_NONE was specified in the prot argument and is not supported. 

[ENXIO] The specified len is not equal to the length of the memory object MAP_FIXED was specified in flags and the combination of addr, len, and off is invalid for the object specified by fildes. 
 

FILES

/usr/lib/libposix4.a

SEE ALSO

munmap(3P4), shm_open(3P4), shm_unlink(3P4), shmget(2), shmat(2), "CX/UX Programmer’s Guide"

BUGS

POSIX.4 states that the addr should be page-aligned according to the value returned by sysconf(2) for {_SC_PAGESIZE}.  For this implementation, addr must be segment-aligned. 

The size of a memory object must be set before it is mapped by any process. 

No partial mapping of a memory object is supported.  This means that the off parameter to the mmap function must be specified as zero.  This also means that the len parameter to mmap must be equal to the size of the memory object. 

POSIX.4 allows a program to create a mapping to an object that is larger than the current size of the object.  If the object is later expanded, the expanded object is now visible to the program.  Under the current implementation, it is not possible to map more of a memory object than its current size. 

It is not possible to perform an mmap over an existing mapping.  The original mapping must first be removed via munmap(3P4). 

WARNING

The interface to mmap is based on IEEE Draft Standard P1003.4/D12.  This is an unapproved draft, subject to change.  Use of information contained in this unapproved draft is at your own risk.  This interface will change to reflect any changes made by future drafts of POSIX 1003.4. 
 

CX/UX Programmer’s Reference Manual