MapViewOfFileExNuma-Funktion (winbase.h)
Ordnet eine Ansicht einer Dateizuordnung dem Adressraum eines aufruften Prozesses zu und gibt den NUMA-Knoten für den physischen Speicher an.
Syntax
LPVOID MapViewOfFileExNuma(
[in] HANDLE hFileMappingObject,
[in] DWORD dwDesiredAccess,
[in] DWORD dwFileOffsetHigh,
[in] DWORD dwFileOffsetLow,
[in] SIZE_T dwNumberOfBytesToMap,
[in, optional] LPVOID lpBaseAddress,
[in] DWORD nndPreferred
);
Parameter
[in] hFileMappingObject
Ein Handle zu einem Dateizuordnungsobjekt. Die CreateFileMappingNuma- und OpenFileMapping- Funktionen geben diesen Handle zurück.
[in] dwDesiredAccess
Der Typ des Zugriffs auf ein Dateizuordnungsobjekt, das den Seitenschutz der Seiten bestimmt. Bei diesem Parameter kann es sich um einen der folgenden Werte oder um eine bitweise ODER Kombination aus mehreren Werten handeln.
| Wert | Bedeutung |
|---|---|
|
Eine Kopier-on-Write-Ansicht der Datei wird zugeordnet. Das Dateizuordnungsobjekt muss mit PAGE_READONLY, PAGE_EXECUTE_READ, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITEoder PAGE_EXECUTE_READWRITE Schutz erstellt worden sein.
Wenn ein Prozess auf eine Kopie-on-Write-Seite 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 "Kopieren beim Schreiben" in "Lese-/Schreibzugriff". Wenn der Schreibzugriff auf Kopieren angegeben ist, wird das System und der Prozess für die gesamte Ansicht übernommen, da der Aufrufvorgang potenziell auf jede Seite in der Ansicht schreiben kann, wodurch alle Seiten privat sind. Der Inhalt der neuen Seite wird nie wieder in die Originaldatei geschrieben und geht verloren, wenn die Ansicht nicht zugeordnet ist. |
|
Eine ausführbare Ansicht der Datei ist zugeordnet (zugeordneter Speicher kann als Code ausgeführt werden). Das Dateizuordnungsobjekt muss mit PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPYoder PAGE_EXECUTE_READWRITE Schutz erstellt worden sein. |
|
Ab Windows 10, Version 1703, gibt dieses Flag an, dass die Ansicht mithilfe Unterstützung für große Seitenzugeordnet werden soll. Die Größe der Ansicht muss ein Vielfaches der Größe einer großen Seite sein, die vom GetLargePageMinimum-Funktion gemeldet wird, und das Dateizuordnungsobjekt muss mithilfe der Option SEC_LARGE_PAGES erstellt worden sein. Wenn Sie einen Wert ungleich NULL für lpBaseAddressangeben, muss der Wert ein Vielfaches von GetLargePageMinimumsein. |
|
Legt alle Speicherorte in der zugeordneten Datei als ungültige Ziele für Control Flow Guard (CFG) fest. Diese Kennzeichnung ähnelt PAGE_TARGETS_INVALID. Verwenden Sie dieses Kennzeichen in Kombination mit der Ausführungsberechtigung FILE_MAP_EXECUTE. Alle indirekten Aufrufe an Speicherorte auf diesen Seiten schlagen CFG-Prüfungen fehl, und der Vorgang wird beendet. Das Standardverhalten für zugeordnete ausführbare Seiten besteht darin, gültige Anrufziele für CFG zu markieren. |
Für dateizuordnungsobjekte, die mit dem attribut SEC_IMAGE erstellt wurden, hat der dwDesiredAccess Parameter keine Auswirkung und sollte auf einen beliebigen gültigen Wert wie FILE_MAP_READfestgelegt werden.
Weitere Informationen zum Zugriff auf Dateizuordnungsobjekte finden Sie unter Dateizuordnungssicherheit und Zugriffsberechtigungen.
[in] dwFileOffsetHigh
Die hohe Reihenfolge DWORD- des Dateioffsets, in dem die Ansicht beginnen soll.
[in] dwFileOffsetLow
Die niedrige Reihenfolge DWORD- des Dateioffsets, in 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 Speicherzuweisung des Systems übereinstimmen. Das heißt, der Offset muss ein Vielfaches der Zuordnungs granularität sein. Um die Granularität der Speicherzuweisung 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 einer Ansicht zugeordnet werden soll. Alle Bytes müssen sich innerhalb der maximalen Größe befinden, die durch CreateFileMappingangegeben wird. Wenn dieser Parameter 0 (null) ist, erstreckt sich die Zuordnung vom angegebenen Offset bis zum Ende der Dateizuordnung.
[in, optional] lpBaseAddress
Ein Zeiger auf die Speicheradresse im Adressraum des aufrufenden Prozesses, in dem die Zuordnung beginnt. Dies muss ein Vielfaches der Speicherzuweisungs granularität des Systems sein, oder die Funktion schlägt fehl. Verwenden Sie die GetSystemInfo-Funktion, um die Granularität der Speicherzuweisung des Systems zu ermitteln. Wenn nicht genügend Adressraum an der angegebenen Adresse vorhanden ist, schlägt die Funktion fehl.
Wenn der parameter lpBaseAddressNULList, wählt das Betriebssystem die Zuordnungsadresse aus.
Obwohl es möglich ist, eine Adresse anzugeben, die jetzt sicher ist (nicht vom Betriebssystem verwendet), gibt es keine Garantie dafür, dass die Adresse im Laufe der Zeit sicher bleibt. Daher ist es besser, das Betriebssystem die Adresse auswählen zu lassen. In diesem Fall würden Sie keine Zeiger in der zugeordneten Speicherdatei speichern; Sie würden Offsets von der Basis der Dateizuordnung speichern, sodass die Zuordnung an einer beliebigen Adresse verwendet werden kann.
[in] nndPreferred
Der NUMA-Knoten, auf dem sich der physische Speicher befinden soll.
| Wert | Bedeutung |
|---|---|
|
Es wird kein NUMA-Knoten bevorzugt. Dies entspricht dem Aufrufen der MapViewOfFileEx--Funktion. |
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Startadresse der zugeordneten Ansicht.
Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie zum Abrufen erweiterter Fehlerinformationen die GetLastError--Funktion auf.
Bemerkungen
Durch die Zuordnung einer Datei wird der angegebene Teil der 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, heben Sie die Zuordnung auf, und ordnen Sie eine neue Ansicht zu.
Um die Größe einer Ansicht abzurufen, verwenden Sie die VirtualQueryEx--Funktion.
Der anfängliche Inhalt der Seiten in einem Dateizuordnungsobjekt, das von der Seitendatei unterstützt wird, ist 0 (null).
Wenn eine vorgeschlagene Zuordnungsadresse angegeben wird, wird die Datei an der angegebenen Adresse zugeordnet (auf die nächste Grenze von 64 KB gerundet), wenn genügend Adressraum an der angegebenen Adresse vorhanden ist. Wenn nicht genügend Adressraum vorhanden ist, schlägt die Funktion fehl.
In der Regel wird die vorgeschlagene Adresse verwendet, um anzugeben, dass eine Datei an derselben Adresse in mehreren Prozessen zugeordnet werden soll. Dazu muss die Region des Adressraums in allen beteiligten Prozessen verfügbar sein. In der Region, die für die Zuordnung verwendet wird, kann keine andere Speicherzuweisung erfolgen, einschließlich der Verwendung der VirtualAllocExNuma-Funktion zum Reservieren des Speichers.
Wenn der parameter lpBaseAddress einen Basisoffset angibt, wird die Funktion erfolgreich ausgeführt, wenn der angegebene Speicherbereich nicht bereits vom aufrufenden Prozess verwendet wird. Das System stellt nicht sicher, dass derselbe Speicherbereich für die zugeordnete Speicherdatei in anderen 32-Bit-Prozessen verfügbar ist.
Mehrere Ansichten einer Datei (oder eines Dateizuordnungsobjekts und der zugeordneten Datei) werden kohärente, wenn sie identische Daten zu einem bestimmten Zeitpunkt enthalten. Dies tritt auf, wenn die Dateiansichten vom gleichen Dateizuordnungsobjekt abgeleitet werden. Ein Prozess kann ein Dateizuordnungsobjekthandle in einen anderen Prozess duplizieren, indem die DuplicateHandle--Funktion verwendet wird, oder ein anderer Prozess kann ein Dateizuordnungsobjekt anhand des Namens mithilfe der OpenFileMapping--Funktion öffnen.
Mit einer wichtigen Ausnahme sind Dateiansichten, die von jedem Dateizuordnungsobjekt abgeleitet werden, das von derselben Datei unterstützt wird, kohärent oder identisch zu einem bestimmten Zeitpunkt. Die Kohärenz ist für Ansichten innerhalb eines Prozesses und für Ansichten gewährleistet, die von verschiedenen Prozessen zugeordnet werden.
Die Ausnahme bezieht sich auf Remotedateien. Obwohl MapViewOfFileExNuma mit Remotedateien funktioniert, bleiben sie nicht kohärent. Wenn beispielsweise zwei Computer eine Datei als schreibbar zuordnen und beide die gleiche Seite ändern, sieht jeder Computer nur eigene Schreibvorgänge auf der Seite. Wenn die Daten auf dem Datenträger aktualisiert werden, wird sie nicht zusammengeführt.
Eine zugeordnete Ansicht einer Datei ist nicht garantiert mit einer Datei, auf die von der ReadFile- oder WriteFile--Funktion zugegriffen wird, nicht kohärent.
Um vor EXCEPTION_IN_PAGE_ERROR Ausnahmen zu schützen, verwenden Sie die strukturierte Ausnahmebehandlung, um Code zu schützen, der in eine speicherzuordnunge Ansicht einer anderen Datei als der Seitendatei schreibt oder liest. Weitere Informationen finden Sie unter Lesen und Schreiben aus einer Dateiansicht.
Beim Ändern einer Datei über eine zugeordnete Ansicht wird der Zeitstempel der letzten Änderung möglicherweise nicht automatisch aktualisiert. Bei Bedarf sollte der Aufrufer SetFileTime- verwenden, um den Zeitstempel festzulegen.
Damit eine Datei mit ausführbaren Berechtigungen vorhanden ist, muss eine Anwendung die CreateFileMappingNuma--Funktion entweder mit PAGE_EXECUTE_READWRITE oder PAGE_EXECUTE_READ aufrufen und dann die MapViewOfFileExNuma- funktion mit FILE_MAP_EXECUTE | FILE_MAP_WRITE oder FILE_MAP_EXECUTE | FILE_MAP_READaufrufen.
In Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Abgestützt |
|---|---|
| Server Message Block (SMB) 3.0-Protokoll | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Skalierungsdateifreigaben (SO) | Ja |
| Freigegebenes Clustervolumedateisystem (CsvFS) | Ja |
| Resilient File System (ReFS) | Ja |
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows Vista [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | winbase.h (enthalten Windows.h) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |