Funzione CreateFileMappingNumaW (memoryapi.h)
Crea o apre un oggetto di mapping di file denominato o senza nome per un file specificato e specifica il nodo NUMA per la memoria fisica.
Sintassi
HANDLE CreateFileMappingNumaW(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCWSTR lpName,
[in] DWORD nndPreferred
);
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 , CreateFileMappingNuma crea un oggetto 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. Membro lpSecurityDescriptor dell'oggetto
SECURITY_ATTRIBUTES struttura specifica un descrittore di sicurezza per un nuovo oggetto di mapping 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 |
|---|---|
|
Alloca l'archiviazione fisica in memoria o il file di paging per tutte le pagine.
Si tratta dell'impostazione predefinita. |
|
Imposta il file specificato per essere 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 e Windows Vista: Questo valore non è supportato prima di Windows Server 2012 e Windows 8. |
|
Consente di usare pagine di grandi dimensioni durante il mapping di immagini o il backup dal file di pagina, ma non quando si esegue il mapping dei dati per i file regolari. Assicurarsi di specificare le dimensioni massime dell'oggetto mapping file come dimensione minima di una pagina di grandi dimensioni segnalata dalla funzione GetLargePageMinimum e per abilitare il privilegio SeLockMemoryPrivilege . |
|
Imposta tutte le pagine su non incachable.
Le applicazioni non devono usare questo flag 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 SEC_RESERVE o SEC_COMMIT da impostare. |
|
Riserva tutte le pagine senza allocare l'archiviazione fisica.
L'intervallo riservato di pagine non può essere usato da altre operazioni di allocazione finché non viene rilasciato l'intervallo di pagine. Le pagine riservate possono essere identificate nelle chiamate successive alla funzione VirtualAllocExNuma . Questo attributo è valido solo se il parametro hFile è INVALID_HANDLE_VALUE , ovvero un oggetto mapping di file supportato dal file di paging del sistema. |
|
Imposta tutte le pagine da combinare in scrittura.
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_WRITECOMBINE può causare un'eccezione EXCEPTION_ILLEGAL_INSTRUCTION . SEC_WRITECOMBINE richiede che sia impostato l'attributo SEC_RESERVE o SEC_COMMIT . |
[in] dwMaximumSizeHigh
DWORD con ordine elevato delle dimensioni massime dell'oggetto di mapping dei file.
[in] dwMaximumSizeLow
DWORD a basso ordine delle dimensioni massime dell'oggetto di mapping dei file.
Se questo parametro e il parametro dwMaximumSizeHigh sono 0 (zero), la dimensione massima dell'oggetto mapping file è uguale alla dimensione corrente del file identificata dal parametro 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 testare i file con lunghezza pari a 0 (zero) e rifiutare tali file.
[in, optional] lpName
Nome dell'oggetto mapping file.
Se questo parametro corrisponde al nome di un oggetto di mapping file esistente, la funzione richiede l'accesso all'oggetto con la protezione specificata dal parametro flProtect .
Se questo parametro è NULL, l'oggetto mapping file viene creato senza un nome.
Se il parametro lpName corrisponde al nome di un evento esistente, semaforo, mutex, timer in attesa 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 richiede il privilegio SeCreateGlobalPrivilege . Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel.
Il passaggio rapido dell'utente viene implementato usando sessioni di Servizi terminal. Il primo utente a eseguire l'accesso usa la sessione 0 (zero), l'utente successivo per accedere usa la sessione 1 (una) e così via. I nomi degli oggetti kernel devono seguire le linee guida in modo che le applicazioni possano supportare più utenti.
[in] nndPreferred
Nodo NUMA in cui risiede la memoria fisica.
| Valore | Significato |
|---|---|
|
Nessun nodo NUMA è preferito. Si tratta dello stesso modo di chiamare la funzione CreateFileMapping . |
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto mapping di file.
Se l'oggetto esiste prima della chiamata alla funzione, la funzione restituisce un handle all'oggetto esistente (con le dimensioni correnti, non le dimensioni specificate) e la funzione GetLastError restituisce ERROR_ALREADY_EXISTS.
Se la funzione ha esito negativo, il valore restituito è NULL. Per ottenere informazioni sull'errore estese, chiamare la funzione GetLastError .
Commenti
Dopo la creazione di un oggetto mapping di file, le dimensioni del file non devono superare le dimensioni dell'oggetto mapping file; se lo fa, non tutti i contenuti del file sono disponibili per la condivisione.
L'oggetto di mapping dei file può essere condiviso dalla duplicazione, dall'ereditarietà o dal nome. Il contenuto iniziale delle pagine in un oggetto di mapping dei file supportato dal file di pagina è 0 (zero).
Se un'applicazione specifica una dimensione per l'oggetto mapping di file maggiore rispetto alle dimensioni del file denominato effettivo sul 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 sul disco viene aumentato in modo da corrispondere alle dimensioni specificate dell'oggetto mapping file. Se il file viene esteso, il contenuto del file tra la fine precedente del file e la nuova fine del file non è garantito zero; il comportamento è definito dal file system.
Se il file non può essere aumentato, il risultato non riesce a creare l'oggetto mapping file e la funzione GetLastError restituisce ERROR_DISK_FULL.
L'handle restituito dalla funzione CreateFileMappingNuma ha accesso completo a un nuovo oggetto di mapping di file e può essere usato con qualsiasi funzione che richiede un handle a un oggetto mapping di file. Un oggetto mapping di file può essere condiviso tramite la creazione del processo, la duplicazione dell'handle o il nome. Per altre informazioni, vedere le funzioni DuplicateHandle e OpenFileMapping .
La creazione di un oggetto mapping di file crea il potenziale per il mapping di una visualizzazione del file, ma non esegue il mapping della visualizzazione. La funzione MapViewOfFileExNuma esegue il mapping di una visualizzazione di un file in uno spazio indirizzi del processo.
Con un'eccezione importante, le visualizzazioni file derivate da un singolo oggetto mapping di file sono coerenti o identiche in un momento specifico. Se più processi hanno handle dello stesso oggetto di mapping dei file, visualizzano una visualizzazione coerente dei dati quando mappano una visualizzazione del file.
L'eccezione è correlata ai file remoti. Anche se la funzione CreateFileMappingNuma funziona con 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 visualizza solo le proprie scritture nella pagina. Quando i dati vengono aggiornati sul disco, la pagina non viene unita.
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.
Per chiudere completamente un oggetto mapping di file, un'applicazione deve annullare il mapping di tutte le visualizzazioni mappate dell'oggetto mapping file chiamando la funzione UnmapViewOfFile e quindi chiudere l'handle dell'oggetto mapping dei file chiamando la funzione CloseHandle .
Queste funzioni possono essere chiamate in qualsiasi ordine. La chiamata alla funzione UnmapViewOfFile è necessaria, perché le visualizzazioni mappate di un oggetto mapping di file mantengono handle aperti interni all'oggetto e un oggetto mapping di file non viene chiuso finché non vengono chiusi tutti gli handle aperti.
Quando si modifica un file tramite una visualizzazione mappata, l'ultimo timestamp di modifica potrebbe non essere aggiornato automaticamente. Se necessario, il chiamante deve usare SetFileTime per impostare il timestamp.
La creazione di un oggetto mapping di file 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 di mapping dei file, qualsiasi processo in esecuzione in qualsiasi sessione può accedere a tale oggetto mapping di file, purché il chiamante disponga dei diritti di accesso necessari.
Usare la gestione delle eccezioni strutturate per proteggere qualsiasi codice che scrive in o legge da una visualizzazione mappata alla memoria. Per altre informazioni, vedere Lettura e scrittura da una visualizzazione file.
Per avere un mapping con autorizzazioni eseguibili, un'applicazione deve chiamare la funzione CreateFileMappingNuma con PAGE_EXECUTE_READWRITE o PAGE_EXECUTE_READ e quindi chiamare la funzione MapViewOfFileExNuma 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 con scalabilità orizzontale (SO) | Sì |
| File system del volume condiviso del cluster (CsvFS) | Sì |
| File system resiliente (ReFS) | Sì |
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | memoryapi.h (includono Windows.h, Memoryapi.h) |
| Libreria | onecore.lib |
| DLL | Kernel32.dll |