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.\" from: @(#)mmap.2 6.2 (Berkeley) 6/5/91 33.\" $Id: mmap.2,v 1.2 1993/08/01 07:42:38 mycroft Exp $ 34.\" 35.Dd "June 5, 1991" 36.Dt MMAP 2 37.Os BSD 4 38.Sh NAME 39.Nm mmap 40.Nd map files or devices into memory 41.Sh SYNOPSIS 42.Fd #include <sys/types.h> 43.Fd #include <sys/mman.h> 44.Ft caddr_t 45.Fn mmap "caddr_t addr" "int len" "int prot" "int flags" "int fd" "off_t offset" 46.Sh DESCRIPTION 47The 48.Nm mmap 49function causes the pages starting at 50.Fa addr 51and continuing for at most 52.Fa len 53bytes to be mapped from the object described by 54.Fa fd , 55starting at byte offset 56.Fa offset . 57If 58.Fa offset 59or 60.Fa len 61is not a multiple of the pagesize, the mapped region may extend past the 62specified range. 63.Pp 64If 65.Fa addr 66is non-zero, it is used as a hint to the system. 67(As a convenience to the system, the actual address of the region may differ 68from the address supplied.) 69If 70.Fa addr 71is zero, an address will be selected by the system. 72The actual starting address of the region is returned. 73A successful 74.Fa mmap 75deletes any previous mapping in the allocated address range. 76.Pp 77The protections (region accessibility) are specified in the 78.Fa prot 79argument by 80.Em or Ap ing 81the following values: 82.Pp 83.Bl -tag -width MAP_FIXEDX 84.It Dv PROT_EXEC 85Pages may be executed. 86.It Dv PROT_READ 87Pages may be read. 88.It Dv PROT_WRITE 89Pages may be written. 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 Ap 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 MAP_ANON regions is used only for 107naming, and may be specified as \-1 if no name is associated with the 108region. 109.It Dv MAP_FILE 110Mapped from a regular file or character-special device memory. 111.It Dv MAP_FIXED 112Do not permit the system to select a different address than the one 113specified. 114If the specified address cannot be used, 115.Nm mmap 116will fail. 117If MAP_FIXED is specified, 118.Fa addr 119must be a multiple of the pagesize. 120Use of this option is discouraged. 121.It Dv MAP_HASSEMAPHORE 122Notify the kernel that the region may contain semaphores and that special 123handling may be necessary. 124.It Dv MAP_INHERIT 125Permit regions to be inherited across 126.Xr exec 2 127system calls. 128.It Dv MAP_PRIVATE 129Modifications are private. 130.It Dv MAP_SHARED 131Modifications are shared. 132.El 133.Pp 134The 135.Xr close 2 136function does not unmap pages, see 137.Xr munmap 2 138for further information. 139.Pp 140The current design does not allow a process to specify the location of 141swap space. 142In the future we may define an additional mapping type, MAP_SWAP, in which 143the file descriptor argument specifies a file or device to which swapping 144should be done. 145.Sh RETURN VALUES 146Upon successful completion, 147.Nm mmap 148returns a pointer to the mapped region. 149Otherwise, a value of -1 is returned and 150.Va errno 151is set to indicate the error. 152.Sh ERRORS 153.Fn Mmap 154will fail if: 155.Bl -tag -width Er 156.It Bq Er EACCES 157The flag PROT_READ was specified as part of the 158.Fa prot 159parameter and 160.Fa fd 161was not open for reading. 162The flags PROT_WRITE, MAP_SHARED and MAP_WRITE were specified as part 163of the 164.Fa flags 165and 166.Fa prot 167parameters and 168.Fa fd 169was not open for writing. 170.It Bq Er EBADF 171.Fa Fd 172is not a valid open file descriptor. 173.It Bq Er EINVAL 174One of MAP_ANON or MAP_FILE was not specified as part of the 175.Fa flags 176parameter. 177MAP_FIXED was specified and the 178.I addr 179parameter was not page aligned. 180.Fa Fd 181did not reference a regular or character special file. 182.It Bq Er ENOMEM 183MAP_FIXED was specified and the 184.Fa addr 185parameter wasn't available. 186MAP_ANON was specified an insufficient memory was available. 187.Sh "SEE ALSO" 188.Xr getpagesize 2 , 189.Xr msync 2 , 190.Xr munmap 2 , 191.Xr mprotect 2 , 192.Xr madvise 2 , 193.Xr mincore 2 194