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

NAME

6       mmap - map pages of memory
7

SYNOPSIS

9       #include <sys/mman.h>
10
11       void *mmap(void *addr, size_t len, int prot, int flags,
12              int fildes, off_t off);
13
14

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

269       None.
270

APPLICATION USAGE

272       Use of mmap() may reduce the amount of memory available to other memory
273       allocation functions.
274
275       Use of MAP_FIXED may result in unspecified behavior in further  use  of
276       malloc()  and  shmat().  The use of MAP_FIXED is discouraged, as it may
277       prevent an  implementation  from  making  the  most  effective  use  of
278       resources.
279
280       The  application  must ensure correct synchronization when using mmap()
281       in conjunction with any other file access method, such  as  read()  and
282       write(), standard input/output, and shmat().
283
284       The mmap() function allows access to resources via address space manip‐
285       ulations, instead of read()/ write(). Once a  file  is  mapped,  all  a
286       process  has to do to access it is use the data at the address to which
287       the file was mapped. So, using pseudo-code to  illustrate  the  way  in
288       which  an  existing program might be changed to use mmap(), the follow‐
289       ing:
290
291
292              fildes = open(...)
293              lseek(fildes, some_offset)
294              read(fildes, buf, len)
295              /* Use data in buf. */
296
297       becomes:
298
299
300              fildes = open(...)
301              address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
302              /* Use data at address. */
303

RATIONALE

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

FUTURE DIRECTIONS

421       None.
422

SEE ALSO

424       exec() , fcntl() , fork() , lockf() , msync() , munmap() , mprotect() ,
425       posix_typed_mem_open() , shmat() , sysconf()  ,  the  Base  Definitions
426       volume of IEEE Std 1003.1-2001, <sys/mman.h>
427
429       Portions  of  this text are reprinted and reproduced in electronic form
430       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
431       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
432       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
433       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
434       event of any discrepancy between this version and the original IEEE and
435       The  Open Group Standard, the original IEEE and The Open Group Standard
436       is the referee document. The original Standard can be  obtained  online
437       at http://www.opengroup.org/unix/online.html .
438
439
440
441IEEE/The Open Group                  2003                              MMAP(P)
Impressum