Fonction MapViewOfFile (memoryapi.h)

Article
08/24/2023

Mappe une vue d’un mappage de fichiers dans l’espace d’adressage d’un processus appelant.

Pour spécifier une adresse de base suggérée pour la vue, utilisez la fonction MapViewOfFileEx . Toutefois, cette pratique n’est pas recommandée.

Syntaxe

LPVOID MapViewOfFile(
  [in] HANDLE hFileMappingObject,
  [in] DWORD  dwDesiredAccess,
  [in] DWORD  dwFileOffsetHigh,
  [in] DWORD  dwFileOffsetLow,
  [in] SIZE_T dwNumberOfBytesToMap
);

Paramètres

[in] hFileMappingObject

Handle vers un objet de mappage de fichiers. Les fonctions CreateFileMapping et OpenFileMapping retournent ce handle.

[in] dwDesiredAccess

Type d’accès à un objet de mappage de fichiers, qui détermine la protection des pages. Ce paramètre peut être l’une des valeurs suivantes ou une combinaison de plusieurs valeurs au niveau du bit OU, le cas échéant.

Valeur	Signification
FILE_MAP_ALL_ACCESS	Une vue en lecture/écriture du fichier est mappée. L’objet de mappage de fichiers doit avoir été créé avec PAGE_READWRITE ou PAGE_EXECUTE_READWRITE protection. Lorsqu’il est utilisé avec la fonction MapViewOfFile , FILE_MAP_ALL_ACCESS équivaut à FILE_MAP_WRITE.
FILE_MAP_READ	Une vue en lecture seule du fichier est mappée. Une tentative d’écriture dans la vue de fichier entraîne une violation d’accès. L’objet de mappage de fichiers doit avoir été créé avec PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE_READ ou PAGE_EXECUTE_READWRITE protection.
FILE_MAP_WRITE	Une vue en lecture/écriture du fichier est mappée. L’objet de mappage de fichiers doit avoir été créé avec PAGE_READWRITE ou PAGE_EXECUTE_READWRITE protection. Lorsqu’ils sont utilisés avec MapViewOfFile, (FILE_MAP_WRITE \| FILE_MAP_READ) et FILE_MAP_ALL_ACCESS sont équivalents à FILE_MAP_WRITE.

À l’aide de OR au niveau du bit, vous pouvez combiner les valeurs ci-dessus avec ces valeurs.

Valeur	Signification
FILE_MAP_COPY	Une vue de copie en écriture du fichier est mappée. L’objet de mappage de fichiers doit avoir été créé avec PAGE_READONLY, PAGE_READ_EXECUTE, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, PAGE_READWRITE ou PAGE_EXECUTE_READWRITE protection. Lorsqu’un processus écrit dans une page de copie en écriture, le système copie la page d’origine vers une nouvelle page qui est privée du processus. La nouvelle page est sauvegardée par le fichier de pagination. La protection de la nouvelle page passe de la copie en écriture à la lecture/écriture. Lorsque l’accès à la copie en écriture est spécifié, les frais de validation du système et du processus pris concernent l’ensemble de l’affichage, car le processus appelant peut potentiellement écrire dans chaque page de l’affichage, ce qui rend toutes les pages privées. Le contenu de la nouvelle page n’est jamais réécrit dans le fichier d’origine et est perdu lorsque l’affichage n’est pas mappé.
FILE_MAP_EXECUTE	Une vue exécutable du fichier est mappée (la mémoire mappée peut être exécutée en tant que code). L’objet de mappage de fichiers doit avoir été créé avec PAGE_EXECUTE_READ, PAGE_EXECUTE_WRITECOPY ou PAGE_EXECUTE_READWRITE protection. Windows Server 2003 et Windows XP : Cette valeur est disponible à partir de Windows XP avec SP2 et de Windows Server 2003 avec SP1.
FILE_MAP_LARGE_PAGES	À compter de Windows 10 version 1703, cet indicateur spécifie que la vue doit être mappée à l’aide de la prise en charge de grandes pages. La taille de la vue doit être un multiple de la taille d’une grande page signalée par la fonction GetLargePageMinimum , et l’objet de mappage de fichiers doit avoir été créé à l’aide de l’option SEC_LARGE_PAGES . Si vous fournissez une valeur non null pour lpBaseAddress, la valeur doit être un multiple de GetLargePageMinimum. Note: Sur les versions du système d’exploitation antérieures à Windows 10 version 1703, l’indicateur FILE_MAP_LARGE_PAGES n’a aucun effet. Dans ces versions, l’affichage est automatiquement mappé à l’aide de grandes pages si la section a été créée avec l’indicateur SEC_LARGE_PAGES défini.
FILE_MAP_TARGETS_INVALID	Définit tous les emplacements du fichier mappé en tant que cibles non valides pour Control Flow Guard (CFG). Cet indicateur est similaire à PAGE_TARGETS_INVALID. Utilisez cet indicateur en combinaison avec le droit d’accès d’exécution FILE_MAP_EXECUTE. Tout appel indirect à des emplacements dans ces pages échoue aux vérifications CFG et le processus est terminé. Le comportement par défaut pour les pages exécutables allouées est de marquer des cibles d’appel valides pour CFG.

