CreateFileMappingA, fonction (winbase.h)
Crée ou ouvre un objet de mappage de fichiers nommé ou non nommé pour un fichier spécifié.
Pour spécifier le nœud NUMA pour la mémoire physique, consultez CreateFileMappingNuma.
Syntaxe
HANDLE CreateFileMappingA(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCSTR lpName
);
Paramètres
[in] hFile
Handle vers le 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 nécessaire, mais il est recommandé que les fichiers que vous envisagez de mapper soient ouverts 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 paramètres dwMaximumSizeLow. Dans ce scénario, CreateFileMapping crée un objet de mappage de fichiers d’une taille spécifiée sauvegardée 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 SECURITY_ATTRIBUTES qui détermine si un handle retourné peut être hérité par les processus enfants. Le lpSecurityDescriptor membre de la structure SECURITY_ATTRIBUTES spécifie un descripteur de sécurité pour un nouvel objet de mappage de fichiers.
Si lpFileMappingAttributes est 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é de mappage de fichiers et droits d’accès.
[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 être l’une des valeurs suivantes.
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 |
|---|---|
|
Si l’objet de mappage de fichiers est soutenu par le fichier de pagination du système d’exploitation (le paramètre 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_COMMIT ne peut pas être combinée avec SEC_RESERVE. Si aucun attribut n’est spécifié, SEC_COMMIT est supposé. |
|
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é à 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. |
|
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 de noyau PsSetLoadImageNotifyRou tine.
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. |
|
Permet aux pages volumineuses d’être utilisées pour les objets de mappage de fichiers 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 sauvegardés par des fichiers image exécutables ou des fichiers de données (le paramètre hFile est un handle vers 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 de vue doivent également être plusieurs de la taille minimale de la page volumineuse. SEC_LARGE_PAGES nécessite que le privilège SeLockMemoryPrivilege soit activé 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 n’est pas pris en charge avec SP1. Windows XP : cette valeur n’est pas prise en charge. |
|
Définit toutes les pages comme non mises en cache.
Les applications ne doivent pas utiliser cet attribut, sauf lorsqu’elles sont explicitement requises pour un appareil. L’utilisation des fonctions interblocées avec de la mémoire mappée avec SEC_NOCACHE peut entraîner une exception EXCEPTION_ILLEGAL_INSTRUCTION. SEC_NOCACHE nécessite que l’attribut SEC_RESERVE ou SEC_COMMIT soit défini. |
|
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, la plage entière 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 validé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ée avec SEC_COMMIT. |
|
Définit toutes les pages à combiner en écriture.
Les applications ne doivent pas utiliser cet attribut, sauf lorsqu’elles sont explicitement requises pour un appareil. L’utilisation des fonctions interblocées avec de la mémoire mappée avec SEC_WRITECOMBINE peut entraîner une exception EXCEPTION_ILLEGAL_INSTRUCTION. SEC_WRITECOMBINE nécessite que l’attribut SEC_RESERVE ou SEC_COMMIT soit défini. Windows Server 2003 et Windows XP : cet indicateur n’est pas pris en charge tant que Windows Vista n’est pas pris en charge. |
[in] dwMaximumSizeHigh
L’ordre élevé DWORD de la taille maximale de l’objet de mappage de fichiers.
[in] dwMaximumSizeLow
L’ordre faible DWORD de la taille maximale de l’objet de mappage de fichiers.
Si ce paramètre et dwMaximumSizeHigh sont 0 (zéro), la taille maximale de l’objet de mappage de fichiers est égale à la taille actuelle du fichier qui hFile identifie.
Une tentative de mappage d’un fichier avec une longueur de 0 (zéro) échoue avec un code d’erreur de ERROR_FILE_INVALID. Les applications doivent tester les fichiers avec une longueur de 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 existant, la fonction demande l’accès à l’objet avec la protection qui flProtect spécifie.
Si ce paramètre est NULL, l’objet de mappage de fichiers est créé sans nom.
Si 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, 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 de 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 noyau.
Le basculement rapide des utilisateurs est implémenté à 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 (un), et ainsi de suite. Les noms d’objets noyau doivent suivre les instructions décrites pour les services Terminal Services afin que les applications puissent prendre en charge plusieurs utilisateurs.
Valeur de retour
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’erreur étendues, appelez 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 fichiers ; si c’est le cas, tout le contenu du fichier n’est pas disponible pour le partage.
Si une application spécifie une taille pour l’objet de mappage de fichiers supérieur à la taille réelle du fichier nommé 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, le contenu du fichier entre l’ancienne fin du fichier et la nouvelle fin du fichier ne sont pas garantis à zéro ; le comportement est défini par le système de fichiers. Si le fichier sur le disque ne peut pas être augmenté, CreateFileMapping échoue et GetLastError retourne ERROR_DISK_FULL.
Le contenu initial des pages d’un objet de mappage de fichiers soutenu par le fichier de pagination du système d’exploitation est égal à 0 (zéro).
Le handle qui CreateFileMapping renvoie 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 pour un objet de mappage de fichiers.
Plusieurs processus peuvent partager une vue du même fichier en utilisant un seul objet de mappage de fichiers partagé ou en créant des objets de mappage de fichiers distincts sauvegardés par le même fichier. Un objet de mappage de fichiers unique peut être partagé par plusieurs processus via l’héritage du handle lors de la création du processus, la duplication du handle ou l’ouverture de l’objet de mappage de fichiers par nom. Pour plus d’informations, consultez les fonctions CreateProcess, DuplicateHandle et Fonctions openFileMapping.
La création d’un objet de mappage de fichiers ne mappe pas réellement la vue dans un espace d’adressage de processus. Les fonctions MapViewOfFile et MapViewOfFileEx mappent une vue d’un fichier dans un espace d’adressage de processus.
À une exception importante, les vues de fichiers dérivées d’un objet de mappage de fichiers soutenu par le même fichier sont cohérentes ou identiques à un moment spécifique. La cohérence est garantie pour les vues au sein d’un processus et pour les vues mappées par différents processus.
L’exception est liée aux fichiers distants. Bien que CreateFileMapping fonctionne avec des fichiers distants, il ne les conserve pas de manière cohérente. Par exemple, si deux ordinateurs mappent un fichier en écriture et modifient 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, elles ne sont pas fusionnées.
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.
Les vues mappées d’un objet de mappage de fichiers conservent des références internes à l’objet, et un objet de mappage de fichiers ne se ferme pas tant que toutes les références ne sont pas publiées. Par conséquent, 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 UnmapViewOfFile et fermer le handle d’objet de mappage de fichiers en appelant CloseHandle. Ces fonctions peuvent être appelées dans n’importe quel ordre.
Lors de la modification d’un fichier via une vue mappée, le dernier horodatage de 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 dans l’espace de noms global à partir d’une session autre que la session zéro nécessite le privilège SeCreateGlobalPrivilege. Notez que cette vérification des privilèges est limitée à la création d’objets de mappage de fichiers et ne s’applique pas à l’ouverture des objets existants. Par exemple, si un service ou le système crée un objet de mappage de fichiers dans l’espace de noms global, tout processus exécuté 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.
Windows XP : L’exigence décrite dans le paragraphe précédent a été introduite avec Windows Server 2003 et Windows XP avec SP2
Utilisez la gestion des exceptions structurées pour protéger tout code qui écrit ou lit à partir d’une vue de fichier. Pour plus d’informations, consultez lecture et écriture à partir d’une vue de fichier.
Pour disposer d’un mappage avec des autorisations exécutables, une application doit appeler CreateFileMapping avec PAGE_EXECUTE_READWRITE ou PAGE_EXECUTE_READ, puis appeler MapViewOfFile 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 | Supporté |
|---|---|
| Protocole SMB (Server Message Block) 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 |
| Cluster Shared Volume File System (CsvFS) | Oui |
| Système de fichiers résilient (ReFS) | Oui |
Exemples
Pour obtenir un exemple, consultez Création d’un de mémoire partagée nommée ou Création d’un mappage de fichiers à l’aide de pages volumineuses.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | winbase.h (include Windows.h, Memoryapi.h) |
| bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |
Voir aussi
création d’un objet de mappage de fichiers
Fonctions de mappage de fichiers