1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95 29.\" $FreeBSD$ 30.\" 31.Dd June 22, 2017 32.Dt MMAP 2 33.Os 34.Sh NAME 35.Nm mmap 36.Nd allocate memory, or map files or devices into memory 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In sys/mman.h 41.Ft void * 42.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 43.Sh DESCRIPTION 44The 45.Fn mmap 46system call causes the pages starting at 47.Fa addr 48and continuing for at most 49.Fa len 50bytes to be mapped from the object described by 51.Fa fd , 52starting at byte offset 53.Fa offset . 54If 55.Fa len 56is not a multiple of the page size, the mapped region may extend past the 57specified range. 58Any such extension beyond the end of the mapped object will be zero-filled. 59.Pp 60If 61.Fa fd 62references a regular file or a shared memory object, the range of 63bytes starting at 64.Fa offset 65and continuing for 66.Fa len 67bytes must be legitimate for the possible (not necessarily 68current) offsets in the object. 69In particular, the 70.Fa offset 71value cannot be negative. 72If the object is truncated and the process later accesses a page that 73is wholly within the truncated region, the access is aborted and a 74.Dv SIGBUS 75signal is delivered to the process. 76.Pp 77If 78.Fa fd 79references a device file, the interpretation of the 80.Fa offset 81value is device specific and defined by the device driver. 82The virtual memory subsystem does not impose any restrictitions on the 83.Fa offset 84value in this case, passing it unchanged to the driver. 85.Pp 86If 87.Fa addr 88is non-zero, it is used as a hint to the system. 89(As a convenience to the system, the actual address of the region may differ 90from the address supplied.) 91If 92.Fa addr 93is zero, an address will be selected by the system. 94The actual starting address of the region is returned. 95A successful 96.Fa mmap 97deletes any previous mapping in the allocated address range. 98.Pp 99The protections (region accessibility) are specified in the 100.Fa prot 101argument by 102.Em or Ns 'ing 103the following values: 104.Pp 105.Bl -tag -width PROT_WRITE -compact 106.It Dv PROT_NONE 107Pages may not be accessed. 108.It Dv PROT_READ 109Pages may be read. 110.It Dv PROT_WRITE 111Pages may be written. 112.It Dv PROT_EXEC 113Pages may be executed. 114.El 115.Pp 116The 117.Fa flags 118argument specifies the type of the mapped object, mapping options and 119whether modifications made to the mapped copy of the page are private 120to the process or are to be shared with other references. 121Sharing, mapping type and options are specified in the 122.Fa flags 123argument by 124.Em or Ns 'ing 125the following values: 126.Bl -tag -width MAP_PREFAULT_READ 127.It Dv MAP_32BIT 128Request a region in the first 2GB of the current process's address space. 129If a suitable region cannot be found, 130.Fn mmap 131will fail. 132This flag is only available on 64-bit platforms. 133.It Dv MAP_ALIGNED Ns Pq Fa n 134Align the region on a requested boundary. 135If a suitable region cannot be found, 136.Fn mmap 137will fail. 138The 139.Fa n 140argument specifies the binary logarithm of the desired alignment. 141.It Dv MAP_ALIGNED_SUPER 142Align the region to maximize the potential use of large 143.Pq Dq super 144pages. 145If a suitable region cannot be found, 146.Fn mmap 147will fail. 148The system will choose a suitable page size based on the size of 149mapping. 150The page size used as well as the alignment of the region may both be 151affected by properties of the file being mapped. 152In particular, 153the physical address of existing pages of a file may require a specific 154alignment. 155The region is not guaranteed to be aligned on any specific boundary. 156.It Dv MAP_ANON 157Map anonymous memory not associated with any specific file. 158The file descriptor used for creating 159.Dv MAP_ANON 160must be \-1. 161The 162.Fa offset 163argument must be 0. 164.\".It Dv MAP_FILE 165.\"Mapped from a regular file or character-special device memory. 166.It Dv MAP_ANONYMOUS 167This flag is identical to 168.Dv MAP_ANON 169and is provided for compatibility. 170.It Dv MAP_EXCL 171This flag can only be used in combination with 172.Dv MAP_FIXED . 173Please see the definition of 174.Dv MAP_FIXED 175for the description of its effect. 176.It Dv MAP_FIXED 177Do not permit the system to select a different address than the one 178specified. 179If the specified address cannot be used, 180.Fn mmap 181will fail. 182If 183.Dv MAP_FIXED 184is specified, 185.Fa addr 186must be a multiple of the page size. 187If 188.Dv MAP_EXCL 189is not specified, a successful 190.Dv MAP_FIXED 191request replaces any previous mappings for the process' 192pages in the range from 193.Fa addr 194to 195.Fa addr 196+ 197.Fa len . 198In contrast, if 199.Dv MAP_EXCL 200is specified, the request will fail if a mapping 201already exists within the range. 202.It Dv MAP_GUARD 203Instead of a mapping, create a guard of the specified size. 204Guards allow a process to create reservations in its address space, 205which can later be replaced by actual mappings. 206.Pp 207.Fa mmap 208will not create mappings in the address range of a guard unless 209the request specifies 210.Dv MAP_FIXED . 211Guards can be destroyed with 212.Xr munmap 2 . 213Any memory access by a thread to the guarded range results 214in the delivery of a 215.Dv SIGSEGV 216signal to that thread. 217.It Dv MAP_NOCORE 218Region is not included in a core file. 219.It Dv MAP_NOSYNC 220Causes data dirtied via this VM map to be flushed to physical media 221only when necessary (usually by the pager) rather than gratuitously. 222Typically this prevents the update daemons from flushing pages dirtied 223through such maps and thus allows efficient sharing of memory across 224unassociated processes using a file-backed shared memory map. 225Without 226this option any VM pages you dirty may be flushed to disk every so often 227(every 30-60 seconds usually) which can create performance problems if you 228do not need that to occur (such as when you are using shared file-backed 229mmap regions for IPC purposes). 230Dirty data will be flushed automatically when all mappings of an object are 231removed and all descriptors referencing the object are closed. 232Note that VM/file system coherency is 233maintained whether you use 234.Dv MAP_NOSYNC 235or not. 236This option is not portable 237across 238.Ux 239platforms (yet), though some may implement the same behavior 240by default. 241.Pp 242.Em WARNING ! 243Extending a file with 244.Xr ftruncate 2 , 245thus creating a big hole, and then filling the hole by modifying a shared 246.Fn mmap 247can lead to severe file fragmentation. 248In order to avoid such fragmentation you should always pre-allocate the 249file's backing store by 250.Fn write Ns ing 251zero's into the newly extended area prior to modifying the area via your 252.Fn mmap . 253The fragmentation problem is especially sensitive to 254.Dv MAP_NOSYNC 255pages, because pages may be flushed to disk in a totally random order. 256.Pp 257The same applies when using 258.Dv MAP_NOSYNC 259to implement a file-based shared memory store. 260It is recommended that you create the backing store by 261.Fn write Ns ing 262zero's to the backing file rather than 263.Fn ftruncate Ns ing 264it. 265You can test file fragmentation by observing the KB/t (kilobytes per 266transfer) results from an 267.Dq Li iostat 1 268while reading a large file sequentially, e.g.,\& using 269.Dq Li dd if=filename of=/dev/null bs=32k . 270.Pp 271The 272.Xr fsync 2 273system call will flush all dirty data and metadata associated with a file, 274including dirty NOSYNC VM data, to physical media. 275The 276.Xr sync 8 277command and 278.Xr sync 2 279system call generally do not flush dirty NOSYNC VM data. 280The 281.Xr msync 2 282system call is usually not needed since 283.Bx 284implements a coherent file system buffer cache. 285However, it may be 286used to associate dirty VM pages with file system buffers and thus cause 287them to be flushed to physical media sooner rather than later. 288.It Dv MAP_PREFAULT_READ 289Immediately update the calling process's lowest-level virtual address 290translation structures, such as its page table, so that every memory 291resident page within the region is mapped for read access. 292Ordinarily these structures are updated lazily. 293The effect of this option is to eliminate any soft faults that would 294otherwise occur on the initial read accesses to the region. 295Although this option does not preclude 296.Fa prot 297from including 298.Dv PROT_WRITE , 299it does not eliminate soft faults on the initial write accesses to the 300region. 301.It Dv MAP_PRIVATE 302Modifications are private. 303.It Dv MAP_SHARED 304Modifications are shared. 305.It Dv MAP_STACK 306.Dv MAP_STACK 307implies 308.Dv MAP_ANON , 309and 310.Fa offset 311of 0. 312The 313.Fa fd 314argument 315must be -1 and 316.Fa prot 317must include at least 318.Dv PROT_READ 319and 320.Dv PROT_WRITE . 321.Pp 322This option creates 323a memory region that grows to at most 324.Fa len 325bytes in size, starting from the stack top and growing down. 326The 327stack top is the starting address returned by the call, plus 328.Fa len 329bytes. 330The bottom of the stack at maximum growth is the starting 331address returned by the call. 332.Pp 333Stacks created with 334.Dv MAP_STACK 335automatically grow. 336Guards prevent inadvertent use of the regions into which those 337stacks can grow without requiring mapping the whole stack in advance. 338.El 339.Pp 340The 341.Xr close 2 342system call does not unmap pages, see 343.Xr munmap 2 344for further information. 345.Sh NOTES 346Although this implementation does not impose any alignment restrictions on 347the 348.Fa offset 349argument, a portable program must only use page-aligned values. 350.Pp 351Large page mappings require that the pages backing an object be 352aligned in matching blocks in both the virtual address space and RAM. 353The system will automatically attempt to use large page mappings when 354mapping an object that is already backed by large pages in RAM by 355aligning the mapping request in the virtual address space to match the 356alignment of the large physical pages. 357The system may also use large page mappings when mapping portions of an 358object that are not yet backed by pages in RAM. 359The 360.Dv MAP_ALIGNED_SUPER 361flag is an optimization that will align the mapping request to the 362size of a large page similar to 363.Dv MAP_ALIGNED , 364except that the system will override this alignment if an object already 365uses large pages so that the mapping will be consistent with the existing 366large pages. 367This flag is mostly useful for maximizing the use of large pages on the 368first mapping of objects that do not yet have pages present in RAM. 369.Sh RETURN VALUES 370Upon successful completion, 371.Fn mmap 372returns a pointer to the mapped region. 373Otherwise, a value of 374.Dv MAP_FAILED 375is returned and 376.Va errno 377is set to indicate the error. 378.Sh ERRORS 379The 380.Fn mmap 381system call 382will fail if: 383.Bl -tag -width Er 384.It Bq Er EACCES 385The flag 386.Dv PROT_READ 387was specified as part of the 388.Fa prot 389argument and 390.Fa fd 391was not open for reading. 392The flags 393.Dv MAP_SHARED 394and 395.Dv PROT_WRITE 396were specified as part of the 397.Fa flags 398and 399.Fa prot 400argument and 401.Fa fd 402was not open for writing. 403.It Bq Er EBADF 404The 405.Fa fd 406argument 407is not a valid open file descriptor. 408.It Bq Er EINVAL 409An invalid (negative) value was passed in the 410.Fa offset 411argument, when 412.Fa fd 413referenced a regular file or shared memory. 414.It Bq Er EINVAL 415An invalid value was passed in the 416.Fa prot 417argument. 418.It Bq Er EINVAL 419An undefined option was set in the 420.Fa flags 421argument. 422.It Bq Er EINVAL 423Both 424.Dv MAP_PRIVATE 425and 426.Dv MAP_SHARED 427were specified. 428.It Bq Er EINVAL 429None of 430.Dv MAP_ANON , 431.Dv MAP_GUARD , 432.Dv MAP_PRIVATE , 433.Dv MAP_SHARED , 434or 435.Dv MAP_STACK 436was specified. 437At least one of these flags must be included. 438.It Bq Er EINVAL 439.Dv MAP_FIXED 440was specified and the 441.Fa addr 442argument was not page aligned, or part of the desired address space 443resides out of the valid address space for a user process. 444.It Bq Er EINVAL 445Both 446.Dv MAP_FIXED 447and 448.Dv MAP_32BIT 449were specified and part of the desired address space resides outside 450of the first 2GB of user address space. 451.It Bq Er EINVAL 452The 453.Fa len 454argument 455was equal to zero. 456.It Bq Er EINVAL 457.Dv MAP_ALIGNED 458was specified and the desired alignment was either larger than the 459virtual address size of the machine or smaller than a page. 460.It Bq Er EINVAL 461.Dv MAP_ANON 462was specified and the 463.Fa fd 464argument was not -1. 465.It Bq Er EINVAL 466.Dv MAP_ANON 467was specified and the 468.Fa offset 469argument was not 0. 470.It Bq Er EINVAL 471Both 472.Dv MAP_FIXED 473and 474.Dv MAP_EXCL 475were specified, but the requested region is already used by a mapping. 476.It Bq Er EINVAL 477.Dv MAP_EXCL 478was specified, but 479.Dv MAP_FIXED 480was not. 481.It Bq Er EINVAL 482.Dv MAP_GUARD 483was specified, but the 484.Fa offset 485argument was not zero, the 486.Fa fd 487argument was not -1, or the 488.Fa prot 489argument was not 490.Dv PROT_NONE . 491.It Bq Er EINVAL 492.Dv MAP_GUARD 493was specified together with one of the flags 494.Dv MAP_ANON , 495.Dv MAP_PREFAULT , 496.Dv MAP_PREFAULT_READ , 497.Dv MAP_PRIVATE , 498.Dv MAP_SHARED , 499.Dv MAP_STACK . 500.It Bq Er ENODEV 501.Dv MAP_ANON 502has not been specified and 503.Fa fd 504did not reference a regular or character special file. 505.It Bq Er ENOMEM 506.Dv MAP_FIXED 507was specified and the 508.Fa addr 509argument was not available. 510.Dv MAP_ANON 511was specified and insufficient memory was available. 512.El 513.Sh SEE ALSO 514.Xr madvise 2 , 515.Xr mincore 2 , 516.Xr minherit 2 , 517.Xr mlock 2 , 518.Xr mprotect 2 , 519.Xr msync 2 , 520.Xr munlock 2 , 521.Xr munmap 2 , 522.Xr getpagesize 3 , 523.Xr getpagesizes 3 524