Função NtAllocateVirtualMemory (ntifs.h)

A rotina NtAllocateVirtualMemory reserva, confirma ou ambas, uma região de páginas dentro do espaço de endereço virtual no modo de usuário de um processo especificado.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtAllocateVirtualMemory(
  [in]      HANDLE    ProcessHandle,
  [in, out] PVOID     *BaseAddress,
  [in]      ULONG_PTR ZeroBits,
  [in, out] PSIZE_T   RegionSize,
  [in]      ULONG     AllocationType,
  [in]      ULONG     Protect
);

Parâmetros

[in] ProcessHandle

Um identificador para o processo para o qual o mapeamento deve ser feito. 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 base da região alocada de páginas. Se o valor inicial de BaseAddress não for NULL, a região será alocada começando no endereço virtual especificado arredondado para baixo até o próximo limite de endereço de tamanho de página do host. Se o valor inicial de BaseAddress for NULL, o sistema operacional determinará onde alocar a região.

[in] ZeroBits

O número de bits de endereço de ordem alta que devem ser zero no endereço base da exibição de seção. Usado somente quando o sistema operacional determina onde alocar a região, como quando BaseAddress* é NULL. Observe que quando ZeroBits é maior que 32, ele se torna uma máscara de bits.

[in, out] RegionSize

Um ponteiro para uma variável que receberá o tamanho real, em bytes, da região alocada de páginas. O valor inicial de RegionSize especifica o tamanho, em bytes, da região e é arredondado para o próximo limite de tamanho de página do host. RegionSize não pode ser zero na entrada.

[in] AllocationType

Uma máscara de bits que contém sinalizadores que especificam o tipo de alocação a ser executada para a região de páginas especificada. A tabela a seguir descreve os sinalizadores mais comuns. Consulte VirtualAlloc para obter uma lista completa de possíveis sinalizadores e descrições.

Observação

Um dos MEM_COMMIT, MEM_RESET ou MEM_RESERVE deve ser definido.

Sinalizador	Significado
MEM_COMMIT	A região especificada das páginas deve ser confirmada.
MEM_RESERVE	A região especificada das páginas deve ser reservada.
MEM_RESET	Redefina o estado da região especificada para que, se as páginas estiverem no arquivo de paginação, elas sejam descartadas e páginas de zeros sejam trazidas. Se as páginas estiverem na memória e modificadas, elas serão marcadas como não modificadas para que não sejam gravadas no arquivo de paginação. O conteúdo não está zerado. O parâmetro Protect não é usado, mas deve ser definido como um valor válido. Se MEM_RESET estiver definido, nenhum outro sinalizador poderá ser definido.
Outros sinalizadores MEM_XXX	Consulte VirtualAlloc.

[in] Protect

Uma máscara de bits que contém sinalizadores de proteção de página que especificam a proteção desejada para a região confirmada das páginas. A tabela a seguir descreve esses sinalizadores.

