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.4 (Berkeley) 06/21/92 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 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 Ns '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 Ns '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 80.Dv MAP_ANON 81regions is used only for 82naming, and may be specified as \-1 if no name is associated with the 83region. 84.It Dv MAP_FILE 85Mapped 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 158One of 159.Dv MAP_ANON 160or 161.Dv MAP_FILE 162was not specified as part of the 163.Fa flags 164parameter. 165.Dv MAP_FIXED 166was specified and the 167.I addr 168parameter was not page aligned. 169.Fa Fd 170did not reference a regular or character special file. 171.It Bq Er ENOMEM 172.Dv MAP_FIXED 173was specified and the 174.Fa addr 175parameter wasn't available. 176.Dv MAP_ANON 177was specified and insufficient memory was available. 178.Sh "SEE ALSO" 179.Xr getpagesize 2 , 180.Xr msync 2 , 181.Xr munmap 2 , 182.Xr mprotect 2 , 183.Xr madvise 2 , 184.Xr mincore 2 185