1.\" $OpenBSD: mmap.2,v 1.51 2014/07/10 19:00:23 matthew 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 $Mdocdate: July 10 2014 $ 34.Dt MMAP 2 35.Os 36.Sh NAME 37.Nm mmap 38.Nd map files or devices into memory 39.Sh SYNOPSIS 40.In sys/mman.h 41.Ft void * 42.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 43.Sh DESCRIPTION 44The 45.Fn mmap 46function causes the contents of 47.Fa fd , 48starting at 49.Fa offset , 50to be mapped in memory at the given 51.Fa addr . 52The mapping will extend at least 53.Fa len 54bytes, subject to page alignment restrictions. 55.Pp 56The 57.Fa addr 58argument describes the address where the system should place the mapping. 59If the 60.Dv MAP_FIXED 61flag is specified, the allocation will happen at the specified address, 62replacing any previously established mappings in its range. 63Otherwise, the mapping will be placed at the available spot at 64.Fa addr ; 65failing that it will be placed "close by". 66If 67.Fa addr 68is 69.Dv NULL 70the system can pick any address. 71Except for 72.Dv MAP_FIXED 73mappings, the system will never replace existing mappings. 74.Pp 75The 76.Fa len 77argument describes the minimum amount of bytes the mapping will span. 78Since 79.Fn mmap 80maps pages into memory, 81.Fa len 82may be rounded up to hit a page boundary. 83If 84.Fa len 85is 0, the mapping will fail with 86.Er EINVAL . 87.Pp 88If an 89.Fa fd 90and 91.Fa offset 92are specified, the resulting address may end up not on a page boundary, 93in order to align the page offset in the 94.Fa addr 95to the page offset in 96.Fa offset . 97.Pp 98The protections (region accessibility) are specified in the 99.Fa prot 100argument. 101It should either be 102.Dv PROT_NONE 103.Pq no permissions 104or the bitwise OR of one or more of the following values: 105.Pp 106.Bl -tag -width "PROT_WRITEXX" -offset indent -compact 107.It Dv PROT_EXEC 108Pages may be executed. 109.It Dv PROT_READ 110Pages may be read. 111.It Dv PROT_WRITE 112Pages may be written. 113.El 114.Pp 115The 116.Fa flags 117parameter specifies the type of the mapped object, mapping options, and 118whether modifications made to the mapped copy of the page are private 119to the process or are to be shared with other references. 120Sharing, mapping type, and options are specified in the 121.Fa flags 122argument by OR'ing the following values. 123Exactly one of the first two values must be specified: 124.Bl -tag -width MAP_ANONYMOUS -offset indent 125.It Dv MAP_PRIVATE 126Modifications are private. 127.It Dv MAP_SHARED 128Modifications are shared. 129.El 130.Pp 131Any combination of the following flags may additionally be used: 132.Bl -tag -width MAP_ANONYMOUS -offset indent 133.It Dv MAP_ANON 134Map anonymous memory not associated with any specific file. 135The file descriptor used for creating 136.Dv MAP_ANON 137must currently be \-1 indicating no name is associated with the 138region. 139.It Dv MAP_ANONYMOUS 140Synonym for 141.Dv MAP_ANON . 142.It Dv MAP_FIXED 143Demand that the mapping is placed at 144.Fa addr , 145rather than having the system select a location. 146.Fa addr , 147.Fa len 148and 149.Fa offset 150(in the case of 151.Fa fd 152mappings) 153must be multiples of the page size. 154Existing mappings in the address range will be replaced. 155Use of this option is discouraged. 156.El 157.Pp 158Finally, the following flags are also provided for 159source compatibility with code written for other operating systems, 160but are not recommended for use in new 161.Ox 162code: 163.Bl -tag -width MAP_ANONYMOUS -offset indent 164.It Dv MAP_COPY 165Modifications are private and, unlike 166.Dv MAP_PRIVATE , 167modifications made by others are not visible. 168On 169.Ox 170this behaves just like 171.Dv MAP_PRIVATE . 172.It Dv MAP_FILE 173Mapped from a regular file, character special file, or block special file 174specified by file descriptor 175.Fa fd . 176On 177.Ox 178and all systems conforming to 179.St -p1003.1-2008 180this is the default mapping type and need not be specified. 181.It Dv MAP_HASSEMAPHORE 182Notify the kernel that the region may contain semaphores and that special 183handling may be necessary. 184On 185.Ox 186this flag is ignored. 187.It Dv MAP_INHERIT 188Permit regions to be inherited across 189.Xr exec 3 190system calls. 191On 192.Ox 193this flag is ignored. 194.It Dv MAP_TRYFIXED 195Attempt to use the hint provided by 196.Fa addr . 197On 198.Ox 199this is the default behavior. 200.El 201.Pp 202The 203.Xr close 2 204function does not unmap pages; see 205.Xr munmap 2 206for further information. 207.Sh RETURN VALUES 208The 209.Fn mmap 210function returns a pointer to the mapped region if successful; 211otherwise the value 212.Dv MAP_FAILED 213is returned and the global variable 214.Va errno 215is set to indicate the error. 216A successful return from 217.Fn mmap 218will never return the value 219.Dv MAP_FAILED . 220.Sh ERRORS 221.Fn mmap 222will fail if: 223.Bl -tag -width Er 224.It Bq Er EACCES 225The flag 226.Dv PROT_READ 227was specified as part of the 228.Fa prot 229parameter and 230.Fa fd 231was not open for reading. 232The flags 233.Dv MAP_SHARED 234and 235.Dv PROT_WRITE 236were specified as part 237of the 238.Fa flags 239and 240.Fa prot 241parameters and 242.Fa fd 243was not open for writing. 244.It Bq Er EBADF 245.Fa fd 246is not a valid open file descriptor. 247.It Bq Er EINVAL 248.Dv MAP_PRIVATE 249and 250.Dv MAP_SHARED 251were both specified. 252.It Bq Er EINVAL 253.Dv MAP_FIXED 254was specified and the 255.Fa addr 256parameter was not page aligned. 257.It Bq Er EINVAL 258.Fa addr 259and 260.Fa len 261specified a region that would extend beyond the end of the address space. 262.It Bq Er EINVAL 263.Fa fd 264did not specify a regular, character special, or block special file. 265.It Bq Er EINVAL 266The allocation 267.Fa len 268was 0. 269.It Bq Er ENOMEM 270.Dv MAP_FIXED 271was specified and the 272.Fa addr 273parameter wasn't available. 274.Dv MAP_ANON 275was specified and insufficient memory was available. 276.El 277.Sh SEE ALSO 278.Xr madvise 2 , 279.Xr mincore 2 , 280.Xr mlock 2 , 281.Xr mprotect 2 , 282.Xr mquery 2 , 283.Xr msync 2 , 284.Xr munmap 2 , 285.Xr getpagesize 3 286.Sh STANDARDS 287The 288.Fn mmap 289function conforms to 290.St -p1003.1-2008 . 291.Sh HISTORY 292The 293.Fn mmap 294system call first appeared in 295.Bx 4.1c . 296.Sh CAVEATS 297.St -p1003.1-2008 298specifies that references to pages beyond the end of a mapped object 299shall generate a 300.Dv SIGBUS 301signal; however, 302.Ox 303generates a 304.Dv SIGSEGV 305signal in this case instead. 306.Pp 307Additionally, 308.St -p1003.1-2008 309specifies that 310.Fn mmap 311shall fail with 312.Er EINVAL 313if neither 314.Dv MAP_PRIVATE 315nor 316.Dv MAP_SHARED 317is specified by 318.Fa flags ; 319however, for compatibility with old programs, 320.Ox 321instead defaults to 322.Dv MAP_SHARED 323for mappings of character special files, and to 324.Dv MAP_PRIVATE 325for all other mappings. 326New programs should not rely on this behavior. 327.Sh BUGS 328Due to a limitation of the current vm system (see 329.Xr uvm 9 ) , 330mapping descriptors 331.Dv PROT_WRITE 332without also specifying 333.Dv PROT_READ 334is useless 335(results in a segmentation fault when first accessing the mapping). 336This means that such descriptors must be opened with 337.Dv O_RDWR , 338which requires both read and write permissions on the underlying 339object. 340