VirtualFreeEx-Funktion (memoryapi.h)

Artikel
08/24/2023

Eine Speicherregion innerhalb des virtuellen Adressraums eines angegebenen Prozesses wird freigegeben, decommittiert oder freigegeben.

Syntax

BOOL VirtualFreeEx(
  [in] HANDLE hProcess,
  [in] LPVOID lpAddress,
  [in] SIZE_T dwSize,
  [in] DWORD  dwFreeType
);

Parameter

[in] hProcess

Ein Handle für einen Prozess. Die Funktion gibt Arbeitsspeicher im virtuellen Adressraum des Prozesses frei.

Das Handle muss über das zugriffsrecht PROCESS_VM_OPERATION verfügen. Weitere Informationen finden Sie unter Prozesssicherheit und Zugriffsrechte.

[in] lpAddress

Ein Zeiger auf die Startadresse des Speicherbereichs, der freigegeben werden soll.

Wenn der dwFreeType-ParameterMEM_RELEASE ist, muss lpAddress die Basisadresse sein, die von der VirtualAllocEx-Funktion zurückgegeben wird, wenn die Region reserviert ist.

[in] dwSize

Die Größe des freizugebenden Speicherbereichs in Bytes.

Wenn der dwFreeType-ParameterMEM_RELEASE ist, muss dwSize 0 (null) sein. Die Funktion gibt die gesamte Region frei, die im anfänglichen Zuordnungsaufruf von VirtualAllocEx reserviert ist.

Wenn dwFreeTypeMEM_DECOMMIT ist, werden von der Funktion alle Speicherseiten, die ein oder mehrere Bytes im Bereich vom parameter lpAddress bis zum (lpAddress+dwSize)enthalten, dekommittiert. Dies bedeutet beispielsweise, dass ein 2-Byte-Speicherbereich, der eine Seitengrenze überspannt, dazu führt, dass beide Seiten decomdiert werden. Wenn lpAddress die von VirtualAllocEx zurückgegebene Basisadresse ist und dwSize 0 (Null) ist, wird die gesamte Region, die von VirtualAllocEx zugewiesen wird, aufgehoben. Danach befindet sich die gesamte Region im reservierten Zustand.

[in] dwFreeType

Der Typ des freien Vorgangs. Dieser Parameter muss einen der folgenden Werte aufweisen.

Wert	Bedeutung
MEM_DECOMMIT 0x00004000	Deaktiviert die angegebene Region der zugesicherten Seiten. Nach dem Vorgang befinden sich die Seiten im reservierten Zustand. Die Funktion schlägt nicht fehl, wenn Sie versuchen, eine nicht festgeschriebene Seite aufzuheben. Dies bedeutet, dass Sie einen Seitenbereich aufheben können, ohne vorher den aktuellen Verpflichtungsstatus zu bestimmen. Der MEM_DECOMMIT Wert wird nicht unterstützt, wenn der lpAddress-Parameter die Basisadresse für eine Enclave bereitstellt. Dies gilt für Enklaven, die die dynamische Speicherverwaltung (z. B. SGX1) nicht unterstützen. SGX2-Enklaven erlauben MEM_DECOMMIT überall in der Enklave.
MEM_RELEASE 0x00008000	Gibt den angegebenen Bereich von Seiten oder Platzhalter frei (für einen Platzhalter wird der Adressraum freigegeben und steht für andere Zuordnungen zur Verfügung). Nach diesem Vorgang sind die Seiten freigegeben. Wenn Sie diesen Wert angeben, muss dwSize 0 (null) sein, und lpAddress muss auf die Basisadresse verweisen, die von der VirtualAlloc-Funktion zurückgegeben wird, wenn die Region reserviert ist. Die Funktion schlägt fehl, wenn eine der beiden Bedingungen nicht erfüllt wird. Wenn derzeit Seiten in der Region committet werden, wird die -Funktion zuerst deaktiviert und dann freigegeben. Die Funktion schlägt nicht fehl, wenn Sie versuchen, Seiten freizugeben, die sich in unterschiedlichen Zuständen befinden, einige reserviert und einige committet. Dies bedeutet, dass Sie einen Bereich von Seiten freigeben können, ohne zuerst den aktuellen Verpflichtungsstatus zu bestimmen.

Wert

Bedeutung

MEM_DECOMMIT
0x00004000

Deaktiviert die angegebene Region der zugesicherten Seiten. Nach dem Vorgang befinden sich die Seiten im reservierten Zustand.

Die Funktion schlägt nicht fehl, wenn Sie versuchen, eine nicht festgeschriebene Seite aufzuheben. Dies bedeutet, dass Sie einen Seitenbereich aufheben können, ohne vorher den aktuellen Verpflichtungsstatus zu bestimmen.

Der MEM_DECOMMIT Wert wird nicht unterstützt, wenn der lpAddress-Parameter die Basisadresse für eine Enclave bereitstellt. Dies gilt für Enklaven, die die dynamische Speicherverwaltung (z. B. SGX1) nicht unterstützen. SGX2-Enklaven erlauben MEM_DECOMMIT überall in der Enklave.

MEM_RELEASE
0x00008000

Gibt den angegebenen Bereich von Seiten oder Platzhalter frei (für einen Platzhalter wird der Adressraum freigegeben und steht für andere Zuordnungen zur Verfügung). Nach diesem Vorgang sind die Seiten freigegeben.

Wenn Sie diesen Wert angeben, muss dwSize 0 (null) sein, und lpAddress muss auf die Basisadresse verweisen, die von der VirtualAlloc-Funktion zurückgegeben wird, wenn die Region reserviert ist. Die Funktion schlägt fehl, wenn eine der beiden Bedingungen nicht erfüllt wird.

