Provided by: manpages-posix-dev_2017a-2_all bug

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.

NAME

       mmap — map pages of memory

SYNOPSIS

       #include <sys/mman.h>

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

DESCRIPTION

       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 ConstantDescription        │
                             ├──────────────────┼──────────────────────────┤
                             │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 ConstantDescription       │
                             ├──────────────────┼─────────────────────────┤
                             │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

       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

       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

       None.

APPLICATION USAGE

       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

       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

       None.

SEE ALSO

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

       The Base Definitions volume of POSIX.1‐2017, <sys_mman.h>

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 .

       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 .