MapViewOfFileExNuma-Funktion (winbase.h)
Ordnet dem Adressraum eines aufrufenden Prozesses eine Ansicht einer Dateizuordnung 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 für ein Dateizuordnungsobjekt. Die Funktionen CreateFileMappingNuma 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. |
|
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. |
|
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 beliebigen gültigen Wert wie FILE_MAP_READ festgelegt werden.
Weitere Informationen zum Zugriff auf Dateizuordnungsobjekte finden Sie unter Dateizuordnungssicherheit und -zugriffsrechte.
[in] dwFileOffsetHigh
Die hohe DWORD-Reihenfolge des Dateioffsets, an dem die Ansicht beginnen soll.
[in] dwFileOffsetLow
Der DWORD-Wert in 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 einer 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.
[in, optional] lpBaseAddress
Ein Zeiger auf die Speicheradresse im Adressraum des aufrufenden Prozesses, an dem die Zuordnung beginnt. Dies muss ein Vielfaches der Arbeitsspeicherzuordnungsgranularität des Systems sein, andernfalls schlägt die Funktion fehl. Verwenden Sie die GetSystemInfo-Funktion , um die Granularität der Speicherbelegung des Systems zu bestimmen. Wenn an der angegebenen Adresse nicht genügend Adressraum vorhanden ist, schlägt die Funktion fehl.
Wenn der lpBaseAddress-ParameterNULL ist, 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 aus 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 Arbeitsspeicher 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 bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie die GetLastError-Funktion auf.
Hinweise
Durch das Zuordnen einer Datei wird der angegebene Teil der Datei im Adressraum des aufrufenden Prozesses sichtbar.
Für 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.
Verwenden Sie die VirtualQueryEx-Funktion , um die Größe einer Ansicht abzurufen.
Der anfängliche Inhalt der Seiten in einem Dateizuordnungsobjekt, das von der Auslagerungsdatei unterstützt wird, ist 0 (null).
Wenn eine vorgeschlagene Zuordnungsadresse angegeben wird, wird die Datei an der angegebenen Adresse zugeordnet (gerundet auf die nächste 64-KB-Grenze), wenn an der angegebenen Adresse genügend Adressraum 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 in mehreren Prozessen an derselben Adresse zugeordnet werden soll. Dies erfordert, dass die Region des Adressraums in allen beteiligten Prozessen verfügbar ist. In der Region, die für die Zuordnung verwendet wird, kann keine andere Speicherbelegung erfolgen, einschließlich der Verwendung der VirtualAllocExNuma-Funktion zum Reservieren von Arbeitsspeicher.
Wenn der lpBaseAddress-Parameter einen Basisoffset angibt, ist die Funktion erfolgreich, wenn der angegebene Speicherbereich noch nicht 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) sind kohärent , wenn sie zu einem bestimmten Zeitpunkt identische Daten enthalten. Dies tritt auf, wenn die Dateiansichten vom gleichen Dateizuordnungsobjekt abgeleitet werden. 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. MapViewOfFileExNuma 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, dass sie mit einer Datei kohärent ist, auf die über die ReadFile- oder WriteFile-Funktion zugegriffen wird.
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 Seitendatei schreibt oder aus dieser 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.
Um über eine Datei mit ausführbaren Berechtigungen zu verfügen, 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_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 |
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winbase.h (einschließlich Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für