VirtualFree-Funktion (memoryapi.h)

Artikel
02/07/2024

Wird eine Region von Seiten innerhalb des virtuellen Adressraums des aufrufenden Prozesses freigegeben, freigegeben oder freigegeben.

Verwenden Sie die VirtualFreeEx-Funktion, um Arbeitsspeicher freizugeben, der in einem anderen Prozess durch die VirtualAllocEx-Funktion zugewiesen wurde.

Syntax

BOOL VirtualFree(
  [in] LPVOID lpAddress,
  [in] SIZE_T dwSize,
  [in] DWORD  dwFreeType
);

Parameter

[in] lpAddress

Ein Zeiger auf die Basisadresse des Bereichs der freizugebenden Seiten.

Wenn der dwFreeType-ParameterMEM_RELEASE ist, muss dieser Parameter die Basisadresse sein, die von der VirtualAlloc-Funktion zurückgegeben wird, wenn der Bereich der Seiten reserviert ist.

[in] dwSize

Die Größe des freizugebenden Speicherbereichs in Bytes.

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

Wenn der dwFreeType-ParameterMEM_DECOMMIT ist, dekommitiert die Funktion alle Speicherseiten, die ein oder mehrere Bytes im Bereich vom parameter lpAddress bis enthalten (lpAddress+dwSize). Dies bedeutet beispielsweise, dass ein 2-Byte-Speicherbereich, der eine Seitengrenze überspannt, dazu führt, dass beide Seiten decomdiert werden. Wenn lpAddress die von VirtualAlloc zurückgegebene Basisadresse ist und dwSize 0 (null) ist, wird die gesamte Region, die von VirtualAlloc zugewiesen wird, von der Funktion 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 ungleich Null.

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 VirtualFree-Funktion kann einen Bereich von Seiten aufheben, die sich in unterschiedlichen Zuständen befinden, einige committet und einige nicht gebunden sind. 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 VirtualAlloc aufrufen, um es zu commiten, oder VirtualFree , um es freizugeben. Versuche, von einer reservierten Seite zu lesen oder in diese zu schreiben, führen zu einer Zugriffsverletzungs-Ausnahme.

Die VirtualFree-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 von Seiten, die ursprünglich von der VirtualAlloc-Funktion reserviert waren, 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 Speicher verweisen. Alle Informationen, die sich möglicherweise in diesem Speicher befinden, sind für immer verschwunden. Der Versuch, von einer freien Seite zu lesen oder darauf zu schreiben, führt zu einer Zugriffsverletzungs-Ausnahme. Wenn Sie Informationen beibehalten müssen, sollten Sie den Speicher, der die Informationen enthält, nicht aufheben oder freigeben.

Die VirtualFree-Funktion kann in einer AWE-Speicherregion verwendet werden und ungültigt alle physischen Seitenzuordnungen in der Region, wenn der Adressraum freigegeben wird. Die physische Seite wird 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 .

Beispiele

Ein Beispiel finden Sie unter Reservieren und Commiten von Arbeitsspeicher.

Anforderungen


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

VirtualFreeEx

In VBS-Enclaves verfügbare Vertdll-APIs