Fonction VirtualFree (memoryapi.h)

Article
02/05/2024

Libère, désengage ou libère et désengage une région de pages dans l’espace d’adressage virtuel du processus appelant.

Pour libérer la mémoire allouée dans un autre processus par la fonction VirtualAllocEx , utilisez la fonction VirtualFreeEx .

Syntaxe

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

Paramètres

[in] lpAddress

Pointeur vers l’adresse de base de la région des pages à libérer.

Si le paramètre dwFreeType est MEM_RELEASE, ce paramètre doit être l’adresse de base retournée par la fonction VirtualAlloc lorsque la région des pages est réservée.

[in] dwSize

Taille de la région de mémoire à libérer, en octets.

Si le paramètre dwFreeType est MEM_RELEASE, ce paramètre doit être égal à 0 (zéro). La fonction libère toute la région réservée dans l’appel d’allocation initial à VirtualAlloc.

Si le paramètre dwFreeType est MEM_DECOMMIT, la fonction déscommitit toutes les pages de mémoire qui contiennent un ou plusieurs octets dans la plage du paramètre lpAddress à (lpAddress+dwSize). Cela signifie, par exemple, qu’une région de mémoire de 2 octets qui chevauche une limite de page entraîne la décompression des deux pages. Si lpAddress est l’adresse de base retournée par VirtualAlloc et si dwSize est égal à 0 (zéro), la fonction désengage toute la région allouée par VirtualAlloc. Après cela, la région entière est à l’état réservé.

[in] dwFreeType

Type d’opération gratuite. Ce paramètre peut prendre les valeurs suivantes.

Valeur	Signification
MEM_DECOMMIT 0x00004000	Déscommitit la région spécifiée des pages validées. Après l’opération, les pages sont à l’état réservé. La fonction n’échoue pas si vous tentez de supprimer une page non validée. Cela signifie que vous pouvez désengagement d’une plage de pages sans déterminer au préalable l’état d’engagement actuel. La valeur MEM_DECOMMIT n’est pas prise en charge lorsque le paramètre lpAddress fournit l’adresse de base d’une enclave. Cela est vrai pour les enclaves qui ne prennent pas en charge la gestion dynamique de la mémoire (par exemple, SGX1). Les enclaves SGX2 permettent MEM_DECOMMIT n’importe où dans l’enclave.
MEM_RELEASE 0x00008000	Libère la région de pages spécifiée ou l’espace réservé (pour un espace réservé, l’espace d’adressage est libéré et disponible pour d’autres allocations). Après cette opération, les pages sont à l’état libre. Si vous spécifiez cette valeur, dwSize doit être égal à 0 (zéro), et lpAddress doit pointer vers l’adresse de base retournée par la fonction VirtualAlloc lorsque la région est réservée. La fonction échoue si l’une de ces conditions n’est pas remplie. Si des pages de la région sont validées actuellement, la fonction désengage d’abord, puis les libère. La fonction n’échoue pas si vous tentez de libérer des pages qui sont dans des états différents, certains réservés et d’autres validées. Cela signifie que vous pouvez publier une plage de pages sans déterminer au préalable l’état d’engagement actuel.

Valeur

Signification

MEM_DECOMMIT
0x00004000

Déscommitit la région spécifiée des pages validées. Après l’opération, les pages sont à l’état réservé.

La fonction n’échoue pas si vous tentez de supprimer une page non validée. Cela signifie que vous pouvez désengagement d’une plage de pages sans déterminer au préalable l’état d’engagement actuel.

La valeur MEM_DECOMMIT n’est pas prise en charge lorsque le paramètre lpAddress fournit l’adresse de base d’une enclave. Cela est vrai pour les enclaves qui ne prennent pas en charge la gestion dynamique de la mémoire (par exemple, SGX1). Les enclaves SGX2 permettent MEM_DECOMMIT n’importe où dans l’enclave.

MEM_RELEASE
0x00008000

Libère la région de pages spécifiée ou l’espace réservé (pour un espace réservé, l’espace d’adressage est libéré et disponible pour d’autres allocations). Après cette opération, les pages sont à l’état libre.

Si vous spécifiez cette valeur, dwSize doit être égal à 0 (zéro), et lpAddress doit pointer vers l’adresse de base retournée par la fonction VirtualAlloc lorsque la région est réservée. La fonction échoue si l’une de ces conditions n’est pas remplie.

Si des pages de la région sont validées actuellement, la fonction désengage d’abord, puis les libère.

