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