Funzione CreateFileMapping2 (memoryapi.h)

Articolo
08/24/2023

Crea o apre un oggetto di mapping di file denominato o senza nome per un file specificato. È possibile specificare un nodo NUMA preferito per la memoria fisica come parametro esteso; vedere il parametro ExtendedParameters .

Sintassi

HANDLE CreateFileMapping2(
  HANDLE                 File,
  SECURITY_ATTRIBUTES    *SecurityAttributes,
  ULONG                  DesiredAccess,
  ULONG                  PageProtection,
  ULONG                  AllocationAttributes,
  ULONG64                MaximumSize,
  PCWSTR                 Name,
  MEM_EXTENDED_PARAMETER *ExtendedParameters,
  ULONG                  ParameterCount
);

Parametri

File

Tipo: _In_ HANDLE

Handle al file da cui creare un oggetto di mapping di file.

Il file deve essere aperto con diritti di accesso compatibili con i flag di protezione specificati dal parametro flProtect . Non è obbligatorio, ma è consigliabile che i file di cui si intende eseguire il mapping vengano aperti per l'accesso esclusivo. Per altre informazioni, vedere Protezione dei file e diritti di accesso.

Se hFile è INVALID_HANDLE_VALUE, il processo chiamante deve specificare anche una dimensione per l'oggetto di mapping dei file nei parametri dwMaximumSizeHigh e dwMaximumSizeLow . In questo scenario CreateFileMapping crea un oggetto di mapping di file di una dimensione specificata supportata dal file di paging di sistema anziché da un file nel file system.

SecurityAttributes

Tipo: _In_opt_ SECURITY_ATTRIBUTES*

Puntatore a una struttura di SECURITY_ATTRIBUTES che determina se un handle restituito può essere ereditato dai processi figlio. Il membro lpSecurityDescriptor della struttura SECURITY_ATTRIBUTES specifica un descrittore di sicurezza per un nuovo oggetto di mapping di file.

Se lpAttributes è NULL, l'handle non può essere ereditato e l'oggetto mapping file ottiene un descrittore di sicurezza predefinito. Gli elenchi di controllo di accesso (ACL) nel descrittore di sicurezza predefinito per un oggetto di mapping dei file provengono dal token primario o di rappresentazione dell'autore. Per altre informazioni, vedere Sicurezza e diritti di accesso per mapping dei file.

DesiredAccess

Tipo: _In_ ULONG

Maschera di accesso desiderata per l'handle di mapping dei file restituito. Per un elenco dei diritti di accesso, vedere Sicurezza e diritti di accesso per mapping dei file.

PageProtection

Tipo: _In_ ULONG

Specifica la protezione della pagina dell'oggetto di mapping dei file. Tutte le viste mappate dell'oggetto devono essere compatibili con questa protezione.

Questo parametro può avere uno dei valori seguenti.

Valore	Significato
PAGE_EXECUTE_READ 0x20	Consente di eseguire il mapping delle visualizzazioni per l'accesso in sola lettura, copia su scrittura o esecuzione. L'handle di file specificato dal parametro hFile deve essere creato con i diritti di accesso GENERIC_READ e GENERIC_EXECUTE . Windows Server 2003 e Windows XP: Questo valore non è disponibile fino a quando Windows XP con SP2 e Windows Server 2003 con SP1.
PAGE_EXECUTE_READWRITE 0x40	Consente di eseguire il mapping delle visualizzazioni per l'accesso in sola lettura, copia su scrittura, lettura/scrittura o esecuzione. L'handle di file specificato dal parametro hFile deve essere creato con i diritti di accesso GENERIC_READ, GENERIC_WRITE e GENERIC_EXECUTE . Windows Server 2003 e Windows XP: Questo valore non è disponibile fino a quando Windows XP con SP2 e Windows Server 2003 con SP1.
PAGE_EXECUTE_WRITECOPY 0x80	Consente di eseguire il mapping delle visualizzazioni per l'accesso in sola lettura, copia su scrittura o esecuzione. Questo valore equivale a PAGE_EXECUTE_READ. L'handle di file specificato dal parametro hFile deve essere creato con i diritti di accesso GENERIC_READ e GENERIC_EXECUTE . Windows Vista: Questo valore non è disponibile fino a quando Windows Vista con SP1. Windows Server 2003 e Windows XP: Questo valore non è supportato.
PAGE_READONLY 0x02	Consente di eseguire il mapping delle visualizzazioni per l'accesso in sola lettura o copia in scrittura. Un tentativo di scrittura in un'area specifica comporta una violazione di accesso. L'handle di file specificato dal parametro hFile deve essere creato con il diritto di accesso GENERIC_READ.
PAGE_READWRITE 0x04	Consente di eseguire il mapping delle visualizzazioni per l'accesso in sola lettura, copia su scrittura o lettura/scrittura. L'handle di file specificato dal parametro hFile deve essere creato con i diritti di accesso GENERIC_READ e GENERIC_WRITE .
PAGE_WRITECOPY 0x08	Consente di eseguire il mapping delle visualizzazioni per l'accesso in sola lettura o copia in scrittura. Questo valore equivale a PAGE_READONLY. L'handle di file specificato dal parametro hFile deve essere creato con il diritto di accesso GENERIC_READ.

