1MMAP(3P)                   POSIX Programmer's Manual                  MMAP(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       mmap — map pages of memory
14

SYNOPSIS

16       #include <sys/mman.h>
17
18       void *mmap(void *addr, size_t len, int prot, int flags,
19           int fildes, off_t off);
20

DESCRIPTION

22       The mmap() function shall establish a mapping between an address  space
23       of a process and a memory object.
24
25       The  mmap()  function  shall  be  supported  for  the  following memory
26       objects:
27
28        *  Regular files
29
30        *  Shared memory objects
31
32        *  Typed memory objects
33
34       Support for any other type of file is unspecified.
35
36       The format of the call is as follows:
37
38           pa=mmap(addr, len, prot, flags, fildes, off);
39
40       The mmap() function shall establish a mapping between the address space
41       of the process at an address pa for len bytes to the memory object rep‐
42       resented by the file descriptor fildes at offset off for len bytes. The
43       value of pa is an implementation-defined function of the parameter addr
44       and the values of flags, further described below. A  successful  mmap()
45       call  shall  return  pa as its result. The address range starting at pa
46       and continuing for len bytes shall be legitimate for the possible  (not
47       necessarily  current)  address space of the process. The range of bytes
48       starting at off and continuing for len bytes shall  be  legitimate  for
49       the  possible  (not  necessarily  current) offsets in the memory object
50       represented by fildes.
51
52       If fildes represents a typed  memory  object  opened  with  either  the
53       POSIX_TYPED_MEM_ALLOCATE  flag  or  the POSIX_TYPED_MEM_ALLOCATE_CONTIG
54       flag, the memory object to be mapped shall be that portion of the typed
55       memory  object  allocated  by the implementation as specified below. In
56       this case, if off is non-zero, the behavior of mmap() is undefined.  If
57       fildes  refers  to  a  valid typed memory object that is not accessible
58       from the calling process, mmap() shall fail.
59
60       The mapping established by mmap() shall replace any  previous  mappings
61       for  those  whole pages containing any part of the address space of the
62       process starting at pa and continuing for len bytes.
63
64       If the size of the mapped file changes after the call to  mmap()  as  a
65       result of some other operation on the mapped file, the effect of refer‐
66       ences to portions of the mapped region  that  correspond  to  added  or
67       removed portions of the file is unspecified.
68
69       If len is zero, mmap() shall fail and no mapping shall be established.
70
71       The  parameter  prot  determines  whether read, write, execute, or some
72       combination of accesses are permitted to the  data  being  mapped.  The
73       prot  shall  be  either PROT_NONE or the bitwise-inclusive OR of one or
74       more of the  other  flags  in  the  following  table,  defined  in  the
75       <sys/mman.h> header.
76
77                   ┌──────────────────┬──────────────────────────┐
78Symbolic Constant Description        
79                   ├──────────────────┼──────────────────────────┤
80                   │PROT_READ         │ Data can be read.        │
81                   │PROT_WRITE        │ Data can be written.     │
82                   │PROT_EXEC         │ Data can be executed.    │
83                   │PROT_NONE         │ Data cannot be accessed. │
84                   └──────────────────┴──────────────────────────┘
85       If  an  implementation  cannot  support the combination of access types
86       specified by prot, the call to mmap() shall fail.
87
88       An implementation may permit accesses other  than  those  specified  by
89       prot;  however,  the implementation shall not permit a write to succeed
90       where PROT_WRITE has not been set and shall not permit any access where
91       PROT_NONE alone has been set. The implementation shall support at least
92       the following values of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the
93       bitwise-inclusive  OR  of PROT_READ and PROT_WRITE. The file descriptor
94       fildes shall have been opened with read permission, regardless  of  the
95       protection  options specified. If PROT_WRITE is specified, the applica‐
96       tion shall ensure that it has opened the file  descriptor  fildes  with
97       write permission unless MAP_PRIVATE is specified in the flags parameter
98       as described below.
99
100       The parameter flags provides other information about  the  handling  of
101       the  mapped  data.   The  value of flags is the bitwise-inclusive OR of
102       these options, defined in <sys/mman.h>:
103
104                    ┌──────────────────┬─────────────────────────┐
105Symbolic Constant Description       
106                    ├──────────────────┼─────────────────────────┤
107                    │MAP_SHARED        │ Changes are shared.     │
108                    │MAP_PRIVATE       │ Changes are private.    │
109                    │MAP_FIXED         │ Interpret addr exactly. │
110                    └──────────────────┴─────────────────────────┘
111       It is implementation-defined  whether  MAP_FIXED  shall  be  supported.
112       MAP_FIXED shall be supported on XSI-conformant systems.
113
114       MAP_SHARED and MAP_PRIVATE describe the disposition of write references
115       to the memory object. If  MAP_SHARED  is  specified,  write  references
116       shall  change the underlying object. If MAP_PRIVATE is specified, modi‐
117       fications to the mapped data by the calling process  shall  be  visible
118       only to the calling process and shall not change the underlying object.
119       It is unspecified whether modifications to the underlying  object  done
120       after  the  MAP_PRIVATE  mapping is established are visible through the
121       MAP_PRIVATE mapping. Either MAP_SHARED or MAP_PRIVATE can be specified,
122       but not both. The mapping type is retained across fork().
123
124       The  state of synchronization objects such as mutexes, semaphores, bar‐
125       riers, and conditional variables placed in shared  memory  mapped  with
126       MAP_SHARED  becomes  undefined when the last region in any process con‐
127       taining the synchronization object is unmapped.
128
129       When fildes represents a typed memory object  opened  with  either  the
130       POSIX_TYPED_MEM_ALLOCATE  flag  or  the POSIX_TYPED_MEM_ALLOCATE_CONTIG
131       flag, mmap() shall, if there are enough resources  available,  map  len
132       bytes  allocated  from the corresponding typed memory object which were
133       not previously allocated to any  process  in  any  processor  that  may
134       access  that  typed  memory  object.  If there are not enough resources
135       available, the function shall fail. If fildes represents a typed memory
136       object  opened  with  the  POSIX_TYPED_MEM_ALLOCATE_CONTIG  flag, these
137       allocated bytes shall be contiguous within the typed memory object.  If
138       fildes   represents   a   typed   memory   object   opened   with   the
139       POSIX_TYPED_MEM_ALLOCATE flag, these allocated bytes may be composed of
140       non-contiguous fragments within the typed memory object. If fildes rep‐
141       resents   a   typed   memory   object   opened   with    neither    the
142       POSIX_TYPED_MEM_ALLOCATE_CONTIG  flag  nor the POSIX_TYPED_MEM_ALLOCATE
143       flag, len bytes starting at offset off within the typed  memory  object
144       are  mapped, exactly as when mapping a file or shared memory object. In
145       this case, if two processes map an area of typed memory using the  same
146       off  and  len  values and using file descriptors that refer to the same
147       memory pool (either from the same port or from a different port),  both
148       processes shall map the same region of storage.
149
150       When  MAP_FIXED  is  set  in  the flags argument, the implementation is
151       informed that the value of pa shall be addr, exactly. If  MAP_FIXED  is
152       set,  mmap()  may  return  MAP_FAILED  and set errno to [EINVAL].  If a
153       MAP_FIXED request is successful,  the  mapping  established  by  mmap()
154       replaces  any  previous mappings for the pages in the range [pa,pa+len)
155       of the process.
156
157       When MAP_FIXED is not set, the implementation uses addr in an implemen‐
158       tation-defined  manner  to  arrive at pa.  The pa so chosen shall be an
159       area of the address space that the implementation deems suitable for  a
160       mapping of len bytes to the file. All implementations interpret an addr
161       value of 0 as granting the implementation complete freedom in selecting
162       pa, subject to constraints described below. A non-zero value of addr is
163       taken to be a suggestion of a process address near  which  the  mapping
164       should  be  placed.  When the implementation selects a value for pa, it
165       never places a mapping at address 0, nor does  it  replace  any  extant
166       mapping.
167
168       If  MAP_FIXED is specified and addr is non-zero, it shall have the same
169       remainder as the off parameter, modulo the page  size  as  returned  by
170       sysconf() when passed _SC_PAGESIZE or _SC_PAGE_SIZE. The implementation
171       may require that off is a multiple of the page size.  If  MAP_FIXED  is
172       specified,  the  implementation  may require that addr is a multiple of
173       the page size. The system performs mapping operations over whole pages.
174       Thus,  while  the  parameter len need not meet a size or alignment con‐
175       straint, the system shall include, in any mapping operation,  any  par‐
176       tial  page specified by the address range starting at pa and continuing
177       for len bytes.
178
179       The system shall always zero-fill any partial page at  the  end  of  an
180       object. Further, the system shall never write out any modified portions
181       of the last page of an object which are  beyond  its  end.   References
182       within the address range starting at pa and continuing for len bytes to
183       whole pages following the end of an object shall result in delivery  of
184       a SIGBUS signal.
185
186       An  implementation  may  generate SIGBUS signals when a reference would
187       cause an error in the mapped object, such as out-of-space condition.
188
189       The mmap() function shall add an extra reference to the file associated
190       with  the  file  descriptor fildes which is not removed by a subsequent
191       close() on that file descriptor. This reference shall be  removed  when
192       there are no more mappings to the file.
193
194       The  last  data  access  timestamp of the mapped file may be marked for
195       update at any time between the mmap() call and the  corresponding  mun‐
196       map()  call.  The  initial  read  or write reference to a mapped region
197       shall cause the file's last data access  timestamp  to  be  marked  for
198       update if it has not already been marked for update.
199
200       The  last data modification and last file status change timestamps of a
201       file that is mapped with MAP_SHARED and PROT_WRITE shall be marked  for
202       update  at  some point in the interval between a write reference to the
203       mapped region and the next call to msync() with MS_ASYNC or MS_SYNC for
204       that  portion of the file by any process.  If there is no such call and
205       if the underlying file is modified as a result of  a  write  reference,
206       then these timestamps shall be marked for update at some time after the
207       write reference.
208
209       There may be implementation-defined limits  on  the  number  of  memory
210       regions that can be mapped (per process or per system).
211
212       If  such  a limit is imposed, whether the number of memory regions that
213       can be mapped by a process is decreased by the use of shmat() is imple‐
214       mentation-defined.
215
216       If mmap() fails for reasons other than [EBADF], [EINVAL], or [ENOTSUP],
217       some of the mappings in the address range starting at addr and continu‐
218       ing for len bytes may have been unmapped.
219

