161183Sbostic.\" Copyright (c) 1991, 1993 261183Sbostic.\" The Regents of the University of California. All rights reserved. 349899Smckusick.\" 449899Smckusick.\" %sccs.include.redist.man% 549899Smckusick.\" 6*69383Smckusick.\" @(#)mmap.2 8.4 (Berkeley) 05/11/95 749899Smckusick.\" 850013Sbostic.Dd "" 950013Sbostic.Dt MMAP 2 1050013Sbostic.Os BSD 4 1150013Sbostic.Sh NAME 1250013Sbostic.Nm mmap 1350013Sbostic.Nd map files or devices into memory 1450013Sbostic.Sh SYNOPSIS 1550013Sbostic.Fd #include <sys/types.h> 1650013Sbostic.Fd #include <sys/mman.h> 1750013Sbostic.Ft caddr_t 1854188Sbostic.Fn mmap "caddr_t addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 1950013Sbostic.Sh DESCRIPTION 2050013SbosticThe 2150013Sbostic.Nm mmap 2250013Sbosticfunction causes the pages starting at 2350013Sbostic.Fa addr 2450013Sbosticand continuing for at most 2550013Sbostic.Fa len 2650013Sbosticbytes to be mapped from the object described by 2750013Sbostic.Fa fd , 2850013Sbosticstarting at byte offset 2950013Sbostic.Fa offset . 3050013SbosticIf 3150013Sbostic.Fa len 3250013Sbosticis not a multiple of the pagesize, the mapped region may extend past the 3350013Sbosticspecified range. 3467246ShiblerAny such extension beyond the end of the mapped object will be zero-filled. 3550013Sbostic.Pp 3650013SbosticIf 3750013Sbostic.Fa addr 3850013Sbosticis non-zero, it is used as a hint to the system. 3950013Sbostic(As a convenience to the system, the actual address of the region may differ 4050013Sbosticfrom the address supplied.) 4150013SbosticIf 4250013Sbostic.Fa addr 4350013Sbosticis zero, an address will be selected by the system. 4450013SbosticThe actual starting address of the region is returned. 4550013SbosticA successful 4650013Sbostic.Fa mmap 4750013Sbosticdeletes any previous mapping in the allocated address range. 4850013Sbostic.Pp 4950013SbosticThe protections (region accessibility) are specified in the 5050013Sbostic.Fa prot 5150013Sbosticargument by 5251438Scael.Em or Ns 'ing 5350013Sbosticthe following values: 5450013Sbostic.Pp 5550013Sbostic.Bl -tag -width MAP_FIXEDX 5650013Sbostic.It Dv PROT_EXEC 5750013SbosticPages may be executed. 5850013Sbostic.It Dv PROT_READ 5950013SbosticPages may be read. 6050013Sbostic.It Dv PROT_WRITE 6150013SbosticPages may be written. 6250013Sbostic.El 6350013Sbostic.Pp 6450013SbosticThe 6550013Sbostic.Fa flags 6650013Sbosticparameter specifies the type of the mapped object, mapping options and 6750013Sbosticwhether modifications made to the mapped copy of the page are private 6850013Sbosticto the process or are to be shared with other references. 6950013SbosticSharing, mapping type and options are specified in the 7050013Sbostic.Fa flags 7150013Sbosticargument by 7251438Scael.Em or Ns 'ing 7350013Sbosticthe following values: 7450013Sbostic.Pp 7550013Sbostic.Bl -tag -width MAP_FIXEDX 7650013Sbostic.It Dv MAP_ANON 7750013SbosticMap anonymous memory not associated with any specific file. 7851438ScaelThe file descriptor used for creating 7951438Scael.Dv MAP_ANON 8067246Shiblermust be \-1. 8167257ShiblerThe 8267246Shibler.Fa offset 8367257Shiblerparameter is ignored. 8457228Sbostic.\".It Dv MAP_FILE 8557228Sbostic.\"Mapped from a regular file or character-special device memory. 8650013Sbostic.It Dv MAP_FIXED 8750013SbosticDo not permit the system to select a different address than the one 8850013Sbosticspecified. 8950013SbosticIf the specified address cannot be used, 9050013Sbostic.Nm mmap 9150013Sbosticwill fail. 9250013SbosticIf MAP_FIXED is specified, 9350013Sbostic.Fa addr 9450013Sbosticmust be a multiple of the pagesize. 9550013SbosticUse of this option is discouraged. 9650013Sbostic.It Dv MAP_HASSEMAPHORE 9750013SbosticNotify the kernel that the region may contain semaphores and that special 9850013Sbostichandling may be necessary. 9950013Sbostic.It Dv MAP_INHERIT 10050013SbosticPermit regions to be inherited across 10150013Sbostic.Xr exec 2 10250013Sbosticsystem calls. 10350013Sbostic.It Dv MAP_PRIVATE 10450013SbosticModifications are private. 10550013Sbostic.It Dv MAP_SHARED 10650013SbosticModifications are shared. 10750013Sbostic.El 10850013Sbostic.Pp 10950013SbosticThe 11050013Sbostic.Xr close 2 11150013Sbosticfunction does not unmap pages, see 11250013Sbostic.Xr munmap 2 11350013Sbosticfor further information. 11450013Sbostic.Pp 11550013SbosticThe current design does not allow a process to specify the location of 11650013Sbosticswap space. 11751438ScaelIn the future we may define an additional mapping type, 11851438Scael.Dv MAP_SWAP , 11951438Scaelin which 12050013Sbosticthe file descriptor argument specifies a file or device to which swapping 12150013Sbosticshould be done. 12250013Sbostic.Sh RETURN VALUES 12350013SbosticUpon successful completion, 12450013Sbostic.Nm mmap 12550013Sbosticreturns a pointer to the mapped region. 12650013SbosticOtherwise, a value of -1 is returned and 12750013Sbostic.Va errno 12850013Sbosticis set to indicate the error. 12950013Sbostic.Sh ERRORS 13050013Sbostic.Fn Mmap 13150013Sbosticwill fail if: 13250013Sbostic.Bl -tag -width Er 13350013Sbostic.It Bq Er EACCES 13451438ScaelThe flag 13551438Scael.Dv PROT_READ 13651438Scaelwas specified as part of the 13750013Sbostic.Fa prot 13850013Sbosticparameter and 13950013Sbostic.Fa fd 14050013Sbosticwas not open for reading. 14151438ScaelThe flags 14251438Scael.Dv MAP_SHARED 14351438Scaeland 144*69383Smckusick.Dv PROT_WRITE 145*69383Smckusickwere specified as part of the 14650013Sbostic.Fa flags 14750013Sbosticand 14850013Sbostic.Fa prot 14950013Sbosticparameters and 15050013Sbostic.Fa fd 15150013Sbosticwas not open for writing. 15250013Sbostic.It Bq Er EBADF 15350013Sbostic.Fa Fd 15450013Sbosticis not a valid open file descriptor. 15567246Shibler.It Bq Er EINVAL 15657228Sbostic.\"One of 15757228Sbostic.\".Dv MAP_ANON 15857228Sbostic.\"or 15957228Sbostic.\".Dv MAP_FILE 16057228Sbostic.\"was not specified as part of the 16157228Sbostic.\".Fa flags 16257228Sbostic.\"parameter. 16351438Scael.Dv MAP_FIXED 16451438Scaelwas specified and the 16567246Shibler.Fa addr 16667246Shiblerparameter was not page aligned or was outside of the 16767246Shiblervalid address range for a process. 16867246Shibler.Dv MAP_ANON was specified and 16967246Shibler.Fa fd 17067246Shiblerwas not \-1. 17150013Sbostic.Fa Fd 17250013Sbosticdid not reference a regular or character special file. 17367246Shibler.Fa Len 17467246Shiblerwas less than zero. 17550013Sbostic.It Bq Er ENOMEM 17651438Scael.Dv MAP_FIXED 17751438Scaelwas specified and the 17850013Sbostic.Fa addr 17950013Sbosticparameter wasn't available. 18051438Scael.Dv MAP_ANON 18151438Scaelwas specified and insufficient memory was available. 18250013Sbostic.Sh "SEE ALSO" 18350013Sbostic.Xr getpagesize 2 , 18450013Sbostic.Xr msync 2 , 18550013Sbostic.Xr munmap 2 , 18650013Sbostic.Xr mprotect 2 , 18750013Sbostic.Xr madvise 2 , 18850013Sbostic.Xr mincore 2 189