Partager via


CreateFileMapping2, fonction (memoryapi.h)

Crée ou ouvre un objet de mappage de fichiers nommé ou sans nom pour un fichier spécifié. Vous pouvez spécifier un nœud NUMA préféré pour la mémoire physique en tant que paramètre étendu ; consultez le paramètre ExtendedParameters .

Syntaxe

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

Paramètres

File

Type : _In_ HANDLE

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, CreateFileMapping crée un objet de mappage de fichiers d’une taille spécifiée qui est soutenu par le fichier de pagination système au lieu d’un fichier dans le système de fichiers.

SecurityAttributes

Type : _In_opt_ SECURITY_ATTRIBUTES*

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

Si lpAttributes 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 au mappage de fichiers.

DesiredAccess

Type : _In_ ULONG

Masque d’accès souhaité pour le handle de mappage de fichiers retourné. Pour obtenir la liste des droits d’accès, consultez Sécurité du mappage de fichiers et droits d’accès.

PageProtection

Type : _In_ ULONG

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 .

Windows Server 2003 et Windows XP : Cette valeur n’est pas disponible tant que Windows XP avec SP2 et Windows Server 2003 avec SP1.

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 .

Windows Server 2003 et Windows XP : Cette valeur n’est pas disponible tant que Windows XP avec SP2 et Windows Server 2003 avec SP1.

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 n’est pas disponible.

Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge.

PAGE_READONLY
0x02
Permet de mapper les vues pour l’accès en lecture seule ou copie en é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 l’accès 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 les vues pour l’accès en lecture seule ou copie en é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 .

AllocationAttributes

Type : _In_ ULONG

Vous pouvez spécifier un ou plusieurs des attributs suivants pour l’objet de mappage de fichiers. Consultez également le paramètre PageProtection .

Valeur Signification
SEC_COMMIT
0x8000000
Si l’objet de mappage de fichiers est soutenu par le fichier de pagination du système d’exploitation (le paramètre hfile est INVALID_HANDLE_VALUE), spécifie que lorsqu’une vue du fichier est mappée dans un espace d’adressage de processus, toute la plage de pages est validée plutôt que réservée. Le système doit avoir suffisamment de pages valides pour contenir l’intégralité du mappage. Sinon, CreateFileMapping échoue.

Cet attribut n’a aucun effet pour les objets de mappage de fichiers qui sont sauvegardés par des fichiers image exécutables ou des fichiers de données (le paramètre hfile est un handle pour un fichier).

SEC_COMMIT ne peut pas être combiné avec SEC_RESERVE.

Si aucun attribut n’est spécifié, SEC_COMMIT est supposé.

SEC_IMAGE
0x1000000
Spécifie que le fichier spécifié par le paramètre hFile est 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 pas de vérifications d’intégrité forcées. 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, Windows Vista, Windows Server 2003 et Windows XP : 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 pour les objets de mappage de fichiers qui sont sauvegardés par le fichier de pagination du système d’exploitation (le paramètre hfile est INVALID_HANDLE_VALUE). Cet attribut n’est pas pris en charge pour les objets de mappage de fichiers qui sont sauvegardés par des fichiers image exécutables ou des fichiers de données (le paramètre hFile est un handle pour une image exécutable ou un fichier de données).

La taille maximale de l’objet de mappage de fichiers doit être un multiple de la taille minimale d’une grande page retournée par la fonction GetLargePageMinimum . Si ce n’est pas le cas, CreateFileMapping échoue. Lors du mappage d’une vue d’un objet de mappage de fichiers créé avec SEC_LARGE_PAGES, l’adresse de base et la taille d’affichage doivent également être des multiples de la taille de page de grande taille minimale.

SEC_LARGE_PAGES nécessite l’activation du privilège SeLockMemoryPrivilege dans le jeton de l’appelant.

Si SEC_LARGE_PAGES est spécifié, SEC_COMMIT doit également être spécifié.

Windows Server 2003 : Cette valeur n’est pas prise en charge tant que Windows Server 2003 avec SP1.

