1.\" $OpenBSD: mmap.2,v 1.65 2019/12/21 05:23:38 jsg 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: December 21 2019 $ 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.It Dv MAP_STACK 157Indicate that the mapping is used as a stack. 158This flag must be used in combination with 159.Dv MAP_ANON 160and 161.Dv MAP_PRIVATE . 162.It Dv MAP_CONCEAL 163Exclude the mapping from core dumps. 164.El 165.Pp 166Finally, the following flags are also provided for 167source compatibility with code written for other operating systems, 168but are not recommended for use in new 169.Ox 170code: 171.Bl -tag -width MAP_ANONYMOUS -offset indent 172.It Dv MAP_COPY 173Modifications are private and, unlike 174.Dv MAP_PRIVATE , 175modifications made by others are not visible. 176On 177.Ox 178this behaves just like 179.Dv MAP_PRIVATE . 180.It Dv MAP_FILE 181Mapped from a regular file, character special file, or block special file 182specified by file descriptor 183.Fa fd . 184On 185.Ox 186and all systems conforming to 187.St -p1003.1-2008 188this is the default mapping type and need not be specified. 189.It Dv MAP_HASSEMAPHORE 190Notify the kernel that the region may contain semaphores and that special 191handling may be necessary. 192On 193.Ox 194this flag is ignored. 195.It Dv MAP_INHERIT 196Permit regions to be inherited across 197.Xr execve 2 198system calls. 199On 200.Ox 201this flag is ignored. 202.It Dv MAP_TRYFIXED 203Attempt to use the hint provided by 204.Fa addr . 205On 206.Ox 207this is the default behavior. 208.El 209.Pp 210The 211.Xr close 2 212function does not unmap pages; see 213.Xr munmap 2 214for further information. 215.Sh RETURN VALUES 216The 217.Fn mmap 218function returns a pointer to the mapped region if successful; 219otherwise the value 220.Dv MAP_FAILED 221is returned and the global variable 222.Va errno 223is set to indicate the error. 224A successful return from 225.Fn mmap 226will never return the value 227.Dv MAP_FAILED . 228.Sh ERRORS 229.Fn mmap 230will fail if: 231.Bl -tag -width Er 232.It Bq Er EACCES 233The flag 234.Dv PROT_READ 235was specified as part of the 236.Fa prot 237parameter and 238.Fa fd 239was not open for reading. 240The flags 241.Dv MAP_SHARED 242and 243.Dv PROT_WRITE 244were specified as part 245of the 246.Fa flags 247and 248.Fa prot 249parameters and 250.Fa fd 251was not open for writing. 252.It Bq Er EBADF 253.Fa fd 254is not a valid open file descriptor. 255.It Bq Er EINVAL 256.Dv MAP_PRIVATE 257and 258.Dv MAP_SHARED 259were both specified. 260.It Bq Er EINVAL 261.Dv MAP_FIXED 262was specified and the 263.Fa addr 264parameter was not page aligned. 265.It Bq Er EINVAL 266.Fa addr 267and 268.Fa len 269specified a region that would extend beyond the end of the address space. 270.It Bq Er EINVAL 271.Fa fd 272did not specify a regular, character special, or block special file. 273.It Bq Er EINVAL 274.Fa fd 275specified a character special or block special file and the underlying 276device does not support memory mapping. 277.It Bq Er EINVAL 278The allocation 279.Fa len 280was 0. 281.It Bq Er ENOMEM 282.Dv MAP_FIXED 283was specified and the 284.Fa addr 285parameter wasn't available. 286.Dv MAP_ANON 287was specified and insufficient memory was available. 288.It Bq Er ENOTSUP 289The accesses requested in the 290.Ar prot 291argument are not allowed. 292In particular, 293.Dv PROT_WRITE | PROT_EXEC 294mappings are not permitted in most binaries (see 295.Dv kern.wxabort 296in 297.Xr sysctl 2 298for more information). 299.El 300.Sh SEE ALSO 301.Xr madvise 2 , 302.Xr mlock 2 , 303.Xr mprotect 2 , 304.Xr mquery 2 , 305.Xr msync 2 , 306.Xr munmap 2 , 307.Xr getpagesize 3 , 308.Xr core 5 309.Sh STANDARDS 310The 311.Fn mmap 312function conforms to 313.St -p1003.1-2008 . 314.Sh HISTORY 315.\" A mmap() system call stub appeared in 4.1c BSD, 316.\" but the functionality wasn't implemented. 317A fully functional 318.Fn mmap 319system call first appeared in SunOS 4.0 320and has been available since 321.Bx 4.3 Net/2 . 322.Sh CAVEATS 323.St -p1003.1-2008 324specifies that references to pages beyond the end of a mapped object 325shall generate a 326.Dv SIGBUS 327signal; however, on some architectures 328.Ox 329generates a 330.Dv SIGSEGV 331signal in this case instead. 332.Pp 333Additionally, 334.St -p1003.1-2008 335specifies that 336.Fn mmap 337shall fail with 338.Er EINVAL 339if neither 340.Dv MAP_PRIVATE 341nor 342.Dv MAP_SHARED 343is specified by 344.Fa flags ; 345however, for compatibility with old programs, 346.Ox 347instead defaults to 348.Dv MAP_SHARED 349for mappings of character special files, and to 350.Dv MAP_PRIVATE 351for all other mappings. 352New programs should not rely on this behavior. 353.Sh BUGS 354Due to a limitation of the current vm system (see 355.Xr uvm_init 9 ) , 356mapping descriptors 357.Dv PROT_WRITE 358without also specifying 359.Dv PROT_READ 360is useless 361(results in a segmentation fault when first accessing the mapping). 362This means that such descriptors must be opened with 363.Dv O_RDWR , 364which requires both read and write permissions on the underlying 365object. 366