CreateFileMapping2-Funktion (memoryapi.h)

Artikel
11/20/2024

Erstellt oder öffnet ein benanntes oder unbenannte Dateizuordnungsobjekt für eine angegebene Datei. Sie können einen bevorzugten NUMA-Knoten für den physischen Speicher als erweiterten Parameter angeben. siehe den parameter ExtendedParameters.

Syntax

HANDLE CreateFileMapping2(
  HANDLE                 File,
  SECURITY_ATTRIBUTES    *SecurityAttributes,
  ULONG                  DesiredAccess,
  ULONG                  PageProtection,
  ULONG                  AllocationAttributes,
  ULONG64                MaximumSize,
  PCWSTR                 Name,
  MEM_EXTENDED_PARAMETER *ExtendedParameters,
  ULONG                  ParameterCount
);

Parameter

File

Typ: _In_ HANDLE

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 Dateisicherheit 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 CreateFileMapping ein Dateizuordnungsobjekt mit einer angegebenen Größe, die von der System-Auslagerungsdatei unterstützt wird, anstatt von einer Datei im Dateisystem.

SecurityAttributes

Typ: _In_opt_ SECURITY_ATTRIBUTES*

Ein Zeiger auf eine SECURITY_ATTRIBUTES Struktur, die bestimmt, ob ein zurückgegebenes Handle von untergeordneten Prozessen geerbt werden kann. Der lpSecurityDescriptor Member der SECURITY_ATTRIBUTES-Struktur gibt einen Sicherheitsdeskriptor für ein neues Dateizuordnungsobjekt an.

Wenn lpAttributes-NULL-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.

DesiredAccess

Typ: _In_ ULONG-

Die gewünschte Zugriffsmaske für das zurückgegebene Dateizuordnungshandle. Eine Liste der Zugriffsrechte finden Sie unter Dateizuordnungssicherheit und Zugriffsberechtigungen.

PageProtection

Typ: _In_ ULONG-

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:

Wert	Bedeutung
PAGE_EXECUTE_READ 0x20	Ermöglicht das Zuordnen von Ansichten zum Schreibschutz, zum Kopieren oder Ausführen des Zugriffs. Das vom hFile- Parameter angegebene Dateihandle muss mit den GENERIC_READ und GENERIC_EXECUTE Zugriffsrechten erstellt werden. Windows Server 2003 und Windows XP: Dieser Wert ist erst verfügbar, wenn Windows XP mit SP2 und Windows Server 2003 mit SP1 verfügbar ist.
PAGE_EXECUTE_READWRITE 0x40	Ermöglicht das Zuordnen von Ansichten für schreibgeschützte, kopieren-on-Write-, Lese-/Schreibzugriff oder Ausführen des Zugriffs. Das Dateihandle, das der hFile Parameter angibt, muss mit dem GENERIC_READ, GENERIC_WRITEund GENERIC_EXECUTE Zugriffsrechten erstellt werden. Windows Server 2003 und Windows XP: Dieser Wert ist erst verfügbar, wenn Windows XP mit SP2 und Windows Server 2003 mit SP1 verfügbar ist.
PAGE_EXECUTE_WRITECOPY 0x80	Ermöglicht das Zuordnen von Ansichten zum Schreibschutz, zum Kopieren oder Ausführen des Zugriffs. Dieser Wert entspricht PAGE_EXECUTE_READ. Das Dateihandle, das der hFile Parameter angibt, muss mit den GENERIC_READ und GENERIC_EXECUTE Zugriffsrechten erstellt werden. Windows Vista: Dieser Wert ist erst verfügbar, wenn Windows Vista mit SP1 verfügbar ist. Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
PAGE_READONLY 0x02	Ermöglicht das Zuordnen von Ansichten für schreibgeschützten oder schreibgeschützten Zugriff. Ein Versuch, in eine bestimmte Region zu schreiben, führt zu einer Zugriffsverletzung. Das Dateihandle, das der hFile Parameter angibt, muss mit dem GENERIC_READ Zugriffsrecht erstellt werden.
PAGE_READWRITE 0x04	Ermöglicht das Zuordnen von Ansichten für schreibgeschützten, kopieren-on-Write- oder Lese-/Schreibzugriff. Das Dateihandle, das der hFile--Parameter angibt, muss mit den GENERIC_READ und GENERIC_WRITE Zugriffsrechten erstellt werden.
PAGE_WRITECOPY 0x08	Ermöglicht das Zuordnen von Ansichten für schreibgeschützten oder schreibgeschützten Zugriff. Dieser Wert entspricht PAGE_READONLY. Das Dateihandle, das der hFile Parameter angibt, muss mit dem GENERIC_READ Zugriffsrecht erstellt werden.

