View source for Mmap

{{Short description|Memory map - POSIX-compliant system call}}
{{lowercase|title=mmap}}
{{Distinguish|nmap}}
In [[computing]], '''<code>mmap(2)</code>''' is a [[POSIX]]-compliant [[Unix]] [[system call]] that maps files or devices into memory. It is a method of [[memory-mapped file]] I/O. It implements [[demand paging]] because file contents are not immediately read from disk and initially use no physical RAM at all. The actual reads from disk are performed after a specific location is accessed, in a [[lazy evaluation|lazy]] manner. After the mapping is no longer needed, the pointers must be unmapped with <code>munmap(2)</code>. [[Memory protection|Protection]] information—for example, marking mapped regions as executable—can be managed using <code>mprotect(2)</code>, and special treatment can be enforced using <code>madvise(2)</code>.

In [[Linux]], [[macOS]] and the [[BSD]]s, <code>mmap</code> can create several types of mappings. Other operating systems may only support a subset of these; for example, shared mappings may not be practical in an operating system without a global [[Virtual file system|VFS]] or I/O cache.

==History==
The original design of memory-mapped files came from the [[TOPS-20]] operating system. <code>mmap</code> and associated systems calls were designed as part of the [[Berkeley Software Distribution]] (BSD) version of Unix. Their API was already described in the 4.2BSD System Manual, even though it was neither implemented in that release, nor in 4.3BSD.<ref>{{cite report |author1=William Joy |author-link=Bill Joy |author2=Eric Cooper |author3=Robert Fabry |author3-link=Bob Fabry |author4=Samuel Leffler |author4-link=Samuel Leffler |author5=Kirk McKusick |author5-link=Marshall Kirk McKusick |author6=David Mosher |title=4.2BSD System Manual |url=http://www.cilinder.be/docs/bsd/4.2BSD_Unix_system_manual.pdf |year=1983 |publisher=[[Computer Systems Research Group]], [[University of California, Berkeley]]}}</ref> [[Sun Microsystems]] had implemented this API, though, in the 4.0 release of their [[SunOS]] operating system.<ref>{{cite web |url=https://citeseerx.ist.psu.edu/document?repid=rep1&type=pdf&doi=a36b01c8fd5071f64b981dd3ffc66a6bce56736d#:~:text=6.1.&text=In%20general%2C%20the%20kernel%20uses,block%20data%20buffer%20cache |title=Virtual Memory Architecture in SunOS |first1=Robert A. |last1=Gingell |first2=Joseph P. |last2=Moran |first3=William A. |last3=Shannon}}</ref> The BSD developers at [[University of California, Berkeley]] unsuccessfully requested Sun to donate its implementation; 4.3BSD-Reno was instead shipped with an implementation based on the virtual memory system of [[Mach (kernel)|Mach]].<ref name="opensources">{{cite encyclopedia |title=Twenty Years of Berkeley Unix: From AT&T-Owned to Freely Redistributable |first=Marshall Kirk |last=McKusick |authorlink=Marshall Kirk McKusick |encyclopedia=Open Sources: Voices from the Open Source Revolution |year=1999 |publisher=O'Reilly}}</ref>

== File-backed and anonymous ==
''File-backed mapping'' maps an area of the process's [[virtual memory]] to files; that is, reading those areas of memory causes the file to be read. It is the default mapping type.

''Anonymous mapping'' maps an area of the process's virtual memory not backed by any file, made available via the <code>MAP_ANONYMOUS</code>/<code>MAP_ANON</code> flags. The contents are initialized to zero.<ref>{{cite web |url=https://pubs.opengroup.org/onlinepubs/9799919799/functions/mmap.html |title=mmap(2) - The Open Group Base Specifications Issue 8}}</ref> In this respect an anonymous mapping is similar to [[C dynamic memory allocation|malloc]], and is used in some malloc implementations for certain allocations, particularly large ones.

== Memory visibility ==
If the mapping is ''shared'' (the <code>MAP_SHARED</code> flag is set), then it is preserved when a process is forked (using a [[fork (system call)|<code>fork(2)</code>]] system call). Therefore, writes to a mapped area in one process are immediately visible in all related (parent, child or sibling) processes. If the mapping is ''shared'' and backed by a file (not <code>MAP_ANONYMOUS</code>) the underlying file medium is only guaranteed to be written after it is passed to the <code>msync(2)</code> system call. In contrast, if the mapping is ''private'' (the <code>MAP_PRIVATE</code> flag is set), the changes will neither be seen by other processes nor written to the file.

A process reading from, or writing to, the underlying file will not always see the same data as a different process that has mapped the file, since segments of the file are copied into RAM and only periodically flushed to disk. Synchronization can be forced with a call to <code>msync(2)</code>.

Using mmap on files can significantly reduce memory overhead for applications accessing the same file; they can share the memory area the file encompasses, instead of loading the file for each application that wants access to it. This means that mmap(2) is sometimes used for [[Interprocess Communication]] (IPC). On modern [[operating system]]s, mmap(2) is typically preferred to the [[System V]] IPC [[Shared memory (interprocess communication)|Shared Memory]] facility.<ref name="Kerrisk 2010 p. 1116">{{cite book | last=Kerrisk | first=Michael | title=The Linux programming interface : a Linux and UNIX system programming handbook | publisher=No Starch Press | publication-place=San Francisco | year=2010 | isbn=978-1-59327-291-3 | oclc=728672600 | page=1116}}</ref>

The main difference between System V shared memory (shmem) and memory mapped I/O (mmap) is that System V shared memory is persistent: unless explicitly removed by a process, it is kept in memory and remains available until the system is shut down. mmap'd memory is not persistent between application executions (unless it is backed by a file).

== Example of usage under the C programming language ==
<syntaxhighlight lang="c" line>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <err.h>
#include <fcntl.h>
#include <sys/types.h>
#include <sys/mman.h>
#include <unistd.h>

/* This example shows how an mmap of /dev/zero is equivalent to
   using anonymous memory (MAP_ANON) not connected to any file.
   N.B. MAP_ANONYMOUS or MAP_ANON are supported by most UNIX
   versions, removing the original purpose of /dev/zero.
*/
/* Does not work on OS X or macOS, where you can't mmap over /dev/zero */
int main(void) {
    const char str1[] = "string 1";
    const char str2[] = "string 2";
    pid_t parpid = getpid();
    pid_t childpid;
    int fd = -1;

    if ((fd = open("/dev/zero", O_RDWR, 0)) == -1) {
        err(1, "open");
    }

    char* anon = (char*)mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_ANON|MAP_SHARED, -1, 0);
    char* zero = (char*)mmap(NULL, 4096, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);

    if (anon == MAP_FAILED || zero == MAP_FAILED) {
        errx(1, "either mmap");
    }

    strcpy(anon, str1);
    strcpy(zero, str1);

    printf("PID %d:\tanonymous %s, zero-backed %s\n", parpid, anon, zero);
    switch ((childpid = fork())) {
        case -1:
            err(1, "fork");
            // not reached
        case 0:
            childpid = getpid();
            printf("PID %d:\tanonymous %s, zero-backed %s\n", childpid, anon, zero);
            sleep(3);

            printf("PID %d:\tanonymous %s, zero-backed %s\n", childpid, anon, zero);
            munmap(anon, 4096);
            munmap(zero, 4096);
            close(fd);
            return EXIT_SUCCESS;
    }

    sleep(2);
    strcpy(anon, str2);
    strcpy(zero, str2);

    printf("PID %d:\tanonymous %s, zero-backed %s\n", parpid, anon, zero);
    munmap(anon, 4096);
    munmap(zero, 4096);
    close(fd);
    return EXIT_SUCCESS;
}
</syntaxhighlight>

sample output:
<pre><nowiki>
PID 22475:      anonymous string 1, zero-backed string 1
PID 22476:      anonymous string 1, zero-backed string 1
PID 22475:      anonymous string 2, zero-backed string 2
PID 22476:      anonymous string 2, zero-backed string 2
</nowiki></pre>

== Usage in database implementations ==
The mmap system call has been used in various database implementations as an alternative for implementing a buffer pool, although this created a different set of problems that could realistically only be fixed using a buffer pool.<ref>{{Cite web |title=Are You Sure You Want to Use MMAP in Your Database Management System? |url=https://db.cs.cmu.edu/mmap-cidr2022/ |access-date=2023-07-04 |website=db.cs.cmu.edu |language=en}}</ref>

== See also ==
* [[Virtual memory]] for when there is more address space than physical memory
* [[Paging]] for the implementation of virtual memory
* [[Page cache]] for a disk caching mechanism utilized by mmap
* [[Demand paging]] for a scheme implemented by mmap

== References ==
{{Reflist}}

== Further reading ==
*[https://pubs.opengroup.org/onlinepubs/9799919799/functions/mmap.html Description from POSIX standard]
*Differences:
**[https://leaf.dragonflybsd.org/cgi/web-man?command=mmap DragonFly BSD]
**[http://www.freebsd.org/cgi/man.cgi?query=mmap FreeBSD]
**[https://man.netbsd.org/cgi-bin/man-cgi?mmap NetBSD]
**[https://man.openbsd.org/mmap OpenBSD]
**[http://illumos.org/man/2/mmap illumos]
**[https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemAdvancedPT/MappingFilesIntoMemory/MappingFilesIntoMemory.html Mac OS X]
**[http://docs.oracle.com/cd/E23824_01/html/821-1463/mmap-2.html#scrolltoc Solaris]
**[https://archive.today/20070310090003/http://devrsrc1.external.hp.com/STKS/cgi-bin/man2html?debug=0&manpage=/usr/share/man/man2.Z/mmap.2 HP-UX]
**[http://www.qnx.com/developers/docs/6.4.1/neutrino/lib_ref/m/mmap.html QNX]
*Windows
**[http://msdn.microsoft.com/en-us/library/aa366761.aspx MapViewOfFile] win32 function is somewhat equivalent to mmap.
*More example source code:
** [https://github.com/simonhf/sharedhashfile SharedHashFile], An open source, shared memory hash table implemented using mmap().

{{Inter-process communication}}

[[Category:Inter-process communication]]
[[Category:C POSIX library]]