Funzione VirtualAllocEx (memoryapi.h)

Articolo
07/16/2024

Riserva, commit o modifica lo stato di un'area di memoria all'interno dello spazio indirizzi virtuale di un processo specificato. La funzione inizializza la memoria allocata a zero.

Per specificare il nodo NUMA per la memoria fisica, vedere VirtualAllocExNuma.

Sintassi

LPVOID VirtualAllocEx(
  [in]           HANDLE hProcess,
  [in, optional] LPVOID lpAddress,
  [in]           SIZE_T dwSize,
  [in]           DWORD  flAllocationType,
  [in]           DWORD  flProtect
);

Parametri

[in] hProcess

Handle di un processo. La funzione alloca memoria all'interno dello spazio indirizzi virtuale di questo processo.

L'handle deve avere il diritto di accesso PROCESS_VM_OPERATION. Per altre informazioni, vedere Process Security and Access Rights.

[in, optional] lpAddress

Puntatore che specifica un indirizzo iniziale desiderato per l'area delle pagine da allocare.

Se si riserva memoria, la funzione arrotonda questo indirizzo fino al multiplo più vicino della granularità di allocazione.

Se si esegue il commit della memoria già riservata, la funzione arrotonda questo indirizzo fino al limite di pagina più vicino. Per determinare le dimensioni di una pagina e la granularità di allocazione nel computer host, usare la funzione GetSystemInfo .

Se lpAddress è NULL, la funzione determina dove allocare l'area.

Se questo indirizzo si trova all'interno di un enclave che non è stato inizializzato chiamando InitializeEnclave, VirtualAllocEx alloca una pagina di zeri per l'enclave in tale indirizzo. La pagina deve essere annullata in precedenza e non verrà misurata con l'istruzione EEXTEND del modello di programmazione Intel Software Guard Extensions.

Se l'indirizzo all'interno di un enclave inizializzato, l'operazione di allocazione ha esito negativo con l'errore ERROR_INVALID_ADDRESS. Ciò vale per le enclave che non supportano la gestione dinamica della memoria (ad esempio SGX1). Le enclave SGX2 consentiranno l'allocazione e la pagina deve essere accettata dall'enclave dopo che è stata allocata.

[in] dwSize

Dimensioni dell'area di memoria da allocare, in byte.

Se lpAddress è NULL, la funzione arrotonda dwSize fino al limite di pagina successivo.

Se lpAddress non è NULL, la funzione alloca tutte le pagine contenenti uno o più byte nell'intervallo compreso tra lpAddresslpAddress+dwSize. Ciò significa, ad esempio, che un intervallo a 2 byte che si allontana da un limite di pagina fa sì che la funzione allochi entrambe le pagine.

[in] flAllocationType

Tipo di allocazione di memoria. Questo parametro deve contenere uno dei valori seguenti.

