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