path: root/man3p/mmap.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "MMAP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" mmap 
.SH NAME
mmap \- map pages of memory
.SH SYNOPSIS
.LP
\fB#include <sys/mman.h>
.br
.sp
void *mmap(void *\fP\fIaddr\fP\fB, size_t\fP \fIlen\fP\fB, int\fP
\fIprot\fP\fB, int\fP \fIflags\fP\fB,
.br
\ \ \ \ \ \  int\fP \fIfildes\fP\fB, off_t\fP \fIoff\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fImmap\fP() function shall establish a mapping between a process'
address space and a file, shared memory object, or
\ typed memory object.  The format of the call is as
follows:
.sp
.RS
.nf

\fIpa\fP\fB=\fP\fImmap\fP\fB(\fP\fIaddr\fP\fB,\fP \fIlen\fP\fB,\fP \fIprot\fP\fB,\fP \fIflags\fP\fB,\fP \fIfildes\fP\fB,\fP \fIoff\fP\fB);
\fP
.fi
.RE
.LP
The \fImmap\fP() function shall establish a mapping between the address
space of the process at an address \fIpa\fP for
\fIlen\fP bytes to the memory object represented by the file descriptor
\fIfildes\fP at offset \fIoff\fP for \fIlen\fP bytes.
The value of \fIpa\fP is an implementation-defined function of the
parameter \fIaddr\fP and the values of \fIflags\fP, further
described below. A successful \fImmap\fP() call shall return \fIpa\fP
as its result. The address range starting at \fIpa\fP and
continuing for \fIlen\fP bytes shall be legitimate for the possible
(not necessarily current) address space of the process. The
range of bytes starting at \fIoff\fP and continuing for \fIlen\fP
bytes shall be legitimate for the possible (not necessarily
current) offsets in the file, shared memory object, or   \ typed memory
object  \ represented by \fIfildes\fP.
.LP
If \fIfildes\fP represents a typed memory object opened with either
the POSIX_TYPED_MEM_ALLOCATE flag or the
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the memory object to be mapped
shall be that portion of the typed memory object allocated by
the implementation as specified below. In this case, if \fIoff\fP
is non-zero, the behavior of \fImmap\fP() is undefined. If
\fIfildes\fP refers to a valid typed memory object that is not accessible
from the calling process, \fImmap\fP() shall fail. 
.LP
The mapping established by \fImmap\fP() shall replace any previous
mappings for those whole pages containing any part of the
address space of the process starting at \fIpa\fP and continuing for
\fIlen\fP bytes.
.LP
If the size of the mapped file changes after the call to \fImmap\fP()
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.
.LP
The \fImmap\fP() function shall be supported for regular files, shared
memory objects, and   \ typed memory
objects.  Support for any other type of file is unspecified.
.LP
The parameter \fIprot\fP determines whether read, write, execute,
or some combination of accesses are permitted to the data
being mapped. The \fIprot\fP shall be either PROT_NONE or the bitwise-inclusive
OR of one or more of the other flags in the
following table, defined in the \fI<sys/mman.h>\fP header.
.TS C
center; l l.
\fBSymbolic Constant\fP	\fBDescription\fP
PROT_READ	Data can be read.
PROT_WRITE	Data can be written.
PROT_EXEC	Data can be executed.
PROT_NONE	Data cannot be accessed.
.TE
.LP
If an implementation cannot support the combination of access types
specified by \fIprot\fP, the call to \fImmap\fP() shall
fail.
.LP
An implementation may permit accesses other than those specified by
\fIprot\fP;   \ however, if
the Memory Protection option is supported, the implementation shall
not permit a write to succeed where PROT_WRITE has not been set
or shall not permit any access where PROT_NONE alone has been set.
The implementation shall support at least the following values
of \fIprot\fP: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive
OR of PROT_READ and PROT_WRITE.  If the Memory Protection option is
not supported, the result of any access
that conflicts with the specified protection is undefined. The file
descriptor \fIfildes\fP shall have been opened with read
permission, regardless of the protection options specified. If PROT_WRITE
is specified, the application shall ensure that it has
opened the file descriptor \fIfildes\fP with write permission unless
MAP_PRIVATE is specified in the \fIflags\fP parameter as
described below.
.LP
The parameter \fIflags\fP provides other information about the handling
of the mapped data. The value of \fIflags\fP is the
bitwise-inclusive OR of these options, defined in \fI<sys/mman.h>\fP:
.TS C
center; l l.
\fBSymbolic Constant\fP	\fBDescription\fP
MAP_SHARED	Changes are shared.
MAP_PRIVATE	Changes are private.
MAP_FIXED	Interpret \fIaddr\fP exactly.
.TE
.LP
Implementations that do not support the Memory Mapped Files option
are not required to support MAP_PRIVATE.
.LP
It is implementation-defined whether MAP_FIXED shall be supported.
\ MAP_FIXED shall be supported on XSI-conformant systems.
.LP
MAP_SHARED and MAP_PRIVATE describe the disposition of write references
to the memory object. If MAP_SHARED is specified, write
references shall change the underlying object. If MAP_PRIVATE is specified,
modifications to the mapped data by the calling process
shall be visible only to the calling process and shall 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 \fIfork\fP().
.LP
When \fIfildes\fP represents a typed memory object opened with either
the POSIX_TYPED_MEM_ALLOCATE flag or the
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, \fImmap\fP() shall, if there
are enough resources available, map \fIlen\fP bytes allocated
from the corresponding typed memory object which were not previously
allocated to any process in any processor that may access that
typed memory object. If there are not enough resources available,
the function shall fail. If \fIfildes\fP represents a typed
memory object opened with the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag,
these allocated bytes shall be contiguous within the typed
memory object. If \fIfildes\fP represents a typed memory object opened
with the POSIX_TYPED_MEM_ALLOCATE flag, these allocated
bytes may be composed of non-contiguous fragments within the typed
memory object. If \fIfildes\fP represents a typed memory object
opened with neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the
POSIX_TYPED_MEM_ALLOCATE flag, \fIlen\fP bytes starting at
offset \fIoff\fP within the typed memory object are mapped, exactly
as when mapping a file or shared memory object. In this case,
if two processes map an area of typed memory using the same \fIoff\fP
and \fIlen\fP values and using file descriptors that refer
to the same memory pool (either from the same port or from a different
port), both processes shall map the same region of storage.
.LP
When MAP_FIXED is set in the \fIflags\fP argument, the implementation
is informed that the value of \fIpa\fP shall be
\fIaddr\fP, exactly. If MAP_FIXED is set, \fImmap\fP() may return
MAP_FAILED and set \fIerrno\fP to [EINVAL]. If a MAP_FIXED
request is successful, the mapping established by \fImmap\fP() replaces
any previous mappings for the process' pages in the range
[\fIpa\fP,\fIpa\fP+\fIlen\fP).
.LP
When MAP_FIXED is not set, the implementation uses \fIaddr\fP in an
implementation-defined manner to arrive at \fIpa\fP. The
\fIpa\fP so chosen shall be an area of the address space that the
implementation deems suitable for a mapping of \fIlen\fP bytes
to the file. All implementations interpret an \fIaddr\fP value of
0 as granting the implementation complete freedom in selecting
\fIpa\fP, subject to constraints described below. A non-zero value
of \fIaddr\fP is taken to be a suggestion of a process address
near which the mapping should be placed. When the implementation selects
a value for \fIpa\fP, it never places a mapping at
address 0, nor does it replace any extant mapping.
.LP
The \fIoff\fP argument is constrained to be aligned and sized according
to the value returned by \fIsysconf\fP() when passed _SC_PAGESIZE
or _SC_PAGE_SIZE. When MAP_FIXED is specified, the
application shall ensure that the argument \fIaddr\fP also meets these
constraints. The implementation performs mapping operations
over whole pages. Thus, while the argument \fIlen\fP need not meet
a size or alignment constraint, the implementation shall
include, in any mapping operation, any partial page specified by the
range [\fIpa\fP,\fIpa\fP+\fIlen\fP).
.LP
The system shall always zero-fill any partial page at the end of an
object. Further, the system shall never write out any
modified portions of the last page of an object which are beyond its
end.   \ References
within the address range starting at \fIpa\fP and continuing for \fIlen\fP
bytes to whole pages following the end of an object
shall result in delivery of a SIGBUS signal. 
.LP
An implementation may generate SIGBUS signals when a reference would
cause an error in the mapped object, such as out-of-space
condition.
.LP
The \fImmap\fP() function shall add an extra reference to the file
associated with the file descriptor \fIfildes\fP which is
not removed by a subsequent \fIclose\fP() on that file descriptor.
This reference shall be
removed when there are no more mappings to the file.
.LP
The \fIst_atime\fP field of the mapped file may be marked for update
at any time between the \fImmap\fP() call and the
corresponding \fImunmap\fP() call. The initial read or write reference
to a mapped region
shall cause the file's \fIst_atime\fP field to be marked for update
if it has not already been marked for update.
.LP
The \fIst_ctime\fP and \fIst_mtime\fP fields of a file that is mapped
with MAP_SHARED and PROT_WRITE shall be marked for
update at some point in the interval between a write reference to
the mapped region and the next call to \fImsync\fP() with MS_ASYNC
or MS_SYNC for that portion of the file by any process. If there is
no
such call and if the underlying file is modified as a result of a
write reference, then these fields shall be marked for update at
some time after the write reference.
.LP
There may be implementation-defined limits on the number of memory
regions that can be mapped (per process or per system).
.LP
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 \fIshmat\fP()
is implementation-defined. 
.LP
If \fImmap\fP() fails for reasons other than [EBADF], [EINVAL], or
[ENOTSUP], some of the mappings in the address range
starting at \fIaddr\fP and continuing for \fIlen\fP bytes may have
been unmapped.
.SH RETURN VALUE
.LP
Upon successful completion, the \fImmap\fP() function shall return
the address at which the mapping was placed ( \fIpa\fP);
otherwise, it shall return a value of MAP_FAILED and set \fIerrno\fP
to indicate the error. The symbol MAP_FAILED is defined in
the \fI<sys/mman.h>\fP header. No successful return from \fImmap\fP()
shall
return the value MAP_FAILED.
.SH ERRORS
.LP
The \fImmap\fP() function shall fail if:
.TP 7
.B EACCES
The \fIfildes\fP argument is not open for read, regardless of the
protection specified, or \fIfildes\fP is not open for write
and PROT_WRITE was specified for a MAP_SHARED type mapping.
.TP 7
.B EAGAIN
The mapping could not be locked in memory, if required by \fImlockall\fP(),
due to a lack
of resources. 
.TP 7
.B EBADF
The \fIfildes\fP argument is not a valid open file descriptor.
.TP 7
.B EINVAL
The \fIaddr\fP argument (if MAP_FIXED was specified) or \fIoff\fP
is not a multiple of the page size as returned by \fIsysconf\fP(),
or is considered invalid by the implementation.
.TP 7
.B EINVAL
The value of \fIflags\fP is invalid (neither MAP_PRIVATE nor MAP_SHARED
is set).
.TP 7
.B EMFILE
The number of mapped regions would exceed an implementation-defined
limit (per process or per system).
.TP 7
.B ENODEV
The \fIfildes\fP argument refers to a file whose type is not supported
by \fImmap\fP().
.TP 7
.B ENOMEM
MAP_FIXED was specified, and the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fP)
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.
.TP 7
.B ENOMEM
The mapping could not be locked in memory, if required by \fImlockall\fP(),
because it
would require more space than the system is able to supply. 
.TP 7
.B ENOMEM
Not enough unallocated memory resources remain in the typed memory
object designated by \fIfildes\fP to allocate \fIlen\fP bytes.
.TP 7
.B ENOTSUP
MAP_FIXED or MAP_PRIVATE was specified in the \fIflags\fP argument
and the implementation does not support this functionality.
.LP
The implementation does not support the combination of accesses requested
in the \fIprot\fP argument.
.TP 7
.B ENXIO
Addresses in the range [\fIoff\fP,\fIoff\fP+\fIlen\fP) are invalid
for the object specified by \fIfildes\fP.
.TP 7
.B ENXIO
MAP_FIXED was specified in \fIflags\fP and the combination of \fIaddr\fP,
\fIlen\fP, and \fIoff\fP is invalid for the
object specified by \fIfildes\fP.
.TP 7
.B ENXIO
The \fIfildes\fP argument refers to a typed memory object that is
not accessible from the calling process. 
.TP 7
.B EOVERFLOW
The file is a regular file and the value of \fIoff\fP plus \fIlen\fP
exceeds the offset maximum established in the open file
description associated with \fIfildes\fP.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
Use of \fImmap\fP() may reduce the amount of memory available to other
memory allocation functions.
.LP
Use of MAP_FIXED may result in unspecified behavior in further use
of \fImalloc\fP() and
\fIshmat\fP(). The use of MAP_FIXED is discouraged, as it may prevent
an implementation from
making the most effective use of resources.
.LP
The application must ensure correct synchronization when using \fImmap\fP()
in conjunction with any other file access method,
such as \fIread\fP() and \fIwrite\fP(), standard
input/output, and \fIshmat\fP().
.LP
The \fImmap\fP() function allows access to resources via address space
manipulations, instead of \fIread\fP()/ \fIwrite\fP(). 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 \fImmap\fP(),
the following:
.sp
.RS
.nf