Valore	Significato
MEM_COMMIT 0x00001000	Alloca i costi di memoria (dalle dimensioni complessive della memoria e dei file di paging su disco) per le pagine di memoria riservate specificate. La funzione garantisce anche che quando il chiamante accede inizialmente alla memoria, il contenuto sarà zero. Le pagine fisiche effettive non vengono allocate a meno che/fino a quando non si accede effettivamente agli indirizzi virtuali. Per riservare ed eseguire il commit delle pagine in un unico passaggio, chiamare VirtualAllocEx con `MEM_COMMIT \| MEM_RESERVE`. Il tentativo di eseguire il commit di un intervallo di indirizzi specifico specificando MEM_COMMIT senza MEM_RESERVE e unNULLlpAddress ha esito negativo a meno che l'intero intervallo non sia già stato riservato. Il codice di errore risultante è ERROR_INVALID_ADDRESS. Un tentativo di eseguire il commit di una pagina già sottoposta a commit non causa l'esito negativo della funzione. Ciò significa che è possibile eseguire il commit delle pagine senza prima determinare lo stato di impegno corrente di ogni pagina. Se lpAddress specifica un indirizzo all'interno di un enclave, flAllocationType deve essere MEM_COMMIT.
MEM_RESERVE 0x00002000	Riserva un intervallo di spazio indirizzi virtuale del processo senza allocare alcuna risorsa di archiviazione fisica effettiva in memoria o nel file di paging su disco. Per eseguire il commit delle pagine riservate, chiamare di nuovo VirtualAllocEx con MEM_COMMIT. Per riservare ed eseguire il commit delle pagine in un unico passaggio, chiamare VirtualAllocEx con `MEM_COMMIT \| MEM_RESERVE`. Altre funzioni di allocazione della memoria, ad esempio malloc e LocalAlloc, non possono usare memoria riservata finché non viene rilasciata.
MEM_RESET 0x00080000	Indica che i dati nell'intervallo di memoria specificato da lpAddress e dwSize non sono più di interesse. Le pagine non devono essere lette o scritte nel file di paging. Tuttavia, il blocco di memoria verrà usato di nuovo in un secondo momento, quindi non deve essere decommesso. Questo valore non può essere utilizzato con altri valori. L'utilizzo di questo valore non garantisce che l'intervallo utilizzato con MEM_RESET contenga zeri. Se si desidera che l'intervallo contenga zeri, decommettere la memoria e quindi ricommetterla. Quando si usa MEM_RESET, la funzione VirtualAllocEx ignora il valore di fProtect. Tuttavia, è comunque necessario impostare fProtect su un valore di protezione valido, ad esempio PAGE_NOACCESS. VirtualAllocEx restituisce un errore se si utilizza MEM_RESET e l'intervallo di memoria viene mappato a un file. Una visualizzazione condivisa è accettabile solo se è mappata a un file di paging.
MEM_RESET_UNDO 0x1000000	MEM_RESET_UNDO deve essere chiamato solo su un intervallo di indirizzi a cui MEM_RESET è stato applicato correttamente in precedenza. Indica che i dati nell'intervallo di memoria specificato da lpAddress e dwSize sono di interesse per il chiamante e tentano di invertire gli effetti di MEM_RESET. Se la funzione ha esito positivo, significa che tutti i dati nell'intervallo di indirizzi specificato sono intatti. Se la funzione ha esito negativo, almeno alcuni dei dati nell'intervallo di indirizzi sono stati sostituiti con zere. Questo valore non può essere utilizzato con altri valori. Se MEM_RESET_UNDO viene chiamato su un intervallo di indirizzi non MEM_RESET precedente, il comportamento non è definito. Quando si specifica MEM_RESET, la funzione VirtualAllocEx ignora il valore di flProtect. Tuttavia, è comunque necessario impostare flProtect su un valore di protezione valido, ad esempio PAGE_NOACCESS. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Il flag MEM_RESET_UNDO non è supportato fino a Windows 8 e Windows Server 2012.

Questo parametro può anche specificare i valori seguenti, come indicato.

Valore	Significato
MEM_LARGE_PAGES 0x20000000	Alloca memoria usando supporto di pagine di grandi dimensioni. Le dimensioni e l'allineamento devono essere un multiplo del minimo di pagina di grandi dimensioni. Per ottenere questo valore, usare la funzione GetLargePageMinimum. Se si specifica questo valore, è necessario specificare anche MEM_RESERVE e MEM_COMMIT.
MEM_PHYSICAL 0x00400000	Riserva un intervallo di indirizzi che può essere utilizzato per eseguire il mapping pagine delle estensioni di finestra degli indirizzi (AWE). Questo valore deve essere usato con MEM_RESERVE e nessun altro valore.
MEM_TOP_DOWN 0x00100000	Alloca la memoria al più alto indirizzo possibile. Questo può essere più lento rispetto alle allocazioni regolari, soprattutto quando sono presenti molte allocazioni.

Valore

Significato

MEM_LARGE_PAGES
0x20000000

Alloca memoria usando supporto di pagine di grandi dimensioni.

Le dimensioni e l'allineamento devono essere un multiplo del minimo di pagina di grandi dimensioni. Per ottenere questo valore, usare la funzione GetLargePageMinimum.

Se si specifica questo valore, è necessario specificare anche MEM_RESERVE e MEM_COMMIT.

