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