1.\" $NetBSD: mmap.2,v 1.41 2009/02/27 16:48:02 wiz 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, 2009 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 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 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. 141.It Dv MAP_FIXED 142Do not permit the system to select a different address than the one 143specified. 144If the specified address cannot be used, 145.Nm mmap 146will fail. 147If MAP_FIXED is specified, 148.Fa addr 149must be a multiple of the pagesize. 150Use of this option is discouraged. 151.It Dv MAP_HASSEMAPHORE 152Notify the kernel that the region may contain semaphores and that special 153handling may be necessary. 154.It Dv MAP_INHERIT 155Permit regions to be inherited across 156.Xr execve 2 157system calls. 158.It Dv MAP_TRYFIXED 159Attempt to use the address 160.Fa addr 161even if it falls within the normally protected process data or 162text segment memory regions. 163If the requested region of memory 164is actually present in the memory map, a different address will 165be selected as if 166.Dv MAP_TRYFIXED 167had not been specified. 168If 169.Fa addr 170is 171.Fa NULL , 172this flag is ignored and the system will select a mapping address. 173.It Dv MAP_WIRED 174Lock the mapped region into memory as with 175.Xr mlock 2 . 176.It Dv MAP_PRIVATE 177Modifications made by this process are private, however modifications made by 178other processes using 179.Dv MAP_SHARED 180will be seen. 181.It Dv MAP_SHARED 182Modifications are shared. 183.El 184.Pp 185The 186.Xr close 2 187function does not unmap pages, see 188.Xr munmap 2 189for further information. 190.Pp 191The current design does not allow a process to specify the location of 192swap space. 193In the future we may define an additional mapping type, 194.Dv MAP_SWAP , 195in which 196the file descriptor argument specifies a file or device to which swapping 197should be done. 198.Pp 199If 200.Dv MAP_FIXED 201is not specified, the system will attempt to place the mapping in an 202unused portion of the address space chosen to minimize possible 203collision between mapped regions and the heap. 204.Sh RETURN VALUES 205Upon successful completion, 206.Nm mmap 207returns a pointer to the mapped region. 208Otherwise, a value of 209.Dv MAP_FAILED 210is returned and 211.Va errno 212is set to indicate the error. 213The symbol 214.Dv MAP_FAILED 215is defined in the header 216.Ao Pa sys/mman.h Ac . 217No successful return from 218.Fn mmap 219will return the value 220.Dv MAP_FAILED . 221.Sh ERRORS 222.Fn mmap 223will fail if: 224.Bl -tag -width Er 225.It Bq Er EACCES 226The flag 227.Dv PROT_READ 228was specified as part of the 229.Fa prot 230parameter and 231.Fa fd 232was not open for reading. 233The flags 234.Dv MAP_SHARED 235and 236.Dv PROT_WRITE 237were specified as part of the 238.Fa flags 239and 240.Fa prot 241parameters and 242.Fa fd 243was not open for writing. 244.It Bq Er EBADF 245.Fa fd 246is not a valid open file descriptor. 247.It Bq Er EINVAL 248.\"One of 249.\".Dv MAP_ANON 250.\"or 251.\".Dv MAP_FILE 252.\"was not specified as part of the 253.\".Fa flags 254.\"parameter. 255.Dv MAP_FIXED 256was specified and the 257.Fa addr 258parameter was not page aligned or was outside of the 259valid address range for a process. 260.Dv MAP_ANON was specified and 261.Fa fd 262was not \-1. 263.It Bq Er ENODEV 264.Fa fd 265did not reference a regular or character special file. 266.It Bq Er ENOMEM 267.Dv MAP_FIXED 268was specified and the 269.Fa addr 270parameter wasn't available. 271.Dv MAP_ANON 272was specified and insufficient memory was available. 273.It Bq Er EOVERFLOW 274.Fa fd 275references a regular file and the value of 276.Fa offset 277plus 278.Fa len 279would exceed the offset maximum established in its open file description. 280.El 281.Sh SEE ALSO 282.Xr madvise 2 , 283.Xr mincore 2 , 284.Xr mlock 2 , 285.Xr mprotect 2 , 286.Xr msync 2 , 287.Xr munmap 2 , 288.Xr getpagesize 3 , 289.Xr sysconf 3 290