MEM_PHYSICAL
0x00400000

Riserva un intervallo di indirizzi che può essere utilizzato per eseguire il mapping pagine delle estensioni di finestra degli indirizzi (AWE).

Questo valore deve essere usato con MEM_RESERVE e nessun altro valore.

MEM_TOP_DOWN
0x00100000

Alloca la memoria al più alto indirizzo possibile. Questo può essere più lento rispetto alle allocazioni regolari, soprattutto quando sono presenti molte allocazioni.

[in] flProtect

Protezione della memoria per l'area delle pagine da allocare. Se viene eseguito il commit delle pagine, è possibile specificare una delle costanti di protezione della memoria .

Se lpAddress specifica un indirizzo all'interno di un enclave, flProtect non può essere uno dei valori seguenti:

PAGE_NOACCESS
PAGE_GUARD
PAGE_NOCACHE
PAGE_WRITECOMBINE

Quando si alloca la memoria dinamica per un enclave, il parametro flProtect deve essere PAGE_READWRITE o PAGE_EXECUTE_READWRITE.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è l'indirizzo di base dell'area allocata delle pagine.

Se la funzione ha esito negativo, il valore restituito è NULL. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

Ogni pagina ha uno stato di pagina associato. La funzione VirtualAllocEx può eseguire le operazioni seguenti:

Eseguire il commit di un'area di pagine riservate
Riservare un'area di pagine gratuite
Riservare ed eseguire il commit simultaneo di un'area di pagine gratuite

VirtualAllocEx non può riservare una pagina riservata. Può eseguire il commit di una pagina già sottoposta a commit. Ciò significa che è possibile eseguire il commit di un intervallo di pagine, indipendentemente dal fatto che sia già stato eseguito il commit e che la funzione non abbia esito negativo.

È possibile usare VirtualAllocEx per riservare un blocco di pagine e quindi effettuare chiamate aggiuntive a VirtualAllocEx per eseguire il commit di singole pagine dal blocco riservato. Ciò consente a un processo di riservare un intervallo di spazio indirizzi virtuale senza consumare spazio di archiviazione fisico fino a quando non è necessario.

Se il parametro lpAddress non è NULL, la funzione usa i parametri lpAddress e dwSize per calcolare l'area delle pagine da allocare. Lo stato corrente dell'intero intervallo di pagine deve essere compatibile con il tipo di allocazione specificato dal parametro flAllocationType. In caso contrario, la funzione ha esito negativo e nessuna delle pagine viene allocata. Questo requisito di compatibilità non impedisce il commit di una pagina già sottoposta a commit; vedere l'elenco precedente.

Per eseguire codice generato in modo dinamico, usare VirtualAllocEx per allocare memoria e la funzione VirtualProtectEx per concedere l'accesso PAGE_EXECUTE.

La funzione VirtualAllocEx può essere usata per riservare un'area di address windowing extensions (AWE) di memoria all'interno dello spazio indirizzi virtuale di un processo specificato. Questa area di memoria può quindi essere usata per eseguire il mapping delle pagine fisiche all'interno e all'esterno della memoria virtuale in base alle esigenze dell'applicazione. I valori MEM_PHYSICAL e MEM_RESERVE devono essere impostati nel parametro AllocationType . Il valore MEM_COMMIT non deve essere impostato. La protezione della pagina deve essere impostata su PAGE_READWRITE.

La funzione VirtualFreeEx può decommettere una pagina di cui è stato eseguito il commit, rilasciare lo spazio di archiviazione della pagina oppure decommettere e rilasciare contemporaneamente una pagina di cui è stato eseguito il commit. Può anche rilasciare una pagina riservata, rendendola una pagina gratuita.

Quando si crea un'area eseguibile, il programma chiamante è responsabile della coerenza della cache tramite una chiamata appropriata a FlushInstructionCache una volta impostato il codice. In caso contrario, i tentativi di eseguire codice dall'area appena eseguibile possono produrre risultati imprevedibili.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	memoryapi.h (include Windows.h, Memoryapi.h)
libreria	onecore.lib
dll	Kernel32.dll