Pour les objets de mappage de fichiers créés avec l’attribut SEC_IMAGE , le paramètre dwDesiredAccess n’a aucun effet et doit être défini sur une valeur valide telle que FILE_MAP_READ.

Pour plus d’informations sur l’accès aux objets de mappage de fichiers, consultez Sécurité et droits d’accès de mappage de fichiers.

[in] dwFileOffsetHigh

DWORD d’ordre élevé du décalage de fichier où la vue commence.

[in] dwFileOffsetLow

DWORD de bas ordre du décalage de fichier où l’affichage doit commencer. La combinaison des décalages élevé et faible doit spécifier un décalage dans le mappage de fichiers. Ils doivent également correspondre à la granularité de l’allocation de mémoire du système. Autrement dit, le décalage doit être un multiple de la granularité d’allocation. Pour obtenir la granularité de l’allocation de mémoire du système, utilisez la fonction GetSystemInfo , qui remplit les membres d’une structure de SYSTEM_INFO .

[in] dwNumberOfBytesToMap

Nombre d’octets d’un mappage de fichier à mapper à la vue. Tous les octets doivent respecter la taille maximale spécifiée par CreateFileMapping. Si ce paramètre est égal à 0 (zéro), le mappage s’étend du décalage spécifié à la fin du mappage de fichiers.

Valeur retournée

Si la fonction réussit, la valeur de retour est l’adresse de départ de la vue mappée.

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

Notes

Le mappage d’un fichier rend la partie spécifiée d’un fichier visible dans l’espace d’adressage du processus appelant.

Pour les fichiers dont la taille est supérieure à l’espace d’adressage, vous ne pouvez mapper qu’une petite partie des données du fichier à la fois. Une fois la première vue terminée, vous pouvez l’annuler et mapper une nouvelle vue.

Pour obtenir la taille d’une vue, utilisez la fonction VirtualQuery .

Plusieurs vues d’un fichier (ou d’un objet de mappage de fichiers et de son fichier mappé) sont cohérentes si elles contiennent des données identiques à un moment spécifié. Cela se produit si les vues de fichiers sont dérivées de n’importe quel objet de mappage de fichiers qui est soutenu par le même fichier. Un processus peut dupliquer un handle d’objet de mappage de fichiers dans un autre processus à l’aide de la fonction DuplicateHandle , ou un autre processus peut ouvrir un objet de mappage de fichiers par nom à l’aide de la fonction OpenFileMapping .

À une exception importante, les vues de fichiers dérivées de n’importe quel objet de mappage de fichiers qui est 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 qui sont mappées par différents processus.

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

Il n’est pas garanti qu’une vue mappée d’un fichier soit cohérente avec un fichier auquel la fonction ReadFile ou WriteFile accède.

Ne stockez pas de pointeurs dans le fichier mappé en mémoire ; stockez les décalages à partir de la base du mappage de fichiers afin que le mappage puisse être utilisé à n’importe quelle adresse.

Pour vous protéger contre les exceptions EXCEPTION_IN_PAGE_ERROR , utilisez la gestion structurée des exceptions pour protéger tout code qui écrit ou lit dans une vue mappée en mémoire d’un fichier autre que le fichier de page. Pour plus d’informations, consultez Lecture et écriture à partir d’un mode Fichier.

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.

Si un objet de mappage de fichiers est sauvegardé par le fichier de pagination (CreateFileMapping est appelé avec le paramètre hFile défini sur INVALID_HANDLE_VALUE), le fichier de pagination doit être suffisamment volumineux pour contenir l’intégralité du mappage. Si ce n’est pas le cas, MapViewOfFile échoue. Le contenu initial des pages d’un objet de mappage de fichiers soutenu par le fichier de pagination est 0 (zéro).

Lorsqu’un objet de mappage de fichiers sauvegardé par le fichier de pagination est créé, l’appelant peut spécifier si MapViewOfFile doit réserver et valider des pages en même temps (SEC_COMMIT) ou simplement réserver des pages (SEC_RESERVE). Le mappage du fichier rend la plage d’adresses virtuelles mappée entière indisponible pour d’autres allocations dans le processus. Une fois qu’une page de la plage réservée est validée, elle ne peut pas être libérée ou libérée en appelant VirtualFree. Les pages réservées et validées sont libérées lorsque l’affichage est décompressé et que l’objet de mappage de fichiers est fermé. Pour plus d’informations, consultez les fonctions UnmapViewOfFile et CloseHandle .

Pour disposer d’autorisations exécutables d’un fichier, 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	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

Lorsque CsvFs est suspendu, cet appel peut échouer avec une erreur indiquant qu’il existe un conflit de verrous.

Exemples

Pour obtenir un exemple, consultez Création de mémoire partagée nommée.

Spécifications


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