Função NtFreeVirtualMemory (ntifs.h)

A rotina NtFreeVirtualMemory libera, descomandos ou versões e compromissos, uma região de páginas dentro do espaço de endereço virtual de um processo especificado.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtFreeVirtualMemory(
  [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 base da região liberada das páginas.

Se o sinalizador MEM_RELEASE estiver definido no parâmetro FreeType , *BaseAddress deverá ser o endereço base retornado por NtAllocateVirtualMemory 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 estiver definido em *FreeType, *RegionSize deverá ser zero. NtFreeVirtualMemory libera toda a região reservada na chamada de alocação inicial para NtAllocateVirtualMemory.

Se o sinalizador MEM_DECOMMIT estiver definido em *FreeType, NtFreeVirtualMemory decomando todas as páginas de memória que contêm um ou mais bytes no intervalo de *BaseAddress a (*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.

NtFreeVirtualMemory confirma toda a região reservada por NtAllocateVirtualMemory. 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 NtAllocateVirtualMemory 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 NtFreeVirtualMemory executará para a região especificada das páginas. Os valores possíveis são listados na tabela a seguir.

Sinalizador	Significado
MEM_DECOMMIT	NtFreeVirtualMemory descomando a região de páginas especificada. As páginas entram no estado reservado. NtFreeVirtualMemory 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	NtFreeVirtualMemory liberará a região de páginas especificada. As páginas entram no estado gratuito. Se você especificar esse sinalizador, RegionSize deverá ser zero e BaseAddress deverá apontar para o endereço base retornado por NtAllocateVirtualMemory quando a região foi reservada. NtFreeVirtualMemory falhará se qualquer uma dessas condições não for atendida. Se alguma página na região estiver confirmada no momento, NtFreeVirtualMemory primeiro decomando-as e, em seguida, as liberará. NtFreeVirtualMemory 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

NtFreeVirtualMemory retorna STATUS_SUCCESS ou um erro status código. 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 na tabela a seguir.

Estado	Significado
FREE	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 NtFreeVirtualMemory para colocar páginas reservadas ou confirmadas no estado livre.
RESERVADO	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 NtFreeVirtualMemory para colocar páginas de memória confirmadas no estado reservado e colocar páginas de memória reservadas no estado livre.
COMETEU	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 NtAllocateVirtualMemory para colocar páginas de memória confirmadas no estado reservado ou livre.

NtFreeVirtualMemory 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.

NtFreeVirtualMemory 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 NtAllocateVirtualMemory para confirmá-lo ou NtFreeVirtualMemory para liberá-lo. Tentar ler ou gravar em uma página reservada resulta em uma exceção de violação de acesso.

NtFreeVirtualMemory 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 NtAllocateVirtualMemory 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 NtFreeVirtualMemory 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 (include Ntifs.h, Fltkernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs, PowerIrpDDis

Confira também

NtAllocateVirtualMemory