Windows XP : Cette valeur n’est pas prise en charge.

SEC_NOCACHE
0x10000000
Définit toutes les pages pour qu’elles ne soient pas mises en cache.

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_NOCACHE peut entraîner une exception EXCEPTION_ILLEGAL_INSTRUCTION .

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

SEC_RESERVE
0x4000000
Si l’objet de mappage de fichiers est sauvegardé par le fichier de pagination du système d’exploitation (le paramètre hfile est INVALID_HANDLE_VALUE), spécifie que lorsqu’une vue du fichier est mappée dans un espace d’adressage de processus, toute la plage de pages est réservée pour une utilisation ultérieure par le processus plutôt que validée.

Les pages réservées peuvent être validées dans les appels suivants à la fonction VirtualAlloc . Une fois les pages validées, elles ne peuvent pas être libérées ou libérées avec la fonction VirtualFree .

Cet attribut n’a aucun effet pour les objets de mappage de fichiers qui sont sauvegardés par des fichiers image exécutables ou des fichiers de données (le paramètre hfile est un handle vers un fichier).

SEC_RESERVE ne peut pas être combiné avec SEC_COMMIT.

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 .

Windows Server 2003 et Windows XP : Cet indicateur n’est pas pris en charge tant que Windows Vista.

MaximumSize

Type : _In_ ULONG64

Taille maximale de l’objet de mappage de fichiers.

Si ce paramètre est égal à 0 (zéro), la taille maximale de l’objet de mappage de fichiers est égale à la taille actuelle du fichier identifié par 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. Vous devez tester les fichiers dont la longueur est égale à 0 (zéro) et rejeter ces fichiers.

Name

Type : _In_opt_ PCWSTR

Nom de l’objet de mappage de fichiers.

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

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

Si lpName correspond au nom d’un événement, sémaphore, mutex, minuteur d’attente ou 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 du caractère barre oblique inverse (\). La création d’un objet de mappage de fichiers dans l’espace de noms global à partir d’une session autre que la session zéro nécessite le privilège SeCreateGlobalPrivilege . Pour plus d’informations, consultez Espaces de noms d’objets de noyau.

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

ExtendedParameters

Type : MEM_EXTENDED_PARAMETER _Inout_updates_opt_(ParameterCount)*

Pointeur facultatif vers un ou plusieurs paramètres étendus de type MEM_EXTENDED_PARAMETER. Chacune de ces valeurs de paramètre étendues peut elle-même avoir un champ Typede MemExtendedParameterAddressRequirements ou MemExtendedParameterNumaNode. Si aucun paramètre étendu MemExtendedParameterNumaNode n’est fourni, le comportement est le même que pour les fonctions VirtualAlloc/MapViewOfFile (autrement dit, le nœud NUMA préféré pour les pages physiques est déterminé en fonction du processeur idéal du thread qui accède d’abord à la mémoire).

ParameterCount

Dans ULONG ParameterCount

Nombre de paramètres étendus pointés vers par ExtendedParameters.

Valeur retournée

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

Si l’objet existe avant l’appel de fonction, la fonction retourne un handle à l’objet existant (avec sa taille actuelle, et non la taille spécifiée), et 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 GetLastError.

Notes

Consultez les remarques relatives à CreateFileMapping.

Exemples

Pour obtenir un exemple, consultez Création de mémoire partagée nommée ou Création d’un mappage de fichiers à l’aide de grandes pages.

Spécifications

   
Client minimal pris en charge Windows 10 Build 20348
Serveur minimal pris en charge Windows 10 Build 20348
Plateforme cible Windows
En-tête memoryapi.h (inclure Windows.h, Memoryapi.h)
Bibliothèque onecore.lib
DLL Kernel32.dll

Voir aussi

CloseHandle

CreateFileMappingNuma

Création d’un objet de mappage de fichiers

DuplicateHandle

MapViewOfFile

MapViewOfFileEx

Fonctions de gestion de la mémoire

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile