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.
AllocationAttributes
Typ: _In_ ULONG
Sie können mindestens eins der folgenden Attribute für das Dateizuordnungsobjekt angeben. Siehe auch den PageProtection-Parameter .
| Wert | Bedeutung |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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 |