1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95 33.\" $FreeBSD$ 34.\" 35.Dd November 17, 2001 36.Dt MMAP 2 37.Os 38.Sh NAME 39.Nm mmap 40.Nd allocate memory, or map files or devices into memory 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In sys/mman.h 45.Ft void * 46.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 47.Sh DESCRIPTION 48The 49.Fn mmap 50system call causes the pages starting at 51.Fa addr 52and continuing for at most 53.Fa len 54bytes to be mapped from the object described by 55.Fa fd , 56starting at byte offset 57.Fa offset . 58If 59.Fa len 60is not a multiple of the pagesize, the mapped region may extend past the 61specified range. 62Any such extension beyond the end of the mapped object will be zero-filled. 63.Pp 64If 65.Fa addr 66is non-zero, it is used as a hint to the system. 67(As a convenience to the system, the actual address of the region may differ 68from the address supplied.) 69If 70.Fa addr 71is zero, an address will be selected by the system. 72The actual starting address of the region is returned. 73A successful 74.Fa mmap 75deletes any previous mapping in the allocated address range. 76.Pp 77The protections (region accessibility) are specified in the 78.Fa prot 79argument by 80.Em or Ns 'ing 81the following values: 82.Pp 83.Bl -tag -width PROT_WRITE -compact 84.It Dv PROT_NONE 85Pages may not be accessed. 86.It Dv PROT_READ 87Pages may be read. 88.It Dv PROT_WRITE 89Pages may be written. 90.It Dv PROT_EXEC 91Pages may be executed. 92.El 93.Pp 94The 95.Fa flags 96argument specifies the type of the mapped object, mapping options and 97whether modifications made to the mapped copy of the page are private 98to the process or are to be shared with other references. 99Sharing, mapping type and options are specified in the 100.Fa flags 101argument by 102.Em or Ns 'ing 103the following values: 104.Bl -tag -width MAP_HASSEMAPHORE 105.It Dv MAP_ANON 106Map anonymous memory not associated with any specific file. 107The file descriptor used for creating 108.Dv MAP_ANON 109must be \-1. 110The 111.Fa offset 112argument is ignored. 113.\".It Dv MAP_FILE 114.\"Mapped from a regular file or character-special device memory. 115.It Dv MAP_FIXED 116Do not permit the system to select a different address than the one 117specified. 118If the specified address cannot be used, 119.Fn mmap 120will fail. 121If 122.Dv MAP_FIXED 123is specified, 124.Fa addr 125must be a multiple of the pagesize. 126Use of this option is discouraged. 127.It Dv MAP_HASSEMAPHORE 128Notify the kernel that the region may contain semaphores and that special 129handling may be necessary. 130.It Dv MAP_INHERIT 131This flag never operated as advertised and is no longer supported. 132Please refer to 133.Xr minherit 2 134for further information. 135.It Dv MAP_NOCORE 136Region is not included in a core file. 137.It Dv MAP_NOSYNC 138Causes data dirtied via this VM map to be flushed to physical media 139only when necessary (usually by the pager) rather than gratuitously. 140Typically this prevents the update daemons from flushing pages dirtied 141through such maps and thus allows efficient sharing of memory across 142unassociated processes using a file-backed shared memory map. 143Without 144this option any VM pages you dirty may be flushed to disk every so often 145(every 30-60 seconds usually) which can create performance problems if you 146do not need that to occur (such as when you are using shared file-backed 147mmap regions for IPC purposes). 148Note that VM/file system coherency is 149maintained whether you use 150.Dv MAP_NOSYNC 151or not. 152This option is not portable 153across 154.Ux 155platforms (yet), though some may implement the same behavior 156by default. 157.Pp 158.Em WARNING ! 159Extending a file with 160.Xr ftruncate 2 , 161thus creating a big hole, and then filling the hole by modifying a shared 162.Fn mmap 163can lead to severe file fragmentation. 164In order to avoid such fragmentation you should always pre-allocate the 165file's backing store by 166.Fn write Ns ing 167zero's into the newly extended area prior to modifying the area via your 168.Fn mmap . 169The fragmentation problem is especially sensitive to 170.Dv MAP_NOSYNC 171pages, because pages may be flushed to disk in a totally random order. 172.Pp 173The same applies when using 174.Dv MAP_NOSYNC 175to implement a file-based shared memory store. 176It is recommended that you create the backing store by 177.Fn write Ns ing 178zero's to the backing file rather than 179.Fn ftruncate Ns ing 180it. 181You can test file fragmentation by observing the KB/t (kilobytes per 182transfer) results from an 183.Dq Li iostat 1 184while reading a large file sequentially, e.g.\& using 185.Dq Li dd if=filename of=/dev/null bs=32k . 186.Pp 187The 188.Xr fsync 2 189system call will flush all dirty data and metadata associated with a file, 190including dirty NOSYNC VM data, to physical media. 191The 192.Xr sync 8 193command and 194.Xr sync 2 195system call generally do not flush dirty NOSYNC VM data. 196The 197.Xr msync 2 198system call is obsolete since 199.Bx 200implements a coherent file system buffer cache. 201However, it may be 202used to associate dirty VM pages with file system buffers and thus cause 203them to be flushed to physical media sooner rather than later. 204.It Dv MAP_PRIVATE 205Modifications are private. 206.It Dv MAP_SHARED 207Modifications are shared. 208.It Dv MAP_STACK 209.Dv MAP_STACK 210implies 211.Dv MAP_ANON , 212and 213.Fa offset 214of 0. 215The 216.Fa fd 217argument 218must be -1 and 219.Fa prot 220must include at least 221.Dv PROT_READ 222and 223.Dv PROT_WRITE . 224This option creates 225a memory region that grows to at most 226.Fa len 227bytes in size, starting from the stack top and growing down. 228The 229stack top is the starting address returned by the call, plus 230.Fa len 231bytes. 232The bottom of the stack at maximum growth is the starting 233address returned by the call. 234.El 235.Pp 236The 237.Xr close 2 238system call does not unmap pages, see 239.Xr munmap 2 240for further information. 241.Pp 242The current design does not allow a process to specify the location of 243swap space. 244In the future we may define an additional mapping type, 245.Dv MAP_SWAP , 246in which 247the file descriptor argument specifies a file or device to which swapping 248should be done. 249.Sh RETURN VALUES 250Upon successful completion, 251.Fn mmap 252returns a pointer to the mapped region. 253Otherwise, a value of 254.Dv MAP_FAILED 255is returned and 256.Va errno 257is set to indicate the error. 258.Sh ERRORS 259The 260.Fn mmap 261system call 262will fail if: 263.Bl -tag -width Er 264.It Bq Er EACCES 265The flag 266.Dv PROT_READ 267was specified as part of the 268.Fa prot 269argument and 270.Fa fd 271was not open for reading. 272The flags 273.Dv MAP_SHARED 274and 275.Dv PROT_WRITE 276were specified as part of the 277.Fa flags 278and 279.Fa prot 280argument and 281.Fa fd 282was not open for writing. 283.It Bq Er EBADF 284The 285.Fa fd 286argument 287is not a valid open file descriptor. 288.It Bq Er EINVAL 289.Dv MAP_FIXED 290was specified and the 291.Fa addr 292argument was not page aligned, or part of the desired address space 293resides out of the valid address space for a user process. 294.It Bq Er EINVAL 295The 296.Fa len 297argument 298was negative. 299.It Bq Er EINVAL 300.Dv MAP_ANON 301was specified and the 302.Fa fd 303argument was not -1. 304.It Bq Er EINVAL 305.Dv MAP_ANON 306has not been specified and 307.Fa fd 308did not reference a regular or character special file. 309.It Bq Er EINVAL 310The 311.Fa offset 312argument 313was not page-aligned. 314(See 315.Sx BUGS 316below.) 317.It Bq Er ENOMEM 318.Dv MAP_FIXED 319was specified and the 320.Fa addr 321argument was not available. 322.Dv MAP_ANON 323was specified and insufficient memory was available. 324The system has reached the per-process mmap limit specified in the 325.Va vm.max_proc_mmap 326sysctl. 327.El 328.Sh SEE ALSO 329.Xr madvise 2 , 330.Xr mincore 2 , 331.Xr minherit 2 , 332.Xr mlock 2 , 333.Xr mprotect 2 , 334.Xr msync 2 , 335.Xr munlock 2 , 336.Xr munmap 2 , 337.Xr getpagesize 3 , 338.Xr make.conf 5 339.Sh BUGS 340The 341.Fa len 342argument 343is limited to 2GB. 344Mmapping slightly more than 2GB does not work, but 345it is possible to map a window of size (filesize % 2GB) for file sizes 346of slightly less than 2G, 4GB, 6GB and 8GB. 347.Pp 348The limit is imposed for a variety of reasons. 349Most of them have to do 350with 351.Fx 352not wanting to use 64 bit offsets in the VM system due to 353the extreme performance penalty. 354So 355.Fx 356uses 32bit page indexes and 357this gives 358.Fx 359a maximum of 8TB filesizes. 360It is actually bugs in 361the file system code that causes the limit to be further restricted to 3621TB (loss of precision when doing blockno calculations). 363.Pp 364Another reason for the 2GB limit is that file system metadata can 365reside at negative offsets. 366.Pp 367Note that an attempt to 368.Fn mmap 369zero bytes has no effect and succeeds, while an attempt to 370.Fn munmap 371zero bytes will return 372.Bq Er EINVAL . 373