Compartilhar via


Função VirtualFreeEx (memoryapi.h)

Libera, decodita ou libera e confirma uma região de memória dentro do espaço de endereço virtual de um processo especificado.

Sintaxe

BOOL VirtualFreeEx(
  [in] HANDLE hProcess,
  [in] LPVOID lpAddress,
  [in] SIZE_T dwSize,
  [in] DWORD  dwFreeType
);

Parâmetros

[in] hProcess

Um identificador para um processo. A função libera memória dentro do espaço de endereço virtual do processo.

O identificador deve ter o direito de acesso PROCESS_VM_OPERATION . Para obter mais informações, consulte Direitos de acesso e segurança do processo.

[in] lpAddress

Um ponteiro para o endereço inicial da região da memória a ser liberada.

Se o parâmetro dwFreeType for MEM_RELEASE, lpAddress deverá ser o endereço base retornado pela função VirtualAllocEx quando a região estiver reservada.

[in] dwSize

O tamanho da região da memória a ser livre, em bytes.

Se o parâmetro dwFreeType for MEM_RELEASE, dwSize deverá ser 0 (zero). A função libera toda a região reservada na chamada de alocação inicial para VirtualAllocEx.

Se dwFreeType for MEM_DECOMMIT, a função decomando todas as páginas de memória que contêm um ou mais bytes no intervalo do parâmetro lpAddress para (lpAddress+dwSize). Isso significa, por exemplo, que uma região de 2 bytes de memória que atravessa um limite de página faz com que ambas as páginas sejam descompactadas. Se lpAddress for o endereço base retornado por VirtualAllocEx e dwSize for 0 (zero), a função decomando toda a região alocada por VirtualAllocEx. Depois disso, toda a região está no estado reservado.

[in] dwFreeType

O tipo de operação gratuita. Esse parâmetro deve usar um dos valores a seguir.

Valor Significado
MEM_DECOMMIT
0x00004000
Confirma a região especificada de páginas confirmadas. Após a operação, as páginas estão no estado reservado.

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

Não suporte para o valor MEM_DECOMMIT quando o parâmetro lpAddress fornece o endereço base para um enclave. Isso é verdadeiro para enclaves que não dão suporte ao gerenciamento dinâmico de memória (ou seja, SGX1). Enclaves SGX2 permitem MEM_DECOMMIT em qualquer lugar do enclave.

MEM_RELEASE
0x00008000
Libera a região especificada de páginas ou espaço reservado (para um espaço reservado, o espaço de endereço é liberado e está disponível para outras alocações). Após essa operação, as páginas estarão no estado livre.

Se você especificar esse valor, dwSize deverá ser 0 (zero) e lpAddress deverá apontar para o endereço base retornado pela função VirtualAlloc quando a região estiver reservada. A função falhará se uma dessas condições não for atendida.

Se alguma página na região estiver confirmada no momento, a função primeiro decodificará e, em seguida, as liberará.

A função 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 o estado de compromisso atual.

Ao usar MEM_RELEASE, esse parâmetro também pode especificar um dos valores a seguir.

Valor Significado
MEM_COALESCE_PLACEHOLDERS
0x00000001
Para unir dois espaços reservados adjacentes, especifique MEM_RELEASE | MEM_COALESCE_PLACEHOLDERS. Quando você unir espaços reservados, lpAddress e dwSize deverão corresponder exatamente ao intervalo geral dos espaços reservados a serem mesclados.
MEM_PRESERVE_PLACEHOLDER
0x00000002
Libera uma alocação de volta para um espaço reservado (depois de substituir um espaço reservado por uma alocação privada usando VirtualAlloc2 ou Virtual2AllocFromApp).

Para dividir um espaço reservado em dois espaços reservados, especifique MEM_RELEASE | MEM_PRESERVE_PLACEHOLDER.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um valor diferente de zero.

Se a função falhar, o valor retornado será zero (0). Para obter informações de erro estendidas, chame GetLastError.

Comentários

Cada página de memória em um espaço de endereço virtual de processo tem um Estado de Página. A função VirtualFreeEx pode descompactar 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 VirtualAllocEx para confirmá-lo ou VirtualFreeEx para liberá-lo. Tentar ler ou gravar em uma página reservada resulta em uma exceção de violação de acesso.

A função VirtualFreeEx 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 VirtualAllocEx 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 for 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. Tentativas de ler ou gravar em uma página gratuita resultam em uma exceção de violação de acesso. Se você precisar manter informações, não descomprompa ou libere a memória que contém as informações.

A função VirtualFreeEx pode ser usada em uma região de memória AWE e invalida todos os mapeamentos de página física na região ao liberar o espaço de endereço. No entanto, as páginas físicas não são excluídas e o aplicativo pode usá-las. O aplicativo deve chamar explicitamente FreeUserPhysicalPages para liberar as páginas físicas. Quando o processo é encerrado, todos os recursos são limpos automaticamente.

Windows 10, versão 1709 e posterior e Windows 11: para excluir o enclave quando terminar de usá-lo, chame DeleteEnclave. Não é possível excluir um enclave de VBS chamando a função VirtualFree ou VirtualFreeEx . Você ainda pode excluir um enclave SGX chamando VirtualFree ou VirtualFreeEx.

Windows 10, versão 1507, Windows 10, versão 1511, Windows 10, versão 1607 e Windows 10, versão 1703: para excluir o enclave quando terminar de usá-lo, chame a função VirtualFree ou VirtualFreeEx e especifique os seguintes valores:

  • O endereço base do enclave para o parâmetro lpAddress .
  • 0 para o parâmetro dwSize .
  • MEM_RELEASE para o parâmetro dwFreeType .

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho memoryapi.h (inclua Windows.h, Memoryapi.h)
Biblioteca onecore.lib
DLL Kernel32.dll

Confira também

Funções de gerenciamento da memória

Funções de memória virtual

VirtualAllocEx