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 Speicher 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 Schutzkennzeichnungen kompatibel sind, die der parameter flProtect angibt. Es ist nicht erforderlich, aber es wird empfohlen, dass Dateien, die Sie zuordnen möchten, für exklusiven Zugriff geöffnet werden sollen. Weitere Informationen finden Sie unter Dateisicherheits- und Zugriffsberechtigungen.

Wenn hFile-INVALID_HANDLE_VALUEist, muss der aufrufende Prozess auch eine Größe für das Dateizuordnungsobjekt im dwMaximumSizeHigh und dwMaximumSizeLow Parameter angeben. In diesem Szenario erstellt CreateFileMappingNuma ein Dateizuordnungsobjekt mit einer angegebenen Größe, die von der System-Auslagerungsdatei anstelle einer 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 Mitglied 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 einen Standardsicherheitsdeskriptor. Die Zugriffssteuerungslisten (Access Control Lists, ACL) im Standardsicherheitsdeskriptor für ein Dateizuordnungsobjekt stammen aus dem primären oder Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Dateizuordnungssicherheit und Zugriffsberechtigungen.

[in] flProtect

Gibt den Seitenschutz des Dateizuordnungsobjekts an. Alle zugeordneten Ansichten des Objekts müssen mit diesem Schutz kompatibel sein.

Dieser Parameter kann einer der folgenden Werte sein:

Eine Anwendung kann ein oder mehrere der folgenden Attribute für das Dateizuordnungsobjekt angeben, indem sie mit einem der vorherigen Seitenschutzwerte kombiniert werden.

[in] dwMaximumSizeHigh

Die hohe Reihenfolge DWORD- der maximalen Größe des Dateizuordnungsobjekts.

[in] dwMaximumSizeLow

Die niedrige Reihenfolge DWORD- 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 der hFile Parameter identifiziert.

Ein Versuch, eine Datei mit einer Länge von 0 (Null) zuzuordnen, schlägt mit einem Fehlercode von ERROR_FILE_INVALIDfehl. 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 parameter lpName mit dem Namen eines vorhandenen Ereignisses, Semaphor, Mutex, Wartezeitgeber oder Auftragsobjekt übereinstimmt, schlägt die Funktion fehl, und die GetLastError--Funktion gibt ERROR_INVALID_HANDLEzurück. Dies geschieht, da diese Objekte denselben Namespace gemeinsam nutzen.

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. Zum Erstellen eines Dateizuordnungsobjekts im globalen Namespace ist das SeCreateGlobalPrivilege Berechtigungen erforderlich. Weitere Informationen finden Sie unter Kernel Object Namespaces.

Schnelle Benutzerumschaltung wird mithilfe von Terminaldienstesitzungen implementiert. Der erste Benutzer, der sich anmeldet, verwendet Sitzung 0 (Null), der nächste Benutzer zum Anmelden Sitzung 1 (eins) 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 Speicher befinden soll.

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 zurück (mit seiner aktuellen Größe, nicht der angegebenen Größe), und die GetLastError-Funktion gibt ERROR_ALREADY_EXISTSzurück.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie zum Abrufen erweiterter Fehlerinformationen die GetLastError--Funktion auf.

Bemerkungen

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, das größer als die Größe der tatsächlich benannten Datei auf dem Datenträger ist und wenn der Seitenschutz Schreibzugriff zulässt (d. h. der parameter flProtect 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_FULLzurü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 über die Prozesserstellung, das Behandeln von Duplizierungen oder den Namen freigegeben werden. Weitere Informationen finden Sie in den funktionen DuplicateHandle und OpenFileMapping.

Durch das Erstellen eines Dateizuordnungsobjekts wird das Potenzial zum Zuordnen einer Ansicht der Datei erstellt, die Ansicht wird jedoch nicht zugeordnet. Die MapViewOfFileExNuma--Funktion ordnet eine Ansicht einer Datei in einem Prozessadressraum zu.

Mit einer wichtigen Ausnahme sind Dateiansichten, die von einem einzelnen Dateizuordnungsobjekt abgeleitet wurden, zu einem bestimmten Zeitpunkt kohärent oder identisch. Wenn mehrere Prozesse über Handles desselben Dateizuordnungsobjekts verfügen, sehen sie eine kohärente Ansicht der Daten, wenn sie eine Ansicht der Datei zuordnen.

Die Ausnahme bezieht sich auf Remotedateien. Obwohl die CreateFileMappingNuma Funktion mit Remotedateien funktioniert, bleiben sie nicht kohärent. Wenn beispielsweise zwei Computer eine Datei als schreibbar zuordnen und beide dieselbe Seite ändern, sieht jeder Computer nur eigene Schreibvorgänge auf der 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) zugegriffen wird (ReadFile- und WriteFile-) sind nicht notwendigerweise kohärent.

Um ein Dateizuordnungsobjekt vollständig zu schließen, muss eine Anwendung die Zuordnung aller zugeordneten Ansichten des Dateizuordnungsobjekts aufheben, indem die UnmapViewOfFile--Funktion aufgerufen und dann das Dateizuordnungsobjekthandle durch Aufrufen der CloseHandle--Funktion geschlossen wird.

Diese Funktionen können in beliebiger Reihenfolge aufgerufen werden. Der Aufruf der UnmapViewOfFile--Funktion ist erforderlich, da zugeordnete Ansichten eines Dateizuordnungsobjekts interne offene Handles für das Objekt verwalten und ein Dateizuordnungsobjekt erst geschlossen wird, wenn alle geöffneten Handles geschlossen werden.

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 Sitzung Null erfordert das SeCreateGlobalPrivilege Berechtigung. Beachten Sie, dass diese Berechtigungsprüfung auf die Erstellung von Dateizuordnungsobjekten beschränkt ist und nicht für das Öffnen vorhandener Objekte gilt. Wenn beispielsweise ein Dienst oder das System ein Dateizuordnungsobjekt erstellt, kann jeder Prozess, der in jeder Sitzung ausgeführt wird, auf dieses Dateizuordnungsobjekt zugreifen, vorausgesetzt, der Aufrufer verfügt über die erforderlichen Zugriffsrechte.

Verwenden Sie die strukturierte Ausnahmebehandlung, um Code zu schützen, der in eine zugeordnete Speicheransicht schreibt oder liest. Weitere Informationen finden Sie unter Lesen und Schreiben aus einer Dateiansicht.

Um über eine Zuordnung mit ausführbaren Berechtigungen verfügen zu können, muss eine Anwendung die CreateFileMappingNuma--Funktion 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.

Anforderungen

Siehe auch

CloseHandle-

CreateFileMapping-

DuplicateHandle-

Dateizuordnungsfunktionen

MapViewOfFileExNuma

NUMA Support-

OpenFileMapping-

ReadFile-

SECURITY_ATTRIBUTES

UnmapViewOfFile-

VirtualAllocExNuma

WriteFile-