1.\" $OpenBSD: mmap.2,v 1.23 2001/08/03 19:44:21 espie Exp $ 2.\" $NetBSD: mmap.2,v 1.5 1995/06/24 10:48:59 cgd Exp $ 3.\" 4.\" Copyright (c) 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)mmap.2 8.1 (Berkeley) 6/4/93 36.\" 37.Dd June 4, 1993 38.Dt MMAP 2 39.Os 40.Sh NAME 41.Nm mmap 42.Nd map files or devices into memory 43.Sh SYNOPSIS 44.Fd #include <sys/types.h> 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 offset 61or 62.Fa len 63is not a multiple of the pagesize, the mapped region may extend past the 64specified range. 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.Tn 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.El 93.Pp 94The 95.Fa flags 96parameter specifies the type of the mapped object, mapping options, and 97whether modifications made to the mapped copy of the page are private 98to the process or are to be shared with other references. 99Sharing, mapping type, and options are specified in the 100.Fa flags 101argument by 102.Em or Ns 'ing 103the following values: 104.Pp 105.Bl -tag -width MAP_FIXEDX 106.It Dv MAP_ANON 107Map anonymous memory not associated with any specific file. 108The file descriptor used for creating 109.Dv MAP_ANON 110regions is used only for 111naming, and may be specified as \-1 if no name is associated with the 112region. 113.It Dv MAP_FILE 114Mapped from a regular file or character-special device memory. 115(This is the default mapping type, and need not be specified.) 116.It Dv MAP_FIXED 117Do not permit the system to select a different address than the one 118specified. 119If the specified address cannot be used, 120.Nm mmap 121will fail. 122If 123.Dv MAP_FIXED 124is specified, 125.Fa addr 126must be a multiple of the pagesize. 127Use of this option is discouraged. 128.It Dv MAP_HASSEMAPHORE 129Notify the kernel that the region may contain semaphores and that special 130handling may be necessary. 131.It Dv MAP_INHERIT 132Permit regions to be inherited across 133.Xr exec 2 134system calls. 135.It Dv MAP_PRIVATE 136Modifications are private. 137.It Dv MAP_SHARED 138Modifications are shared. 139.It Dv MAP_COPY 140Modifications are private and unlike 141.Dv MAP_PRIVATE 142you don't see modifications made by others. 143This option is deprecated, shouldn't be used and behaves just like 144.Dv MAP_PRIVATE 145in the current implementation. 146.El 147.Pp 148The 149.Xr close 2 150function does not unmap pages; see 151.Xr munmap 2 152for further information. 153.Pp 154The current design does not allow a process to specify the location of 155swap space. 156In the future we may define an additional mapping type, 157.Dv MAP_SWAP , 158in which 159the file descriptor argument specifies a file or device to which swapping 160should be done. 161.Sh RETURN VALUES 162Upon successful completion, 163.Nm mmap 164returns a pointer to the mapped region. 165Otherwise, a value of 166.Dv MAP_FAILED 167is returned and 168.Va errno 169is set to indicate the error. 170The symbol 171.Dv MAP_FAILED 172is defined in the header 173.Ao Pa sys/mman.h Ac . 174No successful return from 175.Fn mmap 176will return the value 177.Dv MAP_FAILED . 178.Sh ERRORS 179.Fn mmap 180will fail if: 181.Bl -tag -width Er 182.It Bq Er EACCES 183The flag 184.Dv PROT_READ 185was specified as part of the 186.Fa prot 187parameter and 188.Fa fd 189was not open for reading. 190The flags 191.Dv MAP_SHARED 192and 193.Dv PROT_WRITE 194were specified as part 195of the 196.Fa flags 197and 198.Fa prot 199parameters and 200.Fa fd 201was not open for writing. 202.It Bq Er EBADF 203.Fa fd 204is not a valid open file descriptor. 205.It Bq Er EINVAL 206.Dv MAP_FIXED 207was specified and the 208.Fa addr 209parameter was not page aligned. 210.Fa fd 211did not reference a regular or character special file. 212.It Bq Er ENOMEM 213.Dv MAP_FIXED 214was specified and the 215.Fa addr 216parameter wasn't available. 217.Dv MAP_ANON 218was specified and insufficient memory was available. 219.El 220.Sh BUGS 221Due to a limitation of the current vm system (see 222.Xr uvm 9 ), 223mapping descriptors 224.Dv PROT_WRITE 225without also specifying 226.Dv PROT_READ 227is useless 228(results in a segmentation fault when first accessing the mapping). 229This means that such descriptors must be opened with 230.Dv O_RDWR , 231for which you need both read and write permissions on the underlying 232object. 233.Sh SEE ALSO 234.Xr madvise 2 , 235.Xr mincore 2 , 236.Xr mlock 2 , 237.Xr mprotect 2 , 238.Xr msync 2 , 239.Xr munmap 2 , 240.Xr getpagesize 3 241