1.\" $NetBSD: mmap.2,v 1.20 1999/12/02 21:42:38 kleink 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95 35.\" 36.Dd May 11, 1995 37.Dt MMAP 2 38.Os 39.Sh NAME 40.Nm mmap 41.Nd map files or devices into memory 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.Fd #include <sys/types.h> 46.Fd #include <sys/mman.h> 47.Ft void * 48.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 49.Sh DESCRIPTION 50The 51.Nm mmap 52function causes the pages starting at 53.Fa addr 54and continuing for at most 55.Fa len 56bytes to be mapped from the object described by 57.Fa fd , 58starting at byte offset 59.Fa offset . 60If 61.Fa len 62is not a multiple of the pagesize, the mapped region may extend past the 63specified range. 64Any such extension beyond the end of the mapped object will be zero-filled. 65.Pp 66If 67.Fa addr 68is non-zero, it is used as a hint to the system. 69(As a convenience to the system, the actual address of the region may differ 70from the address supplied.) 71If 72.Fa addr 73is zero, an address will be selected by the system. 74The actual starting address of the region is returned. 75A successful 76.Fa mmap 77deletes any previous mapping in the allocated address range. 78.Pp 79The protections (region accessibility) are specified in the 80.Fa prot 81argument by 82.Em or Ns 'ing 83the following values: 84.Pp 85.Bl -tag -width MAP_FIXEDX 86.It Dv PROT_EXEC 87Pages may be executed. 88.It Dv PROT_READ 89Pages may be read. 90.It Dv PROT_WRITE 91Pages may be written. 92.It Dv PROT_NONE 93Pages may not be accessed. 94.El 95.Pp 96The 97.Fa flags 98parameter specifies the type of the mapped object, mapping options and 99whether modifications made to the mapped copy of the page are private 100to the process or are to be shared with other references. 101Note that either 102.Dv MAP_SHARED , 103.Dv MAP_PRIVATE 104or 105.Dv MAP_COPY 106must be specified. 107Sharing, mapping type and options are specified in the 108.Fa flags 109argument by 110.Em or Ns 'ing 111the following values: 112.Pp 113.Bl -tag -width MAP_FIXEDX 114.It Dv MAP_ANON 115Map anonymous memory not associated with any specific file. 116The file descriptor used for creating 117.Dv MAP_ANON 118regions is used only for 119naming, and may be specified as \-1 if no name is associated with the 120region. 121.It Dv MAP_FILE 122Mapped from a regular file or character-special device memory. 123.It Dv MAP_FIXED 124Do not permit the system to select a different address than the one 125specified. 126If the specified address cannot be used, 127.Nm mmap 128will fail. 129If MAP_FIXED is specified, 130.Fa addr 131must be a multiple of the pagesize. 132Use of this option is discouraged. 133.It Dv MAP_HASSEMAPHORE 134Notify the kernel that the region may contain semaphores and that special 135handling may be necessary. 136.It Dv MAP_INHERIT 137Permit regions to be inherited across 138.Xr execve 2 139system calls. 140.It Dv MAP_PRIVATE 141Modifications made by this process are private, however modifications made by 142other processes using 143.Dv MAP_SHARED 144will be seen. 145.It Dv MAP_SHARED 146Modifications are shared. 147.It Dv MAP_COPY 148Modifications are private, including other processes. 149.El 150.Pp 151The 152.Xr close 2 153function does not unmap pages, see 154.Xr munmap 2 155for further information. 156.Pp 157The current design does not allow a process to specify the location of 158swap space. 159In the future we may define an additional mapping type, 160.Dv MAP_SWAP , 161in which 162the file descriptor argument specifies a file or device to which swapping 163should be done. 164.Sh RETURN VALUES 165Upon successful completion, 166.Nm mmap 167returns a pointer to the mapped region. 168Otherwise, a value of 169.Dv MAP_FAILED 170is returned and 171.Va errno 172is set to indicate the error. 173The symbol 174.Dv MAP_FAILED 175is defined in the header 176.Ao Pa sys/mman.h Ac . 177No successful return from 178.Fn mmap 179will return the value 180.Dv MAP_FAILED . 181.Sh ERRORS 182.Fn mmap 183will fail if: 184.Bl -tag -width Er 185.It Bq Er EACCES 186The flag 187.Dv PROT_READ 188was specified as part of the 189.Fa prot 190parameter and 191.Fa fd 192was not open for reading. 193The flags 194.Dv MAP_SHARED 195and 196.Dv PROT_WRITE 197were specified as part of the 198.Fa flags 199and 200.Fa prot 201parameters and 202.Fa fd 203was not open for writing. 204.It Bq Er EBADF 205.Fa fd 206is not a valid open file descriptor. 207.It Bq Er EINVAL 208.\"One of 209.\".Dv MAP_ANON 210.\"or 211.\".Dv MAP_FILE 212.\"was not specified as part of the 213.\".Fa flags 214.\"parameter. 215.Dv MAP_FIXED 216was specified and the 217.Fa addr 218parameter was not page aligned or was outside of the 219valid address range for a process. 220.Dv MAP_ANON was specified and 221.Fa fd 222was not \-1. 223.Fa len 224was less than zero. 225.It Bq Er ENODEV 226.Fa fd 227did not reference a regular or character special file. 228.It Bq Er ENOMEM 229.Dv MAP_FIXED 230was specified and the 231.Fa addr 232parameter wasn't available. 233.Dv MAP_ANON 234was specified and insufficient memory was available. 235.El 236.Sh SEE ALSO 237.Xr madvise 2 , 238.Xr mincore 2 , 239.Xr mlock 2 , 240.Xr mprotect 2 , 241.Xr msync 2 , 242.Xr munmap 2 , 243.Xr getpagesize 3 244.Sh BUGS 245The 246.Dv MAP_COPY 247flag is not implemented. The current 248.Dv MAP_COPY 249semantics are the same as those of the 250.Dv MAP_PRIVATE 251flag. 252