AllocationAttributes

Tipo: _In_ ULONG

È possibile specificare uno o più degli attributi seguenti per l'oggetto di mapping dei file. Vedere anche il parametro PageProtection .

Valore	Significato
SEC_COMMIT 0x8000000	Se l'oggetto di mapping dei file è supportato dal file di paging del sistema operativo (il parametro hfile è INVALID_HANDLE_VALUE), specifica che quando viene eseguito il mapping di una visualizzazione del file in uno spazio indirizzi del processo, viene eseguito il commit dell'intero intervallo di pagine anziché riservato. Il sistema deve disporre di pagine commit sufficienti per contenere l'intero mapping. In caso contrario, CreateFileMapping ha esito negativo. Questo attributo non ha alcun effetto per gli oggetti di mapping dei file supportati da file di immagine eseguibili o file di dati (il parametro hfile è un handle per un file). SEC_COMMIT non può essere combinato con SEC_RESERVE. Se non viene specificato alcun attributo, si presuppone SEC_COMMIT .
SEC_IMAGE 0x1000000	Specifica che il file specificato dal parametro hFile è un file di immagine eseguibile. L'attributo SEC_IMAGE deve essere combinato con un valore di protezione della pagina, ad esempio PAGE_READONLY. Tuttavia, questo valore di protezione della pagina non ha alcun effetto sulle visualizzazioni del file di immagine eseguibile. La protezione delle pagine per le visualizzazioni di un file di immagine eseguibile è determinata dal file eseguibile stesso. Nessun altro attributo è valido con SEC_IMAGE.
SEC_IMAGE_NO_EXECUTE 0x11000000	Specifica che il file specificato dal parametro hFile è un file di immagine eseguibile che non verrà eseguito e che il file di immagine caricato non avrà alcun controllo di integrità forzato. Inoltre, il mapping di una visualizzazione di un oggetto di mapping di file creato con l'attributo SEC_IMAGE_NO_EXECUTE non richiamerà i callback driver registrati usando l'API kernel PsSetLoadImageNotifyRoutine . L'attributo SEC_IMAGE_NO_EXECUTE deve essere combinato con il valore di protezione della pagina PAGE_READONLY. Nessun altro attributo è valido con SEC_IMAGE_NO_EXECUTE. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato prima di Windows Server 2012 e Windows 8.
SEC_LARGE_PAGES 0x80000000	Consente l'uso di pagine di grandi dimensioni per gli oggetti di mapping dei file supportati dal file di paging del sistema operativo (il parametro hfile è INVALID_HANDLE_VALUE). Questo attributo non è supportato per gli oggetti di mapping di file supportati da file di immagine eseguibili o file di dati (il parametro hFile è un handle per un'immagine eseguibile o un file di dati). La dimensione massima dell'oggetto di mapping del file deve essere un multiplo delle dimensioni minime di una pagina di grandi dimensioni restituita dalla funzione GetLargePageMinimum . In caso contrario, CreateFileMapping ha esito negativo. Quando si esegue il mapping di una visualizzazione di un oggetto di mapping di file creato con SEC_LARGE_PAGES, anche l'indirizzo di base e le dimensioni della vista devono essere multipli delle dimensioni minime della pagina di grandi dimensioni. SEC_LARGE_PAGES richiede che il privilegio SeLockMemoryPrivilege sia abilitato nel token del chiamante. Se si specifica SEC_LARGE_PAGES , è necessario specificare anche SEC_COMMIT . Windows Server 2003: Questo valore non è supportato fino a Windows Server 2003 con SP1. Windows XP: Questo valore non è supportato.
SEC_NOCACHE 0x10000000	Imposta tutte le pagine come non memorizzabili nella cache. Le applicazioni non devono usare questo attributo tranne quando è esplicitamente richiesto per un dispositivo. L'uso delle funzioni interlock con memoria mappata a SEC_NOCACHE può generare un'eccezione EXCEPTION_ILLEGAL_INSTRUCTION . SEC_NOCACHE deve essere impostato l'attributo SEC_RESERVE o SEC_COMMIT .
SEC_RESERVE 0x4000000	Se l'oggetto di mapping dei file è supportato dal file di paging del sistema operativo (il parametro hfile è INVALID_HANDLE_VALUE), specifica che quando viene eseguito il mapping di una visualizzazione del file in uno spazio indirizzi del processo, l'intero intervallo di pagine viene riservato per un uso successivo da parte del processo anziché il commit. È possibile eseguire il commit delle pagine riservate nelle chiamate successive alla funzione VirtualAlloc . Dopo il commit delle pagine, non possono essere liberati o decommessi con la funzione VirtualFree . Questo attributo non ha alcun effetto per gli oggetti di mapping dei file supportati da file di immagine eseguibili o file di dati (il parametro hfile è un handle per un file). SEC_RESERVE non può essere combinato con SEC_COMMIT.
SEC_WRITECOMBINE 0x40000000	Imposta tutte le pagine da combinare in scrittura. Le applicazioni non devono usare questo attributo tranne quando è esplicitamente richiesto per un dispositivo. L'uso delle funzioni interlock con memoria mappata a SEC_WRITECOMBINE può generare un'eccezione EXCEPTION_ILLEGAL_INSTRUCTION . SEC_WRITECOMBINE deve essere impostato l'attributo SEC_RESERVE o SEC_COMMIT . Windows Server 2003 e Windows XP: Questo flag non è supportato fino a Windows Vista.

