Fonction CreateFileMappingNumaA (winbase.h)

Crée ou ouvre un objet de mappage de fichiers nommé ou non nommé pour un fichier spécifié et spécifie le nœud NUMA pour la mémoire physique.

Syntaxe

HANDLE CreateFileMappingNumaA(
  [in]           HANDLE                hFile,
  [in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
  [in]           DWORD                 flProtect,
  [in]           DWORD                 dwMaximumSizeHigh,
  [in]           DWORD                 dwMaximumSizeLow,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 nndPreferred
);

Paramètres

[in] hFile

Handle du fichier à partir duquel créer un objet de mappage de fichiers.

Le fichier doit être ouvert avec des droits d’accès compatibles avec les indicateurs de protection spécifiés par le paramètre flProtect . Il n’est pas obligatoire, mais il est recommandé d’ouvrir les fichiers que vous envisagez de mapper pour un accès exclusif. Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.

Si hFile est INVALID_HANDLE_VALUE, le processus appelant doit également spécifier une taille pour l’objet de mappage de fichiers dans les paramètres dwMaximumSizeHigh et dwMaximumSizeLow . Dans ce scénario, CreateFileMappingNuma crée un objet de mappage de fichiers d’une taille spécifiée qui est sauvegardé par le fichier de pagination système au lieu d’un fichier dans le système de fichiers.

[in, optional] lpFileMappingAttributes

Pointeur vers une structure de SECURITY_ATTRIBUTES qui détermine si un handle retourné peut être hérité par des processus enfants. Membre lpSecurityDescriptor du
SECURITY_ATTRIBUTES structure spécifie un descripteur de sécurité pour un nouvel objet de mappage de fichiers.

Si lpFileMappingAttributes a la valeur NULL, le handle ne peut pas être hérité et l’objet de mappage de fichiers obtient un descripteur de sécurité par défaut. Les listes de contrôle d’accès (ACL) dans le descripteur de sécurité par défaut pour un objet de mappage de fichiers proviennent du jeton principal ou d’emprunt d’identité du créateur. Pour plus d’informations, consultez Sécurité et droits d’accès du mappage de fichiers.

[in] flProtect

Spécifie la protection de page de l’objet de mappage de fichiers. Toutes les vues mappées de l’objet doivent être compatibles avec cette protection.

Ce paramètre peut prendre les valeurs suivantes.

Valeur Signification
PAGE_EXECUTE_READ
0x20
Permet de mapper des vues pour l’accès en lecture seule, la copie en écriture ou l’exécution.

Le handle de fichier spécifié par le paramètre hFile doit être créé avec les droits d’accès GENERIC_READ et GENERIC_EXECUTE .

PAGE_EXECUTE_READWRITE
0x40
Permet de mapper des vues pour l’accès en lecture seule, copie sur écriture, lecture/écriture ou exécution.

Le handle de fichier spécifié par le paramètre hFile doit être créé avec les droits d’accès GENERIC_READ, GENERIC_WRITE et GENERIC_EXECUTE .

PAGE_EXECUTE_WRITECOPY
0x80
Permet de mapper des vues pour l’accès en lecture seule, la copie en écriture ou l’exécution. Cette valeur équivaut à PAGE_EXECUTE_READ.

Le handle de fichier spécifié par le paramètre hFile doit être créé avec les droits d’accès GENERIC_READ et GENERIC_EXECUTE .

Windows Vista : Cette valeur n’est pas disponible tant que Windows Vista avec SP1.

PAGE_READONLY
0x02
Permet de mapper des vues pour l’accès en lecture seule ou en copie sur écriture. Une tentative d’écriture dans une région spécifique entraîne une violation d’accès.

Le handle de fichier spécifié par le paramètre hFile doit être créé avec le droit d’accès GENERIC_READ .

PAGE_READWRITE
0x04
Permet de mapper des vues pour l’accès en lecture seule, à la copie en écriture ou en lecture/écriture.

Le handle de fichier spécifié par le paramètre hFile doit être créé avec les droits d’accès GENERIC_READ et GENERIC_WRITE .

PAGE_WRITECOPY
0x08
Permet de mapper des vues pour l’accès en lecture seule ou en copie sur écriture. Cette valeur équivaut à PAGE_READONLY.

Le handle de fichier spécifié par le paramètre hFile doit être créé avec le droit d’accès GENERIC_READ .

 

Une application peut spécifier un ou plusieurs des attributs suivants pour l’objet de mappage de fichiers en les combinant avec l’une des valeurs de protection de page précédentes.

Valeur Signification
SEC_COMMIT
0x8000000
Alloue le stockage physique en mémoire ou le fichier de pagination pour toutes les pages.

Il s'agit du paramètre par défaut.

SEC_IMAGE
0x1000000
Définit le fichier spécifié comme un fichier image exécutable.

L’attribut SEC_IMAGE doit être combiné avec une valeur de protection de page telle que PAGE_READONLY. Toutefois, cette valeur de protection de page n’a aucun effet sur les vues du fichier image exécutable. La protection des pages pour les vues d’un fichier image exécutable est déterminée par le fichier exécutable lui-même.

Aucun autre attribut n’est valide avec SEC_IMAGE.

SEC_IMAGE_NO_EXECUTE
0x11000000
Spécifie que le fichier spécifié par le paramètre hFile est un fichier image exécutable qui ne sera pas exécuté et que le fichier image chargé n’aura aucune vérification d’intégrité forcée exécutée. En outre, le mappage d’une vue d’un objet de mappage de fichiers créé avec l’attribut SEC_IMAGE_NO_EXECUTE n’appelle pas les rappels de pilotes inscrits à l’aide de l’API du noyau PsSetLoadImageNotifyRoutine .

L’attribut SEC_IMAGE_NO_EXECUTE doit être combiné avec la valeur de protection de page PAGE_READONLY. Aucun autre attribut n’est valide avec SEC_IMAGE_NO_EXECUTE.

Windows Server 2008 R2, Windows 7, Windows Server 2008 et Windows Vista : Cette valeur n’est pas prise en charge avant Windows Server 2012 et Windows 8.

SEC_LARGE_PAGES
0x80000000
Permet d’utiliser des pages volumineuses lors du mappage d’images ou de la sauvegarde à partir du fichier de pages, mais pas lors du mappage de données pour des fichiers standard. Veillez à spécifier la taille maximale de l’objet de mappage de fichiers comme taille minimale d’une grande page signalée par la fonction GetLargePageMinimum et à activer le privilège SeLockMemoryPrivilege .
SEC_NOCACHE
0x10000000
Définit toutes les pages sur non accessibles.

Les applications ne doivent pas utiliser cet indicateur, sauf en cas d’obligation explicite pour un appareil. L’utilisation des fonctions verrouillées avec la mémoire mappée avec SEC_NOCACHE peut entraîner une exception EXCEPTION_ILLEGAL_INSTRUCTION .

SEC_NOCACHE nécessite la définition de SEC_RESERVE ou de SEC_COMMIT .

SEC_RESERVE
0x4000000
Réserve toutes les pages sans allouer de stockage physique.

La plage réservée de pages ne peut pas être utilisée par d’autres opérations d’allocation tant que la plage de pages n’est pas publiée.

Les pages réservées peuvent être identifiées dans les appels suivants à la fonction VirtualAllocExNuma . Cet attribut n’est valide que si le paramètre hFile est INVALID_HANDLE_VALUE (autrement dit, un objet de mappage de fichiers qui est soutenu par le fichier de pagination système).

SEC_WRITECOMBINE
0x40000000
Définit toutes les pages à combiner en écriture.

Les applications ne doivent pas utiliser cet attribut, sauf en cas d’obligation explicite pour un appareil. L’utilisation des fonctions verrouillées avec la mémoire mappée avec SEC_WRITECOMBINE peut entraîner une exception EXCEPTION_ILLEGAL_INSTRUCTION .

SEC_WRITECOMBINE nécessite la définition de l’attribut SEC_RESERVE ou SEC_COMMIT .

[in] dwMaximumSizeHigh

DWORD d’ordre élevé de la taille maximale de l’objet de mappage de fichiers.

[in] dwMaximumSizeLow

DWORD de faible ordre de la taille maximale de l’objet de mappage de fichiers.

Si ce paramètre et le paramètre dwMaximumSizeHigh ont la valeur 0 (zéro), la taille maximale de l’objet de mappage de fichiers est égale à la taille actuelle du fichier identifié par le paramètre hFile .

Une tentative de mappage d’un fichier d’une longueur de 0 (zéro) échoue avec un code d’erreur de ERROR_FILE_INVALID. Les applications doivent tester les fichiers dont la longueur est égale à 0 (zéro) et rejeter ces fichiers.

[in, optional] lpName

Nom de l’objet de mappage de fichiers.

Si ce paramètre correspond au nom d’un objet de mappage de fichiers existant, la fonction demande l’accès à l’objet avec la protection spécifiée par le paramètre flProtect .

Si ce paramètre a la valeur NULL, l’objet de mappage de fichiers est créé sans nom.

Si le paramètre lpName correspond au nom d’un événement, d’un sémaphore, d’un mutex, d’un minuteur d’attente ou d’un objet de travail existant, la fonction échoue et la fonction GetLastError retourne ERROR_INVALID_HANDLE. Cela se produit parce que ces objets partagent le même espace de noms.

Le nom peut avoir un préfixe « Global » ou « Local » pour créer explicitement l’objet dans l’espace de noms global ou de session. Le reste du nom peut contenir n’importe quel caractère à l’exception de la barre oblique inverse (\). La création d’un objet de mappage de fichiers dans l’espace de noms global nécessite le privilège SeCreateGlobalPrivilege . Pour plus d’informations, consultez Espaces de noms d’objets du noyau.

La commutation rapide des utilisateurs est implémentée à l’aide de sessions Terminal Services. Le premier utilisateur à se connecter utilise la session 0 (zéro), l’utilisateur suivant pour se connecter utilise la session 1 (1), et ainsi de suite. Les noms d’objets de noyau doivent suivre les instructions afin que les applications puissent prendre en charge plusieurs utilisateurs.

[in] nndPreferred

Nœud NUMA dans lequel la mémoire physique doit résider.

Valeur Signification
NUMA_NO_PREFERRED_NODE
0xffffffff
Aucun nœud NUMA n’est préféré. Cela revient à appeler la fonction CreateFileMapping .

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle pour l’objet de mappage de fichiers.

Si l’objet existe avant l’appel de la fonction, la fonction retourne un handle à l’objet existant (avec sa taille actuelle, et non la taille spécifiée) et la fonction GetLastError retourne ERROR_ALREADY_EXISTS.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez la fonction GetLastError.

Remarques

Une fois qu’un objet de mappage de fichiers est créé, la taille du fichier ne doit pas dépasser la taille de l’objet de mappage de fichier ; si c’est le cas, tout le contenu du fichier n’est pas disponible pour le partage.

L’objet de mappage de fichiers peut être partagé par duplication, héritage ou par nom. Le contenu initial des pages d’un objet de mappage de fichiers soutenu par le fichier de page est égal à 0 (zéro).

Si une application spécifie pour l’objet de mappage de fichiers une taille supérieure à la taille du fichier nommé réel sur le disque et si la protection de page autorise l’accès en écriture (autrement dit, le paramètre flProtect spécifie PAGE_READWRITE ou PAGE_EXECUTE_READWRITE), le fichier sur le disque est augmenté pour correspondre à la taille spécifiée de l’objet de mappage de fichiers. Si le fichier est étendu, il n’est pas garanti que le contenu du fichier entre l’ancienne fin du fichier et la nouvelle fin du fichier soit égal à zéro . le comportement est défini par le système de fichiers.

Si le fichier ne peut pas être augmenté, la création de l’objet de mappage de fichiers échoue et la fonction GetLastError retourne ERROR_DISK_FULL.

Le handle retourné par la fonction CreateFileMappingNuma a un accès complet à un nouvel objet de mappage de fichiers et peut être utilisé avec n’importe quelle fonction qui nécessite un handle à un objet de mappage de fichiers. Un objet de mappage de fichiers peut être partagé via la création de processus, gérer la duplication ou par nom. Pour plus d’informations, consultez les fonctions DuplicateHandle et OpenFileMapping .

La création d’un objet de mappage de fichiers crée le potentiel de mappage d’une vue du fichier, mais ne mappe pas la vue. La fonction MapViewOfFileExNuma mappe une vue d’un fichier dans un espace d’adressage de processus.

À une exception importante, les vues de fichiers dérivées d’un seul objet de mappage de fichiers sont cohérentes ou identiques à un moment spécifique. Si plusieurs processus ont des handles du même objet de mappage de fichiers, ils voient une vue cohérente des données lorsqu’ils mappent une vue du fichier.

L’exception est liée aux fichiers distants. Bien que la fonction CreateFileMappingNuma fonctionne avec les fichiers distants, elle ne les maintient pas cohérents. Par exemple, si deux ordinateurs mappent un fichier en tant que fichier accessible en écriture et modifient tous les deux la même page, chaque ordinateur ne voit que ses propres écritures dans la page. Lorsque les données sont mises à jour sur le disque, la page n’est pas fusionnée.

Un fichier mappé et un fichier accessible à l’aide des fonctions d’entrée et de sortie (E/S) (ReadFile et WriteFile) ne sont pas nécessairement cohérents.

Pour fermer complètement un objet de mappage de fichiers, une application doit annuler le mappage de toutes les vues mappées de l’objet de mappage de fichiers en appelant la fonction UnmapViewOfFile , puis fermer le handle d’objet de mappage de fichiers en appelant la fonction CloseHandle .

Ces fonctions peuvent être appelées dans n’importe quel ordre. L’appel à la fonction UnmapViewOfFile est nécessaire, car les vues mappées d’un objet de mappage de fichiers conservent les descripteurs ouverts internes à l’objet, et un objet de mappage de fichiers ne se ferme pas tant que tous les handles ouverts à celui-ci ne sont pas fermés.

Lors de la modification d’un fichier via une vue mappée, l’horodatage de la dernière modification peut ne pas être mis à jour automatiquement. Si nécessaire, l’appelant doit utiliser SetFileTime pour définir l’horodatage.

La création d’un objet de mappage de fichiers à partir d’une session autre que la session zéro nécessite le privilège SeCreateGlobalPrivilege . Notez que ce case activée de privilège est limité à la création d’objets de mappage de fichiers et ne s’applique pas à l’ouverture d’objets existants. Par exemple, si un service ou le système crée un objet de mappage de fichiers, tout processus en cours d’exécution dans n’importe quelle session peut accéder à cet objet de mappage de fichiers, à condition que l’appelant dispose des droits d’accès requis.

Utilisez la gestion structurée des exceptions pour protéger tout code qui écrit ou lit dans une vue mappée en mémoire. Pour plus d’informations, consultez Lecture et écriture à partir d’un affichage fichier.

Pour disposer d’un mappage avec des autorisations exécutables, une application doit appeler la fonction CreateFileMappingNuma avec PAGE_EXECUTE_READWRITE ou PAGE_EXECUTE_READ , puis appeler la fonction MapViewOfFileExNuma avec FILE_MAP_EXECUTE | FILE_MAP_WRITE ou FILE_MAP_EXECUTE | FILE_MAP_READ.

Dans Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie Prise en charge
Protocole Server Message Block (SMB) 3.0 Oui
Basculement transparent SMB 3.0 (TFO) Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) Oui
Système de fichiers du volume partagé de cluster (CsvFS) Oui
Système de fichiers résilient (ReFS) Oui

Configuration requise

   
Client minimal pris en charge Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau uniquement]
Plateforme cible Windows
En-tête winbase.h (inclure Windows.h, Memoryapi.h)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

CloseHandle

CreateFileMapping

DuplicateHandle

Fonctions de mappage de fichiers

MapViewOfFileExNuma

Prise en charge de NUMA

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAllocExNuma

WriteFile