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
22 The mmap() function shall establish a mapping between a process'
23 address space and a file, shared memory object, or typed memory
24 object. The format of the call is as follows:
25 pa=mmap(addr, len, prot, flags, fildes, off);
28 The mmap() function shall establish a mapping between the address space
30 of the process at an address pa for len bytes to the memory object rep‐
31 resented by the file descriptor fildes at offset off for len bytes.
32 The value of pa is an implementation-defined function of the parameter
33 addr and the values of flags, further described below. A successful
34 mmap() call shall return pa as its result. The address range starting
35 at pa and continuing for len bytes shall be legitimate for the possible
36 (not necessarily current) address space of the process. The range of
37 bytes starting at off and continuing for len bytes shall be legitimate
38 for the possible (not necessarily current) offsets in the file, shared
39 memory object, or typed memory object represented by fildes.
40 If fildes represents a typed memory object opened with either the
42 POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG
43 flag, the memory object to be mapped shall be that portion of the typed
44 memory object allocated by the implementation as specified below. In
45 this case, if off is non-zero, the behavior of mmap() is undefined. If
46 fildes refers to a valid typed memory object that is not accessible
47 from the calling process, mmap() shall fail.
48 The mapping established by mmap() shall replace any previous mappings
50 for those whole pages containing any part of the address space of the
51 process starting at pa and continuing for len bytes.
52 If the size of the mapped file changes after the call to mmap() as a
54 result of some other operation on the mapped file, the effect of refer‐
55 ences to portions of the mapped region that correspond to added or
56 removed portions of the file is unspecified.
57 The mmap() function shall be supported for regular files, shared memory
59 objects, and typed memory objects. Support for any other type of file
60 is unspecified.
61 The parameter prot determines whether read, write, execute, or some
63 combination of accesses are permitted to the data being mapped. The
64 prot shall be either PROT_NONE or the bitwise-inclusive OR of one or
65 more of the other flags in the following table, defined in the
66 <sys/mman.h> header.
67 Symbolic Constant Description
69 PROT_READ Data can be read.
70 PROT_WRITE Data can be written.
71 PROT_EXEC Data can be executed.
72 PROT_NONE Data cannot be accessed.
73 If an implementation cannot support the combination of access types
75 specified by prot, the call to mmap() shall fail.
76 An implementation may permit accesses other than those specified by
78 prot; however, if the Memory Protection option is supported, the
79 implementation shall not permit a write to succeed where PROT_WRITE has
80 not been set or shall not permit any access where PROT_NONE alone has
81 been set. The implementation shall support at least the following val‐
82 ues of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclu‐
83 sive OR of PROT_READ and PROT_WRITE. If the Memory Protection option
84 is not supported, the result of any access that conflicts with the
85 specified protection is undefined. The file descriptor fildes shall
86 have been opened with read permission, regardless of the protection
87 options specified. If PROT_WRITE is specified, the application shall
88 ensure that it has opened the file descriptor fildes with write permis‐
89 sion unless MAP_PRIVATE is specified in the flags parameter as
90 described below.
91 The parameter flags provides other information about the handling of
93 the mapped data. The value of flags is the bitwise-inclusive OR of
94 these options, defined in <sys/mman.h>:
95 Symbolic Constant Description
97 MAP_SHARED Changes are shared.
98 MAP_PRIVATE Changes are private.
99 MAP_FIXED Interpret addr exactly.
100 Implementations that do not support the Memory Mapped Files option are
102 not required to support MAP_PRIVATE.
103 It is implementation-defined whether MAP_FIXED shall be supported.
105 MAP_FIXED shall be supported on XSI-conformant systems.
106 MAP_SHARED and MAP_PRIVATE describe the disposition of write references
108 to the memory object. If MAP_SHARED is specified, write references
109 shall change the underlying object. If MAP_PRIVATE is specified, modi‐
110 fications to the mapped data by the calling process shall be visible
111 only to the calling process and shall not change the underlying object.
112 It is unspecified whether modifications to the underlying object done
113 after the MAP_PRIVATE mapping is established are visible through the
114 MAP_PRIVATE mapping. Either MAP_SHARED or MAP_PRIVATE can be specified,
115 but not both. The mapping type is retained across fork().
116 When fildes represents a typed memory object opened with either the
118 POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG
119 flag, mmap() shall, if there are enough resources available, map len
120 bytes allocated from the corresponding typed memory object which were
121 not previously allocated to any process in any processor that may
122 access that typed memory object. If there are not enough resources
123 available, the function shall fail. If fildes represents a typed memory
124 object opened with the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these
125 allocated bytes shall be contiguous within the typed memory object. If
126 fildes represents a typed memory object opened with the
127 POSIX_TYPED_MEM_ALLOCATE flag, these allocated bytes may be composed of
128 non-contiguous fragments within the typed memory object. If fildes rep‐
129 resents a typed memory object opened with neither the
130 POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the POSIX_TYPED_MEM_ALLOCATE
131 flag, len bytes starting at offset off within the typed memory object
132 are mapped, exactly as when mapping a file or shared memory object. In
133 this case, if two processes map an area of typed memory using the same
134 off and len values and using file descriptors that refer to the same
135 memory pool (either from the same port or from a different port), both
136 processes shall map the same region of storage.
137 When MAP_FIXED is set in the flags argument, the implementation is
139 informed that the value of pa shall be addr, exactly. If MAP_FIXED is
140 set, mmap() may return MAP_FAILED and set errno to [EINVAL]. If a
141 MAP_FIXED request is successful, the mapping established by mmap()
142 replaces any previous mappings for the process' pages in the range
143 [pa,pa+len).
144 When MAP_FIXED is not set, the implementation uses addr in an implemen‐
146 tation-defined manner to arrive at pa. The pa so chosen shall be an
147 area of the address space that the implementation deems suitable for a
148 mapping of len bytes to the file. All implementations interpret an addr
149 value of 0 as granting the implementation complete freedom in selecting
150 pa, subject to constraints described below. A non-zero value of addr is
151 taken to be a suggestion of a process address near which the mapping
152 should be placed. When the implementation selects a value for pa, it
153 never places a mapping at address 0, nor does it replace any extant
154 mapping.
155 The off argument is constrained to be aligned and sized according to
157 the value returned by sysconf() when passed _SC_PAGESIZE or
158 _SC_PAGE_SIZE. When MAP_FIXED is specified, the application shall
159 ensure that the argument addr also meets these constraints. The imple‐
160 mentation performs mapping operations over whole pages. Thus, while the
161 argument len need not meet a size or alignment constraint, the imple‐
162 mentation shall include, in any mapping operation, any partial page
163 specified by the range [pa,pa+len).
164 The system shall always zero-fill any partial page at the end of an
166 object. Further, the system shall never write out any modified portions
167 of the last page of an object which are beyond its end. References
168 within the address range starting at pa and continuing for len bytes to
169 whole pages following the end of an object shall result in delivery of
170 a SIGBUS signal.
171 An implementation may generate SIGBUS signals when a reference would
173 cause an error in the mapped object, such as out-of-space condition.
174 The mmap() function shall add an extra reference to the file associated
176 with the file descriptor fildes which is not removed by a subsequent
177 close() on that file descriptor. This reference shall be removed when
178 there are no more mappings to the file.
179 The st_atime field of the mapped file may be marked for update at any
181 time between the mmap() call and the corresponding munmap() call. The
182 initial read or write reference to a mapped region shall cause the
183 file's st_atime field to be marked for update if it has not already
184 been marked for update.
185 The st_ctime and st_mtime fields of a file that is mapped with
187 MAP_SHARED and PROT_WRITE shall be marked for update at some point in
188 the interval between a write reference to the mapped region and the
189 next call to msync() with MS_ASYNC or MS_SYNC for that portion of the
190 file by any process. If there is no such call and if the underlying
191 file is modified as a result of a write reference, then these fields
192 shall be marked for update at some time after the write reference.
193 There may be implementation-defined limits on the number of memory
195 regions that can be mapped (per process or per system).
196 If such a limit is imposed, whether the number of memory regions that
198 can be mapped by a process is decreased by the use of shmat() is imple‐
199 mentation-defined.
200 If mmap() fails for reasons other than [EBADF], [EINVAL], or [ENOTSUP],
202 some of the mappings in the address range starting at addr and continu‐
203 ing for len bytes may have been unmapped.
204
206 Upon successful completion, the mmap() function shall return the
207 address at which the mapping was placed ( pa); otherwise, it shall
208 return a value of MAP_FAILED and set errno to indicate the error. The
209 symbol MAP_FAILED is defined in the <sys/mman.h> header. No successful
210 return from mmap() shall return the value MAP_FAILED.
211
213 The mmap() function shall fail if:
214 EACCES The fildes argument is not open for read, regardless of the pro‐
216 tection specified, or fildes is not open for write and
217 PROT_WRITE was specified for a MAP_SHARED type mapping.
218 EAGAIN The mapping could not be locked in memory, if required by mlock‐
220 all(), due to a lack of resources.
221 EBADF The fildes argument is not a valid open file descriptor.
223 EINVAL The addr argument (if MAP_FIXED was specified) or off is not a
225 multiple of the page size as returned by sysconf(), or is con‐
226 sidered invalid by the implementation.
227 EINVAL The value of flags is invalid (neither MAP_PRIVATE nor
229 MAP_SHARED is set).
230 EMFILE The number of mapped regions would exceed an implementation-
232 defined limit (per process or per system).
233 ENODEV The fildes argument refers to a file whose type is not supported
235 by mmap().
236 ENOMEM MAP_FIXED was specified, and the range [addr,addr+len) exceeds
238 that allowed for the address space of a process; or, if
239 MAP_FIXED was not specified and there is insufficient room in
240 the address space to effect the mapping.
241 ENOMEM The mapping could not be locked in memory, if required by mlock‐
243 all(), because it would require more space than the system is
244 able to supply.
245 ENOMEM Not enough unallocated memory resources remain in the typed mem‐
247 ory object designated by fildes to allocate len bytes.
248 ENOTSUP
250 MAP_FIXED or MAP_PRIVATE was specified in the flags argument and
251 the implementation does not support this functionality.
252 The implementation does not support the combination of accesses
254 requested in the prot argument.
255 ENXIO Addresses in the range [off,off+len) are invalid for the object
257 specified by fildes.
258 ENXIO MAP_FIXED was specified in flags and the combination of addr,
260 len, and off is invalid for the object specified by fildes.
261 ENXIO The fildes argument refers to a typed memory object that is not
263 accessible from the calling process.
264 EOVERFLOW
266 The file is a regular file and the value of off plus len exceeds
267 the offset maximum established in the open file description
268 associated with fildes.
269 The following sections are informative.
272
274 None.
275
277 Use of mmap() may reduce the amount of memory available to other memory
278 allocation functions.
279 Use of MAP_FIXED may result in unspecified behavior in further use of
281 malloc() and shmat(). The use of MAP_FIXED is discouraged, as it may
282 prevent an implementation from making the most effective use of
283 resources.
284 The application must ensure correct synchronization when using mmap()
286 in conjunction with any other file access method, such as read() and
287 write(), standard input/output, and shmat().
288 The mmap() function allows access to resources via address space manip‐
290 ulations, instead of read()/ write(). Once a file is mapped, all a
291 process has to do to access it is use the data at the address to which
292 the file was mapped. So, using pseudo-code to illustrate the way in
293 which an existing program might be changed to use mmap(), the follow‐
294 ing:
295 fildes = open(...)
298 lseek(fildes, some_offset)
299 read(fildes, buf, len)
300 /* Use data in buf. */
301 becomes:
303 fildes = open(...)
306 address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset)
307 /* Use data at address. */
308
310 After considering several other alternatives, it was decided to adopt
311 the mmap() definition found in SVR4 for mapping memory objects into
312 process address spaces. The SVR4 definition is minimal, in that it
313 describes only what has been built, and what appears to be necessary
314 for a general and portable mapping facility.
315 Note that while mmap() was first designed for mapping files, it is
317 actually a general-purpose mapping facility. It can be used to map any
318 appropriate object, such as memory, files, devices, and so on, into the
319 address space of a process.
320 When a mapping is established, it is possible that the implementation
322 may need to map more than is requested into the address space of the
323 process because of hardware requirements. An application, however, can‐
324 not count on this behavior. Implementations that do not use a paged
325 architecture may simply allocate a common memory region and return the
326 address of it; such implementations probably do not allocate any more
327 than is necessary. References past the end of the requested area are
328 unspecified.
329 If an application requests a mapping that would overlay existing map‐
331 pings in the process, it might be desirable that an implementation
332 detect this and inform the application. However, the default, portable
333 (not MAP_FIXED) operation does not overlay existing mappings. On the
334 other hand, if the program specifies a fixed address mapping (which
335 requires some implementation knowledge to determine a suitable address,
336 if the function is supported at all), then the program is presumed to
337 be successfully managing its own address space and should be trusted
338 when it asks to map over existing data structures. Furthermore, it is
339 also desirable to make as few system calls as possible, and it might be
340 considered onerous to require an munmap() before an mmap() to the same
341 address range. This volume of IEEE Std 1003.1-2001 specifies that the
342 new mappings replace any existing mappings, following existing practice
343 in this regard.
344 It is not expected, when the Memory Protection option is supported,
346 that all hardware implementations are able to support all combinations
347 of permissions at all addresses. When this option is supported, imple‐
348 mentations are required to disallow write access to mappings without
349 write permission and to disallow access to mappings without any access
350 permission. Other than these restrictions, implementations may allow
351 access types other than those requested by the application. For exam‐
352 ple, if the application requests only PROT_WRITE, the implementation
353 may also allow read access. A call to mmap() fails if the implementa‐
354 tion cannot support allowing all the access requested by the applica‐
355 tion. For example, some implementations cannot support a request for
356 both write access and execute access simultaneously. All implementa‐
357 tions supporting the Memory Protection option must support requests for
358 no access, read access, write access, and both read and write access.
359 Strictly conforming code must only rely on the required checks. These
360 restrictions allow for portability across a wide range of hardware.
361 The MAP_FIXED address treatment is likely to fail for non-page-aligned
363 values and for certain architecture-dependent address ranges. Conform‐
364 ing implementations cannot count on being able to choose address values
365 for MAP_FIXED without utilizing non-portable, implementation-defined
366 knowledge. Nonetheless, MAP_FIXED is provided as a standard interface
367 conforming to existing practice for utilizing such knowledge when it is
368 available.
369 Similarly, in order to allow implementations that do not support vir‐
371 tual addresses, support for directly specifying any mapping addresses
372 via MAP_FIXED is not required and thus a conforming application may not
373 count on it.
374 The MAP_PRIVATE function can be implemented efficiently when memory
376 protection hardware is available. When such hardware is not available,
377 implementations can implement such "mappings" by simply making a real
378 copy of the relevant data into process private memory, though this
379 tends to behave similarly to read().
380 The function has been defined to allow for many different models of
382 using shared memory. However, all uses are not equally portable across
383 all machine architectures. In particular, the mmap() function allows
384 the system as well as the application to specify the address at which
385 to map a specific region of a memory object. The most portable way to
386 use the function is always to let the system choose the address, speci‐
387 fying NULL as the value for the argument addr and not to specify
388 MAP_FIXED.
389 If it is intended that a particular region of a memory object be mapped
391 at the same address in a group of processes (on machines where this is
392 even possible), then MAP_FIXED can be used to pass in the desired map‐
393 ping address. The system can still be used to choose the desired
394 address if the first such mapping is made without specifying MAP_FIXED,
395 and then the resulting mapping address can be passed to subsequent pro‐
396 cesses for them to pass in via MAP_FIXED. The availability of a spe‐
397 cific address range cannot be guaranteed, in general.
398 The mmap() function can be used to map a region of memory that is
400 larger than the current size of the object. Memory access within the
401 mapping but beyond the current end of the underlying objects may result
402 in SIGBUS signals being sent to the process. The reason for this is
403 that the size of the object can be manipulated by other processes and
404 can change at any moment. The implementation should tell the applica‐
405 tion that a memory reference is outside the object where this can be
406 detected; otherwise, written data may be lost and read data may not
407 reflect actual data in the object.
408 Note that references beyond the end of the object do not extend the
410 object as the new end cannot be determined precisely by most virtual
411 memory hardware. Instead, the size can be directly manipulated by
412 ftruncate().
413 Process memory locking does apply to shared memory regions, and the
415 MEMLOCK_FUTURE argument to mlockall() can be relied upon to cause new
416 shared memory regions to be automatically locked.
417 Existing implementations of mmap() return the value -1 when unsuccess‐
419 ful. Since the casting of this value to type void * cannot be guaran‐
420 teed by the ISO C standard to be distinct from a successful value, this
421 volume of IEEE Std 1003.1-2001 defines the symbol MAP_FAILED, which a
422 conforming implementation does not return as the result of a successful
423 call.
424
426 None.
427
429 exec(), fcntl(), fork(), lockf(), msync(), munmap(), mprotect(),
430 posix_typed_mem_open(), shmat(), sysconf(), the Base Definitions volume
431 of IEEE Std 1003.1-2001, <sys/mman.h>
432
434 Portions of this text are reprinted and reproduced in electronic form
435 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
436 -- Portable Operating System Interface (POSIX), The Open Group Base
437 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
438 Electrical and Electronics Engineers, Inc and The Open Group. In the
439 event of any discrepancy between this version and the original IEEE and
440 The Open Group Standard, the original IEEE and The Open Group Standard
441 is the referee document. The original Standard can be obtained online
442 at http://www.opengroup.org/unix/online.html .
443IEEE/The Open Group 2003 MMAP(3P)