mmap(3p) — Linux manual page

PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

MMAP(3P)                POSIX Programmer's Manual               MMAP(3P)

PROLOG         top

       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.

NAME         top

       mmap — map pages of memory

SYNOPSIS         top

       #include <sys/mman.h>

       void *mmap(void *addr, size_t len, int prot, int flags,
           int fildes, off_t off);

DESCRIPTION         top

       The mmap() function shall establish a mapping between an address
       space of a process and a memory object.

       The mmap() function shall be supported for the following memory
       objects:

        *  Regular files

        *  Shared memory objects

        *  Typed memory objects

       Support for any other type of file is unspecified.

       The format of the call is as follows:

           pa=mmap(addr, len, prot, flags, fildes, off);

       The mmap() function shall establish a mapping between the address
       space of the process at an address pa for len bytes to the memory
       object represented by the file descriptor fildes at offset off
       for len bytes. The value of pa is an implementation-defined
       function of the parameter addr and the values of flags, further
       described below. A successful mmap() call shall return pa as its
       result. The address range starting at pa and continuing for len
       bytes shall be legitimate for the possible (not necessarily
       current) address space of the process. The range of bytes
       starting at off and continuing for len bytes shall be legitimate
       for the possible (not necessarily current) offsets in the memory
       object represented by fildes.

       If 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 off is
       non-zero, the behavior of mmap() is undefined. If fildes refers
       to a valid typed memory object that is not accessible from the
       calling process, mmap() shall fail.

       The mapping established by mmap() shall replace any previous
       mappings for those whole pages containing any part of the address
       space of the process starting at pa and continuing for len bytes.

       If the size of the mapped file changes after the call to mmap()
       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.

       If len is zero, mmap() shall fail and no mapping shall be
       established.

       The parameter prot determines whether read, write, execute, or
       some combination of accesses are permitted to the data being
       mapped. The 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 <sys/mman.h> header.
               ┌───────────────────┬──────────────────────────┐
               │ 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. │
               └───────────────────┴──────────────────────────┘

       If an implementation cannot support the combination of access
       types specified by prot, the call to mmap() shall fail.

       An implementation may permit accesses other than those specified
       by 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 prot: PROT_NONE,
       PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of PROT_READ
       and PROT_WRITE. The file descriptor 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 fildes with write
       permission unless MAP_PRIVATE is specified in the flags parameter
       as described below.

       The parameter flags provides other information about the handling
       of the mapped data.  The value of flags is the bitwise-inclusive
       OR of these options, defined in <sys/mman.h>:
               ┌───────────────────┬─────────────────────────┐
               │ Symbolic Constant Description       │
               ├───────────────────┼─────────────────────────┤
               │ MAP_SHARED        │ Changes are shared.     │
               │ MAP_PRIVATE       │ Changes are private.    │
               │ MAP_FIXED         │ Interpret addr exactly. │
               └───────────────────┴─────────────────────────┘

       It is implementation-defined whether MAP_FIXED shall be
       supported.  MAP_FIXED shall be supported on XSI-conformant
       systems.

       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
       fork().

       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.

       When fildes represents a typed memory object opened with either
       the POSIX_TYPED_MEM_ALLOCATE flag or the
       POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, mmap() shall, if there are
       enough resources available, map 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 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 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 fildes represents a typed memory object opened with
       neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the
       POSIX_TYPED_MEM_ALLOCATE flag, len bytes starting at offset 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 off and 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.

       When MAP_FIXED is set in the flags argument, the implementation
       is informed that the value of pa shall be addr, exactly. If
       MAP_FIXED is set, mmap() may return MAP_FAILED and set errno to
       [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 [pa,pa+len) shall be
       removed, as if by an appropriate call to munmap(), before the new
       mapping is established.

       When MAP_FIXED is not set, the implementation uses addr in an
       implementation-defined manner to arrive at pa.  The pa so chosen
       shall be an area of the address space that the implementation
       deems suitable for a mapping of len bytes to the file. All
       implementations interpret an addr value of 0 as granting the
       implementation 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 implementation selects a value for pa,
       it never places a mapping at address 0, nor does it replace any
       extant mapping.

       If MAP_FIXED is specified and addr is non-zero, it shall have the
       same remainder as the off parameter, modulo the page size as
       returned by sysconf() 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 addr is a multiple of the page size. The system performs
       mapping operations over whole pages. Thus, while the parameter
       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 pa and continuing for
       len bytes.

       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 pa and continuing
       for len bytes to whole pages following the end of an object shall
       result in delivery of a SIGBUS signal.

       An implementation may generate SIGBUS signals when a reference
       would cause an error in the mapped object, such as out-of-space
       condition.

       The mmap() function shall add an extra reference to the file
       associated with the file descriptor fildes which is not removed
       by a subsequent close() on that file descriptor. This reference
       shall be removed when there are no more mappings to the file.

       The last data access timestamp of the mapped file may be marked
       for update at any time between the mmap() call and the
       corresponding munmap() 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.

       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 msync() 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.

       There may be implementation-defined limits on the number of
       memory regions that can be mapped (per process or per system).

       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
       shmat() is implementation-defined.

       If mmap() fails for reasons other than [EBADF], [EINVAL], or
       [ENOTSUP], some of the mappings in the address range starting at
       addr and continuing for len bytes may have been unmapped.

RETURN VALUE         top

       Upon successful completion, the mmap() function shall return the
       address at which the mapping was placed (pa); otherwise, it shall
       return a value of MAP_FAILED and set errno to indicate the error.
       The symbol MAP_FAILED is defined in the <sys/mman.h> header. No
       successful return from mmap() shall return the value MAP_FAILED.

ERRORS         top

       The mmap() function shall fail if:

       EACCES The fildes argument is not open for read, regardless of
              the protection specified, or fildes is not open for write
              and PROT_WRITE was specified for a MAP_SHARED type
              mapping.

       EAGAIN The mapping could not be locked in memory, if required by
              mlockall(), due to a lack of resources.

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

       EINVAL The value of len is zero.

       EINVAL The value of flags is invalid (neither MAP_PRIVATE nor
              MAP_SHARED is set).

       EMFILE The number of mapped regions would exceed an
              implementation-defined limit (per process or per system).

       ENODEV The fildes argument refers to a file whose type is not
              supported by mmap().

       ENOMEM MAP_FIXED was specified, and the range [addr,addr+len)
              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.

       ENOMEM The mapping could not be locked in memory, if required by
              mlockall(), because it would require more space than the
              system is able to supply.

       ENOMEM Not enough unallocated memory resources remain in the
              typed memory object designated by fildes to allocate len
              bytes.

       ENOTSUP
              MAP_FIXED or MAP_PRIVATE was specified in the flags
              argument and the implementation does not support this
              functionality.

                   The implementation does not support the combination
                   of accesses requested in the prot argument.

       ENXIO  Addresses in the range [off,off+len) are invalid for the
              object specified by fildes.

       ENXIO  MAP_FIXED was specified in flags and the combination of
              addr, len, and off is invalid for the object specified by
              fildes.

       ENXIO  The fildes argument refers to a typed memory object that
              is not accessible from the calling process.

       EOVERFLOW
              The file is a regular file and the value of off plus len
              exceeds the offset maximum established in the open file
              description associated with fildes.

       The mmap() function may fail if:

       EINVAL The addr argument (if MAP_FIXED was specified) or off is
              not a multiple of the page size as returned by sysconf(),
              or is considered invalid by the implementation.

       The following sections are informative.

EXAMPLES         top

       None.

APPLICATION USAGE         top

       Use of mmap() may reduce the amount of memory available to other
       memory allocation functions.

       Use of MAP_FIXED may result in unspecified behavior in further
       use of malloc() and shmat().  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 off and addr are multiples of the page size as returned by
       sysconf().

       The application must ensure correct synchronization when using
       mmap() in conjunction with any other file access method, such as
       read() and write(), standard input/output, and shmat().

       The mmap() function allows access to resources via address space
       manipulations, instead of read()/write().  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 mmap(), the following:

           fildes = open(...)
           lseek(fildes, some_offset)
           read(fildes, buf, len)
           /* Use data in buf. */

       becomes:

           fildes = open(...)
           address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
           /* Use data at address. */

RATIONALE         top

       After considering several other alternatives, it was decided to
       adopt the mmap() 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.

       Note that while mmap() 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.

       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.

       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
       munmap() before an mmap() to the same address range. This volume
       of POSIX.1‐2017 specifies that the new mapping replaces any
       existing mappings (implying an automatic munmap() 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.

       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 mmap() 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.

       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.

       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.

       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 read().

       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
       mmap() 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 addr and not to specify MAP_FIXED.

       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.

       The mmap() 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.

       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 ftruncate().

       Process memory locking does apply to shared memory regions, and
       the MCL_FUTURE argument to mlockall() can be relied upon to cause
       new shared memory regions to be automatically locked.

       Existing implementations of mmap() return the value -1 when
       unsuccessful. Since the casting of this value to type void *
       cannot be guaranteed by the ISO C standard to be distinct from a
       successful value, this volume of POSIX.1‐2017 defines the symbol
       MAP_FAILED, which a conforming implementation does not return as
       the result of a successful call.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       exec(1p), fcntl(3p), fork(3p), lockf(3p), msync(3p), munmap(3p),
       mprotect(3p), posix_typed_mem_open(3p), shmat(3p), sysconf(3p)

       The Base Definitions volume of POSIX.1‐2017, sys_mman.h(0p)

COPYRIGHT         top

       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 .

       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 .

IEEE/The Open Group               2017                          MMAP(3P)

Pages that refer to this page: sys_mman.h(0p)exec(3p)lockf(3p)mprotect(3p)msync(3p)munmap(3p)posix_madvise(3p)posix_mem_offset(3p)posix_typed_mem_get_info(3p)posix_typed_mem_open(3p)shm_open(3p)shm_unlink(3p)