RETURN VALUE

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

ERRORS

228       The mmap() function shall fail if:
229
230       EACCES The fildes argument is not open for read, regardless of the pro‐
231              tection  specified,  or  fildes  is  not  open  for  write   and
232              PROT_WRITE was specified for a MAP_SHARED type mapping.
233
234       EAGAIN The mapping could not be locked in memory, if required by mlock‐
235              all(), due to a lack of resources.
236
237       EBADF  The fildes argument is not a valid open file descriptor.
238
239       EINVAL The value of len is zero.
240
241       EINVAL The  value  of  flags  is  invalid  (neither   MAP_PRIVATE   nor
242              MAP_SHARED is set).
243
244       EMFILE The  number  of  mapped  regions would exceed an implementation-
245              defined limit (per process or per system).
246
247       ENODEV The fildes argument refers to a file whose type is not supported
248              by mmap().
249
250       ENOMEM MAP_FIXED  was  specified, and the range [addr,addr+len) exceeds
251              that allowed  for  the  address  space  of  a  process;  or,  if
252              MAP_FIXED  was  not  specified and there is insufficient room in
253              the address space to effect the mapping.
254
255       ENOMEM The mapping could not be locked in memory, if required by mlock‐
256              all(),  because  it  would require more space than the system is
257              able to supply.
258
259       ENOMEM Not enough unallocated memory resources remain in the typed mem‐
260              ory object designated by fildes to allocate len bytes.
261
262       ENOTSUP
263              MAP_FIXED or MAP_PRIVATE was specified in the flags argument and
264              the implementation does not support this functionality.
265
266                   The implementation does  not  support  the  combination  of
267                   accesses requested in the prot argument.
268
269       ENXIO  Addresses  in the range [off,off+len) are invalid for the object
270              specified by fildes.
271
272       ENXIO  MAP_FIXED was specified in flags and the  combination  of  addr,
273              len, and off is invalid for the object specified by fildes.
274
275       ENXIO  The  fildes argument refers to a typed memory object that is not
276              accessible from the calling process.
277
278       EOVERFLOW
279              The file is a regular file and the value of off plus len exceeds
280              the  offset  maximum  established  in  the open file description
281              associated with fildes.
282
283       The mmap() function may fail if:
284
285       EINVAL The addr argument (if MAP_FIXED was specified) or off is  not  a
286              multiple  of  the page size as returned by sysconf(), or is con‐
287              sidered invalid by the implementation.
288
289       The following sections are informative.
290

