1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)mmap.2 8.3 (Berkeley) 05/27/94 7.\" 8.Dd "" 9.Dt MMAP 2 10.Os BSD 4 11.Sh NAME 12.Nm mmap 13.Nd map files or devices into memory 14.Sh SYNOPSIS 15.Fd #include <sys/types.h> 16.Fd #include <sys/mman.h> 17.Ft caddr_t 18.Fn mmap "caddr_t addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 19.Sh DESCRIPTION 20The 21.Nm mmap 22function causes the pages starting at 23.Fa addr 24and continuing for at most 25.Fa len 26bytes to be mapped from the object described by 27.Fa fd , 28starting at byte offset 29.Fa offset . 30If 31.Fa len 32is not a multiple of the pagesize, the mapped region may extend past the 33specified range. 34Any such extension beyond the end of the mapped object will be zero-filled. 35.Pp 36If 37.Fa addr 38is non-zero, it is used as a hint to the system. 39(As a convenience to the system, the actual address of the region may differ 40from the address supplied.) 41If 42.Fa addr 43is zero, an address will be selected by the system. 44The actual starting address of the region is returned. 45A successful 46.Fa mmap 47deletes any previous mapping in the allocated address range. 48.Pp 49The protections (region accessibility) are specified in the 50.Fa prot 51argument by 52.Em or Ns 'ing 53the following values: 54.Pp 55.Bl -tag -width MAP_FIXEDX 56.It Dv PROT_EXEC 57Pages may be executed. 58.It Dv PROT_READ 59Pages may be read. 60.It Dv PROT_WRITE 61Pages may be written. 62.El 63.Pp 64The 65.Fa flags 66parameter specifies the type of the mapped object, mapping options and 67whether modifications made to the mapped copy of the page are private 68to the process or are to be shared with other references. 69Sharing, mapping type and options are specified in the 70.Fa flags 71argument by 72.Em or Ns 'ing 73the following values: 74.Pp 75.Bl -tag -width MAP_FIXEDX 76.It Dv MAP_ANON 77Map anonymous memory not associated with any specific file. 78The file descriptor used for creating 79.Dv MAP_ANON 80must be \-1. 81The 82.Fa offset 83parameter is ignored. 84.\".It Dv MAP_FILE 85.\"Mapped from a regular file or character-special device memory. 86.It Dv MAP_FIXED 87Do not permit the system to select a different address than the one 88specified. 89If the specified address cannot be used, 90.Nm mmap 91will fail. 92If MAP_FIXED is specified, 93.Fa addr 94must be a multiple of the pagesize. 95Use of this option is discouraged. 96.It Dv MAP_HASSEMAPHORE 97Notify the kernel that the region may contain semaphores and that special 98handling may be necessary. 99.It Dv MAP_INHERIT 100Permit regions to be inherited across 101.Xr exec 2 102system calls. 103.It Dv MAP_PRIVATE 104Modifications are private. 105.It Dv MAP_SHARED 106Modifications are shared. 107.El 108.Pp 109The 110.Xr close 2 111function does not unmap pages, see 112.Xr munmap 2 113for further information. 114.Pp 115The current design does not allow a process to specify the location of 116swap space. 117In the future we may define an additional mapping type, 118.Dv MAP_SWAP , 119in which 120the file descriptor argument specifies a file or device to which swapping 121should be done. 122.Sh RETURN VALUES 123Upon successful completion, 124.Nm mmap 125returns a pointer to the mapped region. 126Otherwise, a value of -1 is returned and 127.Va errno 128is set to indicate the error. 129.Sh ERRORS 130.Fn Mmap 131will fail if: 132.Bl -tag -width Er 133.It Bq Er EACCES 134The flag 135.Dv PROT_READ 136was specified as part of the 137.Fa prot 138parameter and 139.Fa fd 140was not open for reading. 141The flags 142.Dv PROT_WRITE , 143.Dv MAP_SHARED 144and 145.Dv MAP_WRITE 146were specified as part 147of the 148.Fa flags 149and 150.Fa prot 151parameters and 152.Fa fd 153was not open for writing. 154.It Bq Er EBADF 155.Fa Fd 156is not a valid open file descriptor. 157.It Bq Er EINVAL 158.\"One of 159.\".Dv MAP_ANON 160.\"or 161.\".Dv MAP_FILE 162.\"was not specified as part of the 163.\".Fa flags 164.\"parameter. 165.Dv MAP_FIXED 166was specified and the 167.Fa addr 168parameter was not page aligned or was outside of the 169valid address range for a process. 170.Dv MAP_ANON was specified and 171.Fa fd 172was not \-1. 173.Fa Fd 174did not reference a regular or character special file. 175.Fa Len 176was less than zero. 177.It Bq Er ENOMEM 178.Dv MAP_FIXED 179was specified and the 180.Fa addr 181parameter wasn't available. 182.Dv MAP_ANON 183was specified and insufficient memory was available. 184.Sh "SEE ALSO" 185.Xr getpagesize 2 , 186.Xr msync 2 , 187.Xr munmap 2 , 188.Xr mprotect 2 , 189.Xr madvise 2 , 190.Xr mincore 2 191