Wenn derzeit Seiten in der Region committet werden, wird die -Funktion zuerst deaktiviert und dann freigegeben.

Die Funktion schlägt nicht fehl, wenn Sie versuchen, Seiten freizugeben, die sich in unterschiedlichen Zuständen befinden, einige reserviert und einige committet. Dies bedeutet, dass Sie einen Bereich von Seiten freigeben können, ohne zuerst den aktuellen Verpflichtungsstatus zu bestimmen.

Wenn Sie MEM_RELEASE verwenden, kann dieser Parameter zusätzlich einen der folgenden Werte angeben.

Wert	Bedeutung
MEM_COALESCE_PLACEHOLDERS 0x00000001	Geben Sie zum Zusammenfügen von zwei benachbarten Platzhaltern an `MEM_RELEASE \| MEM_COALESCE_PLACEHOLDERS`. Wenn Sie Platzhalter zusammenführen, müssen lpAddress und dwSize genau dem Gesamtbereich der Platzhalter entsprechen, die zusammengeführt werden sollen.
MEM_PRESERVE_PLACEHOLDER 0x00000002	Gibt eine Zuordnung wieder in einen Platzhalter frei (nachdem Sie einen Platzhalter mithilfe von VirtualAlloc2 oder Virtual2AllocFromApp durch eine private Zuordnung ersetzt haben). Um einen Platzhalter in zwei Platzhalter aufzuteilen, geben Sie an `MEM_RELEASE \| MEM_PRESERVE_PLACEHOLDER`.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Nichtzero-Wert.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert 0 (null). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Jede Seite des Arbeitsspeichers in einem virtuellen Prozessadressraum weist einen Seitenzustand auf. Die VirtualFreeEx-Funktion kann einen Bereich von Seiten aufheben, die sich in unterschiedlichen Zuständen befinden, einige committet und einige nicht festgelegt. Dies bedeutet, dass Sie einen Seitenbereich aufheben können, ohne zuerst den aktuellen Verpflichtungsstatus jeder Seite zu bestimmen. Durch das Aufheben der Aussetzung einer Seite wird ihr physischer Speicher freigegeben, entweder im Arbeitsspeicher oder in der Auslagerungsdatei auf dem Datenträger.

Wenn eine Seite aufgehoben, aber nicht freigegeben wird, ändert sich ihr Zustand in reserviert. Anschließend können Sie VirtualAllocEx aufrufen, um ihn zu commiten, oder VirtualFreeEx , um es freizugeben. Der Versuch, eine reservierte Seite zu lesen oder in diese zu schreiben, führt zu einer Zugriffsverletzungs-Ausnahme.

Die VirtualFreeEx-Funktion kann einen Bereich von Seiten freigeben, die sich in unterschiedlichen Zuständen befinden, einige reserviert und einige committet. Dies bedeutet, dass Sie einen Seitenbereich freigeben können, ohne zuerst den aktuellen Verpflichtungsstatus jeder Seite zu bestimmen. Der gesamte Bereich der ursprünglich von VirtualAllocEx reservierten Seiten muss gleichzeitig freigegeben werden.

Wenn eine Seite freigegeben wird, ändert sich ihr Zustand in free und steht für nachfolgende Zuordnungsvorgänge zur Verfügung. Nachdem der Arbeitsspeicher freigegeben oder aufgehoben wurde, können Sie nie wieder auf den Arbeitsspeicher verweisen. Alle Informationen, die sich möglicherweise in diesem Speicher befinden, sind für immer verschwunden. Versuche, von einer freien Seite zu lesen oder darauf zu schreiben, führen zu einer Zugriffsverletzungs-Ausnahme. Wenn Sie Informationen beibehalten müssen, sollten Sie den Speicher, der die Informationen enthält, nicht aufheben oder freigeben.

Die VirtualFreeEx-Funktion kann in einer AWE-Speicherregion verwendet werden und ungültigt alle physischen Seitenzuordnungen in der Region, wenn der Adressraum freigegeben wird. Die physischen Seiten werden jedoch nicht gelöscht, und die Anwendung kann sie verwenden. Die Anwendung muss Explizit FreeUserPhysicalPages aufrufen, um die physischen Seiten freizugeben. Wenn der Prozess beendet wird, werden alle Ressourcen automatisch bereinigt.

Windows 10, Version 1709 und höher und Windows 11: Rufen Sie DeleteEnclave auf, um die Enclave nach Abschluss der Verwendung zu löschen. Sie können eine VBS-Enclave nicht löschen, indem Sie die Funktion VirtualFree oder VirtualFreeEx aufrufen. Sie können eine SGX-Enklave trotzdem löschen, indem Sie VirtualFree oder VirtualFreeEx aufrufen.

Windows 10, Version 1507, Windows 10, Version 1511, Windows 10, Version 1607 und Windows 10, Version 1703: Rufen Sie die Funktion VirtualFree oder VirtualFreeEx auf, und geben Sie die folgenden Werte an, um die Enclave zu löschen, wenn Sie sie verwenden:

Die Basisadresse der Enclave für den lpAddress-Parameter .
0 für den dwSize-Parameter .
MEM_RELEASE für den dwFreeType-Parameter .

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	memoryapi.h (einschließlich Windows.h, Memoryapi.h)
Bibliothek	onecore.lib
DLL	Kernel32.dll

Siehe auch

Speicherverwaltungsfunktionen

Funktionen des virtuellen Speichers

VirtualAllocEx