Função VirtualAlloc (memoryapi.h)

Reserva, confirma ou altera o estado de uma região de páginas no espaço de endereço virtual do processo de chamada. A memória alocada por essa função é inicializada automaticamente como zero.

Para alocar memória no espaço de endereço de outro processo, use a função VirtualAllocEx.

Sintaxe

LPVOID VirtualAlloc(
  [in, optional] LPVOID lpAddress,
  [in]           SIZE_T dwSize,
  [in]           DWORD  flAllocationType,
  [in]           DWORD  flProtect
);

Parâmetros

[in, optional] lpAddress

O endereço inicial da região a ser alocada. Se a memória estiver sendo reservada, o endereço especificado será arredondado para baixo para o múltiplo mais próximo da granularidade de alocação. Se a memória já estiver reservada e estiver sendo confirmada, o endereço será arredondado para o limite da próxima página. Para determinar o tamanho de uma página e a granularidade de alocação no computador host, use a função GetSystemInfo. Se esse parâmetro for NULL, o sistema determinará onde alocar a região.

Se esse endereço estiver dentro de um enclave que você não inicializou chamando InitializeEnclave, VirtualAlloc alocará uma página de zeros para o enclave nesse endereço. A página deve ser não confirmada anteriormente e não será medida com a instrução EEXTEND do modelo de programação extensões do Intel Software Guard.

Se o endereço estiver dentro de um enclave inicializado, a operação de alocação falhará com o erro ERROR_INVALID_ADDRESS. Isso é verdade para enclaves que não dão suporte ao gerenciamento dinâmico de memória (ou seja, SGX1). Os enclaves SGX2 permitirão a alocação e a página deve ser aceita pelo enclave depois de alocada.

[in] dwSize

O tamanho da região, em bytes. Se o parâmetro lpAddress for NULL, esse valor será arredondado para o limite da próxima página. Caso contrário, as páginas alocadas incluem todas as páginas que contêm um ou mais bytes no intervalo de lpAddress a lpAddress+dwSize. Isso significa que um intervalo de 2 bytes que ultrapassa um limite de página faz com que ambas as páginas sejam incluídas na região alocada.

[in] flAllocationType

O tipo de alocação de memória. Esse parâmetro deve conter um dos valores a seguir.

Esse parâmetro também pode especificar os valores a seguir, conforme indicado.

[in] flProtect

A proteção de memória para a região das páginas a ser alocada. Se as páginas estiverem sendo confirmadas, você poderá especificar qualquer uma das constantes de proteção de memória .

Se lpAddress especificar um endereço dentro de um enclave, flProtect não poderá ser nenhum dos seguintes valores:

• PAGE_NOACCESS
• PAGE_GUARD
• PAGE_NOCACHE
• PAGE_WRITECOMBINE

Ao alocar memória dinâmica para um enclave, o parâmetro flProtect deve ser PAGE_READWRITE ou PAGE_EXECUTE_READWRITE.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será o endereço base da região alocada de páginas.

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

Observações

Cada página tem um estado de página associado. A função VirtualAlloc pode executar as seguintes operações:

• Confirmar uma região de páginas reservadas
• Reservar uma região de páginas gratuitas
• Reservar e confirmar simultaneamente uma região de páginas gratuitas

VirtualAlloc não pode reservar uma página reservada. Ele pode confirmar uma página que já está confirmada. Isso significa que você pode confirmar um intervalo de páginas, independentemente de elas já terem sido confirmadas e a função não falhará.

Você pode usar VirtualAlloc para reservar um bloco de páginas e, em seguida, fazer chamadas adicionais para VirtualAlloc para confirmar páginas individuais do bloco reservado. Isso permite que um processo reserve um intervalo de seu espaço de endereço virtual sem consumir armazenamento físico até que seja necessário.

Se o parâmetro lpAddress não for NULL, a função usará os parâmetros lpAddress e dwSize para calcular a região das páginas a serem alocadas. O estado atual de todo o intervalo de páginas deve ser compatível com o tipo de alocação especificado pelo parâmetro flAllocationType. Caso contrário, a função falhará e nenhuma das páginas será alocada. Esse requisito de compatibilidade não impede a confirmação de uma página já confirmada, conforme mencionado anteriormente.

Para executar o código gerado dinamicamente, use VirtualAlloc para alocar memória e a função VirtualProtect para conceder acesso PAGE_EXECUTE.

A função VirtualAlloc pode ser usada para reservar uma região de memória de extensões de janela de endereço (AWE) dentro do espaço de endereço virtual de um processo especificado. Essa região de memória pode ser usada para mapear páginas físicas para dentro e para fora da memória virtual, conforme exigido pelo aplicativo. Os valores MEM_PHYSICAL e MEM_RESERVE devem ser definidos no parâmetro AllocationType. O valor MEM_COMMIT não deve ser definido. A proteção de página deve ser definida como PAGE_READWRITE.

A função VirtualFree pode descompromissar uma página confirmada, liberar o armazenamento da página ou descompromissar e liberar simultaneamente uma página confirmada. Ele também pode liberar uma página reservada, tornando-a uma página gratuita.

Ao criar uma região que será executável, o programa de chamada é responsável por garantir a coerência do cache por meio de uma chamada apropriada para FlushInstructionCache depois que o código tiver sido definido em vigor. Caso contrário, as tentativas de executar código fora da região recém-executável podem produzir resultados imprevisíveis.

Exemplos

Para obter um exemplo, consulte Reserving and Committing Memory.

Requisitos

Consulte também

Funções de gerenciamento de memória

Funções de memória virtual

VirtualAllocEx

VirtualFree

virtualLock

virtualProtect

VirtualQuery

APIs Vertdll disponíveis em enclaves de VBS