Fonction NtFreeVirtualMemory (ntifs.h)

  • Article

Les versions de routine NtFreeVirtualMemory , les dégagements ou les deux versions et les dégagements, une région de pages dans l’espace d’adressage virtuel d’un processus spécifié.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtFreeVirtualMemory(
  [in]      HANDLE  ProcessHandle,
  [in, out] PVOID   *BaseAddress,
  [in, out] PSIZE_T RegionSize,
  [in]      ULONG   FreeType
);

Paramètres

[in] ProcessHandle

Handle pour le processus dans lequel résident les pages à libérer. Utilisez la macro NtCurrentProcess , définie dans Ntddk.h, pour spécifier le processus actuel.

[in, out] BaseAddress

Pointeur vers une variable qui recevra l’adresse virtuelle de base de la région libérée des pages.

Si l’indicateur MEM_RELEASE est défini dans le paramètre FreeType , *BaseAddress doit être l’adresse de base retournée par NtAllocateVirtualMemory lorsque la région a été réservée.

[in, out] RegionSize

Pointeur vers une variable qui recevra la taille réelle, en octets, de la région libérée des pages. La routine arrondit la valeur initiale de cette variable jusqu’à la limite de taille de page hôte suivante et réécrit la valeur arrondie dans cette variable.

Si l’indicateur MEM_RELEASE est défini dans *FreeType, *RegionSize doit être égal à zéro. NtFreeVirtualMemory libère toute la région qui a été réservée dans l’appel d’allocation initial à NtAllocateVirtualMemory.

Si l’indicateur MEM_DECOMMIT est défini dans *FreeType, NtFreeVirtualMemory supprime toutes les pages mémoire qui contiennent un ou plusieurs octets dans la plage de *BaseAddress à (*BaseAddress + *RegionSize). Cela signifie, par exemple, que si une région de mémoire de deux octets chevauche une limite de page, les deux pages sont décompressée.

NtFreeVirtualMemory désengage toute la région réservée par NtAllocateVirtualMemory. Si les trois conditions suivantes sont remplies, la région entière entre dans l’état réservé :

  • L’indicateur MEM_DECOMMIT est défini.
  • *BaseAddress est l’adresse de base retournée par NtAllocateVirtualMemory lorsque la région a été réservée.
  • *RegionSize est égal à zéro.

[in] FreeType

Masque de bits contenant des indicateurs qui décrivent le type d’opération gratuite effectuée par NtFreeVirtualMemory pour la région de pages spécifiée. Les valeurs possibles sont répertoriées dans le tableau suivant.

Indicateur Signification
MEM_DECOMMIT NtFreeVirtualMemory décommit la région de pages spécifiée. Les pages entrent dans l’état réservé. NtFreeVirtualMemory n’échoue pas si vous tentez de libérer une page non validée. Cela signifie que vous pouvez désengagement d’une plage de pages sans déterminer au préalable leur état d’engagement actuel.
MEM_RELEASE NtFreeVirtualMemory libère la région de pages spécifiée. Les pages entrent dans l’état libre. Si vous spécifiez cet indicateur, RegionSize doit être égal à zéro et BaseAddress doit pointer vers l’adresse de base retournée par NtAllocateVirtualMemory lorsque la région était réservée. NtFreeVirtualMemory échoue si l’une de ces conditions n’est pas remplie. Si des pages de la région sont actuellement validées, NtFreeVirtualMemory commence par les désengagements, puis les libère. NtFreeVirtualMemory 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 leur état d’engagement actuel.

Valeur retournée

NtFreeVirtualMemory retourne STATUS_SUCCESS ou une erreur status code. Les codes status d’erreur possibles incluent les éléments suivants.

Code de retour Description
STATUS_ACCESS_DENIED Un processus a demandé l’accès à un objet, mais ces droits d’accès n’ont pas été accordés.
STATUS_INVALID_HANDLE Une valeur ProcessHandle non valide a été spécifiée.
STATUS_OBJECT_TYPE_MISMATCH Il existe une incompatibilité entre le type d’objet requis par l’opération demandée et le type d’objet spécifié dans la demande.

Remarques

Chaque page de l’espace d’adressage virtuel du processus se trouve dans l’un des trois états décrits dans le tableau suivant.

State Signification
FREE La page n’est ni validée ni réservée. La page n’est pas accessible au processus. 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. Vous pouvez utiliser NtFreeVirtualMemory pour placer les pages réservées ou validées à l’état libre.
RÉSERVÉ La page est réservée. La plage d’adresses ne peut pas être utilisée par d’autres fonctions d’allocation. La page n’est pas accessible au processus et n’a aucun stockage physique associé. La tentative de lecture à partir d’une page réservée ou d’écriture dans une page réservée entraîne une exception de violation d’accès. Vous pouvez utiliser NtFreeVirtualMemory pour placer les pages de mémoire validées à l’état réservé et pour placer les pages de mémoire réservées à l’état libre.
ENGAGÉS La page est validée. Le stockage physique en mémoire ou dans le fichier de pagination sur le disque est alloué à la page, et l’accès est contrôlé par un code de protection. Le système initialise et charge chaque page validée dans la mémoire physique uniquement à la première tentative de lecture ou d’écriture de cette page. Lorsqu’un processus se termine, le système libère tout le stockage pour les pages validées. Vous pouvez utiliser NtAllocateVirtualMemory pour placer les pages de mémoire validées à l’état réservé ou libre.

NtFreeVirtualMemory peut effectuer les opérations suivantes :

  • Décommit une région de pages validées ou non validées. Après cette opération, les pages sont à l’état réservé.
  • Libérer une région de pages réservées. Après cette opération, les pages sont à l’état libre.
  • Désengagez et libérez une région de pages validées ou non validées. Après cette opération, les pages sont à l’état libre.

NtFreeVirtualMemory 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é. Vous pouvez ensuite appeler NtAllocateVirtualMemory pour le valider, ou NtFreeVirtualMemory pour le libérer. La tentative de lecture à partir d’une page réservée ou d’écriture dans une page réservée entraîne une exception de violation d’accès.

NtFreeVirtualMemory peut publier une plage de pages qui sont dans des états différents, certains réservés et d’autres engagés. 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 NtAllocateVirtualMemory 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 libéré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 d’informations, ne désengagez pas ou ne libérez pas la mémoire qui contient ces informations.

Pour plus d’informations sur la prise en charge de la gestion de la mémoire pour les pilotes en mode noyau, consultez Gestion de la mémoire pour les pilotes Windows.

Notes

Si l’appel à la fonction NtFreeVirtualMemory se produit en mode utilisateur, vous devez utiliser le nom « NtFreeVirtualMemory » au lieu de « ZwFreeVirtualMemory ».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000
Plateforme cible Universal
En-tête ntifs.h (include Ntifs.h, Fltkernel.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Règles de conformité DDI HwStorPortProhibitedDDIs, PowerIrpDDis

Voir aussi

NtAllocateVirtualMemory