AllocationAttributes

Typ: _In_ ULONG-

Sie können ein oder mehrere der folgenden Attribute für das Dateizuordnungsobjekt angeben. Siehe auch den parameter PageProtection.

Wert	Bedeutung
SEC_COMMIT 0x8000000	Wenn das Dateizuordnungsobjekt von der Auslagerungsdatei des Betriebssystems unterstützt wird (der hfile Parameter ist INVALID_HANDLE_VALUE), gibt an, dass, wenn eine Ansicht der Datei einem Prozessadressraum zugeordnet wird, der gesamte Seitenbereich zugesichert wird, anstatt reserviert. Das System muss über genügend Committable-Seiten verfügen, um die gesamte Zuordnung zu enthalten. Andernfalls schlägt CreateFileMapping fehl. Dieses Attribut hat keine Auswirkung auf Dateizuordnungsobjekte, die von ausführbaren Bilddateien oder Datendateien unterstützt werden (der hfile Parameter ist ein Handle für eine Datei). SEC_COMMIT können nicht mit SEC_RESERVEkombiniert werden. Wenn kein Attribut angegeben wird, wird SEC_COMMIT angenommen.
SEC_IMAGE 0x1000000	Gibt an, dass die Datei, die der hFile Parameter angibt, eine ausführbare Bilddatei ist. Das attribut SEC_IMAGE muss mit einem Seitenschutzwert wie PAGE_READONLYkombiniert werden. Dieser Seitenschutzwert hat jedoch keine Auswirkungen auf Ansichten der ausführbaren Bilddatei. Der Seitenschutz für Ansichten einer ausführbaren Bilddatei wird durch die ausführbare Datei selbst bestimmt. Mit SEC_IMAGEsind keine anderen Attribute gültig.
SEC_IMAGE_NO_EXECUTE 0x11000000	Gibt an, dass die Datei, die der hFile Parameter angibt, eine ausführbare Bilddatei ist, die nicht ausgeführt wird und die geladene Bilddatei keine erzwungenen Integritätsprüfungen ausgeführt wird. Darüber hinaus ruft die Zuordnung einer Ansicht eines dateizuordnungsobjekts, das mit dem attribut SEC_IMAGE_NO_EXECUTE erstellt wurde, keine Treiberrückrufe auf, die mithilfe der PsSetLoadImageNotifyRoutine Kernel-API registriert sind. Das attribut SEC_IMAGE_NO_EXECUTE muss mit dem PAGE_READONLY Seitenschutzwert kombiniert werden. Mit SEC_IMAGE_NO_EXECUTEsind keine anderen Attribute gültig. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird vor Windows Server 2012 und Windows 8 nicht unterstützt.
SEC_LARGE_PAGES 0x80000000	Ermöglicht die Verwendung großer Seiten für Dateizuordnungsobjekte, die von der Auslagerungsdatei des Betriebssystems unterstützt werden (der hfile--Parameter ist INVALID_HANDLE_VALUE). Dieses Attribut wird für Dateizuordnungsobjekte, die von ausführbaren Bilddateien oder Datendateien gesichert werden, nicht unterstützt (der hFile- Parameter ist ein Handle für ein ausführbares Bild oder eine Datendatei). Die maximale Größe des Dateizuordnungsobjekts muss ein Vielfaches der Mindestgröße einer großen Seite sein, die von der GetLargePageMinimum-Funktion zurückgegeben wird. Ist dies nicht der Fehler, schlägt CreateFileMapping fehl. Beim Zuordnen einer Ansicht eines dateizuordnungsobjekts, das mit SEC_LARGE_PAGESerstellt wurde, muss die Basisadresse und die Ansichtsgröße auch Vielfache der minimal großen Seitengröße sein. SEC_LARGE_PAGES erfordert, dass das SeLockMemoryPrivilege Berechtigung im Token des Aufrufers aktiviert werden muss. Wenn SEC_LARGE_PAGES angegeben ist, muss auch SEC_COMMIT angegeben werden. Windows Server 2003: Dieser Wert wird erst unter Windows Server 2003 mit SP1 unterstützt. Windows XP: Dieser Wert wird nicht unterstützt.
SEC_NOCACHE 0x10000000	Legt fest, dass alle Seiten nicht zwischengespeichert werden können. Anwendungen sollten dieses Attribut nicht verwenden, es sei denn, dies ist explizit für ein Gerät erforderlich. Die Verwendung der verriegelten Funktionen mit speicherinternen Funktionen, die mit SEC_NOCACHE zugeordnet sind, kann zu einer EXCEPTION_ILLEGAL_INSTRUCTION Ausnahme führen. SEC_NOCACHE muss entweder das SEC_RESERVE- oder SEC_COMMIT Attribut festgelegt werden.
SEC_RESERVE 0x4000000	Wenn das Dateizuordnungsobjekt von der Auslagerungsdatei des Betriebssystems unterstützt wird (der hfile Parameter ist INVALID_HANDLE_VALUE), gibt an, dass, wenn eine Ansicht der Datei in einem Prozessadressraum zugeordnet wird, der gesamte Seitenbereich für die spätere Verwendung durch den Prozess reserviert ist und nicht zugesichert wird. Reservierte Seiten können in nachfolgenden Aufrufen der VirtualAlloc--Funktion zugesichert werden. Nachdem die Seiten zugesichert wurden, können sie nicht mit der funktion VirtualFree freigegeben oder dekommissioniert werden. Dieses Attribut hat keine Auswirkung auf Dateizuordnungsobjekte, die von ausführbaren Bilddateien oder Datendateien unterstützt werden (der hfile Parameter ist ein Handle für eine Datei). SEC_RESERVE können nicht mit SEC_COMMITkombiniert werden.
SEC_WRITECOMBINE 0x40000000	Legt fest, dass alle Seiten kombiniert werden sollen. Anwendungen sollten dieses Attribut nicht verwenden, es sei denn, dies ist explizit für ein Gerät erforderlich. Die Verwendung der verriegelten Funktionen mit Speicher, der mit 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. Windows Server 2003 und Windows XP: Dieses Flag wird erst unter Windows Vista unterstützt.

