1.\" Copyright (c) 1991 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)mmap.2 6.2 (Berkeley) 06/05/91 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" "int 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 offset 32or 33.Fa len 34is not a multiple of the pagesize, the mapped region may extend past the 35specified range. 36.Pp 37If 38.Fa addr 39is non-zero, it is used as a hint to the system. 40(As a convenience to the system, the actual address of the region may differ 41from the address supplied.) 42If 43.Fa addr 44is zero, an address will be selected by the system. 45The actual starting address of the region is returned. 46A successful 47.Fa mmap 48deletes any previous mapping in the allocated address range. 49.Pp 50The protections (region accessibility) are specified in the 51.Fa prot 52argument by 53.Em or Ap ing 54the following values: 55.Pp 56.Bl -tag -width MAP_FIXEDX 57.It Dv PROT_EXEC 58Pages may be executed. 59.It Dv PROT_READ 60Pages may be read. 61.It Dv PROT_WRITE 62Pages may be written. 63.El 64.Pp 65The 66.Fa flags 67parameter specifies the type of the mapped object, mapping options and 68whether modifications made to the mapped copy of the page are private 69to the process or are to be shared with other references. 70Sharing, mapping type and options are specified in the 71.Fa flags 72argument by 73.Em or Ap ing 74the following values: 75.Pp 76.Bl -tag -width MAP_FIXEDX 77.It Dv MAP_ANON 78Map anonymous memory not associated with any specific file. 79The file descriptor used for creating MAP_ANON regions is used only for 80naming, and may be specified as \-1 if no name is associated with the 81region. 82.It Dv MAP_FILE 83Mapped from a regular file or character-special device memory. 84.It Dv MAP_FIXED 85Do not permit the system to select a different address than the one 86specified. 87If the specified address cannot be used, 88.Nm mmap 89will fail. 90If MAP_FIXED is specified, 91.Fa addr 92must be a multiple of the pagesize. 93Use of this option is discouraged. 94.It Dv MAP_HASSEMAPHORE 95Notify the kernel that the region may contain semaphores and that special 96handling may be necessary. 97.It Dv MAP_INHERIT 98Permit regions to be inherited across 99.Xr exec 2 100system calls. 101.It Dv MAP_PRIVATE 102Modifications are private. 103.It Dv MAP_SHARED 104Modifications are shared. 105.El 106.Pp 107The 108.Xr close 2 109function does not unmap pages, see 110.Xr munmap 2 111for further information. 112.Pp 113The current design does not allow a process to specify the location of 114swap space. 115In the future we may define an additional mapping type, MAP_SWAP, in which 116the file descriptor argument specifies a file or device to which swapping 117should be done. 118.Sh RETURN VALUES 119Upon successful completion, 120.Nm mmap 121returns a pointer to the mapped region. 122Otherwise, a value of -1 is returned and 123.Va errno 124is set to indicate the error. 125.Sh ERRORS 126.Fn Mmap 127will fail if: 128.Bl -tag -width Er 129.It Bq Er EACCES 130The flag PROT_READ was specified as part of the 131.Fa prot 132parameter and 133.Fa fd 134was not open for reading. 135The flags PROT_WRITE, MAP_SHARED and MAP_WRITE were specified as part 136of the 137.Fa flags 138and 139.Fa prot 140parameters and 141.Fa fd 142was not open for writing. 143.It Bq Er EBADF 144.Fa Fd 145is not a valid open file descriptor. 146.It Bq Er EINVAL 147One of MAP_ANON or MAP_FILE was not specified as part of the 148.Fa flags 149parameter. 150MAP_FIXED was specified and the 151.I addr 152parameter was not page aligned. 153.Fa Fd 154did not reference a regular or character special file. 155.It Bq Er ENOMEM 156MAP_FIXED was specified and the 157.Fa addr 158parameter wasn't available. 159MAP_ANON was specified an insufficient memory was available. 160.Sh "SEE ALSO" 161.Xr getpagesize 2 , 162.Xr msync 2 , 163.Xr munmap 2 , 164.Xr mprotect 2 , 165.Xr madvise 2 , 166.Xr mincore 2 167