Sinalizador	Significado
PAGE_NOACCESS	Nenhum acesso à região confirmada de páginas é permitido. Uma tentativa de ler, gravar ou executar a região confirmada resulta em uma exceção de violação de acesso, chamada de falha de GP (proteção geral).
PAGE_READONLY	Acesso somente leitura e execução à região confirmada de páginas é permitido. Uma tentativa de gravar a região confirmada resulta em uma violação de acesso.
PAGE_READWRITE	Acesso de leitura, gravação e execução à região confirmada das páginas é permitido. Se o acesso de gravação à seção subjacente for permitido, uma única cópia das páginas será compartilhada. Caso contrário, as páginas são compartilhadas somente leitura/cópia na gravação.
PAGE_EXECUTE	É permitido executar o acesso à região confirmada das páginas. Uma tentativa de ler ou gravar na região confirmada resulta em uma violação de acesso.
PAGE_EXECUTE_READ	O acesso de execução e leitura à região confirmada das páginas é permitido. Uma tentativa de gravar na região confirmada resulta em uma violação de acesso.
PAGE_GUARD	As páginas na região se tornam páginas de proteção. Qualquer tentativa de ler ou gravar em uma página de proteção faz com que o sistema gere uma exceção STATUS_GUARD_PAGE. As páginas de proteção atuam, portanto, como um alarme de acesso de um tiro. Esse sinalizador é um modificador de proteção de página, válido somente quando usado com um dos sinalizadores de proteção de página diferente de PAGE_NOACCESS. Quando uma tentativa de acesso leva o sistema a desativar a página de proteção status, a proteção de página subjacente assume o controle. Se ocorrer uma exceção de página de proteção durante um serviço do sistema, o serviço normalmente retornará uma falha status indicador.
PAGE_NOCACHE	A região das páginas deve ser alocada como inconsequente. PAGE_NOCACHE não é permitido para seções.
PAGE_WRITECOMBINE	Habilita a combinação de gravação, ou seja, a união de gravações do cache para main memória, em que o hardware dá suporte a ela. Esse sinalizador é usado principalmente para memória de buffer de quadro para que as gravações na mesma linha de cache sejam combinadas sempre que possível antes de serem gravadas no dispositivo. Isso pode reduzir consideravelmente as gravações no barramento para (por exemplo) memória de vídeo. Se o hardware não der suporte à combinação de gravação, o sinalizador será ignorado. Esse sinalizador é um modificador de proteção de página, válido somente quando usado com um dos sinalizadores de proteção de página diferente de PAGE_NOACCESS.

Retornar valor

NtAllocateVirtualMemory retorna STATUS_SUCCESS ou um erro status código. Os possíveis códigos de status de erro incluem o seguinte:

• STATUS_ACCESS_DENIED
• STATUS_ALREADY_COMMITTED
• STATUS_COMMITMENT_LIMIT
• STATUS_CONFLICTING_ADDRESSES
• STATUS_INSUFFICIENT_RESOURCES
• STATUS_INVALID_HANDLE
• STATUS_INVALID_PAGE_PROTECTION
• STATUS_NO_MEMORY
• STATUS_OBJECT_TYPE_MISMATCH
• STATUS_PROCESS_IS_TERMINATING

Comentários

NtAllocateVirtualMemory pode executar as seguintes operações:

• Confirme uma região de páginas reservada por uma chamada anterior para NtAllocateVirtualMemory.
• Reserve uma região de páginas gratuitas.
• Reserve e confirme uma região de páginas gratuitas.

Os drivers no modo kernel podem usar NtAllocateVirtualMemory para reservar um intervalo de endereços virtuais acessíveis ao aplicativo no processo especificado e, em seguida, fazer chamadas adicionais para NtAllocateVirtualMemory para confirmar páginas individuais do intervalo 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.

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 ou reservada e não está acessível ao processo. NtAllocateVirtualMemory pode reservar ou reservar e confirmar simultaneamente uma página gratuita.
RESERVADO	O intervalo de endereços não pode ser usado por outras funções de alocação, mas a página não está acessível ao processo e não tem armazenamento físico associado a ele. NtAllocateVirtualMemory pode confirmar uma página reservada, mas não pode reservar uma segunda vez. NtFreeVirtualMemory pode liberar uma página reservada, tornando-a uma página gratuita.
COMETEU	O armazenamento físico é 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 apenas na primeira tentativa de ler ou gravar nessa página. Quando o processo é encerrado, o sistema libera o armazenamento para páginas confirmadas. NtAllocateVirtualMemory pode confirmar uma página já 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á. NtFreeVirtualMemory pode descompromissar uma página confirmada, liberar o armazenamento da página ou descompromissar e liberar simultaneamente uma página confirmada.

A memória alocada chamando NtAllocateVirtualMemory deve ser liberada chamando NtFreeVirtualMemory.

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

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

Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do Sistema Nativo do Windows 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 Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo.

Requisitos

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

Confira também

NtFreeVirtualMemory