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.3 1994/07/31 08:49:56 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. (This is 111the default mapping type, and need not be specified.) 112.It Dv MAP_FIXED 113Do not permit the system to select a different address than the one 114specified. 115If the specified address cannot be used, 116.Nm mmap 117will fail. 118If MAP_FIXED is specified, 119.Fa addr 120must be a multiple of the pagesize. 121Use of this option is discouraged. 122.It Dv MAP_HASSEMAPHORE 123Notify the kernel that the region may contain semaphores and that special 124handling may be necessary. 125.It Dv MAP_INHERIT 126Permit regions to be inherited across 127.Xr exec 2 128system calls. 129.It Dv MAP_PRIVATE 130Modifications are private. 131.It Dv MAP_SHARED 132Modifications are shared. 133.El 134.Pp 135The 136.Xr close 2 137function does not unmap pages, see 138.Xr munmap 2 139for further information. 140.Pp 141The current design does not allow a process to specify the location of 142swap space. 143In the future we may define an additional mapping type, MAP_SWAP, in which 144the file descriptor argument specifies a file or device to which swapping 145should be done. 146.Sh RETURN VALUES 147Upon successful completion, 148.Nm mmap 149returns a pointer to the mapped region. 150Otherwise, a value of -1 is returned and 151.Va errno 152is set to indicate the error. 153.Sh ERRORS 154.Fn Mmap 155will fail if: 156.Bl -tag -width Er 157.It Bq Er EACCES 158The flag PROT_READ was specified as part of the 159.Fa prot 160parameter and 161.Fa fd 162was not open for reading. 163The flags PROT_WRITE, MAP_SHARED and MAP_WRITE were specified as part 164of the 165.Fa flags 166and 167.Fa prot 168parameters and 169.Fa fd 170was not open for writing. 171.It Bq Er EBADF 172.Fa Fd 173is not a valid open file descriptor. 174.It Bq Er EINVAL 175MAP_FIXED was specified and the 176.I addr 177parameter was not page aligned. 178.Fa Fd 179did not reference a regular or character special file. 180.It Bq Er ENOMEM 181MAP_FIXED was specified and the 182.Fa addr 183parameter wasn't available. 184MAP_ANON was specified an insufficient memory was available. 185.Sh "SEE ALSO" 186.Xr getpagesize 2 , 187.Xr msync 2 , 188.Xr munmap 2 , 189.Xr mprotect 2 , 190.Xr madvise 2 , 191.Xr mincore 2 192