Função VirtualFree (memoryapi.h)

Libera, descompromissa ou libera e descompromissa uma região de páginas dentro do espaço de endereço virtual do processo de chamada.

Para liberar memória alocada em outro processo pela função VirtualAllocEx , use a função VirtualFreeEx .

Sintaxe

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

Parâmetros

[in] lpAddress

Um ponteiro para o endereço base da região das páginas a serem liberadas.

Se o parâmetro dwFreeType for MEM_RELEASE, esse parâmetro deverá ser o endereço base retornado pela função VirtualAlloc quando a região das páginas estiver reservada.

[in] dwSize

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

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

Se o parâmetro dwFreeType for MEM_DECOMMIT, a função decodificará 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 VirtualAlloc e dwSize for 0 (zero), a função decodificará toda a região alocada pela VirtualAlloc. Depois disso, toda a região fica no estado reservado.

[in] dwFreeType

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

Valor Significado
MEM_DECOMMIT
0x00004000
Descompromissa 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 descompactar uma página não confirmada. Isso significa que você pode descompromissar um intervalo de páginas sem determinar primeiro o estado de compromisso atual.

Não há 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 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 for confirmada no momento, a função primeiro será descoditada 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 algumas 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 devem 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.

Valor retornado

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

Se a função falhar, o valor retornado será 0 (zero). 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 VirtualFree pode descompactar um intervalo de páginas que estão em estados diferentes, algumas confirmadas e algumas não confirmadas. Isso significa que você pode descompromissar 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 for liberada, seu estado será alterado para reservado. Posteriormente, você pode chamar VirtualAlloc para confirmá-lo ou VirtualFree para liberá-lo. As tentativas de ler ou gravar em uma página reservada resultam em uma exceção de violação de acesso.

A função VirtualFree pode liberar um intervalo de páginas que estão em estados diferentes, algumas reservadas e algumas 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 pela função VirtualAlloc deve ser liberado ao mesmo tempo.

Se uma página for liberada, seu estado será alterado gratuitamente e estará disponível para operações de alocação subsequentes. Depois que a memória for liberada ou descompromissada, você nunca mais poderá se referir à memória. Qualquer informação que possa estar nessa memória se foi para sempre. A tentativa de ler ou gravar em uma página gratuita resulta em uma exceção de violação de acesso. Se você precisar manter informações, não descompromisse nem a memória gratuita que contenha as informações.

A função VirtualFree 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, a página física não é excluída 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 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 .

Exemplos

Para obter um exemplo, consulte Reserva e Confirmação de Memória.

Requisitos

   
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

Virtualfreeex