1.\" $NetBSD: mmap.2,v 1.25 2002/02/08 01:28:19 ross 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 \*[Lt]sys/mman.h\*[Gt] 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 95.Bf -symbolic 96Note that, due to hardware limitations, on some platforms 97.Dv PROT_WRITE 98may imply 99.Dv PROT_READ , 100and 101.Dv PROT_READ 102may imply 103.Dv PROT_EXEC . 104Portable programs should not rely on these flags being separately 105enforcable. 106.Ef 107.Pp 108The 109.Fa flags 110parameter specifies the type of the mapped object, mapping options and 111whether modifications made to the mapped copy of the page are private 112to the process or are to be shared with other references. 113Note that either 114.Dv MAP_SHARED , 115.Dv MAP_PRIVATE 116or 117.Dv MAP_COPY 118must be specified. 119Sharing, mapping type and options are specified in the 120.Fa flags 121argument by 122.Em or Ns 'ing 123the following values: 124.Pp 125.Bl -tag -width MAP_FIXEDX 126.It Dv MAP_ANON 127Map anonymous memory not associated with any specific file. 128The file descriptor used for creating 129.Dv MAP_ANON 130regions is used only for 131naming, and may be specified as \-1 if no name is associated with the 132region. 133.It Dv MAP_FILE 134Mapped from a regular file or character-special device memory. 135.It Dv MAP_FIXED 136Do not permit the system to select a different address than the one 137specified. 138If the specified address cannot be used, 139.Nm mmap 140will fail. 141If MAP_FIXED is specified, 142.Fa addr 143must be a multiple of the pagesize. 144Use of this option is discouraged. 145.It Dv MAP_HASSEMAPHORE 146Notify the kernel that the region may contain semaphores and that special 147handling may be necessary. 148.It Dv MAP_INHERIT 149Permit regions to be inherited across 150.Xr execve 2 151system calls. 152.It Dv MAP_PRIVATE 153Modifications made by this process are private, however modifications made by 154other processes using 155.Dv MAP_SHARED 156will be seen. 157.It Dv MAP_SHARED 158Modifications are shared. 159.It Dv MAP_COPY 160Modifications are private, including other processes. 161.El 162.Pp 163The 164.Xr close 2 165function does not unmap pages, see 166.Xr munmap 2 167for further information. 168.Pp 169The current design does not allow a process to specify the location of 170swap space. 171In the future we may define an additional mapping type, 172.Dv MAP_SWAP , 173in which 174the file descriptor argument specifies a file or device to which swapping 175should be done. 176.Sh RETURN VALUES 177Upon successful completion, 178.Nm mmap 179returns a pointer to the mapped region. 180Otherwise, a value of 181.Dv MAP_FAILED 182is returned and 183.Va errno 184is set to indicate the error. 185The symbol 186.Dv MAP_FAILED 187is defined in the header 188.Ao Pa sys/mman.h Ac . 189No successful return from 190.Fn mmap 191will return the value 192.Dv MAP_FAILED . 193.Sh ERRORS 194.Fn mmap 195will fail if: 196.Bl -tag -width Er 197.It Bq Er EACCES 198The flag 199.Dv PROT_READ 200was specified as part of the 201.Fa prot 202parameter and 203.Fa fd 204was not open for reading. 205The flags 206.Dv MAP_SHARED 207and 208.Dv PROT_WRITE 209were specified as part of the 210.Fa flags 211and 212.Fa prot 213parameters and 214.Fa fd 215was not open for writing. 216.It Bq Er EBADF 217.Fa fd 218is not a valid open file descriptor. 219.It Bq Er EINVAL 220.\"One of 221.\".Dv MAP_ANON 222.\"or 223.\".Dv MAP_FILE 224.\"was not specified as part of the 225.\".Fa flags 226.\"parameter. 227.Dv MAP_FIXED 228was specified and the 229.Fa addr 230parameter was not page aligned or was outside of the 231valid address range for a process. 232.Dv MAP_ANON was specified and 233.Fa fd 234was not \-1. 235.Fa len 236was less than zero. 237.It Bq Er ENODEV 238.Fa fd 239did not reference a regular or character special file. 240.It Bq Er ENOMEM 241.Dv MAP_FIXED 242was specified and the 243.Fa addr 244parameter wasn't available. 245.Dv MAP_ANON 246was specified and insufficient memory was available. 247.It Bq Er EOVERFLOW 248.Fa fd 249references a regular file and the value of 250.Fa offset 251plus 252.Fa len 253would exceed the offset maximum established in its open file description. 254.El 255.Sh SEE ALSO 256.Xr madvise 2 , 257.Xr mincore 2 , 258.Xr mlock 2 , 259.Xr mprotect 2 , 260.Xr msync 2 , 261.Xr munmap 2 , 262.Xr getpagesize 3 263.Sh BUGS 264The 265.Dv MAP_COPY 266flag is not implemented. The current 267.Dv MAP_COPY 268semantics are the same as those of the 269.Dv MAP_PRIVATE 270flag. 271