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, the mapping established by mmap()
       replaces any previous mappings for the pages in the range [pa,pa+len)
       of the process.

       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 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
       munmap() before an mmap() to the same address range. This volume of
       POSIX.1‐2008 specifies that the new mappings replace any existing
       mappings, following existing practice in this regard.

       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
       MEMLOCK_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‐2008 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‐2008, sys_mman.h(0p)

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The Open
       Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
       applied.) 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.unix.org/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                 2013                            MMAP(3P)