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