1 '\" te 2 .\" Copyright 2016 James S Blachly, MD. All Rights Reserved. 3 .\" Copyright 2013 OmniTI Computer Consulting, Inc. All Rights Reserved. 4 .\" Copyright 1989 AT&T. Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. 5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at 6 .\" http://www.opengroup.org/bookstore/. 7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. 8 .\" This notice shall appear on any product containing this material. 9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 12 .TH MMAP 2 "August 29, 2016" 13 .SH NAME 14 mmap \- map pages of memory 15 .SH SYNOPSIS 16 .LP 17 .nf 18 #include <sys/mman.h> 19 20 \fBvoid *\fR\fBmmap\fR(\fBvoid *\fR\fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIprot\fR, \fBint\fR \fIflags\fR, 21 \fBint\fR \fIfildes\fR, \fBoff_t\fR \fIoff\fR); 22 .fi 23 24 .SH DESCRIPTION 25 .LP 26 The \fBmmap()\fR function establishes a mapping between a process's address 27 space and a file or shared memory object. The format of the call is as follows: 28 .sp 29 .LP 30 \fIpa\fR = \fBmmap(\fR\fIaddr\fR\fB, \fR\fIlen\fR\fB, \fR\fIprot\fR\fB, 31 \fR\fIflags\fR\fB, \fR\fIfildes\fR\fB, \fR\fIoff\fR\fB);\fR 32 .sp 33 .LP 34 The \fBmmap()\fR function establishes a mapping between the address space of 35 the process at an address \fIpa\fR for \fIlen\fR bytes to the memory object 36 represented by the file descriptor \fIfildes\fR at offset \fIoff\fR for 37 \fIlen\fR bytes. The value of \fIpa\fR is a function of the \fIaddr\fR 38 argument and values of \fIflags\fR, further described below. A successful 39 \fBmmap()\fR call returns \fIpa\fR as its result. The address range starting at 40 \fIpa\fR and continuing for \fIlen\fR bytes will be legitimate for the possible 41 (not necessarily current) address space of the process. The range of bytes 42 starting at \fIoff\fR and continuing for \fIlen\fR bytes will be legitimate for 43 the possible (not necessarily current) offsets in the file or shared memory 44 object represented by \fIfildes\fR. 45 .sp 46 .LP 47 The \fBmmap()\fR function allows [\fIpa, pa + len\fR) to extend beyond the end 48 of the object both at the time of the \fBmmap()\fR and while the mapping 49 persists, such as when the file is created prior to the \fBmmap()\fR call and 50 has no contents, or when the file is truncated. Any reference to addresses 51 beyond the end of the object, however, will result in the delivery of a 52 \fBSIGBUS\fR or \fBSIGSEGV\fR signal. The \fBmmap()\fR function cannot be used 53 to implicitly extend the length of files. 54 .sp 55 .LP 56 The mapping established by \fBmmap()\fR replaces any previous mappings for 57 those whole pages containing any part of the address space of the process 58 starting at \fIpa\fR and continuing for \fIlen\fR bytes. 59 .sp 60 .LP 61 If the size of the mapped file changes after the call to \fBmmap()\fR as a 62 result of some other operation on the mapped file, the effect of references to 63 portions of the mapped region that correspond to added or removed portions of 64 the file is unspecified. 65 .sp 66 .LP 67 The \fBmmap()\fR function is supported for regular files and shared memory 68 objects. Support for any other type of file is unspecified. 69 .sp 70 .LP 71 The \fIprot\fR argument determines whether read, write, execute, or some 72 combination of accesses are permitted to the data being mapped. The \fIprot\fR 73 argument should be either \fBPROT_NONE\fR or the bitwise inclusive \fBOR\fR of 74 one or more of the other flags in the following table, defined in the header 75 <\fBsys/mman.h\fR>. 76 .sp 77 .ne 2 78 .na 79 \fB\fBPROT_READ\fR\fR 80 .ad 81 .RS 14n 82 Data can be read. 83 .RE 84 85 .sp 86 .ne 2 87 .na 88 \fB\fBPROT_WRITE\fR\fR 89 .ad 90 .RS 14n 91 Data can be written. 92 .RE 93 94 .sp 95 .ne 2 96 .na 97 \fB\fBPROT_EXEC\fR\fR 98 .ad 99 .RS 14n 100 Data can be executed. 101 .RE 102 103 .sp 104 .ne 2 105 .na 106 \fB\fBPROT_NONE\fR\fR 107 .ad 108 .RS 14n 109 Data cannot be accessed. 110 .RE 111 112 .sp 113 .LP 114 If an implementation of \fBmmap()\fR for a specific platform cannot support the 115 combination of access types specified by \fIprot\fR, the call to \fBmmap()\fR 116 fails. An implementation may permit accesses other than those specified by 117 \fIprot\fR; however, the implementation will not permit a write to succeed 118 where \fBPROT_WRITE\fR has not been set or permit any access where 119 \fBPROT_NONE\fR alone has been set. Each platform-specific implementation of 120 \fBmmap()\fR supports the following values of \fIprot\fR: \fBPROT_NONE\fR, 121 \fBPROT_READ\fR, \fBPROT_WRITE\fR, and the inclusive \fBOR\fR of 122 \fBPROT_READ\fR and \fBPROT_WRITE\fR. On some platforms, the \fBPROT_WRITE\fR 123 protection option is implemented as \fBPROT_READ|PROT_WRITE\fR and 124 \fBPROT_EXEC\fR as \fBPROT_READ|PROT_EXEC\fR. The file descriptor \fIfildes\fR 125 is opened with read permission, regardless of the protection options specified. 126 If \fBPROT_WRITE\fR is specified, the application must have opened the file 127 descriptor \fIfildes\fR with write permission unless \fBMAP_PRIVATE\fR is 128 specified in the \fIflags\fR argument as described below. 129 .sp 130 .LP 131 The \fIflags\fR argument provides other information about the handling of the 132 mapped data. The value of \fIflags\fR is the bitwise inclusive \fBOR\fR of 133 these options, defined in <\fBsys/mman.h\fR>: 134 .sp 135 .ne 2 136 .na 137 \fB\fBMAP_SHARED\fR\fR 138 .ad 139 .RS 17n 140 Changes are shared. 141 .RE 142 143 .sp 144 .ne 2 145 .na 146 \fB\fBMAP_PRIVATE\fR\fR 147 .ad 148 .RS 17n 149 Changes are private. 150 .RE 151 152 .sp 153 .ne 2 154 .na 155 \fB\fBMAP_FIXED\fR\fR 156 .ad 157 .RS 17n 158 Interpret \fIaddr\fR exactly. 159 .RE 160 161 .sp 162 .ne 2 163 .na 164 \fB\fBMAP_NORESERVE\fR\fR 165 .ad 166 .RS 17n 167 Do not reserve swap space. 168 .RE 169 170 .sp 171 .ne 2 172 .na 173 \fB\fBMAP_ANON\fR\fR 174 .ad 175 .RS 17n 176 Map anonymous memory. 177 .RE 178 179 .sp 180 .ne 2 181 .na 182 \fB\fBMAP_ALIGN\fR\fR 183 .ad 184 .RS 17n 185 Interpret \fIaddr\fR as required aligment. 186 .RE 187 188 .sp 189 .ne 2 190 .na 191 \fB\fBMAP_TEXT\fR\fR 192 .ad 193 .RS 17n 194 Map text. 195 .RE 196 197 .sp 198 .ne 2 199 .na 200 \fB\fBMAP_INITDATA\fR\fR 201 .ad 202 .RS 17n 203 Map initialized data segment. 204 .RE 205 206 .sp 207 .ne 2 208 .na 209 \fB\fBMAP_32BIT\fR\fR 210 .ad 211 .RS 17n 212 Map to the lower 32 bits of address space. 213 .RE 214 215 .sp 216 .ne 2 217 .na 218 \fB\fBMAP_FILE\fR\fR 219 .ad 220 .RS 17n 221 Map a regular file. This is the default behavior; 222 specifying this flag is not required. It is provided 223 for compatibility with other systems and should not be 224 included in new code. 225 .RE 226 227 .sp 228 .LP 229 The \fBMAP_SHARED\fR and \fBMAP_PRIVATE\fR options describe the disposition of 230 write references to the underlying object. If \fBMAP_SHARED\fR is specified, 231 write references will change the memory object. If \fBMAP_PRIVATE\fR is 232 specified, the initial write reference will create a private copy of the memory 233 object page and redirect the mapping to the copy. The private copy is not 234 created until the first write; until then, other users who have the object 235 mapped \fBMAP_SHARED\fR can change the object. Either \fBMAP_SHARED\fR or 236 \fBMAP_PRIVATE\fR must be specified, but not both. The mapping type is retained 237 across \fBfork\fR(2). 238 .sp 239 .LP 240 When \fBMAP_FIXED\fR is set in the \fIflags\fR argument, the system is informed 241 that the value of \fIpa\fR must be \fIaddr\fR, exactly. If \fBMAP_FIXED\fR is 242 set, \fBmmap()\fR may return (\fBvoid *\fR)\(mi1 and set \fBerrno\fR to 243 \fBEINVAL\fR. If a \fBMAP_FIXED\fR request is successful, the mapping 244 established by \fBmmap()\fR replaces any previous mappings for the process's 245 pages in the range [\fIpa, pa + len\fR). The use of \fBMAP_FIXED\fR is 246 discouraged, since it may prevent a system from making the most effective use 247 of its resources. 248 .sp 249 .LP 250 When \fBMAP_FIXED\fR is set and the requested address is the same as previous 251 mapping, the previous address is unmapped and the new mapping is created on top 252 of the old one. 253 .sp 254 .LP 255 When \fBMAP_FIXED\fR is not set, the system uses \fIaddr\fR to arrive at 256 \fIpa\fR. The \fIpa\fR so chosen will be an area of the address space that the 257 system deems suitable for a mapping of \fIlen\fR bytes to the file. The 258 \fBmmap()\fR function interprets an \fIaddr\fR value of 0 as granting the 259 system complete freedom in selecting \fIpa\fR, subject to constraints described 260 below. A non-zero value of \fIaddr\fR is taken to be a suggestion of a process 261 address near which the mapping should be placed. When the system selects a 262 value for \fIpa\fR, it will never place a mapping at address 0, nor will it 263 replace any extant mapping, nor map into areas considered part of the potential 264 data or stack "segments". 265 .sp 266 .LP 267 When \fBMAP_ALIGN\fR is set, the system is informed that the alignment of 268 \fIpa\fR must be the same as \fIaddr\fR. The alignment value in \fIaddr\fR must 269 be 0 or some power of two multiple of page size as returned by 270 \fBsysconf\fR(3C). If addr is 0, the system will choose a suitable alignment. 271 .sp 272 .LP 273 The \fBMAP_NORESERVE\fR option specifies that no swap space be reserved for a 274 mapping. Without this flag, the creation of a writable \fBMAP_PRIVATE\fR 275 mapping reserves swap space equal to the size of the mapping; when the mapping 276 is written into, the reserved space is employed to hold private copies of the 277 data. A write into a \fBMAP_NORESERVE\fR mapping produces results which depend 278 on the current availability of swap space in the system. If space is 279 available, the write succeeds and a private copy of the written page is 280 created; if space is not available, the write fails and a \fBSIGBUS\fR or 281 \fBSIGSEGV\fR signal is delivered to the writing process. \fBMAP_NORESERVE\fR 282 mappings are inherited across \fBfork()\fR; at the time of the \fBfork()\fR, 283 swap space is reserved in the child for all private pages that currently exist 284 in the parent; thereafter the child's mapping behaves as described above. 285 .sp 286 .LP 287 When \fBMAP_ANON\fR is set in \fIflags\fR, and \fIfildes\fR is set to -1, 288 \fBmmap()\fR provides a direct path to return anonymous pages to the caller. 289 This operation is equivalent to passing \fBmmap()\fR an open file descriptor on 290 \fB/dev/zero\fR with \fBMAP_ANON\fR elided from the \fIflags\fR argument. 291 .sp 292 .LP 293 The \fBMAP_TEXT\fR option informs the system that the mapped region will be 294 used primarily for executing instructions. This information can help the system 295 better utilize MMU resources on some platforms. This flag is always passed by 296 the dynamic linker when it maps text segments of shared objects. When the 297 \fBMAP_TEXT\fR option is used for regular file mappings on some platforms, the 298 system can choose a mapping size larger than the page size returned by 299 \fBsysconf\fR(3C). The specific page sizes that are used depend on the platform 300 and the alignment of the addr and len arguments. Several different mapping sizes 301 can be used to map the region with larger page sizes used in the parts of the 302 region that meet alignment and size requirements for those page sizes. 303 .sp 304 .LP 305 The \fBMAP_INITDATA\fR option informs the system that the mapped region is an 306 initialized data segment of an executable or shared object. When the 307 \fBMAP_INITDATA\fR option is used for regular file mappings on some platforms, 308 the system can choose a mapping size larger than the page size returned by 309 \fBsysconf()\fR. The \fBMAP_INITDATA\fR option should be used only by the 310 dynamic linker for mapping initialized data of shared objects. 311 .sp 312 .LP 313 The \fBMAP_32BIT\fR option informs the system that the search space for 314 mapping assignment should be limited to the first 32 bits (4 Gbytes) of the 315 caller's address space. This flag is accepted in both 32-bit and 64-bit 316 process models, but does not alter the mapping strategy when used in a 317 32-bit process model. 318 .sp 319 .LP 320 The \fIoff\fR argument is constrained to be aligned and sized according to the 321 value returned by \fBsysconf()\fR when passed \fB_SC_PAGESIZE\fR or 322 \fB_SC_PAGE_SIZE\fR. When \fBMAP_FIXED\fR is specified, the \fIaddr\fR argument 323 must also meet these constraints. The system performs mapping operations over 324 whole pages. Thus, while the \fIlen\fR argument need not meet a size or 325 alignment constraint, the system will include, in any mapping operation, any 326 partial page specified by the range [\fIpa, pa + len\fR). 327 .sp 328 .LP 329 The system will always zero-fill any partial page at the end of an object. 330 Further, the system will never write out any modified portions of the last page 331 of an object which are beyond its end. References to whole pages following the 332 end of an object will result in the delivery of a \fBSIGBUS\fR or \fBSIGSEGV\fR 333 signal. \fBSIGBUS\fR signals may also be delivered on various file system 334 conditions, including quota exceeded errors. 335 .sp 336 .LP 337 The \fBmmap()\fR function adds an extra reference to the file associated with 338 the file descriptor \fIfildes\fR which is not removed by a subsequent 339 \fBclose\fR(2) on that file descriptor. This reference is removed when there 340 are no more mappings to the file by a call to the \fBmunmap\fR(2) function. 341 .sp 342 .LP 343 The \fBst_atime\fR field of the mapped file may be marked for update at any 344 time between the \fBmmap()\fR call and the corresponding \fBmunmap\fR(2) call. 345 The initial read or write reference to a mapped region will cause the file's 346 \fBst_atime\fR field to be marked for update if it has not already been marked 347 for update. 348 .sp 349 .LP 350 The \fBst_ctime\fR and \fBst_mtime\fR fields of a file that is mapped with 351 \fBMAP_SHARED\fR and \fBPROT_WRITE\fR, will be marked for update at some point 352 in the interval between a write reference to the mapped region and the next 353 call to \fBmsync\fR(3C) with \fBMS_ASYNC\fR or \fBMS_SYNC\fR for that portion 354 of the file by any process. If there is no such call, these fields may be 355 marked for update at any time after a write reference if the underlying file is 356 modified as a result. 357 .sp 358 .LP 359 If the process calls \fBmlockall\fR(3C) with the \fBMCL_FUTURE\fR flag, the 360 pages mapped by all future calls to \fBmmap()\fR will be locked in memory. In 361 this case, if not enough memory could be locked, \fBmmap()\fR fails and sets 362 \fBerrno\fR to \fBEAGAIN\fR. 363 .sp 364 .LP 365 The \fBmmap()\fR function aligns based on the length of the mapping. When 366 determining the amount of space to add to the address space, \fBmmap()\fR 367 includes two 8-Kbyte pages, one at each end of the mapping that are not mapped 368 and are therefore used as "red-zone" pages. Attempts to reference these pages 369 result in access violations. 370 .sp 371 .LP 372 The size requested is incremented by the 16 Kbytes for these pages and is then 373 subject to rounding constraints. The constraints are: 374 .RS +4 375 .TP 376 .ie t \(bu 377 .el o 378 For 32-bit processes: 379 .sp 380 .in +2 381 .nf 382 If length > 4 Mbytes 383 round to 4-Mbyte multiple 384 elseif length > 512 Kbytes 385 round to 512-Kbyte multiple 386 else 387 round to 64-Kbyte multiple 388 .fi 389 .in -2 390 391 .RE 392 .RS +4 393 .TP 394 .ie t \(bu 395 .el o 396 For 64-bit processes: 397 .sp 398 .in +2 399 .nf 400 If length > 4 Mbytes 401 round to 4-Mbyte multiple 402 else 403 round to 1-Mbyte multiple 404 .fi 405 .in -2 406 407 .RE 408 .sp 409 .LP 410 The net result is that for a 32-bit process: 411 .RS +4 412 .TP 413 .ie t \(bu 414 .el o 415 If an \fBmmap()\fR request is made for 4 Mbytes, it results in 4 Mbytes + 16 416 Kbytes and is rounded up to 8 Mbytes. 417 .RE 418 .RS +4 419 .TP 420 .ie t \(bu 421 .el o 422 If an \fBmmap()\fR request is made for 512 Kbytes, it results in 512 Kbytes + 423 16 Kbytes and is rounded up to 1 Mbyte. 424 .RE 425 .RS +4 426 .TP 427 .ie t \(bu 428 .el o 429 If an \fBmmap()\fR request is made for 1 Mbyte, it results in 1 Mbyte + 16 430 Kbytes and is rounded up to 1.5 Mbytes. 431 .RE 432 .RS +4 433 .TP 434 .ie t \(bu 435 .el o 436 Each 8-Kbyte mmap request "consumes" 64 Kbytes of virtual address space. 437 .RE 438 .sp 439 .LP 440 To obtain maximal address space usage for a 32-bit process: 441 .RS +4 442 .TP 443 .ie t \(bu 444 .el o 445 Combine 8-Kbyte requests up to a limit of 48 Kbytes. 446 .RE 447 .RS +4 448 .TP 449 .ie t \(bu 450 .el o 451 Combine amounts over 48 Kbytes into 496-Kbyte chunks. 452 .RE 453 .RS +4 454 .TP 455 .ie t \(bu 456 .el o 457 Combine amounts over 496 Kbytes into 4080-Kbyte chunks. 458 .RE 459 .sp 460 .LP 461 To obtain maximal address space usage for a 64-bit process: 462 .RS +4 463 .TP 464 .ie t \(bu 465 .el o 466 Combine amounts < 1008 Kbytes into chunks <= 1008 Kbytes. 467 .RE 468 .RS +4 469 .TP 470 .ie t \(bu 471 .el o 472 Combine amounts over 1008 Kbytes into 4080-Kbyte chunks. 473 .RE 474 .sp 475 .LP 476 The following is the output from a 32-bit program demonstrating this: 477 .sp 478 .ne 2 479 .na 480 \fBmap 8192 bytes: \fB0xff390000\fR\fR 481 .ad 482 .br 483 .na 484 \fBmap 8192 bytes: \fB0xff380000\fR\fR 485 .ad 486 .sp .6 487 .RS 4n 488 64-Kbyte delta between starting addresses. 489 .RE 490 491 .sp 492 .ne 2 493 .na 494 \fBmap 512 Kbytes: \fB0xff180000\fR\fR 495 .ad 496 .br 497 .na 498 \fBmap 512 Kbytes: \fB0xff080000\fR\fR 499 .ad 500 .sp .6 501 .RS 4n 502 1-Mbyte delta between starting addresses. 503 .RE 504 505 .sp 506 .ne 2 507 .na 508 \fBmap 496 Kbytes: \fB0xff000000\fR\fR 509 .ad 510 .br 511 .na 512 \fBmap 496 Kbytes: \fB0xfef80000\fR\fR 513 .ad 514 .sp .6 515 .RS 4n 516 512-Kbyte delta between starting addresses 517 .RE 518 519 .sp 520 .ne 2 521 .na 522 \fBmap 1 Mbyte: \fB0xfee00000\fR\fR 523 .ad 524 .br 525 .na 526 \fBmap 1 Mbyte: \fB0xfec80000\fR\fR 527 .ad 528 .sp .6 529 .RS 4n 530 1536-Kbyte delta between starting addresses 531 .RE 532 533 .sp 534 .ne 2 535 .na 536 \fBmap 1008 Kbytes: \fB0xfeb80000\fR\fR 537 .ad 538 .br 539 .na 540 \fBmap 1008 Kbytes: \fB0xfea80000\fR\fR 541 .ad 542 .sp .6 543 .RS 4n 544 1-Mbyte delta between starting addresses 545 .RE 546 547 .sp 548 .ne 2 549 .na 550 \fBmap 4 Mbytes: \fB0xfe400000\fR\fR 551 .ad 552 .br 553 .na 554 \fBmap 4 Mbytes: \fB0xfdc00000\fR\fR 555 .ad 556 .sp .6 557 .RS 4n 558 8-Mbyte delta between starting addresses 559 .RE 560 561 .sp 562 .ne 2 563 .na 564 \fBmap 4080 Kbytes: \fB0xfd800000\fR\fR 565 .ad 566 .br 567 .na 568 \fBmap 4080 Kbytes: \fB0xfd400000\fR\fR 569 .ad 570 .sp .6 571 .RS 4n 572 4-Mbyte delta between starting addresses 573 .RE 574 575 .sp 576 .LP 577 The following is the output of the same program compiled as a 64-bit 578 application: 579 .sp 580 .ne 2 581 .na 582 \fBmap 8192 bytes: \fB0xffffffff7f000000\fR\fR 583 .ad 584 .br 585 .na 586 \fBmap 8192 bytes: \fB0xffffffff7ef00000\fR\fR 587 .ad 588 .sp .6 589 .RS 4n 590 1-Mbyte delta between starting addresses 591 .RE 592 593 .sp 594 .ne 2 595 .na 596 \fBmap 512 Kbytes: \fB0xffffffff7ee00000\fR\fR 597 .ad 598 .br 599 .na 600 \fBmap 512 Kbytes: \fB0xffffffff7ed00000\fR\fR 601 .ad 602 .sp .6 603 .RS 4n 604 1-Mbyte delta between starting addresses 605 .RE 606 607 .sp 608 .ne 2 609 .na 610 \fBmap 496 Kbytes: \fB0xffffffff7ec00000\fR\fR 611 .ad 612 .br 613 .na 614 \fBmap 496 Kbytes: \fB0xffffffff7eb00000\fR\fR 615 .ad 616 .sp .6 617 .RS 4n 618 1-Mbyte delta between starting addresses 619 .RE 620 621 .sp 622 .ne 2 623 .na 624 \fBmap 1 Mbyte: \fB0xffffffff7e900000\fR\fR 625 .ad 626 .br 627 .na 628 \fBmap 1 Mbyte: \fB0xffffffff7e700000\fR\fR 629 .ad 630 .sp .6 631 .RS 4n 632 2-Mbyte delta between starting addresses 633 .RE 634 635 .sp 636 .ne 2 637 .na 638 \fBmap 1008 Kbytes: \fB0xffffffff7e600000\fR\fR 639 .ad 640 .br 641 .na 642 \fBmap 1008 Kbytes: \fB0xffffffff7e500000\fR\fR 643 .ad 644 .sp .6 645 .RS 4n 646 1-Mbyte delta between starting addresses 647 .RE 648 649 .sp 650 .ne 2 651 .na 652 \fBmap 4 Mbytes: \fB0xffffffff7e000000\fR\fR 653 .ad 654 .br 655 .na 656 \fBmap 4 Mbytes: \fB0xffffffff7d800000\fR\fR 657 .ad 658 .sp .6 659 .RS 4n 660 8-Mbyte delta between starting addresses 661 .RE 662 663 .sp 664 .ne 2 665 .na 666 \fBmap 4080 Kbytes: \fB0xffffffff7d400000\fR\fR 667 .ad 668 .br 669 .na 670 \fBmap 4080 Kbytes: \fB0xffffffff7d000000\fR\fR 671 .ad 672 .sp .6 673 .RS 4n 674 4-Mbyte delta between starting addresses 675 .RE 676 677 .SH RETURN VALUES 678 .LP 679 Upon successful completion, the \fBmmap()\fR function returns the address at 680 which the mapping was placed (\fIpa\fR); otherwise, it returns a value of 681 \fBMAP_FAILED\fR and sets \fBerrno\fR to indicate the error. The symbol 682 \fBMAP_FAILED\fR is defined in the header <\fBsys/mman.h\fR>. No successful 683 return from \fBmmap()\fR will return the value \fBMAP_FAILED\fR. 684 .sp 685 .LP 686 If \fBmmap()\fR fails for reasons other than \fBEBADF\fR, \fBEINVAL\fR or 687 \fBENOTSUP\fR, some of the mappings in the address range starting at \fIaddr\fR 688 and continuing for \fIlen\fR bytes may have been unmapped. 689 .SH ERRORS 690 .LP 691 The \fBmmap()\fR function will fail if: 692 .sp 693 .ne 2 694 .na 695 \fB\fBEACCES\fR\fR 696 .ad 697 .RS 13n 698 The \fIfildes\fR file descriptor is not open for read, regardless of the 699 protection specified; or \fIfildes\fR is not open for write and 700 \fBPROT_WRITE\fR was specified for a \fBMAP_SHARED\fR type mapping. 701 .RE 702 703 .sp 704 .ne 2 705 .na 706 \fB\fBEAGAIN\fR\fR 707 .ad 708 .RS 13n 709 The mapping could not be locked in memory. 710 .sp 711 There was insufficient room to reserve swap space for the mapping. 712 .RE 713 714 .sp 715 .ne 2 716 .na 717 \fB\fBEBADF\fR\fR 718 .ad 719 .RS 13n 720 The \fIfildes\fR file descriptor is not open (and \fBMAP_ANON\fR was not 721 specified). 722 .RE 723 724 .sp 725 .ne 2 726 .na 727 \fB\fBEINVAL\fR\fR 728 .ad 729 .RS 13n 730 The arguments \fIaddr\fR (if \fBMAP_FIXED\fR was specified) or \fIoff\fR are 731 not multiples of the page size as returned by \fBsysconf()\fR. 732 .sp 733 The argument \fIaddr\fR (if \fBMAP_ALIGN\fR was specified) is not 0 or some 734 power of two multiple of page size as returned by \fBsysconf\fR(3C). 735 .sp 736 \fBMAP_FIXED\fR and \fBMAP_ALIGN\fR are both specified. 737 .sp 738 The field in \fIflags\fR is invalid (neither \fBMAP_PRIVATE\fR or 739 \fBMAP_SHARED\fR is set). 740 .sp 741 The argument \fIlen\fR has a value equal to 0. 742 .sp 743 \fBMAP_ANON\fR was specified, but the file descriptor was not \(mi1. 744 .sp 745 \fBMAP_TEXT\fR was specified but \fBPROT_EXEC\fR was not. 746 .sp 747 \fBMAP_TEXT\fR and \fBMAP_INITDATA\fR were both specified. 748 .RE 749 750 .sp 751 .ne 2 752 .na 753 \fB\fBEMFILE\fR\fR 754 .ad 755 .RS 13n 756 The number of mapped regions would exceed an implementation-dependent limit 757 (per process or per system). 758 .RE 759 760 .sp 761 .ne 2 762 .na 763 \fB\fBENODEV\fR\fR 764 .ad 765 .RS 13n 766 The \fIfildes\fR argument refers to an object for which \fBmmap()\fR is 767 meaningless, such as a terminal. 768 .RE 769 770 .sp 771 .ne 2 772 .na 773 \fB\fBENOMEM\fR\fR 774 .ad 775 .RS 13n 776 The \fBMAP_FIXED\fR option was specified and the range [\fIaddr, addr + len\fR) 777 exceeds that allowed for the address space of a process. 778 .sp 779 The \fBMAP_FIXED\fR option was \fInot\fR specified and there is insufficient 780 room in the address space to effect the mapping. 781 .sp 782 The mapping could not be locked in memory, if required by \fBmlockall\fR(3C), 783 because it would require more space than the system is able to supply. 784 .sp 785 The composite size of \fIlen\fR plus the lengths obtained from all previous 786 calls to \fBmmap()\fR exceeds \fBRLIMIT_VMEM\fR (see \fBgetrlimit\fR(2)). 787 .RE 788 789 .sp 790 .ne 2 791 .na 792 \fB\fBENOTSUP\fR\fR 793 .ad 794 .RS 13n 795 The system does not support the combination of accesses requested in the 796 \fIprot\fR argument. 797 .RE 798 799 .sp 800 .ne 2 801 .na 802 \fB\fBENXIO\fR\fR 803 .ad 804 .RS 13n 805 Addresses in the range [\fIoff, off + len\fR) are invalid for the object 806 specified by \fIfildes\fR. 807 .sp 808 The \fBMAP_FIXED\fR option was specified in \fIflags\fR and the combination of 809 \fIaddr\fR, \fIlen\fR and \fIoff\fR is invalid for the object specified by 810 \fIfildes\fR. 811 .RE 812 813 .sp 814 .ne 2 815 .na 816 \fB\fBEOVERFLOW\fR\fR 817 .ad 818 .RS 13n 819 The file is a regular file and the value of \fIoff\fR plus \fIlen\fR exceeds 820 the offset maximum establish in the open file description associated with 821 \fIfildes\fR. 822 .RE 823 824 .sp 825 .LP 826 The \fBmmap()\fR function may fail if: 827 .sp 828 .ne 2 829 .na 830 \fB\fBEAGAIN\fR\fR 831 .ad 832 .RS 10n 833 The file to be mapped is already locked using advisory or mandatory record 834 locking. See \fBfcntl\fR(2). 835 .RE 836 837 .SH USAGE 838 .LP 839 Use of \fBmmap()\fR may reduce the amount of memory available to other memory 840 allocation functions. 841 .sp 842 .LP 843 \fBMAP_ALIGN\fR is useful to assure a properly aligned value of \fIpa\fR for 844 subsequent use with \fBmemcntl\fR(2) and the \fBMC_HAT_ADVISE\fR command. This 845 is best used for large, long-lived, and heavily referenced regions. 846 \fBMAP_FIXED\fR and \fBMAP_ALIGN\fR are always mutually-exclusive. 847 .sp 848 .LP 849 Use of \fBMAP_FIXED\fR may result in unspecified behavior in further use of 850 \fBbrk\fR(2), \fBsbrk\fR(2), \fBmalloc\fR(3C), and \fBshmat\fR(2). The use of 851 \fBMAP_FIXED\fR is discouraged, as it may prevent an implementation from making 852 the most effective use of resources. 853 .sp 854 .LP 855 The application must ensure correct synchronization when using \fBmmap()\fR in 856 conjunction with any other file access method, such as \fBread\fR(2) and 857 \fBwrite\fR(2), standard input/output, and \fBshmat\fR(2). 858 .sp 859 .LP 860 The \fBmmap()\fR function has a transitional interface for 64-bit file offsets. 861 See \fBlf64\fR(5). 862 .sp 863 .LP 864 The \fBmmap()\fR function allows access to resources using address space 865 manipulations instead of the \fBread()\fR/\fBwrite()\fR interface. Once a file 866 is mapped, all a process has to do to access it is use the data at the address 867 to which the object was mapped. 868 .sp 869 .LP 870 Consider the following pseudo-code: 871 .sp 872 .in +2 873 .nf 874 fildes = open(\|.\|.\|.) 875 lseek(fildes, offset, whence) 876 read(fildes, buf, len) 877 /* use data in buf */ 878 .fi 879 .in -2 880 881 .sp 882 .LP 883 The following is a rewrite using \fBmmap()\fR: 884 .sp 885 .in +2 886 .nf 887 fildes = open(\|.\|.\|.) 888 address = mmap((caddr_t) 0, len, (PROT_READ | PROT_WRITE), 889 MAP_PRIVATE, fildes, offset) 890 /* use data at address */ 891 .fi 892 .in -2 893 894 .SH ATTRIBUTES 895 .LP 896 See \fBattributes\fR(5) for descriptions of the following attributes: 897 .sp 898 899 .sp 900 .TS 901 box; 902 c | c 903 l | l . 904 ATTRIBUTE TYPE ATTRIBUTE VALUE 905 _ 906 Interface Stability Standard 907 _ 908 MT-Level Async-Signal-Safe 909 .TE 910 911 .SH SEE ALSO 912 .LP 913 \fBclose\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), \fBfork\fR(2), 914 \fBgetrlimit\fR(2), \fBmemcntl\fR(2), \fBmmapobj\fR(2), \fBmprotect\fR(2), 915 \fBmunmap\fR(2), \fBshmat\fR(2), \fBlockf\fR(3C), \fBmlockall\fR(3C), 916 \fBmsync\fR(3C), \fBplock\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5), 917 \fBlf64\fR(5), \fBstandards\fR(5), \fBnull\fR(7D), \fBzero\fR(7D)