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.\" 4. 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 September 17, 2014 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 pagesize, 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 addr 62is non-zero, it is used as a hint to the system. 63(As a convenience to the system, the actual address of the region may differ 64from the address supplied.) 65If 66.Fa addr 67is zero, an address will be selected by the system. 68The actual starting address of the region is returned. 69A successful 70.Fa mmap 71deletes any previous mapping in the allocated address range. 72.Pp 73The protections (region accessibility) are specified in the 74.Fa prot 75argument by 76.Em or Ns 'ing 77the following values: 78.Pp 79.Bl -tag -width PROT_WRITE -compact 80.It Dv PROT_NONE 81Pages may not be accessed. 82.It Dv PROT_READ 83Pages may be read. 84.It Dv PROT_WRITE 85Pages may be written. 86.It Dv PROT_EXEC 87Pages may be executed. 88.El 89.Pp 90The 91.Fa flags 92argument specifies the type of the mapped object, mapping options and 93whether modifications made to the mapped copy of the page are private 94to the process or are to be shared with other references. 95Sharing, mapping type and options are specified in the 96.Fa flags 97argument by 98.Em or Ns 'ing 99the following values: 100.Bl -tag -width MAP_PREFAULT_READ 101.It Dv MAP_32BIT 102Request a region in the first 2GB of the current process's address space. 103If a suitable region cannot be found, 104.Fn mmap 105will fail. 106This flag is only available on 64-bit platforms. 107.It Dv MAP_ALIGNED Ns Pq Fa n 108Align the region on a requested boundary. 109If a suitable region cannot be found, 110.Fn mmap 111will fail. 112The 113.Fa n 114argument specifies the binary logarithm of the desired alignment. 115.It Dv MAP_ALIGNED_SUPER 116Align the region to maximize the potential use of large 117.Pq Dq super 118pages. 119If a suitable region cannot be found, 120.Fn mmap 121will fail. 122The system will choose a suitable page size based on the size of 123mapping. 124The page size used as well as the alignment of the region may both be 125affected by properties of the file being mapped. 126In particular, 127the physical address of existing pages of a file may require a specific 128alignment. 129The region is not guaranteed to be aligned on any specific boundary. 130.It Dv MAP_ANON 131Map anonymous memory not associated with any specific file. 132The file descriptor used for creating 133.Dv MAP_ANON 134must be \-1. 135The 136.Fa offset 137argument must be 0. 138.\".It Dv MAP_FILE 139.\"Mapped from a regular file or character-special device memory. 140.It Dv MAP_ANONYMOUS 141This flag is identical to 142.Dv MAP_ANON 143and is provided for compatibility. 144.It Dv MAP_EXCL 145This flag can only be used in combination with 146.Dv MAP_FIXED . 147Please see the definition of 148.Dv MAP_FIXED 149for the description of its effect. 150.It Dv MAP_FIXED 151Do not permit the system to select a different address than the one 152specified. 153If the specified address cannot be used, 154.Fn mmap 155will fail. 156If 157.Dv MAP_FIXED 158is specified, 159.Fa addr 160must be a multiple of the pagesize. 161If 162.Dv MAP_EXCL 163is not specified, a successfull 164.Dv MAP_FIXED 165request replaces any previous mappings for the process' 166pages in the range from 167.Fa addr 168to 169.Fa addr 170+ 171.Fa len . 172In contrast, if 173.Dv MAP_EXCL 174is specified, the request will fail if a mapping 175already exists within the range. 176.It Dv MAP_HASSEMAPHORE 177Notify the kernel that the region may contain semaphores and that special 178handling may be necessary. 179.It Dv MAP_NOCORE 180Region is not included in a core file. 181.It Dv MAP_NOSYNC 182Causes data dirtied via this VM map to be flushed to physical media 183only when necessary (usually by the pager) rather than gratuitously. 184Typically this prevents the update daemons from flushing pages dirtied 185through such maps and thus allows efficient sharing of memory across 186unassociated processes using a file-backed shared memory map. 187Without 188this option any VM pages you dirty may be flushed to disk every so often 189(every 30-60 seconds usually) which can create performance problems if you 190do not need that to occur (such as when you are using shared file-backed 191mmap regions for IPC purposes). 192Note that VM/file system coherency is 193maintained whether you use 194.Dv MAP_NOSYNC 195or not. 196This option is not portable 197across 198.Ux 199platforms (yet), though some may implement the same behavior 200by default. 201.Pp 202.Em WARNING ! 203Extending a file with 204.Xr ftruncate 2 , 205thus creating a big hole, and then filling the hole by modifying a shared 206.Fn mmap 207can lead to severe file fragmentation. 208In order to avoid such fragmentation you should always pre-allocate the 209file's backing store by 210.Fn write Ns ing 211zero's into the newly extended area prior to modifying the area via your 212.Fn mmap . 213The fragmentation problem is especially sensitive to 214.Dv MAP_NOSYNC 215pages, because pages may be flushed to disk in a totally random order. 216.Pp 217The same applies when using 218.Dv MAP_NOSYNC 219to implement a file-based shared memory store. 220It is recommended that you create the backing store by 221.Fn write Ns ing 222zero's to the backing file rather than 223.Fn ftruncate Ns ing 224it. 225You can test file fragmentation by observing the KB/t (kilobytes per 226transfer) results from an 227.Dq Li iostat 1 228while reading a large file sequentially, e.g.\& using 229.Dq Li dd if=filename of=/dev/null bs=32k . 230.Pp 231The 232.Xr fsync 2 233system call will flush all dirty data and metadata associated with a file, 234including dirty NOSYNC VM data, to physical media. 235The 236.Xr sync 8 237command and 238.Xr sync 2 239system call generally do not flush dirty NOSYNC VM data. 240The 241.Xr msync 2 242system call is usually not needed since 243.Bx 244implements a coherent file system buffer cache. 245However, it may be 246used to associate dirty VM pages with file system buffers and thus cause 247them to be flushed to physical media sooner rather than later. 248.It Dv MAP_PREFAULT_READ 249Immediately update the calling process's lowest-level virtual address 250translation structures, such as its page table, so that every memory 251resident page within the region is mapped for read access. 252Ordinarily these structures are updated lazily. 253The effect of this option is to eliminate any soft faults that would 254otherwise occur on the initial read accesses to the region. 255Although this option does not preclude 256.Fa prot 257from including 258.Dv PROT_WRITE , 259it does not eliminate soft faults on the initial write accesses to the 260region. 261.It Dv MAP_PRIVATE 262Modifications are private. 263.It Dv MAP_SHARED 264Modifications are shared. 265.It Dv MAP_STACK 266.Dv MAP_STACK 267implies 268.Dv MAP_ANON , 269and 270.Fa offset 271of 0. 272The 273.Fa fd 274argument 275must be -1 and 276.Fa prot 277must include at least 278.Dv PROT_READ 279and 280.Dv PROT_WRITE . 281This option creates 282a memory region that grows to at most 283.Fa len 284bytes in size, starting from the stack top and growing down. 285The 286stack top is the starting address returned by the call, plus 287.Fa len 288bytes. 289The bottom of the stack at maximum growth is the starting 290address returned by the call. 291.El 292.Pp 293The 294.Xr close 2 295system call does not unmap pages, see 296.Xr munmap 2 297for further information. 298.Sh NOTES 299Although this implementation does not impose any alignment restrictions on 300the 301.Fa offset 302argument, a portable program must only use page-aligned values. 303.Pp 304Large page mappings require that the pages backing an object be 305aligned in matching blocks in both the virtual address space and RAM. 306The system will automatically attempt to use large page mappings when 307mapping an object that is already backed by large pages in RAM by 308aligning the mapping request in the virtual address space to match the 309alignment of the large physical pages. 310The system may also use large page mappings when mapping portions of an 311object that are not yet backed by pages in RAM. 312The 313.Dv MAP_ALIGNED_SUPER 314flag is an optimization that will align the mapping request to the 315size of a large page similar to 316.Dv MAP_ALIGNED , 317except that the system will override this alignment if an object already 318uses large pages so that the mapping will be consistent with the existing 319large pages. 320This flag is mostly useful for maximizing the use of large pages on the 321first mapping of objects that do not yet have pages present in RAM. 322.Sh RETURN VALUES 323Upon successful completion, 324.Fn mmap 325returns a pointer to the mapped region. 326Otherwise, a value of 327.Dv MAP_FAILED 328is returned and 329.Va errno 330is set to indicate the error. 331.Sh ERRORS 332The 333.Fn mmap 334system call 335will fail if: 336.Bl -tag -width Er 337.It Bq Er EACCES 338The flag 339.Dv PROT_READ 340was specified as part of the 341.Fa prot 342argument and 343.Fa fd 344was not open for reading. 345The flags 346.Dv MAP_SHARED 347and 348.Dv PROT_WRITE 349were specified as part of the 350.Fa flags 351and 352.Fa prot 353argument and 354.Fa fd 355was not open for writing. 356.It Bq Er EBADF 357The 358.Fa fd 359argument 360is not a valid open file descriptor. 361.It Bq Er EINVAL 362An invalid value was passed in the 363.Fa prot 364argument. 365.It Bq Er EINVAL 366An undefined option was set in the 367.Fa flags 368argument. 369.It Bq Er EINVAL 370Both 371.Dv MAP_PRIVATE 372and 373.Dv MAP_SHARED 374were specified. 375.It Bq Er EINVAL 376None of 377.Dv MAP_ANON , 378.Dv MAP_PRIVATE , 379.Dv MAP_SHARED , 380or 381.Dv MAP_STACK 382was specified. 383At least one of these flags must be included. 384.It Bq Er EINVAL 385.Dv MAP_FIXED 386was specified and the 387.Fa addr 388argument was not page aligned, or part of the desired address space 389resides out of the valid address space for a user process. 390.It Bq Er EINVAL 391Both 392.Dv MAP_FIXED 393and 394.Dv MAP_32BIT 395were specified and part of the desired address space resides outside 396of the first 2GB of user address space. 397.It Bq Er EINVAL 398The 399.Fa len 400argument 401was equal to zero. 402.It Bq Er EINVAL 403.Dv MAP_ALIGNED 404was specified and the desired alignment was either larger than the 405virtual address size of the machine or smaller than a page. 406.It Bq Er EINVAL 407.Dv MAP_ANON 408was specified and the 409.Fa fd 410argument was not -1. 411.It Bq Er EINVAL 412.Dv MAP_ANON 413was specified and the 414.Fa offset 415argument was not 0. 416.It Bq Er EINVAL 417Both 418.Dv MAP_FIXED 419and 420.Dv MAP_EXCL 421were specified, but the requested region is already used by a mapping. 422.It Bq Er EINVAL 423.Dv MAP_EXCL 424was specified, but 425.Dv MAP_FIXED 426was not. 427.It Bq Er ENODEV 428.Dv MAP_ANON 429has not been specified and 430.Fa fd 431did not reference a regular or character special file. 432.It Bq Er ENOMEM 433.Dv MAP_FIXED 434was specified and the 435.Fa addr 436argument was not available. 437.Dv MAP_ANON 438was specified and insufficient memory was available. 439.El 440.Sh SEE ALSO 441.Xr madvise 2 , 442.Xr mincore 2 , 443.Xr minherit 2 , 444.Xr mlock 2 , 445.Xr mprotect 2 , 446.Xr msync 2 , 447.Xr munlock 2 , 448.Xr munmap 2 , 449.Xr getpagesize 3 , 450.Xr getpagesizes 3 451.Sh BUGS 452The 453.Fa len 454argument 455is limited to the maximum file size or available userland address 456space. 457Files may not be able to be made more than 1TB large on 32 bit systems 458due to file systems restrictions and bugs, but address space is far more 459restrictive. 460Larger files may be possible on 64 bit systems. 461.Pp 462The previous documented limit of 2GB was a documentation bug. 463That limit has not existed since 464.Fx 2.2 . 465