MaximumSize

Tipo: _In_ ULONG64

Dimensione massima dell'oggetto di mapping del file.

Se questo parametro è 0 (zero), la dimensione massima dell'oggetto di mapping del file è uguale alla dimensione corrente del file identificato da hFile .

Un tentativo di eseguire il mapping di un file con una lunghezza pari a 0 (zero) ha esito negativo con un codice di errore di ERROR_FILE_INVALID. È consigliabile testare i file con una lunghezza pari a 0 (zero) e rifiutare tali file.

Name

Tipo: _In_opt_ PCWSTR

Nome dell'oggetto di mapping del file.

Se questo parametro corrisponde al nome di un oggetto di mapping esistente, la funzione richiede l'accesso all'oggetto con la protezione specificata da flProtect .

Se questo parametro è NULL, l'oggetto di mapping file viene creato senza un nome.

Se lpName corrisponde al nome di un evento esistente, semaforo, mutex, timer waitable o oggetto processo, la funzione ha esito negativo e la funzione GetLastError restituisce ERROR_INVALID_HANDLE. Ciò si verifica perché questi oggetti condividono lo stesso spazio dei nomi.

Il nome può avere un prefisso "Global" o "Local" per creare in modo esplicito l'oggetto nello spazio dei nomi globale o sessione. Il resto del nome può contenere qualsiasi carattere ad eccezione del carattere barra rovesciata (\). La creazione di un oggetto mapping di file nello spazio dei nomi globale da una sessione diversa da session zero richiede il privilegio SeCreateGlobalPrivilege . Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel.

Il passaggio rapido degli utenti viene implementato usando le sessioni di Servizi terminal. Il primo utente a eseguire l'accesso usa la sessione 0 (zero), l'utente successivo a cui accedere usa la sessione 1 (uno) e così via. I nomi degli oggetti del kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.

ExtendedParameters

Tipo: _Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*

Puntatore facoltativo a uno o più parametri estesi di tipo MEM_EXTENDED_PARAMETER. Ognuno di questi valori di parametro estesi può avere un campo Type di MemExtendedParameterAddressRequirements o MemExtendedParameterNumaNode. Se non viene fornito alcun parametro esteso MemExtendedParameterNumaNode , il comportamento corrisponde a quello delle funzioni VirtualAlloc/MapViewOfFile , ovvero il nodo NUMA preferito per le pagine fisiche viene determinato in base al processore ideale del thread che accede prima alla memoria.

ParameterCount

Pollici ULONG ParameterCount

Numero di parametri estesi a cui punta ExtendedParameters.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto di mapping di file appena creato.

Se l'oggetto esiste prima della chiamata di funzione, la funzione restituisce un handle all'oggetto esistente (con le dimensioni correnti, non le dimensioni specificate) e GetLastError restituisce ERROR_ALREADY_EXISTS.

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

Commenti

Vedere la sezione Osservazioni per CreateFileMapping.

Esempio

Per un esempio, vedere Creazione di una memoria condivisa denominata o Creazione di un mapping di file tramite pagine di grandi dimensioni.

Requisiti


Client minimo supportato	Windows 10 Build 20348
Server minimo supportato	Windows 10 Build 20348
Piattaforma di destinazione	Windows
Intestazione	memoryapi.h (include Windows.h, Memoryapi.h)
Libreria	onecore.lib
DLL	Kernel32.dll