Função ZwFreeVirtualMemory (ntifs.h)

A rotina ZwFreeVirtualMemory libera, confirma ou ambas, uma região de páginas dentro do espaço de endereço virtual de um processo especificado.

Sintaxe

NTSYSAPI NTSTATUS ZwFreeVirtualMemory(
  [in]      HANDLE  ProcessHandle,
  [in, out] PVOID   *BaseAddress,
  [in, out] PSIZE_T RegionSize,
  [in]      ULONG   FreeType
);

Parâmetros

[in] ProcessHandle

Um identificador para o processo em cujo contexto as páginas a serem liberadas residem. Use a macro NtCurrentProcess , definida em Ntddk.h, para especificar o processo atual.

[in, out] BaseAddress

Um ponteiro para uma variável que receberá o endereço virtual da região de páginas liberada.

Se o sinalizador MEM_RELEASE estiver definido no parâmetro FreeType , BaseAddress deverá ser o endereço base retornado por ZwAllocateVirtualMemory quando a região foi reservada.

[in, out] RegionSize

Um ponteiro para uma variável que receberá o tamanho real, em bytes, da região liberada das páginas. A rotina arredonda o valor inicial dessa variável até o próximo limite de tamanho de página do host e grava o valor arredondado de volta para essa variável.

Se o sinalizador MEM_RELEASE for definido no parâmetro FreeType , a variável apontada por RegionSize deverá ser zero. ZwFreeVirtualMemory libera toda a região reservada na chamada de alocação inicial para ZwAllocateVirtualMemory.

Se o sinalizador MEM_DECOMMIT for definido no parâmetro FreeType , ZwFreeVirtualMemory decomando todas as páginas de memória que contêm um ou mais bytes no intervalo do parâmetro BaseAddress até (BaseAddress + RegionSize). Isso significa, por exemplo, que se uma região de dois bytes de memória ultrapassar um limite de página, ambas as páginas serão descompactadas.

ZwFreeVirtualMemory confirma toda a região reservada por ZwAllocateVirtualMemory. Se as três condições a seguir forem atendidas, toda a região entrará no estado reservado:

• O sinalizador MEM_DECOMMIT está definido.
• BaseAddress é o endereço base retornado por ZwAllocateVirtualMemory quando a região foi reservada.
• RegionSize< é zero.

[in] FreeType

Uma máscara de bits que contém sinalizadores que descrevem o tipo de operação livre que ZwFreeVirtualMemory executará para a região de páginas especificada. Os valores possíveis são os seguintes:

• MEM_DECOMMIT

  • ZwFreeVirtualMemory irá desabilitar a região de páginas especificada. As páginas entram no estado reservado.

  • ZwFreeVirtualMemory não falhará se você tentar decodificar uma página não confirmada. Isso significa que você pode desabilitar um intervalo de páginas sem primeiro determinar seu estado de compromisso atual.

• MEM_RELEASE

  ZwFreeVirtualMemory liberará a região de páginas especificada. As páginas entram no estado gratuito.

  Se você especificar esse sinalizador, a variável para a qual RegionSize aponta deve ser zero e BaseAddress deverá apontar para o endereço base retornado por ZwAllocateVirtualMemory quando a região foi reservada. ZwFreeVirtualMemory falhará se qualquer uma dessas condições não for atendida.

  Se alguma página na região estiver confirmada no momento, ZwFreeVirtualMemory primeiro as decomando e, em seguida, as liberará.

ZwFreeVirtualMemory não falhará se você tentar liberar páginas que estão em estados diferentes, algumas reservadas e outras confirmadas. Isso significa que você pode liberar um intervalo de páginas sem primeiro determinar seu estado de compromisso atual.

Retornar valor

ZwFreeVirtualMemory retorna STATUS_SUCCESS ou um código de status de erro. Possíveis códigos de status de erro incluem o seguinte.

Código de retorno	Descrição
STATUS_ACCESS_DENIED	Um processo solicitou acesso a um objeto, mas não recebeu esses direitos de acesso.
STATUS_INVALID_HANDLE	Um valor ProcessHandle inválido foi especificado.
STATUS_OBJECT_TYPE_MISMATCH	Há uma incompatibilidade entre o tipo de objeto exigido pela operação solicitada e o tipo de objeto especificado na solicitação.

Comentários

Cada página no espaço de endereço virtual do processo está em um dos três estados descritos da seguinte maneira.

• O estado é GRATUITO

  A página não é confirmada nem reservada. A página não está acessível ao processo. Tentar ler ou gravar em uma página gratuita resulta em uma exceção de violação de acesso.

  Você pode usar ZwFreeVirtualMemory para colocar páginas reservadas ou confirmadas no estado livre.

• O estado é RESERVED

  A página é reservada. O intervalo de endereços não pode ser usado por outras funções de alocação. A página não está acessível ao processo e não tem armazenamento físico associado a ela. Tentar ler ou gravar em uma página reservada resulta em uma exceção de violação de acesso.

  Você pode usar ZwFreeVirtualMemory para colocar páginas de memória confirmadas no estado reservado e colocar páginas de memória reservadas no estado livre.

• O estado é COMMITTED

  A página está confirmada. O armazenamento físico na memória ou no arquivo de paginação no disco é alocado para a página e o acesso é controlado por um código de proteção.

  O sistema inicializa e carrega cada página confirmada na memória física somente na primeira tentativa de ler ou gravar nessa página.

  Quando um processo é encerrado, o sistema libera todo o armazenamento para páginas confirmadas.

  Você pode usar ZwAllocateVirtualMemory para colocar páginas de memória confirmadas no estado reservado ou livre.

ZwFreeVirtualMemory pode executar as seguintes operações:

• Descompacte uma região de páginas confirmadas ou não confirmadas. Após essa operação, as páginas estão no estado reservado.
• Libere uma região de páginas reservadas. Após essa operação, as páginas estarão no estado livre.
• Decodificar e liberar uma região de páginas confirmadas ou não confirmadas. Após essa operação, as páginas estarão no estado livre.

ZwFreeVirtualMemory pode decodificar um intervalo de páginas que estão em estados diferentes, algumas confirmadas e outras não confirmadas. Isso significa que você pode desabilitar um intervalo de páginas sem primeiro determinar o estado de compromisso atual de cada página. A descompactação de uma página libera seu armazenamento físico, na memória ou no arquivo de paginação no disco.

Se uma página for descompactada, mas não liberada, seu estado será alterado para reservado. Posteriormente, você pode chamar ZwFreeVirtualMemory para confirmá-lo ou ZwFreeVirtualMemory para liberá-lo. Tentar ler ou gravar em uma página reservada resulta em uma exceção de violação de acesso.

ZwFreeVirtualMemory pode liberar um intervalo de páginas que estão em estados diferentes, algumas reservadas e outras confirmadas. Isso significa que você pode liberar um intervalo de páginas sem primeiro determinar o estado de compromisso atual de cada página. Todo o intervalo de páginas originalmente reservado por ZwAllocateVirtualMemory deve ser liberado ao mesmo tempo.

Se uma página for liberada, seu estado será alterado para gratuito e estará disponível para operações de alocação subsequentes. Depois que a memória tiver sido liberada ou descompactada, você nunca mais poderá fazer referência à memória. Qualquer informação que possa estar nessa memória se foi para sempre. Tentar ler ou gravar em uma página gratuita resulta em uma exceção de violação de acesso. Se você precisar de informações, não descomprompa ou libere a memória que contém essas informações.

Para obter mais informações sobre o suporte ao gerenciamento de memória para drivers no modo kernel, consulte Gerenciamento de memória para drivers do Windows.

Observação

Se a chamada para a função ZwFreeVirtualMemory ocorrer no modo de usuário, você deverá usar o nome "NtFreeVirtualMemory" em vez de "ZwFreeVirtualMemory".

Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua Ntifs.h, Fltkernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Confira também

ZwAllocateVirtualMemory