1.\" $NetBSD: mmap.2,v 1.48 2015/02/27 16:18:00 christos Exp $ 2.\" 3.\" Copyright (c) 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95 31.\" 32.Dd February 27, 2015 33.Dt MMAP 2 34.Os 35.Sh NAME 36.Nm mmap 37.Nd map files or devices into memory 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 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.Nm 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 PROT_WRITEXX -offset indent 81.It Dv PROT_EXEC 82Pages may be executed. 83.It Dv PROT_READ 84Pages may be read. 85.It Dv PROT_WRITE 86Pages may be written. 87.It Dv PROT_NONE 88Pages may not be accessed. 89.El 90.Pp 91.Bf -symbolic 92Note that, due to hardware limitations, on some platforms 93.Dv PROT_WRITE 94may imply 95.Dv PROT_READ , 96and 97.Dv PROT_READ 98may imply 99.Dv PROT_EXEC . 100Portable programs should not rely on these flags being separately 101enforceable. 102.Ef 103.Pp 104The 105.Fa flags 106parameter specifies the type of the mapped object, mapping options and 107whether modifications made to the mapped copy of the page are private 108to the process or are to be shared with other references. 109Note that either 110.Dv MAP_SHARED 111or 112.Dv MAP_PRIVATE 113must be specified. 114Sharing, mapping type and options are specified in the 115.Fa flags 116argument by 117.Em OR Ns 'ing 118the following values: 119.Pp 120.Bl -tag -width MAP_HASSEMAPHOREXX -offset indent 121.It Dv MAP_ALIGNED(n) 122Request that the allocation be aligned to the given boundary. 123The parameter 124.Ar n 125should be the base 2 logarithm of the desired alignment (e.g., to 126request alignment to 16K, use 14 as the value for n). 127The alignment must be equal to or greater than the platform's page 128size as returned by 129.Xr sysconf 3 130with the 131.Dv _SC_PAGESIZE 132request. 133.It Dv MAP_ANON 134Map anonymous memory not associated with any specific file. 135The file descriptor is not used for creating 136.Dv MAP_ANON 137regions, and must be specified as \-1. 138The mapped memory will be zero filled. 139.It Dv MAP_FILE 140Mapped from a regular file or character-special device memory. 141Read accesses beyond the end of of the file or device but less 142than the current page size will be zero-filled. 143Write accesses beyond the end of the file or device but less 144than the current page size will not affect the file or device. 145References beyond the end of file that are beyond the current 146page size will result in the delivery of 147.Dv SIGBUS 148signal. 149.It Dv MAP_FIXED 150Do not permit the system to select a different address than the one 151specified. 152If the specified address cannot be used, 153.Nm mmap 154will fail. 155If MAP_FIXED is specified, 156.Fa addr 157must be a multiple of the pagesize. 158Use of this option is discouraged. 159.It Dv MAP_HASSEMAPHORE 160Notify the kernel that the region may contain semaphores and that special 161handling may be necessary. 162.It Dv MAP_INHERIT 163Permit regions to be inherited across 164.Xr execve 2 165system calls. 166.It Dv MAP_TRYFIXED 167Attempt to use the address 168.Fa addr 169even if it falls within the normally protected process data or 170text segment memory regions. 171If the requested region of memory 172is actually present in the memory map, a different address will 173be selected as if 174.Dv MAP_TRYFIXED 175had not been specified. 176If 177.Fa addr 178is 179.Fa NULL , 180this flag is ignored and the system will select a mapping address. 181.It Dv MAP_WIRED 182Lock the mapped region into memory as with 183.Xr mlock 2 . 184.It Dv MAP_PRIVATE 185Modifications made by this process are private, however modifications made by 186other processes using 187.Dv MAP_SHARED 188will be seen. 189.It Dv MAP_SHARED 190Modifications are shared. 191.El 192.Pp 193The 194.Xr close 2 195function does not unmap pages, see 196.Xr munmap 2 197for further information. 198.Pp 199The current design does not allow a process to specify the location of 200swap space. 201In the future we may define an additional mapping type, 202.Dv MAP_SWAP , 203in which 204the file descriptor argument specifies a file or device to which swapping 205should be done. 206.Pp 207If 208.Dv MAP_FIXED 209is not specified, the system will attempt to place the mapping in an 210unused portion of the address space chosen to minimize possible 211collision between mapped regions and the heap. 212.Sh RETURN VALUES 213Upon successful completion, 214.Nm mmap 215returns a pointer to the mapped region. 216Otherwise, a value of 217.Dv MAP_FAILED 218is returned and 219.Va errno 220is set to indicate the error. 221The symbol 222.Dv MAP_FAILED 223is defined in the header 224.Ao Pa sys/mman.h Ac . 225No successful return from 226.Fn mmap 227will return the value 228.Dv MAP_FAILED . 229.Sh ERRORS 230.Fn mmap 231will fail if: 232.Bl -tag -width Er 233.It Bq Er EACCES 234The flag 235.Dv PROT_READ 236was specified as part of the 237.Fa prot 238parameter and 239.Fa fd 240was not open for reading. 241The flags 242.Dv MAP_SHARED 243and 244.Dv PROT_WRITE 245were specified as part of the 246.Fa flags 247and 248.Fa prot 249parameters and 250.Fa fd 251was not open for writing. 252.It Bq Er EBADF 253.Fa fd 254is not a valid open file descriptor. 255.It Bq Er EINVAL 256.\"One of 257.\".Dv MAP_ANON 258.\"or 259.\".Dv MAP_FILE 260.\"was not specified as part of the 261.\".Fa flags 262.\"parameter. 263.Dv MAP_FIXED 264was specified and the 265.Fa addr 266parameter was not page aligned or was outside of the 267valid address range for a process. 268.Dv MAP_ANON was specified and 269.Fa fd 270was not \-1. 271.It Bq Er ENODEV 272.Fa fd 273did not reference a regular or character special file. 274.It Bq Er ENOMEM 275.Dv MAP_FIXED 276was specified and the 277.Fa addr 278parameter wasn't available. 279.Dv MAP_ANON 280was specified and insufficient memory was available. 281.It Bq Er EOVERFLOW 282.Fa fd 283references a regular file and the value of 284.Fa offset 285plus 286.Fa len 287would exceed the offset maximum established in its open file description. 288.El 289.Sh SEE ALSO 290.Xr madvise 2 , 291.Xr mincore 2 , 292.Xr mlock 2 , 293.Xr mprotect 2 , 294.Xr msync 2 , 295.Xr munmap 2 , 296.Xr getpagesize 3 , 297.Xr sysconf 3 298.Sh STANDARDS 299The 300.Fn mmap 301function conforms to 302.St -p1003.1b-93 . 303.Sh HISTORY 304The 305.Fn mmap 306interface was first designed in 307.Bx 4.2 . 308