1MMAP(3P) POSIX Programmer's Manual MMAP(3P)
2
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
12 mmap — map pages of memory
13
15 #include <sys/mman.h>
16 void *mmap(void *addr, size_t len, int prot, int flags,
18 int fildes, off_t off);
19
21 The mmap() function shall establish a mapping between an address space
22 of a process and a memory object.
23 The mmap() function shall be supported for the following memory
25 objects:
26 * Regular files
28 * Shared memory objects
30 * Typed memory objects
32 Support for any other type of file is unspecified.
34 The format of the call is as follows:
36 pa=mmap(addr, len, prot, flags, fildes, off);
39 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 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 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 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 If len is zero, mmap() shall fail and no mapping shall be established.
70 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 ┌──────────────────┬──────────────────────────┐
78 │Symbolic 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 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 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 ┌──────────────────┬─────────────────────────┐
105 │Symbolic 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 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 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 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 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, then any previous mappings or memory
154 locks for those whole pages containing any part of the address range
155 [pa,pa+len) shall be removed, as if by an appropriate call to munmap(),
156 before the new mapping is established.
157 When MAP_FIXED is not set, the implementation uses addr in an implemen‐
159 tation-defined manner to arrive at pa. The pa so chosen shall be an
160 area of the address space that the implementation deems suitable for a
161 mapping of len bytes to the file. All implementations interpret an addr
162 value of 0 as granting the implementation complete freedom in selecting
163 pa, subject to constraints described below. A non-zero value of addr is
164 taken to be a suggestion of a process address near which the mapping
165 should be placed. When the implementation selects a value for pa, it
166 never places a mapping at address 0, nor does it replace any extant
167 mapping.
168 If MAP_FIXED is specified and addr is non-zero, it shall have the same
170 remainder as the off parameter, modulo the page size as returned by
171 sysconf() when passed _SC_PAGESIZE or _SC_PAGE_SIZE. The implementation
172 may require that off is a multiple of the page size. If MAP_FIXED is
173 specified, the implementation may require that addr is a multiple of
174 the page size. The system performs mapping operations over whole pages.
175 Thus, while the parameter len need not meet a size or alignment con‐
176 straint, the system shall include, in any mapping operation, any par‐
177 tial page specified by the address range starting at pa and continuing
178 for len bytes.
179 The system shall always zero-fill any partial page at the end of an
181 object. Further, the system shall never write out any modified portions
182 of the last page of an object which are beyond its end. References
183 within the address range starting at pa and continuing for len bytes to
184 whole pages following the end of an object shall result in delivery of
185 a SIGBUS signal.
186 An implementation may generate SIGBUS signals when a reference would
188 cause an error in the mapped object, such as out-of-space condition.
189 The mmap() function shall add an extra reference to the file associated
191 with the file descriptor fildes which is not removed by a subsequent
192 close() on that file descriptor. This reference shall be removed when
193 there are no more mappings to the file.
194 The last data access timestamp of the mapped file may be marked for
196 update at any time between the mmap() call and the corresponding mun‐
197 map() call. The initial read or write reference to a mapped region
198 shall cause the file's last data access timestamp to be marked for
199 update if it has not already been marked for update.
200 The last data modification and last file status change timestamps of a
202 file that is mapped with MAP_SHARED and PROT_WRITE shall be marked for
203 update at some point in the interval between a write reference to the
204 mapped region and the next call to msync() with MS_ASYNC or MS_SYNC for
205 that portion of the file by any process. If there is no such call and
206 if the underlying file is modified as a result of a write reference,
207 then these timestamps shall be marked for update at some time after the
208 write reference.
209 There may be implementation-defined limits on the number of memory
211 regions that can be mapped (per process or per system).
212 If such a limit is imposed, whether the number of memory regions that
214 can be mapped by a process is decreased by the use of shmat() is imple‐
215 mentation-defined.
216 If mmap() fails for reasons other than [EBADF], [EINVAL], or [ENOTSUP],
218 some of the mappings in the address range starting at addr and continu‐
219 ing for len bytes may have been unmapped.
220
222 Upon successful completion, the mmap() function shall return the
223 address at which the mapping was placed (pa); otherwise, it shall
224 return a value of MAP_FAILED and set errno to indicate the error. The
225 symbol MAP_FAILED is defined in the <sys/mman.h> header. No successful
226 return from mmap() shall return the value MAP_FAILED.
227
229 The mmap() function shall fail if:
230 EACCES The fildes argument is not open for read, regardless of the pro‐
232 tection specified, or fildes is not open for write and
233 PROT_WRITE was specified for a MAP_SHARED type mapping.
234 EAGAIN The mapping could not be locked in memory, if required by mlock‐
236 all(), due to a lack of resources.
237 EBADF The fildes argument is not a valid open file descriptor.
239 EINVAL The value of len is zero.
241 EINVAL The value of flags is invalid (neither MAP_PRIVATE nor
243 MAP_SHARED is set).
244 EMFILE The number of mapped regions would exceed an implementation-
246 defined limit (per process or per system).
247 ENODEV The fildes argument refers to a file whose type is not supported
249 by mmap().
250 ENOMEM MAP_FIXED was specified, and the range [addr,addr+len) exceeds
252 that allowed for the address space of a process; or, if
253 MAP_FIXED was not specified and there is insufficient room in
254 the address space to effect the mapping.
255 ENOMEM The mapping could not be locked in memory, if required by mlock‐
257 all(), because it would require more space than the system is
258 able to supply.
259 ENOMEM Not enough unallocated memory resources remain in the typed mem‐
261 ory object designated by fildes to allocate len bytes.
262 ENOTSUP
264 MAP_FIXED or MAP_PRIVATE was specified in the flags argument and
265 the implementation does not support this functionality.
266 The implementation does not support the combination of
268 accesses requested in the prot argument.
269 ENXIO Addresses in the range [off,off+len) are invalid for the object
271 specified by fildes.
272 ENXIO MAP_FIXED was specified in flags and the combination of addr,
274 len, and off is invalid for the object specified by fildes.
275 ENXIO The fildes argument refers to a typed memory object that is not
277 accessible from the calling process.
278 EOVERFLOW
280 The file is a regular file and the value of off plus len exceeds
281 the offset maximum established in the open file description
282 associated with fildes.
283 The mmap() function may fail if:
285 EINVAL The addr argument (if MAP_FIXED was specified) or off is not a
287 multiple of the page size as returned by sysconf(), or is con‐
288 sidered invalid by the implementation.
289 The following sections are informative.
291
293 None.
294
296 Use of mmap() may reduce the amount of memory available to other memory
297 allocation functions.
298 Use of MAP_FIXED may result in unspecified behavior in further use of
300 malloc() and shmat(). The use of MAP_FIXED is discouraged, as it may
301 prevent an implementation from making the most effective use of
302 resources. Most implementations require that off and addr are multiples
303 of the page size as returned by sysconf().
304 The application must ensure correct synchronization when using mmap()
306 in conjunction with any other file access method, such as read() and
307 write(), standard input/output, and shmat().
308 The mmap() function allows access to resources via address space manip‐
310 ulations, instead of read()/write(). Once a file is mapped, all a
311 process has to do to access it is use the data at the address to which
312 the file was mapped. So, using pseudo-code to illustrate the way in
313 which an existing program might be changed to use mmap(), the follow‐
314 ing:
315 fildes = open(...)
318 lseek(fildes, some_offset)
319 read(fildes, buf, len)
320 /* Use data in buf. */
321 becomes:
323 fildes = open(...)
326 address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
327 /* Use data at address. */
328
330 After considering several other alternatives, it was decided to adopt
331 the mmap() definition found in SVR4 for mapping memory objects into
332 process address spaces. The SVR4 definition is minimal, in that it
333 describes only what has been built, and what appears to be necessary
334 for a general and portable mapping facility.
335 Note that while mmap() was first designed for mapping files, it is
337 actually a general-purpose mapping facility. It can be used to map any
338 appropriate object, such as memory, files, devices, and so on, into the
339 address space of a process.
340 When a mapping is established, it is possible that the implementation
342 may need to map more than is requested into the address space of the
343 process because of hardware requirements. An application, however, can‐
344 not count on this behavior. Implementations that do not use a paged
345 architecture may simply allocate a common memory region and return the
346 address of it; such implementations probably do not allocate any more
347 than is necessary. References past the end of the requested area are
348 unspecified.
349 If an application requests a mapping that overlaps existing mappings in
351 the process, it might be desirable that an implementation detect this
352 and inform the application. However, if the program specifies a fixed
353 address mapping (which requires some implementation knowledge to deter‐
354 mine a suitable address, if the function is supported at all), then the
355 program is presumed to be successfully managing its own address space
356 and should be trusted when it asks to map over existing data struc‐
357 tures. Furthermore, it is also desirable to make as few system calls as
358 possible, and it might be considered onerous to require an munmap()
359 before an mmap() to the same address range. This volume of POSIX.1‐2017
360 specifies that the new mapping replaces any existing mappings (implying
361 an automatic munmap() on the address range), following existing prac‐
362 tice in this regard. The standard developers also considered whether
363 there should be a way for new mappings to overlay existing mappings,
364 but found no existing practice for this.
365 It is not expected that all hardware implementations are able to sup‐
367 port all combinations of permissions at all addresses. Implementations
368 are required to disallow write access to mappings without write permis‐
369 sion and to disallow access to mappings without any access permission.
370 Other than these restrictions, implementations may allow access types
371 other than those requested by the application. For example, if the
372 application requests only PROT_WRITE, the implementation may also allow
373 read access. A call to mmap() fails if the implementation cannot sup‐
374 port allowing all the access requested by the application. For example,
375 some implementations cannot support a request for both write access and
376 execute access simultaneously. All implementations must support
377 requests for no access, read access, write access, and both read and
378 write access. Strictly conforming code must only rely on the required
379 checks. These restrictions allow for portability across a wide range of
380 hardware.
381 The MAP_FIXED address treatment is likely to fail for non-page-aligned
383 values and for certain architecture-dependent address ranges. Conform‐
384 ing implementations cannot count on being able to choose address values
385 for MAP_FIXED without utilizing non-portable, implementation-defined
386 knowledge. Nonetheless, MAP_FIXED is provided as a standard interface
387 conforming to existing practice for utilizing such knowledge when it is
388 available.
389 Similarly, in order to allow implementations that do not support vir‐
391 tual addresses, support for directly specifying any mapping addresses
392 via MAP_FIXED is not required and thus a conforming application may not
393 count on it.
394 The MAP_PRIVATE function can be implemented efficiently when memory
396 protection hardware is available. When such hardware is not available,
397 implementations can implement such ``mappings'' by simply making a real
398 copy of the relevant data into process private memory, though this
399 tends to behave similarly to read().
400 The function has been defined to allow for many different models of
402 using shared memory. However, all uses are not equally portable across
403 all machine architectures. In particular, the mmap() function allows
404 the system as well as the application to specify the address at which
405 to map a specific region of a memory object. The most portable way to
406 use the function is always to let the system choose the address, speci‐
407 fying NULL as the value for the argument addr and not to specify
408 MAP_FIXED.
409 If it is intended that a particular region of a memory object be mapped
411 at the same address in a group of processes (on machines where this is
412 even possible), then MAP_FIXED can be used to pass in the desired map‐
413 ping address. The system can still be used to choose the desired
414 address if the first such mapping is made without specifying MAP_FIXED,
415 and then the resulting mapping address can be passed to subsequent pro‐
416 cesses for them to pass in via MAP_FIXED. The availability of a spe‐
417 cific address range cannot be guaranteed, in general.
418 The mmap() function can be used to map a region of memory that is
420 larger than the current size of the object. Memory access within the
421 mapping but beyond the current end of the underlying objects may result
422 in SIGBUS signals being sent to the process. The reason for this is
423 that the size of the object can be manipulated by other processes and
424 can change at any moment. The implementation should tell the applica‐
425 tion that a memory reference is outside the object where this can be
426 detected; otherwise, written data may be lost and read data may not
427 reflect actual data in the object.
428 Note that references beyond the end of the object do not extend the
430 object as the new end cannot be determined precisely by most virtual
431 memory hardware. Instead, the size can be directly manipulated by
432 ftruncate().
433 Process memory locking does apply to shared memory regions, and the
435 MCL_FUTURE argument to mlockall() can be relied upon to cause new
436 shared memory regions to be automatically locked.
437 Existing implementations of mmap() return the value -1 when unsuccess‐
439 ful. Since the casting of this value to type void * cannot be guaran‐
440 teed by the ISO C standard to be distinct from a successful value, this
441 volume of POSIX.1‐2017 defines the symbol MAP_FAILED, which a conform‐
442 ing implementation does not return as the result of a successful call.
443
445 None.
446
448 exec, fcntl(), fork(), lockf(), msync(), munmap(), mprotect(),
449 posix_typed_mem_open(), shmat(), sysconf()
450 The Base Definitions volume of POSIX.1‐2017, <sys_mman.h>
452
454 Portions of this text are reprinted and reproduced in electronic form
455 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
456 table Operating System Interface (POSIX), The Open Group Base Specifi‐
457 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
458 Electrical and Electronics Engineers, Inc and The Open Group. In the
459 event of any discrepancy between this version and the original IEEE and
460 The Open Group Standard, the original IEEE and The Open Group Standard
461 is the referee document. The original Standard can be obtained online
462 at http://www.opengroup.org/unix/online.html .
463 Any typographical or formatting errors that appear in this page are
465 most likely to have been introduced during the conversion of the source
466 files to man page format. To report such errors, see https://www.ker‐
467 nel.org/doc/man-pages/reporting_bugs.html .
468IEEE/The Open Group 2017 MMAP(3P)