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