1.\" $NetBSD: mmap.2,v 1.22 2000/06/26 17:00:02 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/mman.h> 46.Ft void * 47.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 48.Sh DESCRIPTION 49The 50.Nm mmap 51function causes the pages starting at 52.Fa addr 53and continuing for at most 54.Fa len 55bytes to be mapped from the object described by 56.Fa fd , 57starting at byte offset 58.Fa offset . 59If 60.Fa len 61is not a multiple of the pagesize, the mapped region may extend past the 62specified range. 63Any such extension beyond the end of the mapped object will be zero-filled. 64.Pp 65If 66.Fa addr 67is non-zero, it is used as a hint to the system. 68(As a convenience to the system, the actual address of the region may differ 69from the address supplied.) 70If 71.Fa addr 72is zero, an address will be selected by the system. 73The actual starting address of the region is returned. 74A successful 75.Fa mmap 76deletes any previous mapping in the allocated address range. 77.Pp 78The protections (region accessibility) are specified in the 79.Fa prot 80argument by 81.Em or Ns 'ing 82the following values: 83.Pp 84.Bl -tag -width MAP_FIXEDX 85.It Dv PROT_EXEC 86Pages may be executed. 87.It Dv PROT_READ 88Pages may be read. 89.It Dv PROT_WRITE 90Pages may be written. 91.It Dv PROT_NONE 92Pages may not be accessed. 93.El 94.Pp 95The 96.Fa flags 97parameter specifies the type of the mapped object, mapping options and 98whether modifications made to the mapped copy of the page are private 99to the process or are to be shared with other references. 100Note that either 101.Dv MAP_SHARED , 102.Dv MAP_PRIVATE 103or 104.Dv MAP_COPY 105must be specified. 106Sharing, mapping type and options are specified in the 107.Fa flags 108argument by 109.Em or Ns 'ing 110the following values: 111.Pp 112.Bl -tag -width MAP_FIXEDX 113.It Dv MAP_ANON 114Map anonymous memory not associated with any specific file. 115The file descriptor used for creating 116.Dv MAP_ANON 117regions is used only for 118naming, and may be specified as \-1 if no name is associated with the 119region. 120.It Dv MAP_FILE 121Mapped from a regular file or character-special device memory. 122.It Dv MAP_FIXED 123Do not permit the system to select a different address than the one 124specified. 125If the specified address cannot be used, 126.Nm mmap 127will fail. 128If MAP_FIXED is specified, 129.Fa addr 130must be a multiple of the pagesize. 131Use of this option is discouraged. 132.It Dv MAP_HASSEMAPHORE 133Notify the kernel that the region may contain semaphores and that special 134handling may be necessary. 135.It Dv MAP_INHERIT 136Permit regions to be inherited across 137.Xr execve 2 138system calls. 139.It Dv MAP_PRIVATE 140Modifications made by this process are private, however modifications made by 141other processes using 142.Dv MAP_SHARED 143will be seen. 144.It Dv MAP_SHARED 145Modifications are shared. 146.It Dv MAP_COPY 147Modifications are private, including other processes. 148.El 149.Pp 150The 151.Xr close 2 152function does not unmap pages, see 153.Xr munmap 2 154for further information. 155.Pp 156The current design does not allow a process to specify the location of 157swap space. 158In the future we may define an additional mapping type, 159.Dv MAP_SWAP , 160in which 161the file descriptor argument specifies a file or device to which swapping 162should be done. 163.Sh RETURN VALUES 164Upon successful completion, 165.Nm mmap 166returns a pointer to the mapped region. 167Otherwise, a value of 168.Dv MAP_FAILED 169is returned and 170.Va errno 171is set to indicate the error. 172The symbol 173.Dv MAP_FAILED 174is defined in the header 175.Ao Pa sys/mman.h Ac . 176No successful return from 177.Fn mmap 178will return the value 179.Dv MAP_FAILED . 180.Sh ERRORS 181.Fn mmap 182will fail if: 183.Bl -tag -width Er 184.It Bq Er EACCES 185The flag 186.Dv PROT_READ 187was specified as part of the 188.Fa prot 189parameter and 190.Fa fd 191was not open for reading. 192The flags 193.Dv MAP_SHARED 194and 195.Dv PROT_WRITE 196were specified as part of the 197.Fa flags 198and 199.Fa prot 200parameters and 201.Fa fd 202was not open for writing. 203.It Bq Er EBADF 204.Fa fd 205is not a valid open file descriptor. 206.It Bq Er EINVAL 207.\"One of 208.\".Dv MAP_ANON 209.\"or 210.\".Dv MAP_FILE 211.\"was not specified as part of the 212.\".Fa flags 213.\"parameter. 214.Dv MAP_FIXED 215was specified and the 216.Fa addr 217parameter was not page aligned or was outside of the 218valid address range for a process. 219.Dv MAP_ANON was specified and 220.Fa fd 221was not \-1. 222.Fa len 223was less than zero. 224.It Bq Er ENODEV 225.Fa fd 226did not reference a regular or character special file. 227.It Bq Er ENOMEM 228.Dv MAP_FIXED 229was specified and the 230.Fa addr 231parameter wasn't available. 232.Dv MAP_ANON 233was specified and insufficient memory was available. 234.It Bq Er EOVERFLOW 235.Fa fd 236references a regular file and the value of 237.Fa offset 238plus 239.Fa len 240would exceed the offset maximum established in its open file description. 241.El 242.Sh SEE ALSO 243.Xr madvise 2 , 244.Xr mincore 2 , 245.Xr mlock 2 , 246.Xr mprotect 2 , 247.Xr msync 2 , 248.Xr munmap 2 , 249.Xr getpagesize 3 250.Sh BUGS 251The 252.Dv MAP_COPY 253flag is not implemented. The current 254.Dv MAP_COPY 255semantics are the same as those of the 256.Dv MAP_PRIVATE 257flag. 258