MapViewOfFile-Funktion (memoryapi.h)
Ordnet eine Ansicht einer Dateizuordnung dem Adressraum eines aufrufenden Prozesses zu.
Verwenden Sie die MapViewOfFileEx-Funktion , um eine vorgeschlagene Basisadresse für die Ansicht anzugeben. Diese Vorgehensweise wird jedoch nicht empfohlen.
Syntax
LPVOID MapViewOfFile(
[in] HANDLE hFileMappingObject,
[in] DWORD dwDesiredAccess,
[in] DWORD dwFileOffsetHigh,
[in] DWORD dwFileOffsetLow,
[in] SIZE_T dwNumberOfBytesToMap
);
Parameter
[in] hFileMappingObject
Ein Handle für ein Dateizuordnungsobjekt. Die Funktionen CreateFileMapping und OpenFileMapping geben dieses Handle zurück.
[in] dwDesiredAccess
Der Typ des Zugriffs auf ein Dateizuordnungsobjekt, das den Seitenschutz der Seiten bestimmt. Dieser Parameter kann einer der folgenden Werte oder ggf. eine bitweise OR-Kombination aus mehreren Werten sein.
Mit bitweisem OR können Sie die obigen Werte mit diesen Werten kombinieren.
| Wert | Bedeutung |
|---|---|
|
Eine Kopieransicht der Datei wird zugeordnet. Das Dateizuordnungsobjekt muss mit PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITE oder PAGE_EXECUTE_READWRITE Erstellt worden sein.
Wenn ein Prozess in eine Seite zum Kopieren beim Schreiben schreibt, kopiert das System die ursprüngliche Seite auf eine neue Seite, die für den Prozess privat ist. Die neue Seite wird von der Auslagerungsdatei unterstützt. Der Schutz der neuen Seite ändert sich von Copy-On-Write in Lese-/Schreibzugriff. Wenn der Kopierzugriff angegeben wird, wird der System- und Prozesscommit für die gesamte Ansicht berechnet, da der aufrufende Prozess potenziell auf jede Seite in der Ansicht schreiben kann, sodass alle Seiten privat sind. Der Inhalt der neuen Seite wird nie in die ursprüngliche Datei zurückgeschrieben und geht verloren, wenn die Ansicht nicht zugeordnet ist. |
|
Eine ausführbare Ansicht der Datei wird zugeordnet (zugeordneter Arbeitsspeicher kann als Code ausgeführt werden). Das Dateizuordnungsobjekt muss mit PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPY oder PAGE_EXECUTE_READWRITE-Schutz erstellt worden sein.
Windows Server 2003 und Windows XP: Dieser Wert ist ab Windows XP mit SP2 und Windows Server 2003 mit SP1 verfügbar. |
|
Ab Windows 10 Version 1703 gibt dieses Flag an, dass die Ansicht mithilfe von Unterstützung für große Seiten zugeordnet werden soll. Die Größe der Ansicht muss ein Vielfaches der Größe einer großen Seite sein, die von der GetLargePageMinimum-Funktion gemeldet wird, und das Dateizuordnungsobjekt muss mit der Option SEC_LARGE_PAGES erstellt worden sein. Wenn Sie einen Wert ungleich NULL für lpBaseAddress angeben, muss der Wert ein Vielfaches von GetLargePageMinimum sein. Hinweis: Bei Betriebssystemversionen vor Windows 10 Version 1703 hat das flag FILE_MAP_LARGE_PAGES keine Auswirkungen. Bei diesen Releases wird die Ansicht automatisch mithilfe großer Seiten zugeordnet, wenn der Abschnitt mit dem SEC_LARGE_PAGES-Flag erstellt wurde. |
|
Legt alle Speicherorte in der zugeordneten Datei als ungültige Ziele für Control Flow Guard (CFG) fest. Dieses Flag ähnelt PAGE_TARGETS_INVALID. Verwenden Sie dieses Flag in Kombination mit dem FILE_MAP_EXECUTE Ausführungsrecht. Jeder indirekte Aufruf von Speicherorten auf diesen Seiten schlägt CFG-Überprüfungen fehl, und der Prozess wird beendet. Das Standardverhalten für ausführbare Seiten, die zugeordnet sind, besteht darin, als gültige Aufrufziele für CFG gekennzeichnet zu werden. |
Bei Dateizuordnungsobjekten, die mit dem attribut SEC_IMAGE erstellt wurden, hat der dwDesiredAccess-Parameter keine Auswirkung und sollte auf einen gültigen Wert wie FILE_MAP_READ festgelegt werden.
Weitere Informationen zum Zugriff auf Dateizuordnungsobjekte finden Sie unter Dateizuordnungssicherheit und -zugriffsrechte.
[in] dwFileOffsetHigh
Ein DWORD mit hoher Reihenfolge des Dateioffsets, an dem die Ansicht beginnt.
[in] dwFileOffsetLow
Ein DWORD mit niedriger Reihenfolge des Dateioffsets, an dem die Ansicht beginnen soll. Die Kombination der hohen und niedrigen Offsets muss einen Offset innerhalb der Dateizuordnung angeben. Sie müssen auch mit der Granularität der Speicherbelegung des Systems übereinstimmen. Das heißt, der Offset muss ein Vielfaches der Zuordnungsgranularität sein. Um die Granularität der Speicherbelegung des Systems zu erhalten, verwenden Sie die GetSystemInfo-Funktion , die die Member einer SYSTEM_INFO-Struktur ausfüllt.
[in] dwNumberOfBytesToMap
Die Anzahl der Bytes einer Dateizuordnung, die der Ansicht zugeordnet werden soll. Alle Bytes müssen innerhalb der von CreateFileMapping angegebenen maximalen Größe sein. Wenn dieser Parameter 0 (null) ist, erstreckt sich die Zuordnung vom angegebenen Offset bis zum Ende der Dateizuordnung.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Startadresse der zugeordneten Ansicht.
Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
Durch die Zuordnung einer Datei wird der angegebene Teil einer Datei im Adressraum des aufrufenden Prozesses sichtbar.
Bei Dateien, die größer als der Adressraum sind, können Sie nur einen kleinen Teil der Dateidaten gleichzeitig zuordnen. Wenn die erste Ansicht abgeschlossen ist, können Sie die Zuordnung aufheben und eine neue Ansicht zuordnen.
Verwenden Sie die VirtualQuery-Funktion , um die Größe einer Ansicht abzurufen.
Mehrere Ansichten einer Datei (oder eines Dateizuordnungsobjekts und der zugeordneten Datei) sind kohärent , wenn sie zu einem bestimmten Zeitpunkt identische Daten enthalten. Dies tritt auf, wenn die Dateiansichten von einem Dateizuordnungsobjekt abgeleitet werden, das von derselben Datei unterstützt wird. Ein Prozess kann ein Dateizuordnungsobjekthandle mithilfe der DuplicateHandle-Funktion in einen anderen Prozess duplizieren, oder ein anderer Prozess kann ein Dateizuordnungsobjekt anhand des Namens mithilfe der OpenFileMapping-Funktion öffnen.
Mit einer wichtigen Ausnahme sind Dateiansichten, die von einem Dateizuordnungsobjekt abgeleitet werden, das von derselben Datei unterstützt wird, kohärent oder zu einem bestimmten Zeitpunkt identisch. Die Kohärenz wird für Ansichten innerhalb eines Prozesses und für Sichten garantiert, die von verschiedenen Prozessen zugeordnet werden.
Die Ausnahme bezieht sich auf Remotedateien. MapViewOfFile funktioniert zwar mit Remotedateien, hält sie jedoch nicht kohärent. Wenn z. B. zwei Computer eine Datei als schreibbar zuordnen und beide dieselbe Seite ändern, sieht jeder Computer nur seine eigenen Schreibvorgänge auf der Seite. Wenn die Daten auf dem Datenträger aktualisiert werden, werden sie nicht zusammengeführt.
Eine zugeordnete Ansicht einer Datei ist nicht garantiert kohärent mit einer Datei, auf die über die ReadFile - oder WriteFile-Funktion zugegriffen wird.
Speichern Sie keine Zeiger in der zugeordneten Speicherdatei. speichern Sie Offsets aus der Basis der Dateizuordnung, damit die Zuordnung an einer beliebigen Adresse verwendet werden kann.
Um sich vor EXCEPTION_IN_PAGE_ERROR Ausnahmen zu schützen, verwenden Sie die strukturierte Ausnahmebehandlung, um code zu schützen, der in eine Speicherzuordnungsansicht einer anderen Datei als der Auslagerungsdatei schreibt oder aus dieser liest. Weitere Informationen finden Sie unter Lesen und Schreiben aus einer Dateiansicht.
Wenn Sie eine Datei über eine zugeordnete Ansicht ändern, wird der Zeitstempel der letzten Änderung möglicherweise nicht automatisch aktualisiert. Bei Bedarf sollte der Aufrufer SetFileTime verwenden, um den Zeitstempel festzulegen.
Wenn ein Dateizuordnungsobjekt von der Auslagerungsdatei unterstützt wird (CreateFileMapping wird aufgerufen, wobei der hFile-Parameter auf INVALID_HANDLE_VALUE festgelegt ist), muss die Auslagerungsdatei groß genug sein, um die gesamte Zuordnung zu enthalten. Ist dies nicht der Fehler, schlägt MapViewOfFile fehl. Der anfängliche Inhalt der Seiten in einem Dateizuordnungsobjekt, das von der Auslagerungsdatei unterstützt wird, ist 0 (null).
Wenn ein Dateizuordnungsobjekt erstellt wird, das von der Auslagerungsdatei unterstützt wird, kann der Aufrufer angeben, ob MapViewOfFile Seiten gleichzeitig reservieren und committen soll (SEC_COMMIT) oder einfach Seiten reservieren (SEC_RESERVE). Durch die Zuordnung der Datei ist der gesamte zugeordnete virtuelle Adressbereich für andere Zuordnungen im Prozess nicht verfügbar. Nachdem ein Commit für eine Seite aus dem reservierten Bereich erfolgt ist, kann sie nicht durch Aufrufen von VirtualFree freigegeben oder decommittediert werden. Reservierte und committete Seiten werden freigegeben, wenn die Ansicht nicht zugeordnet und das Dateizuordnungsobjekt geschlossen wird. Weitere Informationen finden Sie unter den Funktionen UnmapViewOfFile und CloseHandle .
Um über eine Datei mit ausführbaren Berechtigungen zu verfügen, muss eine Anwendung CreateFileMapping entweder mit PAGE_EXECUTE_READWRITE oder PAGE_EXECUTE_READ aufrufen und dann MapViewOfFile mit FILE_MAP_EXECUTE | FILE_MAP_WRITE oder FILE_MAP_EXECUTE | FILE_MAP_READ aufrufen.
In Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| SMB 3.0-Protokoll (Server Message Block) | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | Ja |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Wenn CsvFs angehalten wird, schlägt dieser Aufruf möglicherweise mit einem Fehler fehl, der darauf hinweist, dass ein Sperrkonflikt vorliegt.
Beispiele
Ein Beispiel finden Sie unter Erstellen von benanntem freigegebenem Arbeitsspeicher.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | memoryapi.h (einschließlich Windows.h, Memoryapi.h) |
| Bibliothek | onecore.lib |
| DLL | Kernel32.dll |