path: root/upstream/archlinux/man3p/mmap.3p

'\" et
.TH MMAP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
mmap
\(em map pages of memory
.SH SYNOPSIS
.LP
.nf
#include <sys/mman.h>
.P
void *mmap(void *\fIaddr\fP, size_t \fIlen\fP, int \fIprot\fP, int \fIflags\fP,
    int \fIfildes\fP, off_t \fIoff\fP);
.fi
.SH DESCRIPTION
The
\fImmap\fR()
function shall establish a mapping between an address space
of a process and a memory object.
.P
The
\fImmap\fR()
function shall be supported for the following memory objects:
.IP " *" 4
Regular files
.IP " *" 4
Shared memory objects
.IP " *" 4
Typed memory objects
.P
Support for any other type of file is unspecified.
.P
The format of the call is as follows:
.sp
.RS 4
.nf

\fIpa\fR=\fImmap\fR(\fIaddr\fP, \fIlen\fP, \fIprot\fP, \fIflags\fP, \fIfildes\fP, \fIoff\fP);
.fi
.P
.RE
.P
The
\fImmap\fR()
function shall establish a mapping between the address space of the
process at an address
.IR pa
for
.IR len
bytes to the memory object represented by the file descriptor
.IR fildes
at offset
.IR off
for
.IR len
bytes. The value of
.IR pa
is an implementation-defined function of the parameter
.IR addr
and the values of
.IR flags ,
further described below. A successful
\fImmap\fR()
call shall return
.IR pa
as its result. The address range starting at
.IR pa
and continuing for
.IR len
bytes shall be legitimate for the possible (not necessarily current)
address space of the process. The range of bytes starting at
.IR off
and continuing for
.IR len
bytes shall be legitimate for the possible (not necessarily current)
offsets in the memory object represented by
.IR fildes .
.P
If
.IR fildes
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
.IR off
is non-zero, the behavior of
\fImmap\fR()
is undefined. If
.IR fildes
refers to a valid typed memory object that is not accessible from the
calling process,
\fImmap\fR()
shall fail.
.P
The mapping established by
\fImmap\fR()
shall replace any previous mappings for those whole pages containing
any part of the address space of the process starting at
.IR pa
and continuing for
.IR len
bytes.
.P
If the size of the mapped file changes after the call to
\fImmap\fR()
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.
.P
If
.IR len
is zero,
\fImmap\fR()
shall fail and no mapping shall be established.
.P
The parameter
.IR prot
determines whether read, write, execute, or some combination of
accesses are permitted to the data being mapped. The
.IR prot
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
.IR <sys/mman.h> 
header.
.TS
center box tab(!);
cB | cB
lw(1.5i) | lw(2i).
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.
.TE
.P
If an implementation cannot support the combination of access types
specified by
.IR prot ,
the call to
\fImmap\fR()
shall fail.
.P
An implementation may permit accesses other than those specified by
.IR prot ;
however, the implementation shall not permit a write to succeed
where PROT_WRITE has not been set and shall not permit any access where
PROT_NONE alone has been set. The implementation shall support at least
the following values of
.IR prot :
PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of
PROT_READ and PROT_WRITE. The file descriptor
.IR fildes
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
.IR fildes
with write permission unless MAP_PRIVATE is specified in the
.IR flags
parameter as described below.
.P
The parameter
.IR flags
provides other information about the handling of the mapped data.
The value of
.IR flags
is the bitwise-inclusive OR of these options, defined in
.IR <sys/mman.h> :
.TS
center box tab(!);
cB | cB
lw(1.5i) | lw(2i).
Symbolic Constant!Description
_
MAP_SHARED!Changes are shared.
MAP_PRIVATE!Changes are private.
MAP_FIXED!Interpret \fIaddr\fP exactly.
.TE
.P
It is implementation-defined whether MAP_FIXED shall be supported.
MAP_FIXED shall be supported on XSI-conformant systems.
.P
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\fR().
.P
The state of synchronization objects such as mutexes, semaphores,
barriers, and conditional variables placed in shared memory mapped with
MAP_SHARED becomes undefined when the last region in any process
containing the synchronization object is unmapped.
.P
When
.IR fildes
represents a typed memory object opened with either the
POSIX_TYPED_MEM_ALLOCATE flag or the
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag,
\fImmap\fR()
shall, if there are enough resources available, map
.IR len
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
.IR fildes
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
.IR fildes
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
.IR fildes
represents a typed memory object opened with neither the
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the POSIX_TYPED_MEM_ALLOCATE
flag,
.IR len
bytes starting at offset
.IR off
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
.IR off
and
.IR len
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.
.P
When MAP_FIXED is set in the
.IR flags
argument, the implementation is informed that the value of
.IR pa
shall be
.IR addr ,
exactly. If MAP_FIXED is set,
\fImmap\fR()
may return MAP_FAILED and set
.IR errno
to
.BR [EINVAL] .
If a MAP_FIXED request is successful, then any previous mappings
or memory locks
for those whole pages containing any part of the address range
[\fIpa\fP,\fIpa\fP+\fIlen\fR) shall be removed, as if by an
appropriate call to
\fImunmap\fR(),
before the new mapping is established.
.P
When MAP_FIXED is not set, the implementation uses
.IR addr
in an implementation-defined manner to arrive at
.IR pa .
The
.IR pa
so chosen shall be an area of the address space that the implementation
deems suitable for a mapping of
.IR len
bytes to the file. All implementations interpret an
.IR addr
value of 0 as granting the implementation complete freedom in selecting
.IR pa ,
subject to constraints described below. A non-zero value of
.IR 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
.IR pa ,
it never places a mapping at address 0, nor does it replace any extant
mapping.
.P
If MAP_FIXED is specified and
.IR addr
is non-zero, it shall have the same remainder as the
.IR off
parameter, modulo the page size as returned by
\fIsysconf\fR()
when passed _SC_PAGESIZE or _SC_PAGE_SIZE. The implementation may
require that off is a multiple of the page size. If MAP_FIXED is
specified, the implementation may require that
.IR addr
is a multiple of the page size. The system performs mapping operations
over whole pages. Thus, while the parameter
.IR len
need not meet a size or alignment constraint, the system shall include,
in any mapping operation, any partial page specified by the address
range starting at
.IR pa
and continuing for
.IR len
bytes.
.P
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
.IR pa
and continuing for
.IR len
bytes to whole pages following the end of an object shall result in
delivery of a SIGBUS signal.
.P
An implementation may generate SIGBUS signals when a reference would
cause an error in the mapped object, such as out-of-space condition.
.P
The
\fImmap\fR()
function shall add an extra reference to the file associated with the
file descriptor
.IR fildes
which is not removed by a subsequent
\fIclose\fR()
on that file descriptor. This reference shall be removed when there are
no more mappings to the file.
.P
The last data access timestamp of the mapped file may be marked for
update at any time between the
\fImmap\fR()
call and the corresponding
\fImunmap\fR()
call. The initial read or write reference to a mapped region shall cause
the file's last data access timestamp to be marked for update if it has
not already been marked for update.
.P
The last data modification and last file status change timestamps
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\fR()
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 timestamps shall be marked
for update at some time after the write reference.
.P
There may be implementation-defined limits on the number of memory
regions that can be mapped (per process or per system).
.P
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\fR()
is implementation-defined.
.P
If
\fImmap\fR()
fails for reasons other than
.BR [EBADF] ,
.BR [EINVAL] ,
or
.BR [ENOTSUP] ,
some of the mappings in the address range starting at
.IR addr
and continuing for
.IR len
bytes may have been unmapped.
.SH "RETURN VALUE"
Upon successful completion, the
\fImmap\fR()
function shall return the address at which the mapping was placed (\c
.IR pa );
otherwise, it shall return a value of MAP_FAILED and set
.IR errno
to indicate the error. The symbol MAP_FAILED is defined in the
.IR <sys/mman.h> 
header. No successful return from
\fImmap\fR()
shall return the value MAP_FAILED.
.SH ERRORS
The
\fImmap\fR()
function shall fail if:
.TP
.BR EACCES
The
.IR fildes
argument is not open for read, regardless of the protection specified,
or
.IR fildes
is not open for write and PROT_WRITE was specified for a MAP_SHARED
type mapping.
.TP
.BR EAGAIN
The mapping could not be locked in memory, if required by
\fImlockall\fR(),
due to a lack of resources.
.TP
.BR EBADF
The
.IR fildes
argument is not a valid open file descriptor.
.TP
.BR EINVAL
The value of
.IR len
is zero.
.TP
.BR EINVAL
The value of
.IR flags
is invalid (neither MAP_PRIVATE nor MAP_SHARED is set).
.TP
.BR EMFILE
The number of mapped regions would exceed an implementation-defined
limit (per process or per system).
.TP
.BR ENODEV
The
.IR fildes
argument refers to a file whose type is not supported by
\fImmap\fR().
.TP
.BR ENOMEM
MAP_FIXED was specified, and the range
[\fIaddr\fP,\fIaddr\fP+\fIlen\fR) 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
.BR ENOMEM
The mapping could not be locked in memory, if required by
\fImlockall\fR(),
because it would require more space than the system is able to supply.
.TP
.BR ENOMEM
Not enough unallocated memory resources remain in the typed memory
object designated by
.IR fildes
to allocate
.IR len
bytes.
.TP
.BR ENOTSUP
MAP_FIXED or MAP_PRIVATE was specified in the
.IR flags
argument and the implementation does not support this functionality.
.RS 12 
.P
The implementation does not support the combination of accesses
requested in the
.IR prot
argument.
.RE
.TP
.BR ENXIO
Addresses in the range [\fIoff\fP,\fIoff\fP+\fIlen\fR) are invalid
for the object specified by
.IR fildes .
.TP
.BR ENXIO
MAP_FIXED was specified in
.IR flags
and the combination of
.IR addr ,
.IR len ,
and
.IR off
is invalid for the object specified by
.IR fildes .
.TP
.BR ENXIO
The
.IR fildes
argument refers to a typed memory object that is not accessible from
the calling process.
.TP
.BR EOVERFLOW
The file is a regular file and the value of
.IR off
plus
.IR len
exceeds the offset maximum established in the open file description
associated with
.IR fildes .
.br
.P
The
\fImmap\fR()
function may fail if:
.TP
.BR EINVAL
The
.IR addr
argument (if MAP_FIXED was specified) or
.IR off
is not a multiple of the page size as returned by
\fIsysconf\fR(),
or is considered invalid by the implementation.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
Use of
\fImmap\fR()
may reduce the amount of memory available to other memory allocation
functions.
.P
Use of MAP_FIXED may result in unspecified behavior in further use of
\fImalloc\fR()
and
\fIshmat\fR().
The use of MAP_FIXED is discouraged, as it may prevent an
implementation from making the most effective use of resources. Most
implementations require that
.IR off
and
.IR addr
are multiples of the page size as returned by
\fIsysconf\fR().
.P
The application must ensure correct synchronization when using
\fImmap\fR()
in conjunction with any other file access method, such as
\fIread\fR()
and
\fIwrite\fR(),
standard input/output, and
\fIshmat\fR().
.P
The
\fImmap\fR()
function allows access to resources via address space manipulations,
instead of
\fIread\fR()/\c
\fIwrite\fR().
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\fR(),
the following:
.sp
.RS 4
.nf

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

fildes = open(...)
address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
/* Use data at address. */
.fi
.P
.RE
.SH RATIONALE
After considering several other alternatives, it was decided to adopt
the
\fImmap\fR()
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.
.P
Note that while
\fImmap\fR()
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.
.P
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.
.P
If an application requests a mapping that overlaps existing mappings
in the process, it might be desirable that an implementation detect
this and inform the application. However, 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\fR()
before an
\fImmap\fR()
to the same address range. This volume of POSIX.1\(hy2017 specifies that the new mapping
replaces any existing mappings (implying an automatic
\fImunmap\fR()
on the address range), following existing practice in this regard.
The standard developers also considered whether there should be a way
for new mappings to overlay existing mappings, but found no existing
practice for this.
.P
It is not expected that all hardware implementations are able to
support all combinations of permissions at all addresses.
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\fR()
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 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.
.P
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.
.P
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.
.P
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\fR().
.P
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\fR()
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
.IR addr
and not to specify MAP_FIXED.
.P
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.
.P
The
\fImmap\fR()
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.
.P
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\fR().
.P
Process memory locking does apply to shared memory regions, and the
MCL_FUTURE argument to
\fImlockall\fR()
can be relied upon to cause new shared memory regions to be
automatically locked.
.P
Existing implementations of
\fImmap\fR()
return the value \-1 when unsuccessful. Since the casting of this
value to type
.BR "void *"
cannot be guaranteed by the ISO\ C standard to be distinct from a successful
value, this volume of POSIX.1\(hy2017 defines the symbol MAP_FAILED,
which a conforming implementation does not return as the result of a
successful call.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIexec\fR\^",
.IR "\fIfcntl\fR\^(\|)",
.IR "\fIfork\fR\^(\|)",
.IR "\fIlockf\fR\^(\|)",
.IR "\fImsync\fR\^(\|)",
.IR "\fImunmap\fR\^(\|)",
.IR "\fImprotect\fR\^(\|)",
.IR "\fIposix_typed_mem_open\fR\^(\|)",
.IR "\fIshmat\fR\^(\|)",
.IR "\fIsysconf\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<sys_mman.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .