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 December 24, 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 restrictions 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 322Creates both a mapped region that grows downward on demand and an 323adjoining guard that both reserves address space for the mapped region 324to grow into and limits the mapped region's growth. 325Together, the mapped region and the guard occupy 326.Fa len 327bytes of the address space. 328The guard starts at the returned address, and the mapped region ends at 329the returned address plus 330.Fa len 331bytes. 332Upon access to the guard, the mapped region automatically grows in size, 333and the guard shrinks by an equal amount. 334Essentially, the boundary between the guard and the mapped region moves 335downward so that the access falls within the enlarged mapped region. 336However, the guard will never shrink to less than the number of pages 337specified by the sysctl 338.Dv security.bsd.stack_guard_page , 339thereby ensuring that a gap for detecting stack overflow always exists 340between the downward growing mapped region and the closest mapped region 341beneath it. 342.Pp 343.Dv MAP_STACK 344implies 345.Dv MAP_ANON 346and 347.Fa offset 348of 0. 349The 350.Fa fd 351argument 352must be -1 and 353.Fa prot 354must include at least 355.Dv PROT_READ 356and 357.Dv PROT_WRITE . 358The size of the guard, in pages, is specified by sysctl 359.Dv security.bsd.stack_guard_page . 360.El 361.Pp 362The 363.Xr close 2 364system call does not unmap pages, see 365.Xr munmap 2 366for further information. 367.Sh NOTES 368Although this implementation does not impose any alignment restrictions on 369the 370.Fa offset 371argument, a portable program must only use page-aligned values. 372.Pp 373Large page mappings require that the pages backing an object be 374aligned in matching blocks in both the virtual address space and RAM. 375The system will automatically attempt to use large page mappings when 376mapping an object that is already backed by large pages in RAM by 377aligning the mapping request in the virtual address space to match the 378alignment of the large physical pages. 379The system may also use large page mappings when mapping portions of an 380object that are not yet backed by pages in RAM. 381The 382.Dv MAP_ALIGNED_SUPER 383flag is an optimization that will align the mapping request to the 384size of a large page similar to 385.Dv MAP_ALIGNED , 386except that the system will override this alignment if an object already 387uses large pages so that the mapping will be consistent with the existing 388large pages. 389This flag is mostly useful for maximizing the use of large pages on the 390first mapping of objects that do not yet have pages present in RAM. 391.Sh RETURN VALUES 392Upon successful completion, 393.Fn mmap 394returns a pointer to the mapped region. 395Otherwise, a value of 396.Dv MAP_FAILED 397is returned and 398.Va errno 399is set to indicate the error. 400.Sh ERRORS 401The 402.Fn mmap 403system call 404will fail if: 405.Bl -tag -width Er 406.It Bq Er EACCES 407The flag 408.Dv PROT_READ 409was specified as part of the 410.Fa prot 411argument and 412.Fa fd 413was not open for reading. 414The flags 415.Dv MAP_SHARED 416and 417.Dv PROT_WRITE 418were specified as part of the 419.Fa flags 420and 421.Fa prot 422argument and 423.Fa fd 424was not open for writing. 425.It Bq Er EBADF 426The 427.Fa fd 428argument 429is not a valid open file descriptor. 430.It Bq Er EINVAL 431An invalid (negative) value was passed in the 432.Fa offset 433argument, when 434.Fa fd 435referenced a regular file or shared memory. 436.It Bq Er EINVAL 437An invalid value was passed in the 438.Fa prot 439argument. 440.It Bq Er EINVAL 441An undefined option was set in the 442.Fa flags 443argument. 444.It Bq Er EINVAL 445Both 446.Dv MAP_PRIVATE 447and 448.Dv MAP_SHARED 449were specified. 450.It Bq Er EINVAL 451None of 452.Dv MAP_ANON , 453.Dv MAP_GUARD , 454.Dv MAP_PRIVATE , 455.Dv MAP_SHARED , 456or 457.Dv MAP_STACK 458was specified. 459At least one of these flags must be included. 460.It Bq Er EINVAL 461.Dv MAP_STACK 462was specified and 463.Va len 464is less than or equal to the guard size. 465.It Bq Er EINVAL 466.Dv MAP_FIXED 467was specified and the 468.Fa addr 469argument was not page aligned, or part of the desired address space 470resides out of the valid address space for a user process. 471.It Bq Er EINVAL 472Both 473.Dv MAP_FIXED 474and 475.Dv MAP_32BIT 476were specified and part of the desired address space resides outside 477of the first 2GB of user address space. 478.It Bq Er EINVAL 479The 480.Fa len 481argument 482was equal to zero. 483.It Bq Er EINVAL 484.Dv MAP_ALIGNED 485was specified and the desired alignment was either larger than the 486virtual address size of the machine or smaller than a page. 487.It Bq Er EINVAL 488.Dv MAP_ANON 489was specified and the 490.Fa fd 491argument was not -1. 492.It Bq Er EINVAL 493.Dv MAP_ANON 494was specified and the 495.Fa offset 496argument was not 0. 497.It Bq Er EINVAL 498Both 499.Dv MAP_FIXED 500and 501.Dv MAP_EXCL 502were specified, but the requested region is already used by a mapping. 503.It Bq Er EINVAL 504.Dv MAP_EXCL 505was specified, but 506.Dv MAP_FIXED 507was not. 508.It Bq Er EINVAL 509.Dv MAP_GUARD 510was specified, but the 511.Fa offset 512argument was not zero, the 513.Fa fd 514argument was not -1, or the 515.Fa prot 516argument was not 517.Dv PROT_NONE . 518.It Bq Er EINVAL 519.Dv MAP_GUARD 520was specified together with one of the flags 521.Dv MAP_ANON , 522.Dv MAP_PREFAULT , 523.Dv MAP_PREFAULT_READ , 524.Dv MAP_PRIVATE , 525.Dv MAP_SHARED , 526.Dv MAP_STACK . 527.It Bq Er ENODEV 528.Dv MAP_ANON 529has not been specified and 530.Fa fd 531did not reference a regular or character special file. 532.It Bq Er ENOMEM 533.Dv MAP_FIXED 534was specified and the 535.Fa addr 536argument was not available. 537.Dv MAP_ANON 538was specified and insufficient memory was available. 539.It Bq Er ENOTSUP 540The 541.Fa prot 542argument contains protections which are not a subset of the specified 543maximum protections. 544.El 545.Sh SEE ALSO 546.Xr madvise 2 , 547.Xr mincore 2 , 548.Xr minherit 2 , 549.Xr mlock 2 , 550.Xr mprotect 2 , 551.Xr msync 2 , 552.Xr munlock 2 , 553.Xr munmap 2 , 554.Xr getpagesize 3 , 555.Xr getpagesizes 3 556.Sh HISTORY 557The 558.Nm 559system call was first documented in 560.Bx 4.2 561and implemented in 562.Bx 4.4 . 563.\" XXX: lots of missing history of FreeBSD additions. 564.Pp 565The 566.Dv PROT_MAX 567functionality was introduced in 568.Fx 13 . 569