mmap.3p (23113B)
- '\" 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 .