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: src/lib/libc/sys/mmap.2,v 1.22.2.12 2002/02/27 03:40:13 dd Exp $ 30.\" 31.Dd January 18, 2015 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/types.h 41.In sys/mman.h 42.Ft void * 43.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 44.Sh DESCRIPTION 45The 46.Fn mmap 47function causes the pages starting at 48.Fa addr 49and continuing for at most 50.Fa len 51bytes to be mapped from the object described by 52.Fa fd , 53starting at byte offset 54.Fa offset . 55If 56.Fa len 57is not a multiple of the pagesize, the mapped region may extend past the 58specified range. 59Any such extension beyond the end of the mapped object will be zero-filled. 60.Pp 61If 62.Fa addr 63is non-zero, it is used as a hint to the system. 64(As a convenience to the system, the actual address of the region may differ 65from the address supplied.) 66If 67.Fa addr 68is zero, an address will be selected by the system. 69The actual starting address of the region is returned. 70A successful 71.Fa mmap 72deletes any previous mapping in the allocated address range. 73.Pp 74The protections (region accessibility) are specified in the 75.Fa prot 76argument by 77.Em or Ns 'ing 78the following values: 79.Pp 80.Bl -tag -width ".Dv PROT_WRITE" -compact 81.It Dv PROT_NONE 82Pages may not be accessed. 83.It Dv PROT_READ 84Pages may be read. 85.It Dv PROT_WRITE 86Pages may be written. 87.It Dv PROT_EXEC 88Pages may be executed. 89.El 90.Pp 91The 92.Fa flags 93parameter specifies the type of the mapped object, mapping options and 94whether modifications made to the mapped copy of the page are private 95to the process or are to be shared with other references. 96Sharing, mapping type and options are specified in the 97.Fa flags 98argument by 99.Em or Ns 'ing 100the following values: 101.Bl -tag -width ".Dv MAP_HASSEMAPHORE" 102.It Dv MAP_ANON 103Map anonymous memory not associated with any specific file. 104The file descriptor used for creating 105.Dv MAP_ANON 106must be \-1. 107The 108.Fa offset 109parameter is ignored. 110.It Dv MAP_ANONYMOUS 111This flag is an alias for 112.Dv MAP_ANON 113and is provided for compatibility. 114.\".It Dv MAP_FILE 115.\"Mapped from a regular file or character-special device memory. 116.It Dv MAP_FIXED 117Do not permit the system to select a different address than the one 118specified. 119If the specified address contains other mappings those mappings will 120be replaced. 121If the specified address cannot otherwise be used, 122.Fn mmap 123will fail. 124If 125.Dv MAP_FIXED 126is specified, 127.Fa addr 128must be a multiple of the pagesize. 129.It Dv MAP_TRYFIXED 130Try to do a fixed mapping but fail if another mapping already exists in 131the space instead of overwriting the mapping. 132.Pp 133When used with 134.Dv MAP_STACK 135This flag creates a grow-down stack area with the specified maximum 136stack size. 137It is no longer special-cased and will be converted to a normal anonymous 138.Fn mmap , 139meaning that other 140.Fn mmap 141calls cannot sub-map ungrown areas returned by prior 142.Dv MAP_STACK 143maps using 144.Dv MAP_TRYFIXED . 145The entire area is now applicable to the mapping. 146.Pp 147Note that the kernel itself can still create auto-grow areas but will 148do so for the user stack in order to maintain backwards compatibility 149with older code that might otherwise assume it can map below the user 150stack (in particular, older pthread libraries). 151This compatibility is deprecated and will be removed in a future release. 152.It Dv MAP_HASSEMAPHORE 153Notify the kernel that the region may contain semaphores and that special 154handling may be necessary. 155.It Dv MAP_NOCORE 156Region is not included in a core file. 157.It Dv MAP_NOSYNC 158Causes data dirtied via this VM map to be flushed to physical media 159only when necessary (usually by the pager) rather than gratuitously. 160Typically this prevents the update daemons from flushing pages dirtied 161through such maps and thus allows efficient sharing of memory across 162unassociated processes using a file-backed shared memory map. 163Without 164this option any VM pages you dirty may be flushed to disk every so often 165(every 30-60 seconds usually) which can create performance problems if you 166do not need that to occur (such as when you are using shared file-backed 167mmap regions for IPC purposes). 168Note that VM/filesystem coherency is maintained whether you use 169.Dv MAP_NOSYNC 170or not. 171This option is not portable across 172.Ux 173platforms (yet), though some may implement the same behavior 174by default. 175.Pp 176.Em WARNING ! 177Extending a file with 178.Xr ftruncate 2 , 179thus creating a big hole, and then filling the hole by modifying a shared 180.Fn mmap 181can lead to severe file fragmentation. 182In order to avoid such fragmentation you should always pre-allocate the 183file's backing store by 184.Fn write Ns ing 185zero's into the newly extended area prior to modifying the area via your 186.Fn mmap . 187The fragmentation problem is especially sensitive to 188.Dv MAP_NOSYNC 189pages, because pages may be flushed to disk in a totally random order. 190.Pp 191The same applies when using 192.Dv MAP_NOSYNC 193to implement a file-based shared memory store. 194It is recommended that you create the backing store by 195.Fn write Ns ing 196zero's to the backing file rather than 197.Fn ftruncate Ns ing 198it. 199You can test file fragmentation by observing the KB/t (kilobytes per 200transfer) results from an 201.Dq Li iostat 1 202while reading a large file sequentially, e.g.,\& using 203.Dq Li dd if=filename of=/dev/null bs=32k . 204.Pp 205The 206.Xr fsync 2 207function will flush all dirty data and metadata associated with a file, 208including dirty NOSYNC VM data, to physical media. 209The 210.Xr sync 8 211command and 212.Xr sync 2 213system call generally do not flush dirty NOSYNC VM data. 214The 215.Xr msync 2 216system call is obsolete since 217.Bx 218implements a coherent filesystem buffer cache. 219However, it may be 220used to associate dirty VM pages with filesystem buffers and thus cause 221them to be flushed to physical media sooner rather than later. 222.It Dv MAP_PRIVATE 223Modifications are private. 224.It Dv MAP_SHARED 225Modifications are shared. 226.It Dv MAP_STACK 227Map the area as a stack. 228.Dv MAP_ANON 229is implied. 230.Fa Offset 231should be 0, 232.Fa fd 233must be -1, and 234.Fa prot 235should include at least 236.Dv PROT_READ 237and 238.Dv PROT_WRITE . 239This option creates 240a memory region that grows to at most 241.Fa len 242bytes in size, starting from the stack top and growing down. 243The stack top is the starting address returned by the call, plus 244.Fa len 245bytes. 246The bottom of the stack at maximum growth is the starting 247address returned by the call. 248.Pp 249The entire area is reserved from the point of view of other 250.Fn mmap 251calls, even if not faulted in yet. 252.Pp 253Note that unless 254.Dv MAP_FIXED 255or 256.Dv MAP_TRYFIXED 257is used, you cannot count on the returned address matching the hint 258you have provided. 259.It Dv MAP_VPAGETABLE 260Memory accessed via this map is not linearly mapped and will be governed 261by a virtual page table. 262The base address of the virtual page table may be set using 263.Xr mcontrol 2 264with 265.Dv MADV_SETMAP . 266Virtual page tables work with anonymous memory but there 267is no way to populate the page table so for all intents and purposes 268.Dv MAP_VPAGETABLE 269can only be used when mapping file descriptors. 270Since the kernel will update the 271.Dv VPTE_M 272bit in the virtual page table, the mapping must R+W 273even though actual access to the memory will be properly governed by 274the virtual page table. 275.Pp 276Addressable backing store is limited by the range supported in the virtual 277page table entries. 278The kernel may implement a page table abstraction capable 279of addressing a larger range within the backing store then could otherwise 280be mapped into memory. 281.El 282.Pp 283The 284.Xr close 2 285function does not unmap pages, see 286.Xr munmap 2 287for further information. 288.Pp 289The current design does not allow a process to specify the location of 290swap space. 291In the future we may define an additional mapping type, 292.Dv MAP_SWAP , 293in which 294the file descriptor argument specifies a file or device to which swapping 295should be done. 296.Sh RETURN VALUES 297Upon successful completion, 298.Fn mmap 299returns a pointer to the mapped region. 300Otherwise, a value of 301.Dv MAP_FAILED 302is returned and 303.Va errno 304is set to indicate the error. 305.Sh ERRORS 306.Fn Mmap 307will fail if: 308.Bl -tag -width Er 309.It Bq Er EACCES 310The flag 311.Dv PROT_READ 312was specified as part of the 313.Fa prot 314parameter and 315.Fa fd 316was not open for reading. 317The flags 318.Dv MAP_SHARED 319and 320.Dv PROT_WRITE 321were specified as part of the 322.Fa flags 323and 324.Fa prot 325parameters and 326.Fa fd 327was not open for writing. 328.It Bq Er EBADF 329.Fa fd 330is not a valid open file descriptor. 331.It Bq Er EINVAL 332.Dv MAP_FIXED 333was specified and the 334.Fa addr 335parameter was not page aligned, or part of the desired address space 336resides out of the valid address space for a user process. 337.It Bq Er EINVAL 338.Fa Len 339was negative. 340.It Bq Er EINVAL 341.Dv MAP_ANON 342was specified and the 343.Fa fd 344parameter was not -1. 345.It Bq Er EINVAL 346.Dv MAP_ANON 347has not been specified and 348.Fa fd 349did not reference a regular or character special file. 350.It Bq Er EINVAL 351.Fa Offset 352was not page-aligned. 353.It Bq Er ENOMEM 354.Dv MAP_FIXED 355was specified and the 356.Fa addr 357parameter wasn't available. 358.Dv MAP_ANON 359was specified and insufficient memory was available. 360The system has reached the per-process mmap limit specified in the 361.Va vm.max_proc_mmap 362sysctl. 363.El 364.Sh SEE ALSO 365.Xr madvise 2 , 366.Xr mincore 2 , 367.Xr mlock 2 , 368.Xr mprotect 2 , 369.Xr msync 2 , 370.Xr munlock 2 , 371.Xr munmap 2 , 372.Xr getpagesize 3 373