EXAMPLES

292       None.
293

APPLICATION USAGE

295       Use of mmap() may reduce the amount of memory available to other memory
296       allocation functions.
297
298       Use  of  MAP_FIXED may result in unspecified behavior in further use of
299       malloc() and shmat().  The use of MAP_FIXED is discouraged, as  it  may
300       prevent  an  implementation  from  making  the  most  effective  use of
301       resources. Most implementations require that off and addr are multiples
302       of the page size as returned by sysconf().
303
304       The  application  must ensure correct synchronization when using mmap()
305       in conjunction with any other file access method, such  as  read()  and
306       write(), standard input/output, and shmat().
307
308       The mmap() function allows access to resources via address space manip‐
309       ulations, instead of read()/write().  Once a  file  is  mapped,  all  a
310       process  has to do to access it is use the data at the address to which
311       the file was mapped. So, using pseudo-code to  illustrate  the  way  in
312       which  an  existing program might be changed to use mmap(), the follow‐
313       ing:
314
315           fildes = open(...)
316           lseek(fildes, some_offset)
317           read(fildes, buf, len)
318           /* Use data in buf. */
319
320       becomes:
321
322           fildes = open(...)
323           address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
324           /* Use data at address. */
325

RATIONALE

327       After considering several other alternatives, it was decided  to  adopt
328       the  mmap()  definition  found  in SVR4 for mapping memory objects into
329       process address spaces. The SVR4 definition  is  minimal,  in  that  it
330       describes  only  what  has been built, and what appears to be necessary
331       for a general and portable mapping facility.
332
333       Note that while mmap() was first designed  for  mapping  files,  it  is
334       actually  a general-purpose mapping facility. It can be used to map any
335       appropriate object, such as memory, files, devices, and so on, into the
336       address space of a process.
337
338       When  a  mapping is established, it is possible that the implementation
339       may need to map more than is requested into the address  space  of  the
340       process because of hardware requirements. An application, however, can‐
341       not count on this behavior. Implementations that do  not  use  a  paged
342       architecture  may simply allocate a common memory region and return the
343       address of it; such implementations probably do not allocate  any  more
344       than  is  necessary.  References past the end of the requested area are
345       unspecified.
346
347       If an application requests a mapping that would overlay  existing  map‐
348       pings  in  the  process,  it  might be desirable that an implementation
349       detect this and inform the application. However, the default,  portable
350       (not  MAP_FIXED)  operation  does not overlay existing mappings. On the
351       other hand, if the program specifies a  fixed  address  mapping  (which
352       requires some implementation knowledge to determine a suitable address,
353       if the function is supported at all), then the program is  presumed  to
354       be  successfully  managing  its own address space and should be trusted
355       when it asks to map over existing data structures. Furthermore,  it  is
356       also desirable to make as few system calls as possible, and it might be
357       considered onerous to require an munmap() before an mmap() to the  same
358       address  range. This volume of POSIX.1‐2008 specifies that the new map‐
359       pings replace any existing mappings,  following  existing  practice  in
360       this regard.
361
362       It  is  not expected that all hardware implementations are able to sup‐
363       port all combinations of permissions at all addresses.  Implementations
364       are required to disallow write access to mappings without write permis‐
365       sion and to disallow access to mappings without any access  permission.
366       Other  than  these restrictions, implementations may allow access types
367       other than those requested by the  application.  For  example,  if  the
368       application requests only PROT_WRITE, the implementation may also allow
369       read access. A call to mmap() fails if the implementation  cannot  sup‐
370       port allowing all the access requested by the application. For example,
371       some implementations cannot support a request for both write access and
372       execute   access   simultaneously.  All  implementations  must  support
373       requests for no access, read access, write access, and  both  read  and
374       write  access.  Strictly conforming code must only rely on the required
375       checks. These restrictions allow for portability across a wide range of
376       hardware.
377
378       The  MAP_FIXED address treatment is likely to fail for non-page-aligned
379       values and for certain architecture-dependent address ranges.  Conform‐
380       ing implementations cannot count on being able to choose address values
381       for MAP_FIXED without  utilizing  non-portable,  implementation-defined
382       knowledge.  Nonetheless,  MAP_FIXED is provided as a standard interface
383       conforming to existing practice for utilizing such knowledge when it is
384       available.
385
386       Similarly,  in  order to allow implementations that do not support vir‐
387       tual addresses, support for directly specifying any  mapping  addresses
388       via MAP_FIXED is not required and thus a conforming application may not
389       count on it.
390
391       The MAP_PRIVATE function can be  implemented  efficiently  when  memory
392       protection  hardware is available. When such hardware is not available,
393       implementations can implement such ``mappings'' by simply making a real
394       copy  of  the  relevant  data  into process private memory, though this
395       tends to behave similarly to read().
396
397       The function has been defined to allow for  many  different  models  of
398       using  shared memory. However, all uses are not equally portable across
399       all machine architectures. In particular, the  mmap()  function  allows
400       the  system  as well as the application to specify the address at which
401       to map a specific region of a memory object. The most portable  way  to
402       use the function is always to let the system choose the address, speci‐
403       fying NULL as the value for  the  argument  addr  and  not  to  specify
404       MAP_FIXED.
405
406       If it is intended that a particular region of a memory object be mapped
407       at the same address in a group of processes (on machines where this  is
408       even  possible), then MAP_FIXED can be used to pass in the desired map‐
409       ping address. The system can  still  be  used  to  choose  the  desired
410       address if the first such mapping is made without specifying MAP_FIXED,
411       and then the resulting mapping address can be passed to subsequent pro‐
412       cesses  for  them  to pass in via MAP_FIXED. The availability of a spe‐
413       cific address range cannot be guaranteed, in general.
414
415       The mmap() function can be used to map  a  region  of  memory  that  is
416       larger  than  the  current size of the object. Memory access within the
417       mapping but beyond the current end of the underlying objects may result
418       in  SIGBUS  signals  being  sent to the process. The reason for this is
419       that the size of the object can be manipulated by other  processes  and
420       can  change  at any moment. The implementation should tell the applica‐
421       tion that a memory reference is outside the object where  this  can  be
422       detected;  otherwise,  written  data  may be lost and read data may not
423       reflect actual data in the object.
424
425       Note that references beyond the end of the object  do  not  extend  the
426       object  as  the  new end cannot be determined precisely by most virtual
427       memory hardware. Instead, the  size  can  be  directly  manipulated  by
428       ftruncate().
429
430       Process  memory  locking  does  apply to shared memory regions, and the
431       MEMLOCK_FUTURE argument to mlockall() can be relied upon to  cause  new
432       shared memory regions to be automatically locked.
433
434       Existing  implementations of mmap() return the value −1 when unsuccess‐
435       ful. Since the casting of this value to type void * cannot  be  guaran‐
436       teed by the ISO C standard to be distinct from a successful value, this
437       volume of POSIX.1‐2008 defines the symbol MAP_FAILED, which a  conform‐
438       ing implementation does not return as the result of a successful call.
439

FUTURE DIRECTIONS

441       None.
442

SEE ALSO

444       exec,   fcntl(),   fork(),   lockf(),  msync(),  munmap(),  mprotect(),
445       posix_typed_mem_open(), shmat(), sysconf()
446
447       The Base Definitions volume of POSIX.1‐2008, <sys_mman.h>
448
450       Portions of this text are reprinted and reproduced in  electronic  form
451       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
452       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
453       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
454       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
455       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
456       event of any discrepancy between this version and the original IEEE and
457       The  Open Group Standard, the original IEEE and The Open Group Standard
458       is the referee document. The original Standard can be  obtained  online
459       at http://www.unix.org/online.html .
460
461       Any  typographical  or  formatting  errors that appear in this page are
462       most likely to have been introduced during the conversion of the source
463       files  to  man page format. To report such errors, see https://www.ker
464       nel.org/doc/man-pages/reporting_bugs.html .
465
466
467
468IEEE/The Open Group                  2013                             MMAP(3P)
Impressum