La fonction n’échoue pas si vous tentez de libérer des pages qui sont dans des états différents, certains réservés et d’autres validées. Cela signifie que vous pouvez publier une plage de pages sans déterminer au préalable l’état d’engagement actuel.

Lorsque vous utilisez MEM_RELEASE, ce paramètre peut également spécifier l’une des valeurs suivantes.

Valeur	Signification
MEM_COALESCE_PLACEHOLDERS 0x00000001	Pour fusionner deux espaces réservés adjacents, spécifiez `MEM_RELEASE \| MEM_COALESCE_PLACEHOLDERS`. Lorsque vous fusionnez des espaces réservés, lpAddress et dwSize doivent correspondre exactement à la plage globale des espaces réservés à fusionner.
MEM_PRESERVE_PLACEHOLDER 0x00000002	Libère une allocation dans un espace réservé (après avoir remplacé un espace réservé par une allocation privée à l’aide de VirtualAlloc2 ou Virtual2AllocFromApp). Pour diviser un espace réservé en deux espaces réservés, spécifiez `MEM_RELEASE \| MEM_PRESERVE_PLACEHOLDER`.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est zéro (0). Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Chaque page de mémoire d’un espace d’adressage virtuel de processus a un état de page. La fonction VirtualFree peut supprimer une plage de pages qui se trouvent dans des états différents, certains validés et d’autres non validés. Cela signifie que vous pouvez désengagement d’une plage de pages sans déterminer au préalable l’état d’engagement actuel de chaque page. Le désengagement d’une page libère son stockage physique, soit en mémoire, soit dans le fichier de pagination sur le disque.

Si une page est décommise, mais pas publiée, son état devient réservé. Par la suite, vous pouvez appeler VirtualAlloc pour le valider, ou VirtualFree pour le libérer. Les tentatives de lecture à partir d’une page réservée ou d’écriture dans une page réservée entraînent une exception de violation d’accès.

La fonction VirtualFree peut libérer une plage de pages qui sont dans des états différents, certains réservés et d’autres validées. Cela signifie que vous pouvez publier une plage de pages sans déterminer au préalable l’état d’engagement actuel de chaque page. Toute la plage de pages initialement réservées par la fonction VirtualAlloc doit être publiée en même temps.

Si une page est publiée, son état devient gratuit et elle est disponible pour les opérations d’allocation suivantes. Une fois la mémoire libérée ou supprimée, vous ne pouvez plus jamais faire référence à la mémoire. Toutes les informations qui ont pu se trouver dans cette mémoire sont disparues pour toujours. La tentative de lecture à partir d’une page gratuite ou d’écriture dans une page gratuite entraîne une exception de violation d’accès. Si vous avez besoin de conserver des informations, ne désengagez pas ou ne libérez pas la mémoire qui contient les informations.

La fonction VirtualFree peut être utilisée sur une région de mémoire AWE, et elle invalide tous les mappages de pages physiques dans la région lors de la libération de l’espace d’adressage. Toutefois, la page physique n’est pas supprimée et l’application peut les utiliser. L’application doit appeler explicitement FreeUserPhysicalPages pour libérer les pages physiques. Lorsque le processus est terminé, toutes les ressources sont nettoyées automatiquement.

Windows 10, version 1709 et ultérieure et Windows 11 : pour supprimer l’enclave lorsque vous avez fini de l’utiliser, appelez DeleteEnclave. Vous ne pouvez pas supprimer une enclave VBS en appelant la fonction VirtualFree ou VirtualFreeEx . Vous pouvez toujours supprimer une enclave SGX en appelant VirtualFree ou VirtualFreeEx.

Windows 10, version 1507, Windows 10, version 1511, Windows 10, version 1607 et Windows 10, version 1703 : Pour supprimer l’enclave lorsque vous avez terminé de l’utiliser, appelez la fonction VirtualFree ou VirtualFreeEx et spécifiez les valeurs suivantes :

Adresse de base de l’enclave pour le paramètre lpAddress .
0 pour le paramètre dwSize .
MEM_RELEASE pour le paramètre dwFreeType .

Exemples

Pour obtenir un exemple, consultez Réserver et valider la mémoire.

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	memoryapi.h (inclure Windows.h, Memoryapi.h)
Bibliothèque	onecore.lib
DLL	Kernel32.dll

Voir aussi

Fonctions de gestion de la mémoire

Fonctions de mémoire virtuelle

VirtualFreeEx

API Vertdll disponibles dans les enclaves VBS