1.\" Copyright (c) 1991 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)mmap.2 6.2 (Berkeley) 6/5/91 33.\" 34.Dd "June 5, 1991" 35.Dt MMAP 2 36.Os BSD 4 37.Sh NAME 38.Nm mmap 39.Nd map files or devices into memory 40.Sh SYNOPSIS 41.Fd #include <sys/types.h> 42.Fd #include <sys/mman.h> 43.Ft caddr_t 44.Fn mmap "caddr_t addr" "int len" "int prot" "int flags" "int fd" "off_t offset" 45.Sh DESCRIPTION 46The 47.Nm mmap 48function causes the pages starting at 49.Fa addr 50and continuing for at most 51.Fa len 52bytes to be mapped from the object described by 53.Fa fd , 54starting at byte offset 55.Fa offset . 56If 57.Fa offset 58or 59.Fa len 60is not a multiple of the pagesize, the mapped region may extend past the 61specified range. 62.Pp 63If 64.Fa addr 65is non-zero, it is used as a hint to the system. 66(As a convenience to the system, the actual address of the region may differ 67from the address supplied.) 68If 69.Fa addr 70is zero, an address will be selected by the system. 71The actual starting address of the region is returned. 72A successful 73.Fa mmap 74deletes any previous mapping in the allocated address range. 75.Pp 76The protections (region accessibility) are specified in the 77.Fa prot 78argument by 79.Em or Ap ing 80the following values: 81.Pp 82.Bl -tag -width MAP_FIXEDX 83.It Dv PROT_EXEC 84Pages may be executed. 85.It Dv PROT_READ 86Pages may be read. 87.It Dv PROT_WRITE 88Pages may be written. 89.El 90.Pp 91The 92.Fa flags 93parameter specifies the type of the mapped object, mapping options and 94whether modifications made to the mapped copy of the page are private 95to the process or are to be shared with other references. 96Sharing, mapping type and options are specified in the 97.Fa flags 98argument by 99.Em or Ap ing 100the following values: 101.Pp 102.Bl -tag -width MAP_FIXEDX 103.It Dv MAP_ANON 104Map anonymous memory not associated with any specific file. 105The file descriptor used for creating MAP_ANON regions is used only for 106naming, and may be specified as \-1 if no name is associated with the 107region. 108.It Dv MAP_FILE 109Mapped from a regular file or character-special device memory. 110.It Dv MAP_FIXED 111Do not permit the system to select a different address than the one 112specified. 113If the specified address cannot be used, 114.Nm mmap 115will fail. 116If MAP_FIXED is specified, 117.Fa addr 118must be a multiple of the pagesize. 119Use of this option is discouraged. 120.It Dv MAP_HASSEMAPHORE 121Notify the kernel that the region may contain semaphores and that special 122handling may be necessary. 123.It Dv MAP_INHERIT 124Permit regions to be inherited across 125.Xr exec 2 126system calls. 127.It Dv MAP_PRIVATE 128Modifications are private. 129.It Dv MAP_SHARED 130Modifications are shared. 131.El 132.Pp 133The 134.Xr close 2 135function does not unmap pages, see 136.Xr munmap 2 137for further information. 138.Pp 139The current design does not allow a process to specify the location of 140swap space. 141In the future we may define an additional mapping type, MAP_SWAP, in which 142the file descriptor argument specifies a file or device to which swapping 143should be done. 144.Sh RETURN VALUES 145Upon successful completion, 146.Nm mmap 147returns a pointer to the mapped region. 148Otherwise, a value of -1 is returned and 149.Va errno 150is set to indicate the error. 151.Sh ERRORS 152.Fn Mmap 153will fail if: 154.Bl -tag -width Er 155.It Bq Er EACCES 156The flag PROT_READ was specified as part of the 157.Fa prot 158parameter and 159.Fa fd 160was not open for reading. 161The flags PROT_WRITE, MAP_SHARED and MAP_WRITE were specified as part 162of the 163.Fa flags 164and 165.Fa prot 166parameters and 167.Fa fd 168was not open for writing. 169.It Bq Er EBADF 170.Fa Fd 171is not a valid open file descriptor. 172.It Bq Er EINVAL 173One of MAP_ANON or MAP_FILE was not specified as part of the 174.Fa flags 175parameter. 176MAP_FIXED was specified and the 177.I addr 178parameter was not page aligned. 179.Fa Fd 180did not reference a regular or character special file. 181.It Bq Er ENOMEM 182MAP_FIXED was specified and the 183.Fa addr 184parameter wasn't available. 185MAP_ANON was specified an insufficient memory was available. 186.Sh "SEE ALSO" 187.Xr getpagesize 2 , 188.Xr msync 2 , 189.Xr munmap 2 , 190.Xr mprotect 2 , 191.Xr madvise 2 , 192.Xr mincore 2 193