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 February 26, 2020 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 116In addition to these protection flags, 117.Fx 118provides the ability to set the maximum protection of a region allocated by 119.Nm 120and later altered by 121.Xr mprotect 2 . 122This is accomplished by 123.Em or Ns 'ing 124one or more 125.Dv PROT_ 126values wrapped in the 127.Dv PROT_MAX() 128macro into the 129.Fa prot 130argument. 131.Pp 132The 133.Fa flags 134argument specifies the type of the mapped object, mapping options and 135whether modifications made to the mapped copy of the page are private 136to the process or are to be shared with other references. 137Sharing, mapping type and options are specified in the 138.Fa flags 139argument by 140.Em or Ns 'ing 141the following values: 142.Bl -tag -width MAP_PREFAULT_READ 143.It Dv MAP_32BIT 144Request a region in the first 2GB of the current process's address space. 145If a suitable region cannot be found, 146.Fn mmap 147will fail. 148This flag is only available on 64-bit platforms. 149.It Dv MAP_ALIGNED Ns Pq Fa n 150Align the region on a requested boundary. 151If a suitable region cannot be found, 152.Fn mmap 153will fail. 154The 155.Fa n 156argument specifies the binary logarithm of the desired alignment. 157.It Dv MAP_ALIGNED_SUPER 158Align the region to maximize the potential use of large 159.Pq Dq super 160pages. 161If a suitable region cannot be found, 162.Fn mmap 163will fail. 164The system will choose a suitable page size based on the size of 165mapping. 166The page size used as well as the alignment of the region may both be 167affected by properties of the file being mapped. 168In particular, 169the physical address of existing pages of a file may require a specific 170alignment. 171The region is not guaranteed to be aligned on any specific boundary. 172.It Dv MAP_ANON 173Map anonymous memory not associated with any specific file. 174The file descriptor used for creating 175.Dv MAP_ANON 176must be \-1. 177The 178.Fa offset 179argument must be 0. 180.\".It Dv MAP_FILE 181.\"Mapped from a regular file or character-special device memory. 182.It Dv MAP_ANONYMOUS 183This flag is identical to 184.Dv MAP_ANON 185and is provided for compatibility. 186.It Dv MAP_EXCL 187This flag can only be used in combination with 188.Dv MAP_FIXED . 189Please see the definition of 190.Dv MAP_FIXED 191for the description of its effect. 192.It Dv MAP_FIXED 193Do not permit the system to select a different address than the one 194specified. 195If the specified address cannot be used, 196.Fn mmap 197will fail. 198If 199.Dv MAP_FIXED 200is specified, 201.Fa addr 202must be a multiple of the page size. 203If 204.Dv MAP_EXCL 205is not specified, a successful 206.Dv MAP_FIXED 207request replaces any previous mappings for the process' 208pages in the range from 209.Fa addr 210to 211.Fa addr 212+ 213.Fa len . 214In contrast, if 215.Dv MAP_EXCL 216is specified, the request will fail if a mapping 217already exists within the range. 218.It Dv MAP_GUARD 219Instead of a mapping, create a guard of the specified size. 220Guards allow a process to create reservations in its address space, 221which can later be replaced by actual mappings. 222.Pp 223.Fa mmap 224will not create mappings in the address range of a guard unless 225the request specifies 226.Dv MAP_FIXED . 227Guards can be destroyed with 228.Xr munmap 2 . 229Any memory access by a thread to the guarded range results 230in the delivery of a 231.Dv SIGSEGV 232signal to that thread. 233.It Dv MAP_NOCORE 234Region is not included in a core file. 235.It Dv MAP_NOSYNC 236Causes data dirtied via this VM map to be flushed to physical media 237only when necessary (usually by the pager) rather than gratuitously. 238Typically this prevents the update daemons from flushing pages dirtied 239through such maps and thus allows efficient sharing of memory across 240unassociated processes using a file-backed shared memory map. 241Without 242this option any VM pages you dirty may be flushed to disk every so often 243(every 30-60 seconds usually) which can create performance problems if you 244do not need that to occur (such as when you are using shared file-backed 245mmap regions for IPC purposes). 246Dirty data will be flushed automatically when all mappings of an object are 247removed and all descriptors referencing the object are closed. 248Note that VM/file system coherency is 249maintained whether you use 250.Dv MAP_NOSYNC 251or not. 252This option is not portable 253across 254.Ux 255platforms (yet), though some may implement the same behavior 256by default. 257.Pp 258.Em WARNING ! 259Extending a file with 260.Xr ftruncate 2 , 261thus creating a big hole, and then filling the hole by modifying a shared 262.Fn mmap 263can lead to severe file fragmentation. 264In order to avoid such fragmentation you should always pre-allocate the 265file's backing store by 266.Fn write Ns ing 267zero's into the newly extended area prior to modifying the area via your 268.Fn mmap . 269The fragmentation problem is especially sensitive to 270.Dv MAP_NOSYNC 271pages, because pages may be flushed to disk in a totally random order. 272.Pp 273The same applies when using 274.Dv MAP_NOSYNC 275to implement a file-based shared memory store. 276It is recommended that you create the backing store by 277.Fn write Ns ing 278zero's to the backing file rather than 279.Fn ftruncate Ns ing 280it. 281You can test file fragmentation by observing the KB/t (kilobytes per 282transfer) results from an 283.Dq Li iostat 1 284while reading a large file sequentially, e.g.,\& using 285.Dq Li dd if=filename of=/dev/null bs=32k . 286.Pp 287The 288.Xr fsync 2 289system call will flush all dirty data and metadata associated with a file, 290including dirty NOSYNC VM data, to physical media. 291The 292.Xr sync 8 293command and 294.Xr sync 2 295system call generally do not flush dirty NOSYNC VM data. 296The 297.Xr msync 2 298system call is usually not needed since 299.Bx 300implements a coherent file system buffer cache. 301However, it may be 302used to associate dirty VM pages with file system buffers and thus cause 303them to be flushed to physical media sooner rather than later. 304.It Dv MAP_PREFAULT_READ 305Immediately update the calling process's lowest-level virtual address 306translation structures, such as its page table, so that every memory 307resident page within the region is mapped for read access. 308Ordinarily these structures are updated lazily. 309The effect of this option is to eliminate any soft faults that would 310otherwise occur on the initial read accesses to the region. 311Although this option does not preclude 312.Fa prot 313from including 314.Dv PROT_WRITE , 315it does not eliminate soft faults on the initial write accesses to the 316region. 317.It Dv MAP_PRIVATE 318Modifications are private. 319.It Dv MAP_SHARED 320Modifications are shared. 321.It Dv MAP_STACK 322.Dv MAP_STACK 323implies 324.Dv MAP_ANON , 325and 326.Fa offset 327of 0. 328The 329.Fa fd 330argument 331must be -1 and 332.Fa prot 333must include at least 334.Dv PROT_READ 335and 336.Dv PROT_WRITE . 337.Pp 338This option creates 339a memory region that grows to at most 340.Fa len 341bytes in size, starting from the stack top and growing down. 342The 343stack top is the starting address returned by the call, plus 344.Fa len 345bytes. 346The bottom of the stack at maximum growth is the starting 347address returned by the call. 348.Pp 349Stacks created with 350.Dv MAP_STACK 351automatically grow. 352Guards prevent inadvertent use of the regions into which those 353stacks can grow without requiring mapping the whole stack in advance. 354.El 355.Pp 356The 357.Xr close 2 358system call does not unmap pages, see 359.Xr munmap 2 360for further information. 361.Sh NOTES 362Although this implementation does not impose any alignment restrictions on 363the 364.Fa offset 365argument, a portable program must only use page-aligned values. 366.Pp 367Large page mappings require that the pages backing an object be 368aligned in matching blocks in both the virtual address space and RAM. 369The system will automatically attempt to use large page mappings when 370mapping an object that is already backed by large pages in RAM by 371aligning the mapping request in the virtual address space to match the 372alignment of the large physical pages. 373The system may also use large page mappings when mapping portions of an 374object that are not yet backed by pages in RAM. 375The 376.Dv MAP_ALIGNED_SUPER 377flag is an optimization that will align the mapping request to the 378size of a large page similar to 379.Dv MAP_ALIGNED , 380except that the system will override this alignment if an object already 381uses large pages so that the mapping will be consistent with the existing 382large pages. 383This flag is mostly useful for maximizing the use of large pages on the 384first mapping of objects that do not yet have pages present in RAM. 385.Sh RETURN VALUES 386Upon successful completion, 387.Fn mmap 388returns a pointer to the mapped region. 389Otherwise, a value of 390.Dv MAP_FAILED 391is returned and 392.Va errno 393is set to indicate the error. 394.Sh ERRORS 395The 396.Fn mmap 397system call 398will fail if: 399.Bl -tag -width Er 400.It Bq Er EACCES 401The flag 402.Dv PROT_READ 403was specified as part of the 404.Fa prot 405argument and 406.Fa fd 407was not open for reading. 408The flags 409.Dv MAP_SHARED 410and 411.Dv PROT_WRITE 412were specified as part of the 413.Fa flags 414and 415.Fa prot 416argument and 417.Fa fd 418was not open for writing. 419.It Bq Er EBADF 420The 421.Fa fd 422argument 423is not a valid open file descriptor. 424.It Bq Er EINVAL 425An invalid (negative) value was passed in the 426.Fa offset 427argument, when 428.Fa fd 429referenced a regular file or shared memory. 430.It Bq Er EINVAL 431An invalid value was passed in the 432.Fa prot 433argument. 434.It Bq Er EINVAL 435An undefined option was set in the 436.Fa flags 437argument. 438.It Bq Er EINVAL 439Both 440.Dv MAP_PRIVATE 441and 442.Dv MAP_SHARED 443were specified. 444.It Bq Er EINVAL 445None of 446.Dv MAP_ANON , 447.Dv MAP_GUARD , 448.Dv MAP_PRIVATE , 449.Dv MAP_SHARED , 450or 451.Dv MAP_STACK 452was specified. 453At least one of these flags must be included. 454.It Bq Er EINVAL 455.Dv MAP_FIXED 456was specified and the 457.Fa addr 458argument was not page aligned, or part of the desired address space 459resides out of the valid address space for a user process. 460.It Bq Er EINVAL 461Both 462.Dv MAP_FIXED 463and 464.Dv MAP_32BIT 465were specified and part of the desired address space resides outside 466of the first 2GB of user address space. 467.It Bq Er EINVAL 468The 469.Fa len 470argument 471was equal to zero. 472.It Bq Er EINVAL 473.Dv MAP_ALIGNED 474was specified and the desired alignment was either larger than the 475virtual address size of the machine or smaller than a page. 476.It Bq Er EINVAL 477.Dv MAP_ANON 478was specified and the 479.Fa fd 480argument was not -1. 481.It Bq Er EINVAL 482.Dv MAP_ANON 483was specified and the 484.Fa offset 485argument was not 0. 486.It Bq Er EINVAL 487Both 488.Dv MAP_FIXED 489and 490.Dv MAP_EXCL 491were specified, but the requested region is already used by a mapping. 492.It Bq Er EINVAL 493.Dv MAP_EXCL 494was specified, but 495.Dv MAP_FIXED 496was not. 497.It Bq Er EINVAL 498.Dv MAP_GUARD 499was specified, but the 500.Fa offset 501argument was not zero, the 502.Fa fd 503argument was not -1, or the 504.Fa prot 505argument was not 506.Dv PROT_NONE . 507.It Bq Er EINVAL 508.Dv MAP_GUARD 509was specified together with one of the flags 510.Dv MAP_ANON , 511.Dv MAP_PREFAULT , 512.Dv MAP_PREFAULT_READ , 513.Dv MAP_PRIVATE , 514.Dv MAP_SHARED , 515.Dv MAP_STACK . 516.It Bq Er ENODEV 517.Dv MAP_ANON 518has not been specified and 519.Fa fd 520did not reference a regular or character special file. 521.It Bq Er ENOMEM 522.Dv MAP_FIXED 523was specified and the 524.Fa addr 525argument was not available. 526.Dv MAP_ANON 527was specified and insufficient memory was available. 528.It Bq Er ENOTSUP 529The 530.Fa prot 531argument contains protections which are not a subset of the specified 532maximum protections. 533.El 534.Sh SEE ALSO 535.Xr madvise 2 , 536.Xr mincore 2 , 537.Xr minherit 2 , 538.Xr mlock 2 , 539.Xr mprotect 2 , 540.Xr msync 2 , 541.Xr munlock 2 , 542.Xr munmap 2 , 543.Xr getpagesize 3 , 544.Xr getpagesizes 3 545.Sh HISTORY 546The 547.Nm 548system call was first documented in 549.Bx 4.2 550and implemented in 551.Bx 4.4 . 552.\" XXX: lots of missing history of FreeBSD additions. 553.Pp 554The 555.Dv PROT_MAX 556functionality was introduced in 557.Fx 13 . 558