.\" -*- coding: UTF-8 -*-
'\" t
.\" Copyright (C) 1996 Andries Brouwer <aeb@cwi.nl>
.\" and Copyright (C) 2006, 2007 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified 2000-03-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
.\" Modified 2001-10-04 by John Levon <moz@compsoc.man.ac.uk>
.\" Modified 2003-02-02 by Andi Kleen <ak@muc.de>
.\" Modified 2003-05-21 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"	MAP_LOCKED works from Linux 2.5.37
.\" Modified 2004-06-17 by Michael Kerrisk <mtk.manpages@gmail.com>
.\" Modified 2004-09-11 by aeb
.\" Modified 2004-12-08, from Eric Estievenart <eric.estievenart@free.fr>
.\" Modified 2004-12-08, mtk, formatting tidy-ups
.\" Modified 2006-12-04, mtk, various parts rewritten
.\" 2007-07-10, mtk, Added an example program.
.\" 2008-11-18, mtk, document MAP_STACK
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH mmap 2 "15. Juni 2024" "Linux man\-pages 6.9.1" 
.SH BEZEICHNUNG
mmap, munmap \- (un)mapt Dateien oder Geräte im Speicher
.SH BIBLIOTHEK
Standard\-C\-Bibliothek (\fIlibc\fP, \fI\-lc\fP)
.SH ÜBERSICHT
.nf
\fB#include <sys/mman.h>\fP
.P
\fBvoid *mmap(void \fP\fIAdr\fP\fB[.\fP\fIlaenge\fP\fB], size_t \fP\fIlaenge\fP\fB, int \fP\fIprot\fP\fB, int \fP\fISchalter\fP\fB,\fP
\fB           int \fP\fIdd\fP\fB, off_t \fP\fIVersatz\fP\fB);\fP
\fBint munmap(void \fP\fIAdr\fP\fB[.\fP\fIlaenge\fP\fB], size_t \fP\fIlaenge\fP\fB);\fP
.fi
.P
Siehe ANMERKUNGEN für Informationen über Feature\-Test\-Makros\-Anforderungen.
.SH BESCHREIBUNG
\fBmmap\fP() erstellt ein neues Mapping in den virtuellen Adressraum des
aufrufenden Prozesses. Die Anfangsadresse für dieses neue Mapping wird in
\fIAdr\fP angegeben. Das Argument \fIlaenge\fP gibt an, welche Größe das Mapping
haben soll (dies muss größer als 0 sein).
.P
.\" Before Linux 2.6.24, the address was rounded up to the next page
.\" boundary; since Linux 2.6.24, it is rounded down!
Falls \fIAdr\fP NULL ist, wählt der Kernel die (Seiten\-ausgerichtete) Adresse
aus, an der das Mapping erstellt wird. Dies ist die portabelste Methode, ein
neues Mapping zu erstellen. Falls \fIAdr\fP nicht NULL ist, wertet der Kernel
die Adresse als Hinweis, wo das Mapping erstellt werden soll. Unter Linux
wird das Mapping dann eine Speicherseitengrenze in der Nähe auswählen
(allerdings immer identisch zu oder oberhalb von dem durch
\fI/proc/sys/vm/mmap_min_addr\fP festgelegten Wert) und versuchen, dort ein
Mapping zu erstellen. Falls dort bereits ein anderes Mapping existiert, dann
wählt der Kernel eine neue Adresse, die den Hinweis berücksichtigen kann,
aber nicht muss. Die Adresse des neuen Mappings wird als Ergebnis des
Aufrufs zurückgegeben.
.P
Die Inhalte eines Datei\-Mappings werden initialisiert, indem \fIlaenge\fP Byte
aus der Datei (oder einem anderen Objekt), die durch den Dateideskriptor
\fIdd\fP beschrieben wird, ab dem Versatz \fIVersatz\fP verwendet werden. Dies ist
anders als beim anonymen Mapping, siehe \fBMAP_ANONYMOUS\fP unten. \fIVersatz\fP
muss ein Vielfaches der Seitengröße sein, die von \fIsysconf(_SC_PAGE_SIZE)\fP
zurückgegeben wird.
.P
Nachdem der \fBmmap\fP()\-Aufruf zurückgekehrt ist, kann der Dateideskriptor
\fIdd\fP sofort geschlossen werden, ohne dass das Mapping ungültig wird.
.P
Das Argument \fIprot\fP beschreibt den gewünschten Speicherschutz des Mappings
(und darf nicht im Widerspruch zum Öffnungsmodus der Datei stehen). Es ist
entweder \fBPROT_NONE\fP oder das bitweise ODER von einem oder mehreren der
folgenden Schalter:
.TP  1.1i
\fBPROT_EXEC\fP
Seiten können ausgeführt werden.
.TP 
\fBPROT_READ\fP
Seiten dürfen gelesen werden.
.TP 
\fBPROT_WRITE\fP
Seiten dürfen beschrieben werden.
.TP 
\fBPROT_NONE\fP
.\"
Auf die Seiten darf nicht zugegriffen werden.
.SS "Das Argument »Schalter«"
Das Argument \fISchalter\fP bestimmt, ob Aktualisierungen des Mappings für
andere Prozesse sichtbar sind, die denselben Bereich mappen und ob
Aktualisierungen auch in die zugrundeliegende Datei weitergereicht
werden. Dieses Verhalten wird durch genau einen der folgenden Werte in
\fISchalter\fP festgelegt:
.TP 
\fBMAP_SHARED\fP
Das Mapping gemeinsam benutzen. Aktualisierungen dieses Mappings sind für
andere Prozesse in dem gleichen Bereich sichtbar und (falls es sich um
Datei\-basierende Mappings handelt) werden zu der zugrundeliegenden Datei
weitergereicht. (Um genau zu steuern, wann Aktualisierungen zu der
zugrundeliegenden Datei weitergereicht werden, muss \fBmsync\fP(2) eingesetzt
werden.)
.TP 
\fBMAP_SHARED_VALIDATE\fP (seit Linux 4.15)
Dieser Schalter stellt das gleiche Verhalten wie \fBMAP_SHARED\fP bereit, außer
dass \fBMAP_SHARED\fP\-Mappings unbekannte Schalter in \fISchalter\fP
ignorieren. Im Gegensatz überprüft der Kernel, wenn er Mappings mittels
\fBMAP_SHARED_VALIDATE\fP erstellt, dass alle übergebenen Schalter bekannt sind
und schlägt mit dem Fehler \fBEOPNOTSUPP\fP bei unbekannten Schaltern
fehl. Dieser Mapping\-Typ wird auch benötigt, um bestimmte Mapping\-Schalter
(z.B. \fBMAP_SYNC\fP) verwenden zu können.
.TP 
\fBMAP_PRIVATE\fP
Erstellt ein privates, beim Kopieren zu schreibendes
Mapping. Aktualisierungen an dem Mapping sind für andere Prozesse, die die
gleiche Datei mappen, nicht sichtbar, und werden nicht an die
zugrundeliegende Datei weitergeleitet. Es ist nicht spezifiziert, ob
Änderungen an der Datei, die nach dem Aufruf von \fBmmap\fP() erfolgen, in der
gemappten Region sichtbar sind.
.P
Sowohl \fBMAP_SHARED\fP als auch \fBMAP_PRIVATE\fP werden in POSIX.1\-2001 und
POSIX.1\-2008 beschrieben. \fBMAP_SHARED_VALIDATE\fP ist eine Linux\-Erweiterung.
.P
Zusätzlich können null oder mehrere der folgenden Werte mit OR in
\fISchalter\fP hinzugefügt werden:
.TP 
\fBMAP_32BIT\fP (seit Linux 2.4.20, 2.6)
.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08
Legt das Mapping in die ersten zwei Gigabyte des Prozessadressraums. Dieser
Schalter wird nur auf X86\-64 für 64\-Bit\-Programme unterstützt. Er wurde
hinzugefügt, damit Thread\-Stacks irgendwo innerhalb der ersten 2\ GB
Speicher zugewiesen werden können, damit die Leistung des
Kontext\-Umschaltens auf einigen der ersten 64\-Bit\-Prozessoren erhöht
wird. Moderne X86\-64\-Prozessoren haben dieses Leistungsproblem nicht mehr,
wodurch der Einsatz dieses Schalters auf diesen Systemen nicht mehr benötigt
wird. Der Schalter \fBMAP_32BIT\fP wird ignoriert, wenn \fBMAP_FIXED\fP gesetzt
ist.
.TP 
\fBMAP_ANON\fP
Synonym für \fBMAP_ANONYMOUS\fP; zur Kompatibilität mit anderen
Implementierungen bereitgestellt.
.TP 
\fBMAP_ANONYMOUS\fP
.\" See the pgoff overflow check in do_mmap().
.\" See the offset check in sys_mmap in arch/x86/kernel/sys_x86_64.c.
Diesem Mapping liegt keine Datei zugrunde; ihr Inhalt wird mit Nullen
initialisiert. Das Argument \fIdd\fP wird ignoriert, einige Implementierungen
verlangen aber, dass \fIdd\fP \-1 ist, falls \fBMAP_ANONYMOUS\fP (oder \fBMAP_ANON\fP)
festgelegt ist, und portable Anwendungen sollten dies sicherstellen. Das
Argument \fIVersatz\fP sollte 0 sein. Die Unterstützung für \fBMAP_ANONYMOUS\fP
mit \fBMAP_SHARED\fP wurde in Linux 2.4 hinzugefügt.
.TP 
\fBMAP_DENYWRITE\fP
.\" Introduced in 1.1.36, removed in 1.3.24.
Dieser Schalter wird ignoriert. (Vor langer Zeit \[en] Linux 2.0 und älter
\[en] signalisierte er, dass Schreibversuche auf die zugrundeliegende Datei
mit \fBETXTBSY\fP fehlschlagen sollten. Dies war aber eine Quelle von
Diensteverweigerungsangriffen.
.TP 
\fBMAP_EXECUTABLE\fP
.\" Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link.
.\" (Long ago, it signaled that the underlying file is an executable.
.\" However, that information was not really used anywhere.)
.\" Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of
.\" MAP_DENYWRITE?
Dieser Schalter wird ignoriert.
.TP 
\fBMAP_FILE\fP
.\" On some systems, this was required as the opposite of
.\" MAP_ANONYMOUS -- mtk, 1 May 2007
Kompatibilitätsschalter. Ignoriert.
.TP 
\fBMAP_FIXED\fP
\fIAdr\fP wird nicht als Hinweis interpretiert; legt das Mapping genau an
dieser Adresse an. \fIAdr\fP muss geeignet ausgerichtet sein: bei den meisten
Architekturen reicht ein Vielfaches der Seitengröße aus, allerdings könnten
einige Architekturen zusätzliche Anforderungen stellen. Falls der mit \fIAdr\fP
und \fIlaenge\fP festgelegte Speicherbereich bestehende Mappings überlappt,
dann wird der überlappende Anteil des bestehenden Mappings verworfen. Falls
die angegebene Adresse nicht verwandt werden kann, wird \fBmmap\fP()
fehlschlagen.
.IP
Software, die Portierbarkeit anstrebt, sollte den Schalter \fBMAP_FIXED\fP mit
Vorsicht verwenden und dabei berücksichtigen, dass sich die genaue Anordnung
der Mappings des Prozesses im Speicher deutlich zwischen Linuxversionen,
C\-Bibliotheksversionen und Betriebssystemveröffentlichungen unterscheiden
kann. \fILesen Sie die Erörterung dieses Schalters im Abschnitt ANMERKUNGEN sorgfältig!\fP
.TP 
\fBMAP_FIXED_NOREPLACE\fP (seit Linux 4.17)
.\" commit a4ff8e8620d3f4f50ac4b41e8067b7d395056843
Dieser Schalter stellt ein Verhalten bereit, das \fBMAP_FIXED\fP im Hinblick
auf die Erzwingung von \fIAdr\fP ähnelt, sich aber dadurch unterscheidet, dass
\fBMAP_FIXED_NOREPLACE\fP einen bereits bestehenden, gemappten Bereich
durcheinanderbringt. Falls der angeforderte Bereich mit einem bestehenden
Mapping kollidieren würde, dann schlägt dieser Aufruf mit \fBEEXIST\fP
fehl. Dieser Schalter kann daher für atomare (im Hinblick auf andere
Threads) Versuche, einen Adressbereich zu mappen, verwandt werden: ein
Thread hat Erfolg, alle anderen berichten einen Fehlschlag.
.IP
Beachten Sie, dass ältere Kernel, die den Schalter \fBMAP_FIXED_NOREPLACE\fP
nicht erkennen, typischerweise (bei der Erkennung einer Kollision mit einem
bereits bestehenden Mapping) auf den Verhaltenstyp von »nicht\-\fBMAP_FIXED\fP«
zurückfallen: sie liefern eine Adresse zurück, die sich von der
angeforderten Adresse unterscheidet. Daher sollte rückwärtskompatible
Software die zurückgelieferte Adresse mit der angeforderten Adresse
vergleichen.
.TP 
\fBMAP_GROWSDOWN\fP
Dieser Schalter wird für Stacks verwandt. Er zeigt dem Kernelsystem für
virtuellen Speicher an, dass sich das Mapping nach unten im Speicher
ausdehnen soll. Die zurückgelieferte Adresse ist eine Seite tiefer als der
Speicherbereich, der tatsächlich im virtuellen Adressraum des Prozesses
erstellt wird. Wird eine Adresse in der »Wächter«\-Seite unterhalb des
Mappings berührt, dann wächst das Mapping um eine Seite. Dieses Wachstum
kann wiederholt werden, bis das Mapping bis auf eine Seite innerhalb des
hohen Endes des nächst\-niedrigeren Mappings anwächst \- zu diesem Zeitpunkt
führt das Berühren der »Wächter«\-Seite zu einem \fBSIGSEGV\fP\-Signal.
.TP 
\fBMAP_HUGETLB\fP (seit Linux 2.6.32)
Reserviert das Mapping mittels »großer« Speicherseiten. Siehe die
Linux\-Kernelquelldatei \fIDocumentation/admin\-guide/mm/hugetlbpage.rst\fP sowie
die nachfolgenden ANMERKUNGEN für weitere Details.
.TP 
\fBMAP_HUGE_2MB\fP
.TQ
\fBMAP_HUGE_1GB\fP (seit Linux 3.8)
.\" See https://lwn.net/Articles/533499/
Wird in Zusammenhang mit \fBMAP_HUGETLB\fP verwandt, um alternative
hugetlb\-Seitengrößen (respektive 2\ MB und 1\ GB) auf Systemen auszuwählen,
die mehrere hugetlb\-Seitengrößen unterstützen.
.IP
Allgemeiner kann die gewünschte Größe der großen Speicherseiten durch
Kodierung des Logarithmus zur Basis 2 der gewünschten Seitengröße in den
sechs Bits am Versatz \fBMAP_HUGE_SHIFT\fP konfiguriert werden. (Ein Wert 0 in
diesem Bitfeld stellt die standardmäßige große Speicherseitengröße bereit;
die Vorgabegröße großer Speicherseiten kann mittels des durch
\fI/proc/meminfo\fP offengelegten Feldes \fIHugepagesize\fP ermittelt werden.)
Daher sind die obigen zwei Konstanten wie folgt definiert:
.IP
.in +4n
.EX
#define MAP_HUGE_2MB    (21 << MAP_HUGE_SHIFT)
#define MAP_HUGE_1GB    (30 << MAP_HUGE_SHIFT)
.EE
.in
.IP
Der von dem System unterstützte Bereich der Größe der großen Speicherseiten
kann durch Auflisten der Unterverzeichnisse in \fI/sys/kernel/mm/hugepages\fP
ermittelt werden.
.TP 
\fBMAP_LOCKED\fP (seit Linux 2.5.37)
.\" If set, the mapped pages will not be swapped out.
Markiert den gemappten Bereich auf die gleiche Art wie \fBmlock\fP(2). Diese
Implementierung wird versuchen, den gesamten Bereich vorzubelegen
(»prefault«) aber der Aufruf von \fBmmap\fP() wird nicht mit \fBENOMEM\fP
fehlschlagen, falls dies nicht gelingt. Daher können später große
Ausnahmebehandlungen passieren. Daher ist die Semantik nicht so stark wie
\fBmlock\fP(2). Sie sollten \fBmmap\fP() mit \fBmlock\fP(2) verwenden, wenn große
Ausnahmebehandlungen nach der Initialisierung des Mappings nicht
akzeptierbar sind. Der Schalter \fBMAP_LOCKED\fP wird unter älteren Kerneln
ignoriert.
.TP 
\fBMAP_NONBLOCK\fP (seit Linux 2.5.46)
.\" commit 54cb8821de07f2ffcd28c380ce9b93d5784b40d7
Dieser Schalter ergibt nur im Zusammenhang mit \fBMAP_POPULATE\fP Sinn. Es wird
kein Vorauslesen durchgeführt, es werden Seitentabelleneinträge nur für
Seiten erstellt, die bereits im RAM vorhanden sind. Seit Linux 2.6.23 führt
dieser Schalter dazu, dass \fBMAP_POPULATE\fP nichts macht. Irgendwann könnte
die Kombination von \fBMAP_POPULATE\fP und \fBMAP_NONBLOCK\fP wieder implementiert
werden.
.TP 
\fBMAP_NORESERVE\fP
Reserviert für dieses Mapping keinen Auslagerungsspeicher. Wenn
Auslagerungsspeicher reserviert wird, muss garantiert werden, dass
Änderungen an dem Mapping möglich sind. Wird kein Auslagerungsspeicher
reserviert, könnte beim Schreiben ein \fBSIGSEGV\fP empfangen werden, falls
kein physischer Speicher verfügbar ist. Siehe auch die Diskussion der Datei
\fI/proc/sys/vm/overcommit_memory\fP in \fBproc\fP(5). Vor Linux 2.6 hatte dieser
Schalter nur für private, schreibbare Mappings eine Wirkung.
.TP 
\fBMAP_POPULATE\fP (seit Linux 2.5.46)
Belegt (»prefault«) Seitentabellen für ein Mapping. Für ein Datei\-Mapping
führt dies zu einem Vorablesen der Datei. Dies hilft dabei, später
Blockierungen bei Seitenausnahmebehandlungen zu vermeiden. Der Aufruf
\fBmmap\fP() schlägt nicht fehl, falls das Mapping nicht belegt werden kann
(beispielsweise aufgrund von Beschränkungen der Anzahl der gemappten großen
Seiten bei der Verwendung von \fBMAP_HUGETLB\fP). Die Unterstützung für
\fBMAP_POPULATE\fP zusammen mit privaten Mappings wurde in Linux 2.6.23
hinzugefügt.
.TP 
\fBMAP_STACK\fP (seit Linux 2.6.27)
Reserverviert ein Mapping an einer Adresse, die für einen Stack eines
Prozesses oder Threads geeignet ist.
.IP
.\" See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08
.\" commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7
.\" http://thread.gmane.org/gmane.linux.kernel/720412
.\" "pthread_create() slow for many threads; also time to revisit 64b
.\"  context switch optimization?"
Dieser Schalter löst derzeit nichts aus. Durch Einsatz dieses Schalters
können Anwendungen aber transparent sicherstellen, dass sie die
Unterstützung erlangen, wenn dieser Schalter in der Zukunft implementiert
wird. Daher wird er in der Glibc\-Threading\-Implementierung verwandt, um der
Tatsache Rechnung zu tragen, dass auf einigen Architekturen (später) eine
besondere Behandlung von Stack\-Zuweisungen nötig sein könnte. Ein weiterer
Grund, diesen Schalter einzusetzen, ist die Portabilität: \fBMAP_STACK\fP
existiert (und hat eine Auswirkung) auf einigen anderen Systemen
(z.B. einigen BSDs).
.TP 
\fBMAP_SYNC\fP (seit Linux 4.15)
Dieser Schalter ist nur mit dem Mapping\-Typ \fBMAP_SHARED_VALIDATE\fP
verfügbar. Mappings vom Typ \fBMAP_SHARED\fP ignorieren diesen Schalter ohne
Rückmeldung. Dieser Schalter wird nur für Dateien, die DAX (direktes Mapping
von dauerhaftem Speicher) unterstützen, unterstützt. Für andere Dateien wird
das Erstellen eines Mappings mit diesem Schalter zu einem
\fBEOPNOTSUPP\fP\-Fehler führen.
.IP
Gemeinsame Datei\-Mappings mit diesem Schalter garantieren, dass der
schreibbare eingemappte Speicheranteil im Adressraum des Prozesses auch in
der gleichen Datei an dem gleichen Versatz selbst nach einem Systemabsturz
oder \-neustart sichtbar ist. Im Zusammenhang mit dem Einsatz geeigneter
CPU\-Anweisungen stellt dieses Benutzern solcher Mappings eine effizientere
Art bereit, solche Datenveränderungen dauerhaft zu machen.
.TP 
\fBMAP_UNINITIALIZED\fP (seit Linux 2.6.33)
Die anonymen Seiten nicht bereinigen. Dieser Schalter ist für die
Verbesserung der Leistung auf eingebetteten Systemen gedacht. Dieser
Schalter wird nur berücksichtigt, falls der Kernel mit der Option
\fBCONFIG_MMAP_ALLOW_UNINITIALIZED\fP konfiguriert worden war. Aufgrund der
Sicherheitsauswirkungen wird diese Option normalerweise nur auf
eingebetteten Geräten (d.h. Geräten, bei denen komplette Kontrolle über die
Speicherinhalte besteht) aktiviert.
.P
.\" FIXME . for later review when Issue 8 is one day released...
.\" POSIX may add MAP_ANON in the future
.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
.\" http://austingroupbugs.net/view.php?id=850
Von den obigen Schaltern ist nur \fBMAP_FIXED\fP in POSIX.1\-2001 und
POSIX.1\-2008 spezifiziert. Allerdings unterstützen die meisten Systeme
\fBMAP_ANONYMOUS\fP (oder sein Synonym \fBMAP_ANON\fP).
.SS munmap()
Der \fBmunmap\fP\-Systemaufruf hebt die Mappings im angegebenen Speicherbereich
auf. Zukünftige Zugriffe auf diesen Adressraum erzeugen dann einen Fehler
vom Typ »invalid memory reference« \- Ungültiger Speicherzugriff. Der
Adressraum wird außerdem automatisch ausgemappt, wenn der Prozess beendet
wird. Das Schließen des Dateideskriptors hingegen führt nicht dazu, dass der
Adress\-Mapping aufgehoben wird.
.P
Die Adresse \fIAdr\fP muss ein Vielfaches der Seitengröße sein (für \fIlaenge\fP
ist das nicht der Fall). Alle Seiten, die einen Teil des angezeigten
Bereichs enthalten, werden ausgemappt, und nachfolgende Referenzen auf diese
Seiten führen zu \fBSIGSEGV\fP. Es ist kein Fehler, falls der angezeigte
Bereich keine gemappten Seiten enthält.
.SH RÜCKGABEWERT
Bei Erfolg gibt \fBmmap\fP einen Zeiger auf den gemappten Speicherbereich
zurück. Bei Fehlern wird \fBMAP_FAILED\fP (\fI(void\ *)\ \-1\fP) zurückgegeben und
\fIerrno\fP gesetzt, um den Fehler anzuzeigen.
.P
Bei Erfolg liefert \fBmunmap\fP() 0 zurück. Im Fehlerfall liefert es \-1 und
\fIerrno\fP wird gesetzt, um den Fehler (wahrscheinlich \fBEINVAL\fP) anzuzeigen.
.SH FEHLER
.TP 
\fBEACCES\fP
Ein Dateideskriptor bezieht sich auf eine nicht normale Datei. Oder ein
Datei\-Mapping wurde angefordert, aber \fIdd\fP ist nicht zum Lesen
geöffnet. Oder \fBMAP_SHARED\fP wurde erbeten und \fBPROT_WRITE\fP ist gesetzt,
aber \fIdd\fP ist nicht zum Lesen/Schreiben geöffnet (\fBO_RDWR\fP). Oder
\fBPROT_WRITE\fP ist angegeben, aber die Datei darf nur am Ende weiter
beschrieben werden (»append\-only«).
.TP 
\fBEAGAIN\fP
Die Datei wurde gesperrt oder zuviel Speicher wurde gesperrt (siehe
\fBsetrlimit\fP(2)).
.TP 
\fBEBADF\fP
\fIdd\fP ist kein gültiger Dateideskriptor (und \fBMAP_ANONYMOUS\fP wurde nicht
gesetzt).
.TP 
\fBEEXIST\fP
\fBMAP_FIXED_NOREPLACE\fP wurde in \fISchalter\fP angegeben und der durch \fIAdr\fP
und \fIlaenge\fP abgedeckte Bereich überschneidet sich mit einem bestehenden
Mapping.
.TP 
\fBEINVAL\fP
Die Adressen, die durch \fIAdr\fP, \fIlaenge\fP oder \fIVersatz\fP angegeben wurden,
sind ungültig. (Z.B. sind sie zu groß oder nicht an einer
Speicherseitengröße ausgerichtet.)
.TP 
\fBEINVAL\fP
(seit Linux 2.6.12)  \fIlaenge\fP war 0.
.TP 
\fBEINVAL\fP
\fISchalter\fP enthielt weder \fBMAP_PRIVATE\fP, \fBMAP_SHARED\fP noch
\fBMAP_SHARED_VALIDATE\fP.
.TP 
\fBENFILE\fP
.\" This is for shared anonymous segments
.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
.\" .TP
.\" .B ENOEXEC
.\" A file could not be mapped for reading.
Die systemweite Beschränkung für die Gesamtzahl offener Dateien wurde
erreicht.
.TP 
\fBENODEV\fP
Das zugrundeliegende Dateisystem der angegebenen Datei unterstützt das
Speicher\-Mapping nicht.
.TP 
\fBENOMEM\fP
Es ist kein Speicher verfügbar.
.TP 
\fBENOMEM\fP
Die maximale Anzahl von Mappings des Prozesses würde überschritten. Dieser
Fehler kann auch für \fBmunmap\fP() beim Aufheben von Mappings einer Region in
der Mitte eines bestehenden Mappings auftreten, da dies zu zwei kleineren
Mappings auf jeder Seite des entmappten Bereichs führt.
.TP 
\fBENOMEM\fP
(seit Linux 4.7). Die Prozessbeschränkung \fBRLIMIT_DATA\fP, beschrieben in
\fBgetrlimit\fP(2), würde überschritten.
.TP 
\fBENOMEM\fP
Wir mögen \fIAdr\fP nicht, da es den virtuellen Adressraum der CPU
überschreitet.
.TP 
\fBEOVERFLOW\fP
Auf 32\-Bit\-Architekturen zusammen mit den Erweiterungen für große Dateien
(d.h. der Verwendung von 64\-Bit \fIoff_t\fP): die Anzahl der für \fIlaenge\fP
sowie die Anzahl der für \fIVersatz\fP verwandten Seiten würde einen Überlauf
von \fIunsigned long\fP (32\-Bit) hervorrufen.
.TP 
\fBEPERM\fP
.\" (Since Linux 2.4.25 / Linux 2.6.0.)
Das Argument \fIprot\fP verlangt \fBPROT_EXEC\fP, aber der gemappte Bereich gehört
zu einer Datei auf einem Dateisystem, das ohne Ausführrechte eingehängt
wurde (»no\-exec«).
.TP 
\fBEPERM\fP
Die Aktion wurde durch eine Dateiversiegelung verhindert; siehe \fBfcntl\fP(2).
.TP 
\fBEPERM\fP
Der Schalter \fBMAP_HUGETLB\fP wurde angegeben, aber der Aufrufende war nicht
privilegiert (verfügte nicht über die Capability \fBCAP_IPC_LOCK\fP) und ist
kein Mitglied der Gruppe \fIsysctl_hugetlb_shm_group\fP; siehe die Beschreibung
von \fI/proc/sys/vm/sysctl_hugetlb_shm_group\fP in \fBproc_sys\fP(5).
.TP 
\fBETXTBSY\fP
\fBMAP_DENYWRITE\fP wurde angegeben, aber das durch \fIdd\fP bezeichnete Objekt
ist zum Schreiben geöffnet.
.P
Die Verwendung eines gemappten Bereichs kann diese Signale verursachen:
.TP 
\fBSIGSEGV\fP
Es wurde versucht, in einen Bereich zu schreiben, der nur lesbar gemappt
wurde.
.TP 
\fBSIGBUS\fP
Es wurde versucht, auf eine Seite des Puffers zuzugreifen, die hinter dem
Ende der gemappten Datei liegt. Für eine Erläuterung der Behandlung von
Bytes in der Seite, die dem Ende der gemappten Datei entspricht, die kein
Vielfaches der Seitengröße ist, siehe ANMERKUNGEN.
.SH ATTRIBUTE
Siehe \fBattributes\fP(7) für eine Erläuterung der in diesem Abschnitt
verwandten Ausdrücke.
.TS
allbox;
lbx lb lb
l l l.
Schnittstelle	Attribut	Wert
T{
.na
.nh
\fBmmap\fP(),
\fBmunmap\fP()
T}	Multithread\-Fähigkeit	MT\-Sicher
.TE
.SH VERSIONEN
Auf einigen Hardware\-Architekturen (z.B. i386) impliziert \fBPROT_WRITE\fP
\fBPROT_READ\fP. Es ist architekturabhängig, ob \fBPROT_READ\fP \fBPROT_EXEC\fP
impliziert (oder nicht). Portable Programme sollten immer \fBPROT_EXEC\fP
setzen, falls sie vorhaben, Code in dem neuen Mapping auszuführen.
.P
Die portierbare Art, ein Mapping zu erstellen, ist die Angabe von \fIAdr\fP als
0 (NULL) und das Auslassen von \fBMAP_FIXED\fP aus \fISchalter\fP. In diesem Fall
wählt das System die Adresse für das Mapping; die Adresse wird so gewählt,
dass sie mit keinem bestehenden Mapping in Konflikt steht und nicht 0 sein
wird. Falls der Schalter \fBMAP_FIXED\fP angegeben und \fIAdr\fP 0 (NULL) ist,
dann wird die gemappte Adresse 0 (NULL) sein.
.P
Bestimmte \fISchalter\fP\-Konstanten sind nur definiert, falls die geeigneten
Feature\-Test\-Makros definiert sind (möglicherweise standardmäßig):
\fB_DEFAULT_SOURCE\fP mit Glibc 2.19 oder neuer; oder \fB_BSD_SOURCE\fP oder
\fB_SVID_SOURCE\fP in Glibc 2.19 und älter. (Es reicht auch aus, \fB_GNU_SOURCE\fP
einzusetzen, und dieses Makro zu verlangen, wäre logischer gewesen, da alle
diese Schalter Linux\-spezifisch sind). Die relevanten Schalter sind:
\fBMAP_32BIT\fP, \fBMAP_ANONYMOUS\fP (und das Synonym \fBMAP_ANON\fP),
\fBMAP_DENYWRITE\fP, \fBMAP_EXECUTABLE\fP, \fBMAP_FILE\fP, \fBMAP_GROWSDOWN\fP,
\fBMAP_HUGETLB\fP, \fBMAP_LOCKED\fP, \fBMAP_NONBLOCK\fP, \fBMAP_NORESERVE\fP,
\fBMAP_POPULATE\fP und \fBMAP_STACK\fP.
.SS "Unterschiede C\-Bibliothek/Kernel"
.\" Since around glibc 2.1/2.2, depending on the platform.
Diese Seite beschreibt die durch den \fBmmap\fP()\-Wrapper der Glibc
bereitgestellte Funktion. Ursprünglich rief diese Funktion einen
Systemaufruf mit dem gleichen Namen auf. Seit Linux 2.4 wurde dieser
Systemaufruf durch \fBmmap2\fP(2) ersetzt und heutzutage ruft die
Wrapperfunktion \fBmmap\fP() der Glibc \fBmmap2\fP(2) mit einem geeignet
angepassten Wert für \fIVersatz\fP auf.
.SH STANDARDS
POSIX.1\-2008.
.SH GESCHICHTE
.\" SVr4 documents additional error codes ENXIO and ENODEV.
.\" SUSv2 documents additional error codes EMFILE and EOVERFLOW.
POSIX.1\-2001, SVr4, 4.4BSD.
.P
.\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
.\" -1: unavailable, 0: ask using sysconf().
.\" glibc defines it to 1.
Auf POSIX\-Systemen, auf denen \fBmmap\fP(), \fBmsync\fP(2) und \fBmunmap\fP()
verfügbar sind, ist \fB_POSIX_MAPPED_FILES\fP in \fI<unistd.h>\fP auf
einen Wert größer 0 definiert. (Siehe auch \fBsysconf\fP(3).)
.SH ANMERKUNGEN
Speicher, der mit \fBmmap\fP() gemappt wurde, wird über \fBfork\fP(2) hinweg mit
den gleichen Attributen erhalten.
.P
Eine Datei wird in Vielfachen der Seitengröße gemappt. Für eine Datei, die
nicht ein Vielfaches der Seitengröße ist, werden die verbliebenen Bytes in
der unvollständigen Seite am Ende des Mappings beim Mappen mit Nullen
überschrieben und Änderungen an diesem Bereich werden nicht in die Datei
geschrieben. Es ist nicht spezifiziert, wie sich die Größenänderung der
zugrundeliegenden Datei auf das Mapping der Seiten, die hinzugefügten oder
entfernten Regionen der Datei entsprechen, auswirkt.
.P
.\"
Durch Verwendung von \fBmincore\fP(2) kann eine Anwendung ermitteln, welche
Seiten eines Mappings sich derzeit im Puffer/Seitenzwischenspeicher
befinden.
.SS "MAP_FIXED sicher benutzen"
Der einzige sichere Anwendungsfall für \fBMAP_FIXED\fP ist, falls der durch
\fIAdr\fP und \fIlaenge\fP festgelegte Adressbereich vorher durch ein anderes
Mapping reserviert wurde; andernfalls ist die Verwendung von \fBMAP_FIXED\fP
gefährlich, da sie bereits bestehende Mappings zwangsweise entfernt, wodurch
es für einen Prozess mit mehreren Threads leicht wird, seinen eigenen
Adressraum zu beschädigen.
.P
Nehmen wir beispielsweise an, dass Thread A \fI/proc/\fPPID\fI/maps\fP durchsucht,
um einen nicht benutzten Adressbereich zu finden, den er mittels
\fBMAP_FIXED\fP mappen kann, während Thread B gleichzeitig Teile des gleichen
Adressbereichs (oder den gesamten Adressbereich) erlangt. Wenn Thread A
anschließend \fBmmap(MAP_FIXED)\fP einsetzt, wird es das Mapping, das Thread B
erstellte, durcheinanderbringen. In diesem Szenario muss Thread B nicht das
Mapping direkt erstellen: einfach ein Aufruf einer Bibliotheksfunktion, die
intern \fBdlopen\fP(3) zum Laden einer anderen dynamische Bibliothek verwendet,
reicht aus. Der Aufruf von \fBdlopen\fP(3) wird die Bibliothek in den
Adressraum des Prozesses einmappen. Desweiteren kann fast jeder
Bibliotheksaufruf auf eine Art implementiert sein, die Speicher\-Mappings zu
dem Adressraum hinzufügt, entweder mit dieser Technik oder einfach durch
Reservierung von Speicher. Beispiele sind \fBbrk\fP(2), \fBmalloc\fP(3),
\fBpthread_create\fP(3) und die PAM\-Bibliotheken
.UR http://www.linux\-pam.org
.UE .
.P
.\"
Seit Linux 4.17 kann ein Multithread\-Programm den Schalter
\fBMAP_FIXED_NOREPLACE\fP verwenden, um die oben beschriebene Gefahr zu
vermeiden, dass ein Mapping an einer festen Adresse versucht wird, die nicht
durch ein bereits existierendes Mapping reserviert wurde.
.SS "Zeitstempeländerungen für Datei\-basierte Mappings"
Für Datei\-basierte Mappings wird das Feld \fIst_atime\fP für die gemappte Datei
zu jedem Zeitpunkt zwischen \fBmmap\fP() und dem entsprechenden Entmappen
aufgerufen werden; die erste Referenz auf die gemappte Seite wird das Feld
aktualisieren, falls es nicht bereits erfolgt ist.
.P
.\"
Das Feld \fIst_ctime\fP und \fIst_mtime\fP für eine mit \fBPROT_WRITE\fP und
\fBMAP_SHARED\fP gemappte Datei wird nach einem Schreibzugriff auf den
gemappten Bereich und vor dem nachfolgenden \fBmsync\fP(2) mit den Schalter
\fBMS_SYNC\fP oder \fBMS_ASYNC\fP, falls dieser erfolgt, aktualisiert.
.SS "Mappings großer Speicherseiten (Huge TLB)"
Für Mappings, die große Speicherseiten einsetzen, unterscheiden sich die
Anforderungen für die Argumente von \fBmmap\fP() und \fBmunmap\fP() etwas von den
Anforderungen für Mappings, die die native Systemseitengröße verwenden.
.P
Für \fBmmap\fP() muss \fIVersatz\fP ein Vielfaches der unterliegenden Größe der
großen Speicherseiten sein. Das System richtet \fIlaenge\fP automatisch aus,
dass es ein Vielfaches der unterliegenden Größe der großen Speicherseiten
ist.
.P
.\"
Für \fBmunmap\fP() müssen sowohl \fIAdr\fP als auch \fIlaenge\fP ein Vielfaches der
unterliegenden Größe der großen Speicherseiten sein.
.SH FEHLER
Unter Linux gibt es keine Garantien, wie die, die unter \fBMAP_NORESERVE\fP
vorgeschlagen werden. Standardmäßig kann jeder Prozess jederzeit getötet
werden, wenn dem System der Speicher ausgeht.
.P
Vor Linux 2.6.7 hatte der Schalter \fBMAP_POPULATE\fP nur einen Effekt, falls
\fIprot\fP als \fBPROT_NONE\fP festgelegt ist.
.P
SUSv3 spezifiziert, dass \fBmmap\fP() fehlschlagen soll, falls \fIlaenge\fP 0
ist. Vor Linux 2.6.12 war \fBmmap\fP() in diesem Fall allerdings erfolgreich:
es wurde kein Mapping erstellt und der Aufruf lieferte \fIAdr\fP zurück. Seit
Linux 2.6.12 schlägt es in diesem Fall mit dem Fehler \fBEINVAL\fP fehl.
.P
POSIX spezifiziert, dass das System immer jede teilweise gefüllte Seite am
Ende des Objektes mit Nullen auffüllen muss und dass das System niemals
Änderungen an dem Objekt hinter seinem Ende schreibt. Unter Linux verbleiben
sämtliche geschriebenen Daten in solchen Teilseiten nach dem Ende des
Objektes im Seitenzwischenspeicher, selbst nachdem die Datei geschlossen und
entmappt wurde und selbst obwohl die Daten niemals zu der Datei selbst
geschrieben wurden, könnten nachfolgende Mappings die veränderten Inhalte
sehen. In einigen Fällen könnte dies durch einen Aufruf von \fBmsync\fP(2),
bevor das Aufheben des Mappings stattfindet, behoben werden, allerdings
funktioniert dies nicht auf \fBtmpfs\fP(5) (beispielsweise beim Einsatz der
POSIX\-Schnittstelle für gemeinsamen Speicher, wie in \fBshm_overview\fP(7)
dokumentiert).
.SH BEISPIELE
.\" FIXME . Add an example here that uses an anonymous shared region for
.\" IPC between parent and child.
Das nachfolgende Programm gibt Teile der als sein erstes
Befehlszeilenargument übergebenen Datei auf die Standardausgabe aus. Der
ausgegebene Byte\-Bereich wird mittels des Versatzes und des Längenwertes im
zweiten und dritten Befehlszeilenargument angegeben. Das Programm erstellt
ein Speicher\-Mapping der benötigten Seiten der Datei und verwendet
\fBwrite\fP(2), um die gewünschten Bytes auszugeben.
.SS Programmquelltext
.\" SRC BEGIN (mmap.c)
.EX
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
\&
#define handle_error(msg) \[rs]
    do { perror(msg); exit(EXIT_FAILURE); } while (0)
\&
int
main(int argc, char *argv[])
{
    int          fd;
    char         *addr;
    off_t        offset, pa_offset;
    size_t       length;
    ssize_t      s;
    struct stat  sb;
\&
    if (argc < 3 || argc > 4) {
        fprintf(stderr, "%s Dateiversatz [Länge]\[rs]n", argv[0]);
        exit(EXIT_FAILURE);
    }
\&
    fd = open(argv[1], O_RDONLY);
    if (fd == \-1)
        handle_error("open");
\&
    if (fstat(fd, &sb) == \-1)           /* Um die Dateigröße zu erhalten */
        handle_error("fstat");
\&
    offset = atoi(argv[2]);
    pa_offset = offset & \[ti](sysconf(_SC_PAGE_SIZE) \- 1);
        /* Versatz für mmap() muss an der Seite ausgerichtet sein */
\&
    if (offset >= sb.st_size) {
        fprintf(stderr, "Versatz ist hinter dem Dateiende\[rs]n");
        exit(EXIT_FAILURE);
    }
\&
    if (argc == 4) {
        length = atoi(argv[3]);
        if (offset + length > sb.st_size)
            length = sb.st_size \- offset;
                /* Bytes hinter dem Dateiende können nicht angezeigt werden */
\&
    } else {    /* Kein Längen\-Argument ==> Anzeige bis zum Dateiende */
        length = sb.st_size \- offset;
    }
\&
    addr = mmap(NULL, length + offset \- pa_offset, PROT_READ,
                MAP_PRIVATE, fd, pa_offset);
    if (addr == MAP_FAILED)
        handle_error("mmap");
\&
    s = write(STDOUT_FILENO, addr + offset \- pa_offset, length);
    if (s != length) {
        if (s == \-1)
            handle_error("write");
\&
        fprintf(stderr, "Schreiben unvollständig");
        exit(EXIT_FAILURE);
    }
\&
    munmap(addr, length + offset \- pa_offset);
    close(fd);
\&
    exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH "SIEHE AUCH"
\fBftruncate\fP(2), \fBgetpagesize\fP(2), \fBmemfd_create\fP(2), \fBmincore\fP(2),
\fBmlock\fP(2), \fBmmap2\fP(2), \fBmprotect\fP(2), \fBmremap\fP(2), \fBmsync\fP(2),
\fBremap_file_pages\fP(2), \fBsetrlimit\fP(2), \fBshmat\fP(2), \fBuserfaultfd\fP(2),
\fBshm_open\fP(3), \fBshm_overview\fP(7)
.P
Die Beschreibung der folgenden Dateien in \fBproc\fP(5): \fI/proc/\fPPID\fI/maps\fP,
\fI/proc/\fPPID\fI/map_files\fP und \fI/proc/\fPPID\fI/smaps\fP.
.P
B.O. Gallmeister, POSIX.4, O'Reilly, Seiten 128\[en]129 und 389\[en]391.
.\"
.\" Repeat after me: private read-only mappings are 100% equivalent to
.\" shared read-only mappings. No ifs, buts, or maybes. -- Linus
.PP
.SH ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von
Johnny Teveßen <j.tevessen@gmx.de>,
Martin Schulze <joey@infodrom.org>,
Dr. Tobias Quathamer <toddy@debian.org>
und
Helge Kreutzmann <debian@helgefjell.de>
erstellt.
.PP
Diese Übersetzung ist Freie Dokumentation; lesen Sie die
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License Version 3
.UE
oder neuer bezüglich der
Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.
.PP
Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden,
schicken Sie bitte eine E-Mail an die
.MT debian-l10n-german@lists.debian.org
Mailingliste der Übersetzer
.ME .