1mmap(2) System Calls mmap(2)
2
6 mmap - map pages of memory
7
9 #include <sys/mman.h>
10 void *mmap(void *addr, size_t len, int prot, int flags,
12 int fildes, off_t off);
13
16 The mmap() function establishes a mapping between a process's address
17 space and a file or shared memory object. The format of the call is as
18 follows:
19 pa = mmap(addr, len, prot, flags, fildes, off);
22 The mmap() function establishes a mapping between the address space of
25 the process at an address pa for len bytes to the memory object repre‐
26 sented by the file descriptor fildes at offset off for len bytes. The
27 value of pa is a function of the addr argument and values of flags,
28 further described below. A successful mmap() call returns pa as its
29 result. The address range starting at pa and continuing for len bytes
30 will be legitimate for the possible (not necessarily current) address
31 space of the process. The range of bytes starting at off and continuing
32 for len bytes will be legitimate for the possible (not necessarily cur‐
33 rent) offsets in the file or shared memory object represented by
34 fildes.
35 The mmap() function allows [pa, pa + len) to extend beyond the end of
38 the object both at the time of the mmap() and while the mapping per‐
39 sists, such as when the file is created prior to the mmap() call and
40 has no contents, or when the file is truncated. Any reference to
41 addresses beyond the end of the object, however, will result in the
42 delivery of a SIGBUS or SIGSEGV signal. The mmap() function cannot be
43 used to implicitly extend the length of files.
44 The mapping established by mmap() replaces any previous mappings for
47 those whole pages containing any part of the address space of the
48 process starting at pa and continuing for len bytes.
49 If the size of the mapped file changes after the call to mmap() as a
52 result of some other operation on the mapped file, the effect of refer‐
53 ences to portions of the mapped region that correspond to added or
54 removed portions of the file is unspecified.
55 The mmap() function is supported for regular files and shared memory
58 objects. Support for any other type of file is unspecified.
59 The prot argument determines whether read, write, execute, or some
62 combination of accesses are permitted to the data being mapped. The
63 prot argument should be either PROT_NONE or the bitwise inclusive OR of
64 one or more of the other flags in the following table, defined in the
65 header <sys/mman.h>.
66 PROT_READ Data can be read.
68 PROT_WRITE Data can be written.
71 PROT_EXEC Data can be executed.
74 PROT_NONE Data cannot be accessed.
77 If an implementation of mmap() for a specific platform cannot support
81 the combination of access types specified by prot, the call to mmap()
82 fails. An implementation may permit accesses other than those specified
83 by prot; however, the implementation will not permit a write to succeed
84 where PROT_WRITE has not been set or permit any access where PROT_NONE
85 alone has been set. Each platform-specific implementation of mmap()
86 supports the following values of prot: PROT_NONE, PROT_READ,
87 PROT_WRITE, and the inclusive OR of PROT_READ and PROT_WRITE. On some
88 platforms, the PROT_WRITE protection option is implemented as
89 PROT_READ|PROT_WRITE and PROT_EXEC as PROT_READ|PROT_EXEC. The file
90 descriptor fildes is opened with read permission, regardless of the
91 protection options specified. If PROT_WRITE is specified, the applica‐
92 tion must have opened the file descriptor fildes with write permission
93 unless MAP_PRIVATE is specified in the flags argument as described
94 below.
95 The flags argument provides other information about the handling of
98 the mapped data. The value of flags is the bitwise inclusive OR of
99 these options, defined in <sys/mman.h>:
100 MAP_SHARED Changes are shared.
102 MAP_PRIVATE Changes are private.
105 MAP_FIXED Interpret addr exactly.
108 MAP_NORESERVE Do not reserve swap space.
111 MAP_ANON Map anonymous memory.
114 MAP_ALIGN Interpret addr as required aligment.
117 MAP_TEXT Map text.
120 MAP_INITDATA Map initialized data segment.
123 The MAP_SHARED and MAP_PRIVATE options describe the disposition of
127 write references to the underlying object. If MAP_SHARED is specified,
128 write references will change the memory object. If MAP_PRIVATE is spec‐
129 ified, the initial write reference will create a private copy of the
130 memory object page and redirect the mapping to the copy. The private
131 copy is not created until the first write; until then, other users who
132 have the object mapped MAP_SHARED can change the object. Either
133 MAP_SHARED or MAP_PRIVATE must be specified, but not both. The mapping
134 type is retained across fork(2).
135 When MAP_FIXED is set in the flags argument, the system is informed
138 that the value of pa must be addr, exactly. If MAP_FIXED is set, mmap()
139 may return (void *)−1 and set errno to EINVAL. If a MAP_FIXED request
140 is successful, the mapping established by mmap() replaces any previous
141 mappings for the process's pages in the range [pa, pa + len). The use
142 of MAP_FIXED is discouraged, since it may prevent a system from making
143 the most effective use of its resources.
144 When MAP_FIXED is set and the requested address is the same as previous
147 mapping, the previous address is unmapped and the new mapping is cre‐
148 ated on top of the old one.
149 When MAP_FIXED is not set, the system uses addr to arrive at pa. The pa
152 so chosen will be an area of the address space that the system deems
153 suitable for a mapping of len bytes to the file. The mmap() function
154 interprets an addr value of 0 as granting the system complete freedom
155 in selecting pa, subject to constraints described below. A non-zero
156 value of addr is taken to be a suggestion of a process address near
157 which the mapping should be placed. When the system selects a value for
158 pa, it will never place a mapping at address 0, nor will it replace any
159 extant mapping, nor map into areas considered part of the potential
160 data or stack "segments".
161 When MAP_ALIGN is set, the system is informed that the alignment of pa
164 must be the same as addr. The alignment value in addr must be 0 or some
165 power of two multiple of page size as returned by sysconf(3C). If addr
166 is 0, the system will choose a suitable alignment.
167 The MAP_NORESERVE option specifies that no swap space be reserved for a
170 mapping. Without this flag, the creation of a writable MAP_PRIVATE map‐
171 ping reserves swap space equal to the size of the mapping; when the
172 mapping is written into, the reserved space is employed to hold private
173 copies of the data. A write into a MAP_NORESERVE mapping produces
174 results which depend on the current availability of swap space in the
175 system. If space is available, the write succeeds and a private copy
176 of the written page is created; if space is not available, the write
177 fails and a SIGBUS or SIGSEGV signal is delivered to the writing
178 process. MAP_NORESERVE mappings are inherited across fork(); at the
179 time of the fork(), swap space is reserved in the child for all private
180 pages that currently exist in the parent; thereafter the child's map‐
181 ping behaves as described above.
182 When MAP_ANON is set in flags, and fildes is set to -1, mmap() provides
185 a direct path to return anonymous pages to the caller. This operation
186 is equivalent to passing mmap() an open file descriptor on /dev/zero
187 with MAP_ANON elided from the flags argument.
188 The MAP_TEXT option informs the system that the mapped region will be
191 used primarily for executing instructions. This information can help
192 the system better utilize MMU resources on some platforms. This flag is
193 always passed by the dynamic linker when it maps text segments of
194 shared objects. When the MAP_TEXT option is used for regular file map‐
195 pings on some platforms, the system can choose a mapping size larger
196 than the page size returned by sysconf(3C). The specific page sizes
197 that are used depend on the platform and the alignment of the addr and
198 len arguments. Several diffrent mapping sizes can be used to map the
199 region with larger page sizes used in the parts of the region that meet
200 alignment and size requirements for those page sizes.
201 The MAP_INITDATA option informs the system that the mapped region is an
204 initialized data segment of an executable or shared object. When the
205 MAP_INITDATA option is used for regular file mappings on some plat‐
206 forms, the system can choose a mapping size larger than the page size
207 returned by sysconf(). The MAP_INITDATA option should be used only by
208 the dynamic linker for mapping initialized data of shared objects.
209 The off argument is constrained to be aligned and sized according to
212 the value returned by sysconf() when passed _SC_PAGESIZE or
213 _SC_PAGE_SIZE. When MAP_FIXED is specified, the addr argument must also
214 meet these constraints. The system performs mapping operations over
215 whole pages. Thus, while the len argument need not meet a size or
216 alignment constraint, the system will include, in any mapping opera‐
217 tion, any partial page specified by the range [pa, pa + len).
218 The system will always zero-fill any partial page at the end of an
221 object. Further, the system will never write out any modified portions
222 of the last page of an object which are beyond its end. References to
223 whole pages following the end of an object will result in the delivery
224 of a SIGBUS or SIGSEGV signal. SIGBUS signals may also be delivered on
225 various file system conditions, including quota exceeded errors.
226 The mmap() function adds an extra reference to the file associated with
229 the file descriptor fildes which is not removed by a subsequent
230 close(2) on that file descriptor. This reference is removed when there
231 are no more mappings to the file by a call to the munmap(2) function.
232 The st_atime field of the mapped file may be marked for update at any
235 time between the mmap() call and the corresponding munmap(2) call. The
236 initial read or write reference to a mapped region will cause the
237 file's st_atime field to be marked for update if it has not already
238 been marked for update.
239 The st_ctime and st_mtime fields of a file that is mapped with
242 MAP_SHARED and PROT_WRITE, will be marked for update at some point in
243 the interval between a write reference to the mapped region and the
244 next call to msync(3C) with MS_ASYNC or MS_SYNC for that portion of the
245 file by any process. If there is no such call, these fields may be
246 marked for update at any time after a write reference if the underlying
247 file is modified as a result.
248 If the process calls mlockall(3C) with the MCL_FUTURE flag, the pages
251 mapped by all future calls to mmap() will be locked in memory. In this
252 case, if not enough memory could be locked, mmap() fails and sets errno
253 to EAGAIN.
254 The mmap() function aligns based on the length of the mapping. When
257 determining the amount of space to add to the address space, mmap()
258 includes two 8-Kbyte pages, one at each end of the mapping that are not
259 mapped and are therefore used as "red-zone" pages. Attempts to refer‐
260 ence these pages result in access violations.
261 The size requested is incremented by the 16 Kbytes for these pages and
264 is then subject to rounding constraints. The constraints are:
265 o For 32-bit processes:
267 If length > 4 Mbytes
269 round to 4-Mbyte multiple
270 elseif length > 512 Kbytes
271 round to 512-Kbyte multiple
272 else
273 round to 64-Kbyte multiple
274 o For 64-bit processes:
277 If length > 4 Mbytes
279 round to 4-Mbyte multiple
280 else
281 round to 1-Mbyte multiple
282 The net result is that for a 32-bit process:
286 o If an mmap() request is made for 4 Mbytes, it results in 4
288 Mbytes + 16 Kbytes and is rounded up to 8 Mbytes.
289 o If an mmap() request is made for 512 Kbytes, it results in
291 512 Kbytes + 16 Kbytes and is rounded up to 1 Mbyte.
292 o If an mmap() request is made for 1 Mbyte, it results in 1
294 Mbyte + 16 Kbytes and is rounded up to 1.5 Mbytes.
295 o Each 8-Kbyte mmap request "consumes" 64 Kbytes of virtual
297 address space.
298 To obtain maximal address space usage for a 32-bit process:
301 o Combine 8-Kbyte requests up to a limit of 48 Kbytes.
303 o Combine amounts over 48 Kbytes into 496-Kbyte chunks.
305 o Combine amounts over 496 Kbytes into 4080-Kbyte chunks.
307 To obtain maximal address space usage for a 64-bit process:
310 o Combine amounts < 1008 Kbytes into chunks <= 1008 Kbytes.
312 o Combine amounts over 1008 Kbytes into 4080-Kbyte chunks.
314 The following is the output from a 32-bit program demonstrating this:
317 map 8192 bytes: 0xff390000
319 map 8192 bytes: 0xff380000
320 64-Kbyte delta between starting addresses.
322 map 512 Kbytes: 0xff180000
325 map 512 Kbytes: 0xff080000
326 1-Mbyte delta between starting addresses.
328 map 496 Kbytes: 0xff000000
331 map 496 Kbytes: 0xfef80000
332 512-Kbyte delta between starting addresses
334 map 1 Mbyte: 0xfee00000
337 map 1 Mbyte: 0xfec80000
338 1536-Kbyte delta between starting addresses
340 map 1008 Kbytes: 0xfeb80000
343 map 1008 Kbytes: 0xfea80000
344 1-Mbyte delta between starting addresses
346 map 4 Mbytes: 0xfe400000
349 map 4 Mbytes: 0xfdc00000
350 8-Mbyte delta between starting addresses
352 map 4080 Kbytes: 0xfd800000
355 map 4080 Kbytes: 0xfd400000
356 4-Mbyte delta between starting addresses
358 The following is the output of the same program compiled as a 64-bit
362 application:
363 map 8192 bytes: 0xffffffff7f000000
365 map 8192 bytes: 0xffffffff7ef00000
366 1-Mbyte delta between starting addresses
368 map 512 Kbytes: 0xffffffff7ee00000
371 map 512 Kbytes: 0xffffffff7ed00000
372 1-Mbyte delta between starting addresses
374 map 496 Kbytes: 0xffffffff7ec00000
377 map 496 Kbytes: 0xffffffff7eb00000
378 1-Mbyte delta between starting addresses
380 map 1 Mbyte: 0xffffffff7e900000
383 map 1 Mbyte: 0xffffffff7e700000
384 2-Mbyte delta between starting addresses
386 map 1008 Kbytes: 0xffffffff7e600000
389 map 1008 Kbytes: 0xffffffff7e500000
390 1-Mbyte delta between starting addresses
392 map 4 Mbytes: 0xffffffff7e000000
395 map 4 Mbytes: 0xffffffff7d800000
396 8-Mbyte delta between starting addresses
398 map 4080 Kbytes: 0xffffffff7d400000
401 map 4080 Kbytes: 0xffffffff7d000000
402 4-Mbyte delta between starting addresses
404
407 Upon successful completion, the mmap() function returns the address at
408 which the mapping was placed (pa); otherwise, it returns a value of
409 MAP_FAILED and sets errno to indicate the error. The symbol MAP_FAILED
410 is defined in the header <sys/mman.h>. No successful return from mmap()
411 will return the value MAP_FAILED.
412 If mmap() fails for reasons other than EBADF, EINVAL or ENOTSUP, some
415 of the mappings in the address range starting at addr and continuing
416 for len bytes may have been unmapped.
417
419 The mmap() function will fail if:
420 EACCES The fildes file descriptor is not open for read, regard‐
422 less of the protection specified; or fildes is not open
423 for write and PROT_WRITE was specified for a MAP_SHARED
424 type mapping.
425 EAGAIN The mapping could not be locked in memory.
428 There was insufficient room to reserve swap space for the
430 mapping.
431 EBADF The fildes file descriptor is not open (and MAP_ANON was
434 not specified).
435 EINVAL The arguments addr (if MAP_FIXED was specified) or off are
438 not multiples of the page size as returned by sysconf().
439 The argument addr (if MAP_ALIGN was specified) is not 0 or
441 some power of two multiple of page size as returned by
442 sysconf(3C).
443 MAP_FIXED and MAP_ALIGN are both specified.
445 The field in flags is invalid (neither MAP_PRIVATE or
447 MAP_SHARED is set).
448 The argument len has a value equal to 0.
450 MAP_ANON was specified, but the file descriptor was not
452 −1.
453 MAP_TEXT was specified but PROT_EXEC was not.
455 MAP_TEXT and MAP_INITDATA were both specified.
457 EMFILE The number of mapped regions would exceed an implementa‐
460 tion-dependent limit (per process or per system).
461 ENODEV The fildes argument refers to an object for which mmap()
464 is meaningless, such as a terminal.
465 ENOMEM The MAP_FIXED option was specified and the range [addr,
468 addr + len) exceeds that allowed for the address space of
469 a process.
470 The MAP_FIXED option was not specified and there is insuf‐
472 ficient room in the address space to effect the mapping.
473 The mapping could not be locked in memory, if required by
475 mlockall(3C), because it would require more space than the
476 system is able to supply.
477 The composite size of len plus the lengths obtained from
479 all previous calls to mmap() exceeds RLIMIT_VMEM (see
480 getrlimit(2)).
481 ENOTSUP The system does not support the combination of accesses
484 requested in the prot argument.
485 ENXIO Addresses in the range [off, off + len) are invalid for
488 the object specified by fildes.
489 The MAP_FIXED option was specified in flags and the combi‐
491 nation of addr, len and off is invalid for the object
492 specified by fildes.
493 EOVERFLOW The file is a regular file and the value of off plus len
496 exceeds the offset maximum establish in the open file
497 description associated with fildes.
498 The mmap() function may fail if:
502 EAGAIN The file to be mapped is already locked using advisory or
504 mandatory record locking. See fcntl(2).
505
508 Use of mmap() may reduce the amount of memory available to other memory
509 allocation functions.
510 MAP_ALIGN is useful to assure a properly aligned value of pa for subse‐
513 quent use with memcntl(2) and the MC_HAT_ADVISE command. This is best
514 used for large, long-lived, and heavily referenced regions. MAP_FIXED
515 and MAP_ALIGN are always mutually-exclusive.
516 Use of MAP_FIXED may result in unspecified behavior in further use of
519 brk(2), sbrk(2), malloc(3C), and shmat(2). The use of MAP_FIXED is dis‐
520 couraged, as it may prevent an implementation from making the most
521 effective use of resources.
522 The application must ensure correct synchronization when using mmap()
525 in conjunction with any other file access method, such as read(2) and
526 write(2), standard input/output, and shmat(2).
527 The mmap() function has a transitional interface for 64-bit file off‐
530 sets. See lf64(5).
531 The mmap() function allows access to resources using address space
534 manipulations instead of the read()/write() interface. Once a file is
535 mapped, all a process has to do to access it is use the data at the
536 address to which the object was mapped.
537 Consider the following pseudo-code:
540 fildes = open(...)
542 lseek(fildes, offset, whence)
543 read(fildes, buf, len)
544 /* use data in buf */
545 The following is a rewrite using mmap():
549 fildes = open(...)
551 address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE),
552 MAP_PRIVATE, fildes, offset)
553 /* use data at address */
554
557 See attributes(5) for descriptions of the following attributes:
558 ┌─────────────────────────────┬─────────────────────────────┐
563 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
564 ├─────────────────────────────┼─────────────────────────────┤
565 │Interface Stability │Standard │
566 ├─────────────────────────────┼─────────────────────────────┤
567 │MT-Level │Async-Signal-Safe │
568 └─────────────────────────────┴─────────────────────────────┘
569
571 close(2), exec(2), fcntl(2), fork(2), getrlimit(2), memcntl(2),
572 mmapobj(2), mprotect(2), munmap(2), shmat(2), lockf(3C), mlockall(3C),
573 msync(3C), plock(3C), sysconf(3C), attributes(5), lf64(5), stan‐
574 dards(5), null(7D), zero(7D)
575SunOS 5.11 4 Feb 2009 mmap(2)