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