\fBfildes = open(...)
lseek(fildes, some_offset)
read(fildes, buf, len)
/* Use data in buf. */
\fP
.fi
.RE
.LP
becomes:
.sp
.RS
.nf

\fBfildes = open(...)
address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
/* Use data at address. */
\fP
.fi
.RE
.SH RATIONALE
.LP
After considering several other alternatives, it was decided to adopt
the \fImmap\fP() definition found in SVR4 for mapping
memory objects into process address spaces. The SVR4 definition is
minimal, in that it describes only what has been built, and what
appears to be necessary for a general and portable mapping facility.
.LP
Note that while \fImmap\fP() was first designed for mapping files,
it is actually a general-purpose mapping facility. It can be
used to map any appropriate object, such as memory, files, devices,
and so on, into the address space of a process.
.LP
When a mapping is established, it is possible that the implementation
may need to map more than is requested into the address
space of the process because of hardware requirements. An application,
however, cannot count on this behavior. Implementations that
do not use a paged architecture may simply allocate a common memory
region and return the address of it; such implementations
probably do not allocate any more than is necessary. References past
the end of the requested area are unspecified.
.LP
If an application requests a mapping that would overlay existing mappings
in the process, it might be desirable that an
implementation detect this and inform the application. However, the
default, portable (not MAP_FIXED) operation does not overlay
existing mappings. On the other hand, if the program specifies a fixed
address mapping (which requires some implementation
knowledge to determine a suitable address, if the function is supported
at all), then the program is presumed to be successfully
managing its own address space and should be trusted when it asks
to map over existing data structures. Furthermore, it is also
desirable to make as few system calls as possible, and it might be
considered onerous to require an \fImunmap\fP() before an \fImmap\fP()
to the same address range. This volume of
IEEE\ Std\ 1003.1-2001 specifies that the new mappings replace any
existing mappings, following existing practice in this
regard.
.LP
It is not expected, when the Memory Protection option is supported,
that all hardware implementations are able to support all
combinations of permissions at all addresses. When this option is
supported, implementations are required to disallow write access
to mappings without write permission and to disallow access to mappings
without any access permission. Other than these
restrictions, implementations may allow access types other than those
requested by the application. For example, if the application
requests only PROT_WRITE, the implementation may also allow read access.
A call to \fImmap\fP() fails if the implementation cannot
support allowing all the access requested by the application. For
example, some implementations cannot support a request for both
write access and execute access simultaneously. All implementations
supporting the Memory Protection option must support requests
for no access, read access, write access, and both read and write
access. Strictly conforming code must only rely on the required
checks. These restrictions allow for portability across a wide range
of hardware.
.LP
The MAP_FIXED address treatment is likely to fail for non-page-aligned
values and for certain architecture-dependent address
ranges. Conforming implementations cannot count on being able to choose
address values for MAP_FIXED without utilizing
non-portable, implementation-defined knowledge. Nonetheless, MAP_FIXED
is provided as a standard interface conforming to existing
practice for utilizing such knowledge when it is available.
.LP
Similarly, in order to allow implementations that do not support virtual
addresses, support for directly specifying any mapping
addresses via MAP_FIXED is not required and thus a conforming application
may not count on it.
.LP
The MAP_PRIVATE function can be implemented efficiently when memory
protection hardware is available. When such hardware is not
available, implementations can implement such "mappings" by simply
making a real copy of the relevant data into process private
memory, though this tends to behave similarly to \fIread\fP().
.LP
The function has been defined to allow for many different models of
using shared memory. However, all uses are not equally
portable across all machine architectures. In particular, the \fImmap\fP()
function allows the system as well as the application
to specify the address at which to map a specific region of a memory
object. The most portable way to use the function is always to
let the system choose the address, specifying NULL as the value for
the argument \fIaddr\fP and not to specify MAP_FIXED.
.LP
If it is intended that a particular region of a memory object be mapped
at the same address in a group of processes (on machines
where this is even possible), then MAP_FIXED can be used to pass in
the desired mapping address. The system can still be used to
choose the desired address if the first such mapping is made without
specifying MAP_FIXED, and then the resulting mapping address
can be passed to subsequent processes for them to pass in via MAP_FIXED.
The availability of a specific address range cannot be
guaranteed, in general.
.LP
The \fImmap\fP() function can be used to map a region of memory that
is larger than the current size of the object. Memory
access within the mapping but beyond the current end of the underlying
objects may result in SIGBUS signals being sent to the
process. The reason for this is that the size of the object can be
manipulated by other processes and can change at any moment. The
implementation should tell the application that a memory reference
is outside the object where this can be detected; otherwise,
written data may be lost and read data may not reflect actual data
in the object.
.LP
Note that references beyond the end of the object do not extend the
object as the new end cannot be determined precisely by most
virtual memory hardware. Instead, the size can be directly manipulated
by \fIftruncate\fP().
.LP
Process memory locking does apply to shared memory regions, and the
MEMLOCK_FUTURE argument to \fImlockall\fP() can be relied upon to
cause new shared memory regions to be automatically
locked.
.LP
Existing implementations of \fImmap\fP() return the value -1 when
unsuccessful. Since the casting of this value to type \fBvoid
*\fP cannot be guaranteed by the ISO\ C standard to be distinct from
a successful value, this volume of
IEEE\ Std\ 1003.1-2001 defines the symbol MAP_FAILED, which a conforming
implementation does not return as the result of a
successful call.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIexec\fP() , \fIfcntl\fP() , \fIfork\fP() , \fIlockf\fP() , \fImsync\fP()
, \fImunmap\fP() , \fImprotect\fP() , \fIposix_typed_mem_open\fP()
, \fIshmat\fP() , \fIsysconf\fP() , the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<sys/mman.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .