Freigeben über


CreateFileMapping2-Funktion (memoryapi.h)

Erstellt oder öffnet ein benanntes oder unbenannte Dateizuordnungsobjekt für eine angegebene Datei. Sie können einen bevorzugten NUMA-Knoten für den physischen Arbeitsspeicher 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 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 CreateFileMapping ein Dateizuordnungsobjekt mit einer angegebenen Größe, das durch die System pagingdatei und nicht durch eine Datei im Dateisystem unterstützt wird.

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. Das lpSecurityDescriptor-Element der SECURITY_ATTRIBUTES-Struktur gibt einen Sicherheitsdeskriptor für ein neues Dateizuordnungsobjekt an.

Wenn lpAttributesNULL 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.

DesiredAccess

Typ: _In_ ULONG

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

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 einen der folgenden Werte annehmen.

Wert Bedeutung
PAGE_EXECUTE_READ
0x20
Ermöglicht das Zuordnen von Ansichten für schreibgeschützten Zugriff, Kopieren beim Schreiben oder Ausführen des Zugriffs.

Das durch den hFile-Parameter angegebene Dateihandle muss mit dem GENERIC_READ und GENERIC_EXECUTE Zugriffsrechten erstellt werden.

Windows Server 2003 und Windows XP: Dieser Wert ist erst unter Windows XP mit SP2 und Windows Server 2003 mit SP1 verfügbar.

PAGE_EXECUTE_READWRITE
0x40
Ermöglicht die Zuordnung von Ansichten für schreibgeschützt, kopieren/schreiben, Lesen/Schreiben oder Ausführen des Zugriffs.

Das Dateihandle, das der hFile-Parameter angibt, muss mit den Zugriffsrechten GENERIC_READ, GENERIC_WRITE und GENERIC_EXECUTE erstellt werden.

Windows Server 2003 und Windows XP: Dieser Wert ist erst unter Windows XP mit SP2 und Windows Server 2003 mit SP1 verfügbar.

PAGE_EXECUTE_WRITECOPY
0x80
Ermöglicht das Zuordnen von Ansichten für schreibgeschützten Zugriff, Kopieren beim Schreiben oder Ausführen des Zugriffs. Dieser Wert entspricht PAGE_EXECUTE_READ.

Das Dateihandle, das der hFile-Parameter angibt, muss mit dem GENERIC_READ und GENERIC_EXECUTE Zugriffsrechten erstellt werden.

Windows Vista: Dieser Wert ist erst unter Windows Vista mit SP1 verfügbar.

Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.

PAGE_READONLY
0x02
Ermöglicht das Zuordnen von Ansichten für den schreibgeschützten oder kopiergeschü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 zugriffsrecht GENERIC_READ erstellt werden.

PAGE_READWRITE
0x04
Ermöglicht die Zuordnung von Ansichten für schreibgeschützten Zugriff, Kopierzugriff oder Lese-/Schreibzugriff.

Das Dateihandle, das der hFile-Parameter angibt, muss mit dem GENERIC_READ und GENERIC_WRITE Zugriffsrechten erstellt werden.

PAGE_WRITECOPY
0x08
Ermöglicht das Zuordnen von Ansichten für den schreibgeschützten oder kopiergeschützten Zugriff. Dieser Wert entspricht PAGE_READONLY.

Das Dateihandle, das der hFile-Parameter angibt, muss mit dem zugriffsrecht GENERIC_READ erstellt werden.

AllocationAttributes

Typ: _In_ ULONG

Sie können mindestens eins der folgenden Attribute für das Dateizuordnungsobjekt angeben. Siehe auch den PageProtection-Parameter .

Wert Bedeutung
SEC_COMMIT
0x8000000
Wenn das Dateizuordnungsobjekt durch die Auslagerungsdatei des Betriebssystems unterstützt wird (der hfile-Parameter ist INVALID_HANDLE_VALUE), gibt an, dass der gesamte Seitenbereich committet und nicht reserviert wird, wenn eine Ansicht der Datei einem Prozessadressraum zugeordnet wird. Das System muss über genügend commitfähige Seiten verfügen, um die gesamte Zuordnung zu enthalten. Andernfalls schlägt CreateFileMapping fehl.

Dieses Attribut hat keine Auswirkungen auf Dateizuordnungsobjekte, die durch ausführbare Bilddateien oder Datendateien gesichert werden (der hfile-Parameter ist ein Handle für eine Datei).

SEC_COMMIT können nicht mit SEC_RESERVE kombiniert 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 Imagedatei ist.

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.

SEC_IMAGE_NO_EXECUTE
0x11000000
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, 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 nicht für Dateizuordnungsobjekte unterstützt, die von ausführbaren Bilddateien oder Datendateien unterstützt werden (der hFile-Parameter ist ein Handle für ein ausführbares Image oder eine ausführbare 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. Andernfalls schlägt CreateFileMapping fehl. Beim Zuordnen einer Ansicht eines mit SEC_LARGE_PAGES erstellten Dateizuordnungsobjekts müssen die Basisadresse und die Ansichtsgröße auch ein Vielfaches der minimalen großen Seitengröße sein.

SEC_LARGE_PAGES erfordert die Aktivierung des SeLockMemoryPrivilege-Rechtes im Token des Aufrufers.

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 nur verwenden, wenn sie für ein Gerät explizit erforderlich sind. Die Verwendung der verriegelten Funktionen mit Speicher, der SEC_NOCACHE zugeordnet ist, 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 einem Prozessadressraum zugeordnet wird, der gesamte Seitenbereich für die spätere Verwendung durch den Prozess und nicht für ein Commit reserviert ist.

Reservierte Seiten können in nachfolgenden Aufrufen der VirtualAlloc-Funktion committet werden. Nachdem die Seiten committet wurden, können sie nicht mehr mit der VirtualFree-Funktion freigegeben oder decomdiert werden.

Dieses Attribut hat keine Auswirkungen auf Dateizuordnungsobjekte, die durch ausführbare Bilddateien oder Datendateien gesichert werden (der hfile-Parameter ist ein Handle für eine Datei).

SEC_RESERVE können nicht mit SEC_COMMIT kombiniert werden.

SEC_WRITECOMBINE
0x40000000
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.

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 der Länge 0 (null) zuzuordnen, schlägt mit dem Fehlercode ERROR_FILE_INVALID fehl. 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, den flProtect angibt.

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

Wenn lpName mit dem Namen eines vorhandenen Ereignisses, Semaphore, Mutex, wartebarer Timer oder Auftragsobjekt ü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 aus einer anderen Sitzung als Session Zero 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, 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 mit MemExtendedParameterAddressRequirements oder MemExtendedParameterNumaNode aufweisen. Wenn kein erweiterter MemExtendedParameterNumaNode-Parameter angegeben wird, ist das Verhalten identisch mit den VirtualAlloc/MapViewOfFile-Funktionen (das heißt, der bevorzugte NUMA-Knoten für die physischen Seiten wird basierend auf dem idealen Prozessor des Threads bestimmt, der zuerst auf den Arbeitsspeicher zugreift).

ParameterCount

In ULONG ParameterCount

Die Anzahl der erweiterten Parameter, auf die von ExtendedParameters verwiesen 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 (mit seiner aktuellen Größe, nicht der angegebenen Größe) zurück, und GetLastError 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 GetLastError auf.

Hinweise

Weitere Informationen finden Sie in den Anmerkungen zu CreateFileMapping.

Beispiele

Ein Beispiel finden Sie unter Erstellen von benanntem freigegebenem Arbeitsspeicher oder Erstellen einer Dateizuordnung mit großen Seiten.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 10 Build 20348
Unterstützte Mindestversion (Server) Windows 10 Build 20348
Zielplattform Windows
Kopfzeile memoryapi.h (einschließlich Windows.h, Memoryapi.h)
Bibliothek onecore.lib
DLL Kernel32.dll

Siehe auch

CloseHandle

CreateFileMappingNuma

Erstellen eines Dateizuordnungsobjekts

DuplicateHandle

MapViewOfFile

MapViewOfFileEx

Speicherverwaltungsfunktionen

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile