1 MMAP(2) System Calls MMAP(2) 2 3 4 5 NAME 6 mmap - map pages of memory 7 8 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 15 DESCRIPTION 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 20 21 pa = mmap(addr, len, prot, flags, fildes, off); 22 23 24 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 26 represented by the file descriptor fildes at offset off for len bytes. 27 The value of pa is a function of the addr argument and values of 28 flags, further described below. A successful mmap() call returns pa as 29 its result. The address range starting at pa and continuing for len 30 bytes will be legitimate for the possible (not necessarily current) 31 address space of the process. The range of bytes starting at off and 32 continuing for len bytes will be legitimate for the possible (not 33 necessarily current) offsets in the file or shared memory object 34 represented by fildes. 35 36 37 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 39 persists, 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 45 46 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 50 51 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 53 references to portions of the mapped region that correspond to added or 54 removed portions of the file is unspecified. 55 56 57 The mmap() function is supported for regular files and shared memory 58 objects. Support for any other type of file is unspecified. 59 60 61 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 67 PROT_READ 68 Data can be read. 69 70 71 PROT_WRITE 72 Data can be written. 73 74 75 PROT_EXEC 76 Data can be executed. 77 78 79 PROT_NONE 80 Data cannot be accessed. 81 82 83 84 If an implementation of mmap() for a specific platform cannot support 85 the combination of access types specified by prot, the call to mmap() 86 fails. An implementation may permit accesses other than those specified 87 by prot; however, the implementation will not permit a write to succeed 88 where PROT_WRITE has not been set or permit any access where PROT_NONE 89 alone has been set. Each platform-specific implementation of mmap() 90 supports the following values of prot: PROT_NONE, PROT_READ, 91 PROT_WRITE, and the inclusive OR of PROT_READ and PROT_WRITE. On some 92 platforms, the PROT_WRITE protection option is implemented as 93 PROT_READ|PROT_WRITE and PROT_EXEC as PROT_READ|PROT_EXEC. The file 94 descriptor fildes is opened with read permission, regardless of the 95 protection options specified. If PROT_WRITE is specified, the 96 application must have opened the file descriptor fildes with write 97 permission unless MAP_PRIVATE is specified in the flags argument as 98 described below. 99 100 101 The flags argument provides other information about the handling of 102 the mapped data. The value of flags is the bitwise inclusive OR of 103 these options, defined in <sys/mman.h>: 104 105 MAP_SHARED 106 Changes are shared. 107 108 109 MAP_PRIVATE 110 Changes are private. 111 112 113 MAP_FIXED 114 Interpret addr exactly. 115 116 117 MAP_NORESERVE 118 Do not reserve swap space. 119 120 121 MAP_ANON 122 Map anonymous memory. 123 124 125 MAP_ALIGN 126 Interpret addr as required aligment. 127 128 129 MAP_TEXT 130 Map text. 131 132 133 MAP_INITDATA 134 Map initialized data segment. 135 136 137 MAP_32BIT 138 Map to the lower 32 bits of address space. 139 140 141 MAP_FILE 142 Map a regular file. This is the default behavior; 143 specifying this flag is not required. It is provided 144 for compatibility with other systems and should not be 145 included in new code. 146 147 148 149 The MAP_SHARED and MAP_PRIVATE options describe the disposition of 150 write references to the underlying object. If MAP_SHARED is specified, 151 write references will change the memory object. If MAP_PRIVATE is 152 specified, the initial write reference will create a private copy of 153 the memory object page and redirect the mapping to the copy. The 154 private copy is not created until the first write; until then, other 155 users who have the object mapped MAP_SHARED can change the object. 156 Either MAP_SHARED or MAP_PRIVATE must be specified, but not both. The 157 mapping type is retained across fork(2). 158 159 160 When MAP_FIXED is set in the flags argument, the system is informed 161 that the value of pa must be addr, exactly. If MAP_FIXED is set, mmap() 162 may return (void *)-1 and set errno to EINVAL. If a MAP_FIXED request 163 is successful, the mapping established by mmap() replaces any previous 164 mappings for the process's pages in the range [pa, pa + len). The use 165 of MAP_FIXED is discouraged, since it may prevent a system from making 166 the most effective use of its resources. 167 168 169 When MAP_FIXED is set and the requested address is the same as previous 170 mapping, the previous address is unmapped and the new mapping is 171 created on top of the old one. 172 173 174 When MAP_FIXED is not set, the system uses addr to arrive at pa. The pa 175 so chosen will be an area of the address space that the system deems 176 suitable for a mapping of len bytes to the file. The mmap() function 177 interprets an addr value of 0 as granting the system complete freedom 178 in selecting pa, subject to constraints described below. A non-zero 179 value of addr is taken to be a suggestion of a process address near 180 which the mapping should be placed. When the system selects a value for 181 pa, it will never place a mapping at address 0, nor will it replace any 182 extant mapping, nor map into areas considered part of the potential 183 data or stack "segments". 184 185 186 When MAP_ALIGN is set, the system is informed that the alignment of pa 187 must be the same as addr. The alignment value in addr must be 0 or some 188 power of two multiple of page size as returned by sysconf(3C). If addr 189 is 0, the system will choose a suitable alignment. 190 191 192 The MAP_NORESERVE option specifies that no swap space be reserved for a 193 mapping. Without this flag, the creation of a writable MAP_PRIVATE 194 mapping reserves swap space equal to the size of the mapping; when the 195 mapping is written into, the reserved space is employed to hold private 196 copies of the data. A write into a MAP_NORESERVE mapping produces 197 results which depend on the current availability of swap space in the 198 system. If space is available, the write succeeds and a private copy 199 of the written page is created; if space is not available, the write 200 fails and a SIGBUS or SIGSEGV signal is delivered to the writing 201 process. MAP_NORESERVE mappings are inherited across fork(); at the 202 time of the fork(), swap space is reserved in the child for all private 203 pages that currently exist in the parent; thereafter the child's 204 mapping behaves as described above. 205 206 207 When MAP_ANON is set in flags, and fildes is set to -1, mmap() provides 208 a direct path to return anonymous pages to the caller. This operation 209 is equivalent to passing mmap() an open file descriptor on /dev/zero 210 with MAP_ANON elided from the flags argument. 211 212 213 The MAP_TEXT option informs the system that the mapped region will be 214 used primarily for executing instructions. This information can help 215 the system better utilize MMU resources on some platforms. This flag is 216 always passed by the dynamic linker when it maps text segments of 217 shared objects. When the MAP_TEXT option is used for regular file 218 mappings on some platforms, the system can choose a mapping size larger 219 than the page size returned by sysconf(3C). The specific page sizes 220 that are used depend on the platform and the alignment of the addr and 221 len arguments. Several different mapping sizes can be used to map the 222 region with larger page sizes used in the parts of the region that meet 223 alignment and size requirements for those page sizes. 224 225 226 The MAP_INITDATA option informs the system that the mapped region is an 227 initialized data segment of an executable or shared object. When the 228 MAP_INITDATA option is used for regular file mappings on some 229 platforms, the system can choose a mapping size larger than the page 230 size returned by sysconf(). The MAP_INITDATA option should be used only 231 by the dynamic linker for mapping initialized data of shared objects. 232 233 234 The MAP_32BIT option informs the system that the search space for 235 mapping assignment should be limited to the first 32 bits (4 Gbytes) of 236 the caller's address space. This flag is accepted in both 32-bit and 237 64-bit process models, but does not alter the mapping strategy when 238 used in a 32-bit process model. 239 240 241 The off argument is constrained to be aligned and sized according to 242 the value returned by sysconf() when passed _SC_PAGESIZE or 243 _SC_PAGE_SIZE. When MAP_FIXED is specified, the addr argument must also 244 meet these constraints. The system performs mapping operations over 245 whole pages. Thus, while the len argument need not meet a size or 246 alignment constraint, the system will include, in any mapping 247 operation, any partial page specified by the range [pa, pa + len). 248 249 250 The system will always zero-fill any partial page at the end of an 251 object. Further, the system will never write out any modified portions 252 of the last page of an object which are beyond its end. References to 253 whole pages following the end of an object will result in the delivery 254 of a SIGBUS or SIGSEGV signal. SIGBUS signals may also be delivered on 255 various file system conditions, including quota exceeded errors. 256 257 258 The mmap() function adds an extra reference to the file associated with 259 the file descriptor fildes which is not removed by a subsequent 260 close(2) on that file descriptor. This reference is removed when there 261 are no more mappings to the file by a call to the munmap(2) function. 262 263 264 The st_atime field of the mapped file may be marked for update at any 265 time between the mmap() call and the corresponding munmap(2) call. The 266 initial read or write reference to a mapped region will cause the 267 file's st_atime field to be marked for update if it has not already 268 been marked for update. 269 270 271 The st_ctime and st_mtime fields of a file that is mapped with 272 MAP_SHARED and PROT_WRITE, will be marked for update at some point in 273 the interval between a write reference to the mapped region and the 274 next call to msync(3C) with MS_ASYNC or MS_SYNC for that portion of the 275 file by any process. If there is no such call, these fields may be 276 marked for update at any time after a write reference if the underlying 277 file is modified as a result. 278 279 280 If the process calls mlockall(3C) with the MCL_FUTURE flag, the pages 281 mapped by all future calls to mmap() will be locked in memory. In this 282 case, if not enough memory could be locked, mmap() fails and sets errno 283 to EAGAIN. 284 285 286 The mmap() function aligns based on the length of the mapping. When 287 determining the amount of space to add to the address space, mmap() 288 includes two 8-Kbyte pages, one at each end of the mapping that are not 289 mapped and are therefore used as "red-zone" pages. Attempts to 290 reference these pages result in access violations. 291 292 293 The size requested is incremented by the 16 Kbytes for these pages and 294 is then subject to rounding constraints. The constraints are: 295 296 o For 32-bit processes: 297 298 If length > 4 Mbytes 299 round to 4-Mbyte multiple 300 elseif length > 512 Kbytes 301 round to 512-Kbyte multiple 302 else 303 round to 64-Kbyte multiple 304 305 306 o For 64-bit processes: 307 308 If length > 4 Mbytes 309 round to 4-Mbyte multiple 310 else 311 round to 1-Mbyte multiple 312 313 314 315 The net result is that for a 32-bit process: 316 317 o If an mmap() request is made for 4 Mbytes, it results in 4 318 Mbytes + 16 Kbytes and is rounded up to 8 Mbytes. 319 320 o If an mmap() request is made for 512 Kbytes, it results in 321 512 Kbytes + 16 Kbytes and is rounded up to 1 Mbyte. 322 323 o If an mmap() request is made for 1 Mbyte, it results in 1 324 Mbyte + 16 Kbytes and is rounded up to 1.5 Mbytes. 325 326 o Each 8-Kbyte mmap request "consumes" 64 Kbytes of virtual 327 address space. 328 329 330 To obtain maximal address space usage for a 32-bit process: 331 332 o Combine 8-Kbyte requests up to a limit of 48 Kbytes. 333 334 o Combine amounts over 48 Kbytes into 496-Kbyte chunks. 335 336 o Combine amounts over 496 Kbytes into 4080-Kbyte chunks. 337 338 339 To obtain maximal address space usage for a 64-bit process: 340 341 o Combine amounts < 1008 Kbytes into chunks <= 1008 Kbytes. 342 343 o Combine amounts over 1008 Kbytes into 4080-Kbyte chunks. 344 345 346 The following is the output from a 32-bit program demonstrating this: 347 348 map 8192 bytes: 0xff390000 349 map 8192 bytes: 0xff380000 350 351 64-Kbyte delta between starting addresses. 352 353 354 map 512 Kbytes: 0xff180000 355 map 512 Kbytes: 0xff080000 356 357 1-Mbyte delta between starting addresses. 358 359 360 map 496 Kbytes: 0xff000000 361 map 496 Kbytes: 0xfef80000 362 363 512-Kbyte delta between starting addresses 364 365 366 map 1 Mbyte: 0xfee00000 367 map 1 Mbyte: 0xfec80000 368 369 1536-Kbyte delta between starting addresses 370 371 372 map 1008 Kbytes: 0xfeb80000 373 map 1008 Kbytes: 0xfea80000 374 375 1-Mbyte delta between starting addresses 376 377 378 map 4 Mbytes: 0xfe400000 379 map 4 Mbytes: 0xfdc00000 380 381 8-Mbyte delta between starting addresses 382 383 384 map 4080 Kbytes: 0xfd800000 385 map 4080 Kbytes: 0xfd400000 386 387 4-Mbyte delta between starting addresses 388 389 390 391 The following is the output of the same program compiled as a 64-bit 392 application: 393 394 map 8192 bytes: 0xffffffff7f000000 395 map 8192 bytes: 0xffffffff7ef00000 396 397 1-Mbyte delta between starting addresses 398 399 400 map 512 Kbytes: 0xffffffff7ee00000 401 map 512 Kbytes: 0xffffffff7ed00000 402 403 1-Mbyte delta between starting addresses 404 405 406 map 496 Kbytes: 0xffffffff7ec00000 407 map 496 Kbytes: 0xffffffff7eb00000 408 409 1-Mbyte delta between starting addresses 410 411 412 map 1 Mbyte: 0xffffffff7e900000 413 map 1 Mbyte: 0xffffffff7e700000 414 415 2-Mbyte delta between starting addresses 416 417 418 map 1008 Kbytes: 0xffffffff7e600000 419 map 1008 Kbytes: 0xffffffff7e500000 420 421 1-Mbyte delta between starting addresses 422 423 424 map 4 Mbytes: 0xffffffff7e000000 425 map 4 Mbytes: 0xffffffff7d800000 426 427 8-Mbyte delta between starting addresses 428 429 430 map 4080 Kbytes: 0xffffffff7d400000 431 map 4080 Kbytes: 0xffffffff7d000000 432 433 4-Mbyte delta between starting addresses 434 435 436 RETURN VALUES 437 Upon successful completion, the mmap() function returns the address at 438 which the mapping was placed (pa); otherwise, it returns a value of 439 MAP_FAILED and sets errno to indicate the error. The symbol MAP_FAILED 440 is defined in the header <sys/mman.h>. No successful return from mmap() 441 will return the value MAP_FAILED. 442 443 444 If mmap() fails for reasons other than EBADF, EINVAL or ENOTSUP, some 445 of the mappings in the address range starting at addr and continuing 446 for len bytes may have been unmapped. 447 448 ERRORS 449 The mmap() function will fail if: 450 451 EACCES 452 The fildes file descriptor is not open for read, 453 regardless of the protection specified; or fildes is not 454 open for write and PROT_WRITE was specified for a 455 MAP_SHARED type mapping. 456 457 458 EAGAIN 459 The mapping could not be locked in memory. 460 461 There was insufficient room to reserve swap space for the 462 mapping. 463 464 465 EBADF 466 The fildes file descriptor is not open (and MAP_ANON was 467 not specified). 468 469 470 EINVAL 471 The arguments addr (if MAP_FIXED was specified) or off are 472 not multiples of the page size as returned by sysconf(). 473 474 The argument addr (if MAP_ALIGN was specified) is not 0 or 475 some power of two multiple of page size as returned by 476 sysconf(3C). 477 478 MAP_FIXED and MAP_ALIGN are both specified. 479 480 The field in flags is invalid (neither MAP_PRIVATE or 481 MAP_SHARED is set). 482 483 The argument len has a value equal to 0. 484 485 MAP_ANON was specified, but the file descriptor was not 486 -1. 487 488 MAP_TEXT was specified but PROT_EXEC was not. 489 490 MAP_TEXT and MAP_INITDATA were both specified. 491 492 493 EMFILE 494 The number of mapped regions would exceed an 495 implementation-dependent limit (per process or per 496 system). 497 498 499 ENODEV 500 The fildes argument refers to an object for which mmap() 501 is meaningless, such as a terminal. 502 503 504 ENOMEM 505 The MAP_FIXED option was specified and the range [addr, 506 addr + len) exceeds that allowed for the address space of 507 a process. 508 509 The MAP_FIXED option was not specified and there is 510 insufficient room in the address space to effect the 511 mapping. 512 513 The mapping could not be locked in memory, if required by 514 mlockall(3C), because it would require more space than the 515 system is able to supply. 516 517 The composite size of len plus the lengths obtained from 518 all previous calls to mmap() exceeds RLIMIT_VMEM (see 519 getrlimit(2)). 520 521 522 ENOTSUP 523 The system does not support the combination of accesses 524 requested in the prot argument. 525 526 527 ENXIO 528 Addresses in the range [off, off + len) are invalid for 529 the object specified by fildes. 530 531 The MAP_FIXED option was specified in flags and the 532 combination of addr, len and off is invalid for the object 533 specified by fildes. 534 535 536 EOVERFLOW 537 The file is a regular file and the value of off plus len 538 exceeds the offset maximum establish in the open file 539 description associated with fildes. 540 541 542 543 The mmap() function may fail if: 544 545 EAGAIN 546 The file to be mapped is already locked using advisory or 547 mandatory record locking. See fcntl(2). 548 549 550 USAGE 551 Use of mmap() may reduce the amount of memory available to other memory 552 allocation functions. 553 554 555 MAP_ALIGN is useful to assure a properly aligned value of pa for 556 subsequent use with memcntl(2) and the MC_HAT_ADVISE command. This is 557 best used for large, long-lived, and heavily referenced regions. 558 MAP_FIXED and MAP_ALIGN are always mutually-exclusive. 559 560 561 Use of MAP_FIXED may result in unspecified behavior in further use of 562 brk(2), sbrk(2), malloc(3C), and shmat(2). The use of MAP_FIXED is 563 discouraged, as it may prevent an implementation from making the most 564 effective use of resources. 565 566 567 The application must ensure correct synchronization when using mmap() 568 in conjunction with any other file access method, such as read(2) and 569 write(2), standard input/output, and shmat(2). 570 571 572 The mmap() function has a transitional interface for 64-bit file 573 offsets. See lf64(5). 574 575 576 The mmap() function allows access to resources using address space 577 manipulations instead of the read()/write() interface. Once a file is 578 mapped, all a process has to do to access it is use the data at the 579 address to which the object was mapped. 580 581 582 Consider the following pseudo-code: 583 584 fildes = open(...) 585 lseek(fildes, offset, whence) 586 read(fildes, buf, len) 587 /* use data in buf */ 588 589 590 591 The following is a rewrite using mmap(): 592 593 fildes = open(...) 594 address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE), 595 MAP_PRIVATE, fildes, offset) 596 /* use data at address */ 597 598 599 ATTRIBUTES 600 See attributes(5) for descriptions of the following attributes: 601 602 603 604 605 +--------------------+-------------------+ 606 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 607 +--------------------+-------------------+ 608 |Interface Stability | Standard | 609 +--------------------+-------------------+ 610 |MT-Level | Async-Signal-Safe | 611 +--------------------+-------------------+ 612 613 SEE ALSO 614 close(2), exec(2), fcntl(2), fork(2), getrlimit(2), memcntl(2), 615 mmapobj(2), mprotect(2), munmap(2), shmat(2), lockf(3C), mlockall(3C), 616 msync(3C), plock(3C), sysconf(3C), attributes(5), lf64(5), 617 standards(5), null(7D), zero(7D) 618 619 620 621 August 29, 2016 MMAP(2)