1.\" $NetBSD: mmap.2,v 1.51 2017/06/12 14:59:04 abhinav 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 April 27, 2017 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.Bl -tag -width PROT_WRITEXX -offset indent 80.It Dv PROT_EXEC 81Pages may be executed. 82.It Dv PROT_READ 83Pages may be read. 84.It Dv PROT_WRITE 85Pages may be written. 86.It Dv PROT_NONE 87Placeholder when requesting no access permission. 88.El 89.Pp 90As a 91.Nx 92extension, 93.Dv PROT_MPROTECT 94can be used to request additional permissions for later use with 95.Fn mprotect 2 . 96This is necessary for switching pages between writable and executable 97when PAX mprotect restrictions are in place. 98.Pp 99.Bf -symbolic 100Note that, due to hardware limitations, on some platforms 101.Dv PROT_WRITE 102may imply 103.Dv PROT_READ , 104and 105.Dv PROT_READ 106may imply 107.Dv PROT_EXEC . 108Portable programs should not rely on these flags being separately 109enforceable. 110.Ef 111.Pp 112The 113.Fa flags 114parameter specifies the type of the mapped object, mapping options and 115whether modifications made to the mapped copy of the page are private 116to the process or are to be shared with other references. 117Note that either 118.Dv MAP_SHARED 119or 120.Dv MAP_PRIVATE 121must be specified. 122Sharing, mapping type and options are specified in the 123.Fa flags 124argument by 125.Em OR Ns 'ing 126the following values: 127.Bl -tag -width MAP_HASSEMAPHOREXX -offset indent 128.It Dv MAP_ALIGNED(n) 129Request that the allocation be aligned to the given boundary. 130The parameter 131.Ar n 132should be the base 2 logarithm of the desired alignment (e.g., to 133request alignment to 16K, use 14 as the value for n). 134The alignment must be equal to or greater than the platform's page 135size as returned by 136.Xr sysconf 3 137with the 138.Dv _SC_PAGESIZE 139request. 140.It Dv MAP_ANON 141Map anonymous memory not associated with any specific file. 142The file descriptor is not used for creating 143.Dv MAP_ANON 144regions, and must be specified as \-1. 145The mapped memory will be zero filled. 146.It Dv MAP_FILE 147Mapped from a regular file or character-special device memory. 148Read accesses beyond the end of of the file or device but less 149than the current page size will be zero-filled. 150Write accesses beyond the end of the file or device but less 151than the current page size will not affect the file or device. 152References beyond the end of file that are beyond the current 153page size will result in the delivery of 154.Dv SIGBUS 155signal. 156.It Dv MAP_FIXED 157Do not permit the system to select a different address than the one 158specified. 159If the specified address cannot be used, 160.Nm mmap 161will fail. 162If MAP_FIXED is specified, 163.Fa addr 164must be a multiple of the pagesize. 165Use of this option is discouraged. 166.It Dv MAP_HASSEMAPHORE 167Notify the kernel that the region may contain semaphores and that special 168handling may be necessary. 169.It Dv MAP_INHERIT 170Permit regions to be inherited across 171.Xr execve 2 172system calls. 173.It Dv MAP_TRYFIXED 174Attempt to use the address 175.Fa addr 176even if it falls within the normally protected process data or 177text segment memory regions. 178If the requested region of memory 179is actually present in the memory map, a different address will 180be selected as if 181.Dv MAP_TRYFIXED 182had not been specified. 183If 184.Fa addr 185is 186.Fa NULL , 187this flag is ignored and the system will select a mapping address. 188.It Dv MAP_WIRED 189Lock the mapped region into memory as with 190.Xr mlock 2 . 191.It Dv MAP_PRIVATE 192Modifications made by this process are private, however modifications made by 193other processes using 194.Dv MAP_SHARED 195will be seen. 196.It Dv MAP_SHARED 197Modifications are shared. 198.El 199.Pp 200The 201.Xr close 2 202function does not unmap pages, see 203.Xr munmap 2 204for further information. 205.Pp 206The current design does not allow a process to specify the location of 207swap space. 208In the future we may define an additional mapping type, 209.Dv MAP_SWAP , 210in which 211the file descriptor argument specifies a file or device to which swapping 212should be done. 213.Pp 214If 215.Dv MAP_FIXED 216is not specified, the system will attempt to place the mapping in an 217unused portion of the address space chosen to minimize possible 218collision between mapped regions and the heap. 219.Sh RETURN VALUES 220Upon successful completion, 221.Nm mmap 222returns a pointer to the mapped region. 223Otherwise, a value of 224.Dv MAP_FAILED 225is returned and 226.Va errno 227is set to indicate the error. 228The symbol 229.Dv MAP_FAILED 230is defined in the header 231.Ao Pa sys/mman.h Ac . 232No successful return from 233.Fn mmap 234will return the value 235.Dv MAP_FAILED . 236.Sh ERRORS 237.Fn mmap 238will fail if: 239.Bl -tag -width Er 240.It Bq Er EACCES 241The flag 242.Dv PROT_READ 243was specified as part of the 244.Fa prot 245parameter and 246.Fa fd 247was not open for reading. 248.Pp 249The flags 250.Dv MAP_SHARED 251and 252.Dv PROT_WRITE 253were specified as part of the 254.Fa flags 255and 256.Fa prot 257parameters and 258.Fa fd 259was not open for writing. 260.Pp 261PAX mprotect restrictions prohibit the requested protection. 262.It Bq Er EBADF 263.Fa fd 264is not a valid open file descriptor. 265.It Bq Er EINVAL 266.\"One of 267.\".Dv MAP_ANON 268.\"or 269.\".Dv MAP_FILE 270.\"was not specified as part of the 271.\".Fa flags 272.\"parameter. 273.Dv MAP_FIXED 274was specified and the 275.Fa addr 276parameter was not page aligned or was outside of the 277valid address range for a process. 278.Pp 279.Dv MAP_ANON was specified and 280.Fa fd 281was not \-1. 282.It Bq Er ENODEV 283.Fa fd 284did not reference a regular or character special file. 285.It Bq Er ENOMEM 286.Dv MAP_FIXED 287was specified and the 288.Fa addr 289parameter wasn't available. 290.Pp 291.Dv MAP_ANON 292was specified and insufficient memory was available. 293.It Bq Er EOVERFLOW 294.Fa fd 295references a regular file and the value of 296.Fa offset 297plus 298.Fa len 299would exceed the offset maximum established in its open file description. 300.El 301.Sh SEE ALSO 302.Xr madvise 2 , 303.Xr mincore 2 , 304.Xr mlock 2 , 305.Xr mprotect 2 , 306.Xr msync 2 , 307.Xr munmap 2 , 308.Xr getpagesize 3 , 309.Xr sysconf 3 310.Sh STANDARDS 311The 312.Fn mmap 313function conforms to 314.St -p1003.1b-93 . 315.Sh HISTORY 316The 317.Fn mmap 318interface was first designed in 319.Bx 4.2 . 320