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.4 (Berkeley) 05/11/95 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 MAP_SHARED 143and 144.Dv PROT_WRITE 145were specified as part of the 146.Fa flags 147and 148.Fa prot 149parameters and 150.Fa fd 151was not open for writing. 152.It Bq Er EBADF 153.Fa Fd 154is not a valid open file descriptor. 155.It Bq Er EINVAL 156.\"One of 157.\".Dv MAP_ANON 158.\"or 159.\".Dv MAP_FILE 160.\"was not specified as part of the 161.\".Fa flags 162.\"parameter. 163.Dv MAP_FIXED 164was specified and the 165.Fa addr 166parameter was not page aligned or was outside of the 167valid address range for a process. 168.Dv MAP_ANON was specified and 169.Fa fd 170was not \-1. 171.Fa Fd 172did not reference a regular or character special file. 173.Fa Len 174was less than zero. 175.It Bq Er ENOMEM 176.Dv MAP_FIXED 177was specified and the 178.Fa addr 179parameter wasn't available. 180.Dv MAP_ANON 181was specified and insufficient memory was available. 182.Sh "SEE ALSO" 183.Xr getpagesize 2 , 184.Xr msync 2 , 185.Xr munmap 2 , 186.Xr mprotect 2 , 187.Xr madvise 2 , 188.Xr mincore 2 189