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 del 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
Se hFile è INVALID_HANDLE_VALUE, il processo chiamante deve inoltre specificare una dimensione per l'oggetto mapping di file nei parametri dwMaximumSizeHighHigh e dwMaximumSizeLow. In questo scenario, CreateFileMappingNuma 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.
[in, optional] lpFileMappingAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES che determina se un handle restituito può essere ereditato dai processi figlio. Membro del lpSecurityDescriptor di
SECURITY_ATTRIBUTES struttura specifica un descrittore di sicurezza per un nuovo oggetto di mapping di file.
Se lpFileMappingAttributes è NULL, l'handle non può essere ereditato e l'oggetto di mapping dei 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 File Mapping Security and Access Rights.
[in] flProtect
Specifica la protezione della pagina dell'oggetto di mapping file. Tutte le viste mappate dell'oggetto devono essere compatibili con questa protezione.
Questo parametro può essere uno dei valori seguenti.
Un'applicazione può specificare uno o più degli attributi seguenti per l'oggetto di mapping dei 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.
Questa è l'impostazione predefinita. |
|
Imposta il file specificato come 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. |
|
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 del driver registrati usando l'API del kernel PsSetLoadImageNotifyRou tine.
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 l'uso di 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 normali. Assicurarsi di specificare la dimensione massima dell'oggetto di mapping file come dimensione minima di una pagina di grandi dimensioni segnalata dalla funzione GetLargePageMinimum |
|
Imposta tutte le pagine su non selezionabile.
Le applicazioni non devono usare questo flag tranne quando richiesto in modo esplicito per un dispositivo. L'uso delle funzioni interlock con memoria mappata a SEC_NOCACHE può comportare un'eccezione EXCEPTION_ILLEGAL_INSTRUCTION. SEC_NOCACHE deve essere impostato SEC_RESERVE o SEC_COMMIT. |
|
Riserva tutte le pagine senza allocare spazio di archiviazione fisico.
L'intervallo riservato di pagine non può essere utilizzato da altre operazioni di allocazione fino al rilascio dell'intervallo di pagine. Le pagine riservate possono essere identificate nelle chiamate successive alla funzione VirtualAllocExNuma |
|
Imposta tutte le pagine da combinare in scrittura.
Le applicazioni non devono usare questo attributo tranne quando sono esplicitamente necessarie per un dispositivo. L'uso delle funzioni interlocked con memoria mappata a SEC_WRITECOMBINE può comportare un'eccezione EXCEPTION_ILLEGAL_INSTRUCTION. SEC_WRITECOMBINE deve essere impostato l'attributo SEC_RESERVE o SEC_COMMIT. |
[in] dwMaximumSizeHigh
L'ordine elevato DWORD delle dimensioni massime dell'oggetto di mapping dei file.
[in] dwMaximumSizeLow
L'DWORD in ordine basso delle dimensioni massime dell'oggetto di mapping dei file.
Se questo parametro e il parametro
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 di file esistente, la funzione richiede l'accesso all'oggetto con la protezione specificata dal parametro flProtect.
Se questo parametro è NULL, l'oggetto di 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 di mapping di file nello spazio dei nomi globale richiede il privilegio SeCreateGlobalPrivilege. Per altre informazioni, vedere spazi dei nomi dell'oggetto kernel .
Il passaggio rapido degli utenti viene implementato tramite 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 (uno) e così via. I nomi degli oggetti del kernel devono seguire le linee guida in modo che le applicazioni possano supportare più utenti.
[in] nndPreferred
Nodo NUMA in cui deve risiedere la memoria fisica.
| Valore | Significato |
|---|---|
|
Non è preferibile alcun nodo NUMA. Equivale a chiamare la funzione CreateFileMapping |
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto di mapping del file.
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 la funzione GetLastError restituisce ERROR_ALREADY_EXISTS.
Se la funzione ha esito negativo, il valore restituito è NULL. Per ottenere informazioni estese sull'errore, chiamare la funzione GetLastError
Osservazioni
Dopo aver creato un oggetto di mapping dei file, le dimensioni del file non devono superare le dimensioni dell'oggetto di mapping dei file; in caso contrario, non tutti i contenuti del file sono disponibili per la condivisione.
L'oggetto di mapping dei file può essere condiviso tramite duplicazione, ereditarietà o nome. Il contenuto iniziale delle pagine in un oggetto di mapping di file supportato dal file di pagina è 0 (zero).
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 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 non può essere aumentato, il risultato è un errore durante la creazione dell'oggetto di mapping del 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 per un oggetto di mapping di file. Un oggetto di mapping di file può essere condiviso tramite la creazione del processo, la duplicazione dell'handle o il nome. Per altre informazioni, vedere le funzioni di DuplicateHandle
La creazione di un oggetto di 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 di mapping di file sono coerenti o identici in un momento specifico. Se più processi hanno handle dello stesso oggetto di mapping di file, visualizzano una visualizzazione coerente dei dati quando eseguono il mapping di una visualizzazione del file.
L'eccezione è correlata ai file remoti. Anche se la funzione CreateFileMappingNuma
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 di mapping di file, un'applicazione deve rimuovere il mapping di tutte le visualizzazioni mappate dell'oggetto di mapping file chiamando la funzione
Queste funzioni possono essere chiamate in qualsiasi ordine. La chiamata alla funzione UnmapViewOfFile è necessaria, perché le visualizzazioni mappate di un oggetto di mapping di file mantengono handle aperti interni all'oggetto e un oggetto di mapping dei file non si chiude finché non vengono chiusi tutti gli handle aperti.
Quando si modifica un file tramite una visualizzazione mappata, il timestamp dell'ultima modifica potrebbe non essere aggiornato automaticamente. Se necessario, il chiamante deve usare SetFileTime per impostare il timestamp.
La creazione di un oggetto di 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 di file e non si applica all'apertura di quelli esistenti. Ad esempio, se un servizio o il sistema crea un oggetto di mapping di file, qualsiasi processo in esecuzione in qualsiasi sessione può accedere a tale oggetto di mapping di file purché il chiamante disponga dei diritti di accesso necessari.
Usare la gestione delle eccezioni strutturate per proteggere qualsiasi codice che scrive o legge da una vista 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 | Sostenuto |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| SMB 3.0 Transparent Failover (TFO) | Sì |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | Sì |
| Cluster Shared Volume File System (CsvFS) | Sì |
| Resilient File System (ReFS) | Sì |
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows Vista [solo app desktop] |
| server minimo supportato | Windows Server 2008 [solo app desktop] |
| piattaforma di destinazione | Finestre |
| intestazione |
memoryapi.h (include Windows.h, Memoryapi.h) |
| libreria |
onecore.lib |
| dll | Kernel32.dll |