Funzione CreateFileMappingA (winbase.h)
Crea o apre un oggetto di mapping di file denominato o senza nome per un file specificato.
Per specificare il nodo NUMA per la memoria fisica, vedere CreateFileMappingNuma.
Sintassi
HANDLE CreateFileMappingA(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCSTR lpName
);
Parametri
[in] hFile
Handle per il file da cui creare un oggetto mapping 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 che si intende eseguire il mapping vengano aperti per l'accesso esclusivo. Per altre informazioni, vedere Sicurezza file e diritti di accesso.
Se hFile è INVALID_HANDLE_VALUE, il processo chiamante deve specificare anche una dimensione per l'oggetto mapping di file nel parametro dwMaximumSizeHigh e dwMaximumSizeLow. In questo scenario CreateFileMapping crea un oggetto di mapping di file di dimensioni specificate supportato dal file di paging del sistema anziché da un file nel file system.
[in, optional] lpFileMappingAttributes
Puntatore a una struttura 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 dei file.
Se lpFileMappingAttributes è NULL, l'handle non può essere ereditato e l'oggetto mapping di file ottiene un descrittore di sicurezza predefinito. Gli elenchi di controllo di accesso (ACL) nel descrittore di sicurezza predefinito per un oggetto di mapping file provengono dal token primario o di rappresentazione dell'autore. Per altre informazioni, vedere Sicurezza mapping file e diritti di accesso.
[in] flProtect
Specifica la protezione della pagina dell'oggetto mapping dei file. Tutte le viste mappate dell'oggetto devono essere compatibili con questa protezione.
Questo parametro può avere uno dei valori seguenti.
Un'applicazione può specificare uno o più degli attributi seguenti per l'oggetto mapping di file combinandoli con uno dei valori di protezione della pagina precedenti.
| Valore | Significato |
|---|---|
|
Se l'oggetto mapping file è supportato dal file di paging del sistema operativo (il parametro hfile è INVALID_HANDLE_VALUE), specifica che quando viene mappata una visualizzazione del file in uno spazio indirizzi del processo, l'intero intervallo di pagine viene eseguito il commit 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, viene assunto SEC_COMMIT . |
|
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 pagina, ad esempio PAGE_READONLY. Tuttavia, questo valore di protezione 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. |
|
Specifica che il file specificato dal parametro hFile è un file di immagine eseguibile che non verrà eseguito e il file immagine caricato non avrà alcun controllo di integrità forzato.
Inoltre, il mapping di una visualizzazione di un oggetto mapping di file creato con l'attributo SEC_IMAGE_NO_EXECUTE non richiama 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. |
|
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 dei 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 dei 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, l'indirizzo di base e le dimensioni della visualizzazione devono essere anche più delle dimensioni minime di pagina di grandi dimensioni. SEC_LARGE_PAGES richiede l'abilitazione del privilegio SeLockMemoryPrivilege nel token del chiamante. Se viene specificato SEC_LARGE_PAGES , è necessario specificare anche SEC_COMMIT . Windows Server 2003: Questo valore non è supportato finché Windows Server 2003 con SP1. Windows XP: Questo valore non è supportato. |
|
Imposta tutte le pagine da non memorizzare nella cache.
Le applicazioni non devono usare questo attributo tranne quando è necessario in modo esplicito per un dispositivo. L'uso delle funzioni interlock con memoria mappata con SEC_NOCACHE può causare un'eccezione EXCEPTION_ILLEGAL_INSTRUCTION . SEC_NOCACHE richiede che sia impostato l'attributo SEC_RESERVE o SEC_COMMIT . |
|
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. |
|
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. |
[in] dwMaximumSizeHigh
DWORD di ordine elevato della dimensione massima dell'oggetto di mapping del file.
[in] dwMaximumSizeLow
DWORD in ordine basso delle dimensioni massime dell'oggetto di mapping del file.
Se questo parametro e dwMaximumSizeHigh sono 0 (zero), le dimensioni massime dell'oggetto di mapping del file sono uguali alle dimensioni correnti 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. Le applicazioni devono verificare la disponibilità di file con una lunghezza pari a 0 (zero) e rifiutare tali file.
[in, optional] lpName
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.
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
Dopo la creazione di un oggetto di mapping dei file, le dimensioni del file non devono superare le dimensioni dell'oggetto di mapping del file; in caso contrario, non tutti i contenuti del file sono disponibili per la condivisione.
Se un'applicazione specifica una dimensione per l'oggetto di mapping di file maggiore delle dimensioni del file denominato effettivo su disco e se la protezione della pagina consente l'accesso in scrittura( ovvero, il parametro flProtect specifica PAGE_READWRITE o PAGE_EXECUTE_READWRITE), il file su disco viene aumentato in modo da corrispondere alle dimensioni specificate dell'oggetto di mapping del file. Se il file viene esteso, il contenuto del file tra la fine precedente del file e la nuova fine del file non è garantito che sia zero; il comportamento è definito dal file system. Se il file su disco non può essere aumentato, CreateFileMapping ha esito negativo e GetLastError restituisce ERROR_DISK_FULL.
Il contenuto iniziale delle pagine in un oggetto di mapping di file supportato dal file di paging del sistema operativo è 0 (zero).
L'handle restituito da CreateFileMapping ha accesso completo a un nuovo oggetto di mapping di file e può essere usato con qualsiasi funzione che richiede un handle per un oggetto di mapping di file.
Più processi possono condividere una visualizzazione dello stesso file usando un singolo oggetto mapping di file condiviso o creando oggetti di mapping di file separati supportati dallo stesso file. Un singolo oggetto di mapping di file può essere condiviso da più processi tramite l'ereditarietà dell'handle durante la creazione del processo, la duplicazione dell'handle o l'apertura dell'oggetto di mapping del file in base al nome. Per altre informazioni, vedere le funzioni CreateProcess, DuplicateHandle e OpenFileMapping .
La creazione di un oggetto di mapping di file non esegue effettivamente il mapping della visualizzazione in uno spazio indirizzi del processo. Le funzioni MapViewOfFile e MapViewOfFileEx eseguono il mapping di una visualizzazione di un file in uno spazio indirizzi del processo.
Con un'eccezione importante, le visualizzazioni file derivate da qualsiasi oggetto di mapping di file supportato dallo stesso file sono coerenti o identici in un momento specifico. La coerenza è garantita per le visualizzazioni all'interno di un processo e per le visualizzazioni mappate da processi diversi.
L'eccezione è correlata ai file remoti. Anche se CreateFileMapping funziona con i file remoti, non li mantiene coerenti. Ad esempio, se due computer eseguono il mapping di un file come scrivibile e entrambi modificano la stessa pagina, ogni computer vede solo le proprie scritture nella pagina. Quando i dati vengono aggiornati sul disco, non vengono uniti.
Un file mappato e un file a cui si accede usando le funzioni di input e output (I/O) (ReadFile e WriteFile) non sono necessariamente coerenti.
Le visualizzazioni mappate di un oggetto di mapping di file mantengono riferimenti interni all'oggetto e un oggetto di mapping di file non viene chiuso finché non vengono rilasciati tutti i riferimenti. Pertanto, per chiudere completamente un oggetto di mapping di file, un'applicazione deve annullare il mapping di tutte le visualizzazioni mappate dell'oggetto di mapping file chiamando UnmapViewOfFile e chiudere l'handle dell'oggetto di mapping file chiamando CloseHandle. Queste funzioni possono essere chiamate in qualsiasi ordine.
Quando si modifica un file tramite una visualizzazione mappata, è possibile che il timestamp dell'ultima modifica non venga aggiornato automaticamente. Se necessario, il chiamante deve usare SetFileTime per impostare il timestamp.
La creazione di un oggetto mapping di file nello spazio dei nomi globale da una sessione diversa da session zero richiede il privilegio SeCreateGlobalPrivilege . Si noti che questo controllo dei privilegi è limitato alla creazione di oggetti di mapping dei file e non si applica all'apertura di quelli esistenti. Ad esempio, se un servizio o il sistema crea un oggetto mapping di file nello spazio dei nomi globale, qualsiasi processo in esecuzione in qualsiasi sessione può accedere a tale oggetto di mapping dei file a condizione che il chiamante disponga dei diritti di accesso necessari.
Windows XP: Il requisito descritto nel paragrafo precedente è stato introdotto con Windows Server 2003 e Windows XP con SP2
Usare la gestione delle eccezioni strutturate per proteggere qualsiasi codice che scrive o legge da una visualizzazione file. Per altre informazioni, vedere Lettura e scrittura da una visualizzazione file.
Per avere un mapping con autorizzazioni eseguibili, un'applicazione deve chiamare CreateFileMapping con PAGE_EXECUTE_READWRITE o PAGE_EXECUTE_READ, quindi chiamare MapViewOfFile con FILE_MAP_EXECUTE | FILE_MAP_WRITE o FILE_MAP_EXECUTE | FILE_MAP_READ.
In Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | Sì |
| SMB 3.0 con condivisioni file di scalabilità orizzontale (SO) | Sì |
| File system del volume condiviso cluster (CsvFS) | Sì |
| Resilient File System (ReFS) | Sì |
Esempi
Per un esempio, vedere Creazione di una memoria condivisa denominata o Creazione di un mapping di file tramite pagine di grandi dimensioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winbase.h (include Windows.h, Memoryapi.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |
Vedere anche
Creazione di un oggetto mapping di file
Funzioni di mapping dei file