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