MaximumSize

Typ: _In_ ULONG64

Die maximale Größe des Dateizuordnungsobjekts.

Wenn dieser Parameter 0 (null) ist, entspricht die maximale Größe des Dateizuordnungsobjekts der aktuellen Größe der Datei, die hFile- identifiziert.

Ein Versuch, eine Datei mit einer Länge von 0 (Null) zuzuordnen, schlägt mit einem Fehlercode von ERROR_FILE_INVALIDfehl. Sie sollten auf Dateien mit einer Länge von 0 (Null) testen und diese Dateien ablehnen.

Name

Typ: _In_opt_ PCWSTR-

Der Name des Dateizuordnungsobjekts.

Wenn dieser Parameter mit dem Namen eines vorhandenen Zuordnungsobjekts übereinstimmt, fordert die Funktion den Zugriff auf das Objekt mit dem Schutz an, der flProtect- angibt.

Wenn dieser Parameter NULL-ist, wird das Dateizuordnungsobjekt ohne Namen erstellt.

Wenn lpName- mit dem Namen eines vorhandenen Ereignisses, Semaphor, Mutex, Wartezeitgeber oder Auftragsobjekts ü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. Das Erstellen eines Dateizuordnungsobjekts im globalen Namespace aus einer anderen Sitzung als Sitzung Null erfordert das SeCreateGlobalPrivilege-Berechtigung. 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, die für Terminaldienste beschrieben sind, damit Anwendungen mehrere Benutzer unterstützen können.

ExtendedParameters

Typ: _Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*

Ein optionaler Zeiger auf einen oder mehrere erweiterte Parameter vom Typ MEM_EXTENDED_PARAMETER. Jeder dieser erweiterten Parameterwerte kann selbst ein Type-Feld von entweder MemExtendedParameterAddressRequirements oder MemExtendedParameterNumaNodehaben. Wenn kein MemExtendedParameterNumaNode erweiterter Parameter bereitgestellt wird, ist das Verhalten identisch mit den Funktionen VirtualAlloc/MapViewOfFile (d. a. der bevorzugte NUMA-Knoten für die physischen Seiten wird basierend auf dem idealen Prozessor des Threads bestimmt, der zuerst auf den Speicher zugreift).

ParameterCount

In ULONG ParameterCount

Die Anzahl der erweiterten Parameter, auf die durch ExtendedParametersverwiesen wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das neu erstellte 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 GetLastError gibt ERROR_ALREADY_EXISTSzurück.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Siehe die Hinweise für CreateFileMapping.

Beispiele

Ein Beispiel finden Sie unter Erstellen von benanntem freigegebenem Speicheroder Erstellen einer Dateizuordnung mithilfe großer Seiten.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 10 Build 20348
mindestens unterstützte Server-	Windows 10 Build 20348
Zielplattform-	Fenster
Header-	memoryapi.h (include Windows.h, Memoryapi.h)
Library	onecore.lib
DLL-	Kernel32.dll