CreateFileMappingNumaA-Funktion (winbase.h)
Erstellt oder öffnet ein benanntes oder unbenannte Dateizuordnungsobjekt für eine angegebene Datei und gibt den NUMA-Knoten für den physischen Arbeitsspeicher an.
Syntax
HANDLE CreateFileMappingNumaA(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCSTR lpName,
[in] DWORD nndPreferred
);
Parameter
[in] hFile
Ein Handle für die Datei, aus der ein Dateizuordnungsobjekt erstellt werden soll.
Die Datei muss mit Zugriffsrechten geöffnet werden, die mit den Schutzflags kompatibel sind, die der flProtect-Parameter angibt. Es ist nicht erforderlich, aber es wird empfohlen, Dateien, die Sie zuordnen möchten, für den exklusiven Zugriff geöffnet zu werden. Weitere Informationen finden Sie unter Dateisicherheit und Zugriffsrechte.
Wenn hFileINVALID_HANDLE_VALUE ist, muss der aufrufende Prozess auch eine Größe für das Dateizuordnungsobjekt in den Parametern dwMaximumSizeHigh und dwMaximumSizeLow angeben. In diesem Szenario erstellt CreateFileMappingNuma ein Dateizuordnungsobjekt mit einer angegebenen Größe, das durch die System pagingdatei und nicht durch eine Datei im Dateisystem unterstützt wird.
[in, optional] lpFileMappingAttributes
Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur , die bestimmt, ob ein zurückgegebenes Handle von untergeordneten Prozessen geerbt werden kann. Das lpSecurityDescriptor-Element des
SECURITY_ATTRIBUTES-Struktur gibt einen Sicherheitsdeskriptor für ein neues Dateizuordnungsobjekt an.
Wenn lpFileMappingAttributesNULL ist, kann das Handle nicht geerbt werden, und das Dateizuordnungsobjekt erhält eine Standardsicherheitsbeschreibung. Die Zugriffssteuerungslisten (Access Control Lists, ACL) im Standardsicherheitsdeskriptor für ein Dateizuordnungsobjekt stammen aus dem primären Token oder identitätswechsel des Erstellers. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für die Dateizuordnung.
[in] flProtect
Gibt den Seitenschutz des Dateizuordnungsobjekts an. Alle zugeordneten Ansichten des Objekts müssen mit diesem Schutz kompatibel sein.
Dieser Parameter kann einen der folgenden Werte annehmen.
Eine Anwendung kann mindestens eins der folgenden Attribute für das Dateizuordnungsobjekt angeben, indem sie sie mit einem der vorherigen Seitenschutzwerte kombiniert.
| Wert | Bedeutung |
|---|---|
|
Ordnet physischen Speicher im Arbeitsspeicher oder der Auslagerungsdatei für alle Seiten zu.
Dies ist die Standardeinstellung. |
|
Legt die Datei fest, die als ausführbare Imagedatei angegeben wird.
Das attribut SEC_IMAGE muss mit einem Seitenschutzwert wie PAGE_READONLY kombiniert werden. Dieser Seitenschutzwert hat jedoch keine Auswirkungen auf die Ansichten der ausführbaren Imagedatei. Der Seitenschutz für Ansichten einer ausführbaren Imagedatei wird durch die ausführbare Datei selbst bestimmt. Mit SEC_IMAGE sind keine anderen Attribute gültig. |
|
Gibt an, dass die Datei, die der hFile-Parameter angibt, eine ausführbare Imagedatei ist, die nicht ausgeführt wird und die geladene Imagedatei keine erzwungenen Integritätsprüfungen ausgeführt wird.
Darüber hinaus ruft das Zuordnen einer Ansicht eines Dateizuordnungsobjekts, das mit dem attribut SEC_IMAGE_NO_EXECUTE erstellt wurde, keine Treiberrückrufe auf, die mit der Kernel-API PsSetLoadImageNotifyRoutine registriert wurden.
Das attribut SEC_IMAGE_NO_EXECUTE muss mit dem PAGE_READONLY seitenschutzwert kombiniert werden. Mit SEC_IMAGE_NO_EXECUTE sind keine anderen Attribute gültig. Windows Server 2008 R2, Windows 7, Windows Server 2008 und Windows Vista: Dieser Wert wird vor Windows Server 2012 und Windows 8 nicht unterstützt. |
|
Ermöglicht die Verwendung großer Seiten beim Zuordnen von Bildern oder beim Sichern aus der Seitendatei, nicht aber beim Zuordnen von Daten für reguläre Dateien. Achten Sie darauf, die maximale Größe des Dateizuordnungsobjekts als mindestgröße einer großen Seite anzugeben, die von der GetLargePageMinimum-Funktion gemeldet wird, und das SeLockMemoryPrivilege-Recht zu aktivieren. |
|
Legt alle Seiten auf nicht erreichbar fest.
Anwendungen sollten dieses Flag nur verwenden, wenn sie für ein Gerät explizit erforderlich sind. Die Verwendung der verriegelten Funktionen mit speicherzuordnungen SEC_NOCACHE kann zu einer EXCEPTION_ILLEGAL_INSTRUCTION Ausnahme führen. SEC_NOCACHE muss entweder SEC_RESERVE oder SEC_COMMIT festgelegt werden. |
|
Reserviert alle Seiten, ohne physischen Speicher zuzuweisen.
Der reservierte Seitenbereich kann erst von anderen Zuordnungsvorgängen verwendet werden, bis der Seitenbereich freigegeben wird. Reservierte Seiten können in nachfolgenden Aufrufen der Funktion VirtualAllocExNuma identifiziert werden. Dieses Attribut ist nur gültig, wenn der hFile-ParameterINVALID_HANDLE_VALUE ist (d. h. ein Dateizuordnungsobjekt, das von der System pagingdatei unterstützt wird). |
|
Legt fest, dass alle Seiten kombiniert werden sollen.
Anwendungen sollten dieses Attribut nur verwenden, wenn sie für ein Gerät explizit erforderlich sind. Die Verwendung der verriegelten Funktionen mit Speicher, der SEC_WRITECOMBINE zugeordnet ist, kann zu einer EXCEPTION_ILLEGAL_INSTRUCTION Ausnahme führen. SEC_WRITECOMBINE muss entweder das SEC_RESERVE - oder SEC_COMMIT-Attribut festgelegt werden. |
[in] dwMaximumSizeHigh
Die hohe DWORD-Reihenfolge der maximalen Größe des Dateizuordnungsobjekts.
[in] dwMaximumSizeLow
Das DWORD mit niedriger Reihenfolge der maximalen Größe des Dateizuordnungsobjekts.
Wenn dieser Parameter und der dwMaximumSizeHigh-Parameter 0 (null) sind, entspricht die maximale Größe des Dateizuordnungsobjekts der aktuellen Größe der Datei, die vom hFile-Parameter identifiziert wird.
Ein Versuch, eine Datei mit der Länge 0 (null) zuzuordnen, schlägt mit dem Fehlercode ERROR_FILE_INVALID fehl. Anwendungen sollten auf Dateien mit einer Länge von 0 (null) testen und diese Dateien ablehnen.
[in, optional] lpName
Der Name des Dateizuordnungsobjekts.
Wenn dieser Parameter mit dem Namen eines vorhandenen Dateizuordnungsobjekts übereinstimmt, fordert die Funktion den Zugriff auf das Objekt mit dem Schutz an, den der flProtect-Parameter angibt.
Wenn dieser Parameter NULL ist, wird das Dateizuordnungsobjekt ohne Namen erstellt.
Wenn der lpName-Parameter mit dem Namen eines vorhandenen Ereignisses, Semaphore, Mutex, wartebaren Timers oder Auftragsobjekts übereinstimmt, schlägt die Funktion fehl, und die GetLastError-Funktion gibt ERROR_INVALID_HANDLE zurück. Dies tritt auf, weil diese Objekte denselben Namespace verwenden.
Der Name kann ein Präfix "Global" oder "Local" aufweisen, um das Objekt explizit im globalen Oder Sitzungsnamespace zu erstellen. Der Rest des Namens kann ein beliebiges Zeichen mit Ausnahme des umgekehrten Schrägstrichs (\) enthalten. Das Erstellen eines Dateizuordnungsobjekts im globalen Namespace erfordert das SeCreateGlobalPrivilege-Recht . Weitere Informationen finden Sie unter Kernelobjektnamespaces.
Der schnelle Benutzerwechsel wird mithilfe von Terminaldienstesitzungen implementiert. Der erste Benutzer, der sich anmeldet, verwendet Sitzung 0 (Null), der nächste Benutzer zum Anmelden verwendet Sitzung 1 (1) usw. Kernelobjektnamen müssen den Richtlinien entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.
[in] nndPreferred
Der NUMA-Knoten, auf dem sich der physische Arbeitsspeicher befinden soll.
| Wert | Bedeutung |
|---|---|
|
Es wird kein NUMA-Knoten bevorzugt. Dies ist identisch mit dem Aufrufen der CreateFileMapping-Funktion . |
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Dateizuordnungsobjekt.
Wenn das Objekt vor dem Funktionsaufruf vorhanden ist, gibt die Funktion ein Handle an das vorhandene Objekt (mit seiner aktuellen Größe, nicht der angegebenen Größe) zurück, und die GetLastError-Funktion gibt ERROR_ALREADY_EXISTS zurück.
Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie die GetLastError-Funktion auf.
Hinweise
Nachdem ein Dateizuordnungsobjekt erstellt wurde, darf die Größe der Datei die Größe des Dateizuordnungsobjekts nicht überschreiten. wenn dies der Fall ist, stehen nicht alle Dateiinhalte für die Freigabe zur Verfügung.
Das Dateizuordnungsobjekt kann durch Duplizierung, Vererbung oder nach Name freigegeben werden. Der anfängliche Inhalt der Seiten in einem Dateizuordnungsobjekt, das von der Seitendatei unterstützt wird, ist 0 (null).
Wenn eine Anwendung eine Größe für das Dateizuordnungsobjekt angibt, die größer ist als die Größe der tatsächlich benannten Datei auf dem Datenträger und wenn der Seitenschutz Schreibzugriff zulässt (d. h. der flProtect-Parameter gibt PAGE_READWRITE oder PAGE_EXECUTE_READWRITE an), wird die Datei auf dem Datenträger erhöht, um der angegebenen Größe des Dateizuordnungsobjekts zu entsprechen. Wenn die Datei erweitert wird, ist der Inhalt der Datei zwischen dem alten Ende der Datei und dem neuen Ende der Datei nicht garantiert null; das Verhalten wird vom Dateisystem definiert.
Wenn die Datei nicht erhöht werden kann, ist das Ergebnis ein Fehler beim Erstellen des Dateizuordnungsobjekts, und die GetLastError-Funktion gibt ERROR_DISK_FULL zurück.
Das Handle, das die CreateFileMappingNuma-Funktion zurückgibt, hat Vollzugriff auf ein neues Dateizuordnungsobjekt und kann mit jeder Funktion verwendet werden, die ein Handle für ein Dateizuordnungsobjekt erfordert. Ein Dateizuordnungsobjekt kann durch Prozesserstellung, Behandeln von Duplizierungen oder nach Name freigegeben werden. Weitere Informationen finden Sie in den Funktionen DuplicateHandle und OpenFileMapping .
Durch das Erstellen eines Dateizuordnungsobjekts wird das Potenzial für die Zuordnung einer Ansicht der Datei geschaffen, die Ansicht wird jedoch nicht zugeordnet. Die MapViewOfFileExNuma-Funktion ordnet eine Ansicht einer Datei einem Prozessadressraum zu.
Mit einer wichtigen Ausnahme sind Dateisichten, die von einem einzelnen Dateizuordnungsobjekt abgeleitet werden, kohärent oder zu einem bestimmten Zeitpunkt identisch. Wenn mehrere Prozesse über Handles desselben Dateizuordnungsobjekts verfügen, wird eine kohärente Ansicht der Daten angezeigt, wenn sie eine Ansicht der Datei zuordnen.
Die Ausnahme bezieht sich auf Remotedateien. Obwohl die CreateFileMappingNuma-Funktion mit Remotedateien funktioniert, bleibt sie nicht kohärent. Wenn beispielsweise zwei Computer eine Datei als beschreibbar zuordnen und beide dieselbe Seite ändern, sieht jeder Computer nur eigene Schreibvorgänge auf die Seite. Wenn die Daten auf dem Datenträger aktualisiert werden, wird die Seite nicht zusammengeführt.
Eine zugeordnete Datei und eine Datei, auf die mithilfe der Eingabe- und Ausgabefunktionen (E/A) (ReadFile und WriteFile) zugegriffen wird, sind nicht unbedingt kohärent.
Um ein Dateizuordnungsobjekt vollständig zu schließen, muss eine Anwendung die Zuordnung aller zugeordneten Ansichten des Dateizuordnungsobjekts aufheben, indem sie die Funktion UnmapViewOfFile aufruft und dann das Objekthandle des Dateizuordnungsobjekts durch Aufrufen der CloseHandle-Funktion schließen.
Diese Funktionen können in beliebiger Reihenfolge aufgerufen werden. Der Aufruf der UnmapViewOfFile-Funktion ist erforderlich, da zugeordnete Ansichten eines Dateizuordnungsobjekts interne geöffnete Handles für das Objekt beibehalten und ein Dateizuordnungsobjekt erst geschlossen wird, wenn alle geöffneten Handles für das Objekt geschlossen sind.
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.
Das Erstellen eines Dateizuordnungsobjekts aus einer anderen Sitzung als Session Zero erfordert das SeCreateGlobalPrivilege-Recht . Beachten Sie, dass diese Berechtigungsprüfung auf die Erstellung von Dateizuordnungsobjekten beschränkt ist und nicht auf das Öffnen vorhandener Objekte angewendet wird. Wenn beispielsweise ein Dienst oder das System ein Dateizuordnungsobjekt erstellt, kann jeder Prozess, der in einer Beliebigen Sitzung ausgeführt wird, auf dieses Dateizuordnungsobjekt zugreifen, sofern der Aufrufer über die erforderlichen Zugriffsrechte verfügt.
Verwenden Sie die strukturierte Ausnahmebehandlung, um code zu schützen, der in eine speicherzuordnungen Ansicht schreibt oder aus dieser liest. Weitere Informationen finden Sie unter Lesen und Schreiben aus einer Dateiansicht.
Um über eine Zuordnung 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_READaufrufen.
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
| 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, Memoryapi.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |