mmap, munmap − Ãtablir/supprimer une projection en mémoire (map/unmap) des fichiers ou des périphériques.

#include <sys/mman.h>

void *mmap(void *start, size_t length, int prot,int flags ,
           int fd, off_t offset);

int munmap(void *start, size_t length);

La fonction mmap() demande la projection en mémoire de length octets commençant à la position offset depuis un fichier (ou un autre objet) indiqué par le descripteur fd, de préférence à l’adresse pointée par start. Cette adresse n’est qu’une préférence, généralement 0. La véritable adresse où l’objet est projeté est renvoyée par la fonction mmap(), et n’est jamais nulle.

L’argument prot indique la protection que l’on désire pour cette zone de mémoire, et ne doit pas entrer en conflit avec le mode d’ouverture du fichier. Il s’agit soit de PROT_NONE (le contenu de la mémoire est inaccessible) soit d’un OU binaire entre les constantes suivantes :

PROT_EXEC

On peut exécuter du code dans la zone mémoire.

PROT_READ

On peut lire le contenu de la zone mémoire.

PROT_WRITE

On peut écrire dans la zone mémoire.

PROT_NONE

Les pages ne peuvent pas être accédées.

Le paramètre flags indique le type de fichier projeté, les options de projection, et si les modifications faites sur la portion projetée sont privées ou doivent être partagées avec les autres références. Les options sont :

MAP_FIXED

N’utiliser que l’adresse indiquée. Si la région de la mémoire spécifiée par start et len chevauche les pages d’un mappage existant, la partie chevauchée du mappage existant sera écrasée. Si l’adresse indiquée ne peut être utilisée, mmap() échouera. Si est spécifié, start doit être un multiple de la longueur de page. Il est déconseillé d’utiliser cette option.

MAP_SHARED

Partager la projection avec tout autre processus utilisant l’objet. L’écriture dans la zone est équivalente à une écriture dans le fichier. En revanche, ce dernier n’est pas nécessairement mis à jour tant qu’on n’a pas appelé msync(2) ou munmap(2).

MAP_PRIVATE

Créer une projection privée, utilisant la méthode de copie à l’écriture. L’écriture dans la zone ne modifie pas le fichier. Il n’est pas précisé si les changements effectués dans le fichier après l’appel mmap() seront visibles.

Vous devez indiquer soit MAP_SHARED, soit MAP_PRIVATE.

Les trois attributs ci-dessus sont décrits dans POSIX.1-20012. Linux propose également des attributs non standards :

MAP_DENYWRITE

Cet attribut est ignoré. (Autrefois, une tentative d’écriture dans le fichier sous-jacent échouait avec l’erreur ETXTBUSY. Mais ceci permettait des attaques de déni de service).

MAP_EXECUTABLE

Cet attribut est ignoré.

MAP_NORESERVE

Ne pas réserver d’espace de swap pour les pages de cette projection. Une telle réservation garantit que l’on puisse modifier la projection. Sans réservation, on peut recevoir un signal SIGSEGV durant une écriture, s’il n’y a plus de mémoire physique disponible. Voir également la discussion sur le fichier /proc/sys/vm/overcommit_memory dans proc(5). Dans les noyaux précédant le 2.6, cet attribut n’avait d’effet que pour les projections privées.

MAP_LOCKED (depuis Linux 2.5.37)

Verrouille la page projetée en mémoire à la manière de mlock(). Cet attribut est ignoré sur les noyaux plus anciens.

MAP_GROWSDOWN

Utilisé pour les piles. Indique au système de gestion de la mémoire virtuelle que la projection doit s’étendre en croissant vers le bas de la mémoire.

MAP_ANONYMOUS

La projection n’est supportée par aucun fichier. Les arguments fd et offset sont ignorés. Cet attribut, utilisé en conjonction de MAP_SHARED, n’est supporté sous Linux que depuis le noyay 2.4.

MAP_ANON

Alias de MAP_ANONYMOUS. Déconseillé.

MAP_FILE

Attribut pour compatibilité. Ignoré.

MAP_32BIT

Faire la projection dans les premiers 2 Go de l’espace d’adressage du processus. Ignoré si MAP_FIXED est présent. Cet attribut n’est supporté que sur x86-64 pour les programmes 64-bits.

MAP_POPULATE (depuis Linux 2.5.46)

Remplit les tables de pages pour une projection de fichier en effectuant une lecture anticipée sur le fichier. Les accès ultérieurs à la projection ne seront pas bloqués par des fautes de pages.

MAP_NONBLOCK (depuis Linux 2.5.46)

N’a de sens qu’en conjonction avec MAP_POPULATE. Ne pas efectuer de lecture anticipée : créer seulement les entrées de tables de page pour les pages déjà présentes en RAM.

Certains systèmes utilisent les attributs supplémentaires MAP_AUTOGROW, MAP_AUTORESRV, MAP_COPY, et MAP_LOCAL.

fd doit être un descripteur de fichier valide, sauf si on utilise MAP_ANONYMOUS. Si MAP_ANONYMOUS est positionné, fd est ignoré sous Linux. Toutefois, certaines implémentations réclament que fd valle −1 si MAP_ANONYMOUS (ou MAP_ANON) est spécifié, et les applications portables devraient s’en assuree.

L’argument offset doit normalement être un multiple de la taille de page renvoyée par l’appel getpagesize(2).

La mémoire obtenue par mmap() est préservée lors d’un fork(2), avec les mêmes attributs.

La projection doit avoir une taille multiple de celle des pages. Pour un fichier dont la longueur n’est pas un multiple de la taille de page, la mémoire restante est remplie de zéros lors de la projection, et les écritures dans cette zone n’affectent pas le fichier. Les effets de la modification de la taille du fichier sous-jacent sur les pages correspondant aux zones ajoutées ou supprimées ne sont pas précisés. L’appel système munmap() détruit la projection dans la zone de mémoire spécifiée, et s’arrange pour que toute référence ultérieure à cette zone mémoire déclenche une erreur d’adressage. La projection est aussi automatiquement détruite lorsque le processus se termine. à l’inverse, la fermeture du descripteur de fichier ne supprime pas la projection.

L’adresse start doit être un multiple de la taille de page. Tous les pages contenant une partie de l’intervalle indiqué sont libérées, et tout accès ultérieur déclenchera SIGSEGV. Aucune erreur n’est détectée si l’intervalle indiqué ne contient pas de page projetée.

Pour les projections supportées par un fichier, le champ st_atime du fichier peut être mis à jour à tout moment entre l’appel mmap() et le munmap() correspondant. Le premier accès dans la page projetée mettra le champ à jour si cela n’a pas été déjà fait.

Les champs st_ctime et st_mtime pour un fichier projeté avec PROT_WRITE et MAP_SHARED seront mis à jour après une écriture dans la région projetée, et avant l’éventuel msync() suivant avec attribut MS_SYNC ou MS_ASYNC.

mmap() renvoie un pointeur sur la zone de mémoire, s’il réussit. En cas d’échec il retourne la valeur MAP_FAILED (c.-à -d. (void *) −1) et errno contient le code d’erreur.

munmap() renvoie 0 s’il réussit. En cas d’échec, −1 est renvoyé et errno contient le code d’erreur (probablement EINVAL).

Suivant l’architecture, PROT_READ peut include PROT_EXEC ou non. Les programmes portables doivent toujours indiquer PROT_EXEC s’ils veulent exécuter du code dans la projection.

EACCES

Le descripteur ne correspond pas à un fichier normal, ou on demande une projection privée MAP_PRIVATE mais fd n’est pas ouvert en lecture, ou on demande une projection partagée MAP_SHARED avec protection PROT_WRITE, mais fd n’est pas ouvert en lecture et écriture (O_RDWR). Ou encore PROT_WRITE est demandé, mais le fichier est ouvert en ajout seulement.

EAGAIN

Le fichier est verrouillé, ou trop de pages ont été verrouillées en mémoire (voir setrlimit(2)).

EBADF

fd n’est pas un descripteur de fichier valide (et MAP_ANONYMOUS n’était pas précisé).

EINVAL

start ou length ou offset sont invalides. (Par exemple : zone trop grande, ou non alignée sur une frontière de page).

ENFILE

La limite du nombre total de fichiers ouverts sur le système a été atteinte.

ENODEV

Le système de fichiers sous-jacent ne supporte pas la projection en mémoire.

ENOMEM

pas assez de mémoire, ou le nombre maximal de projection par processus a été dépassé.

EPERM

L’argument prot a demandé PROT_EXEC mais la zone appartient aà un fichier sur une système de fichiers monté sans permissions d’exécution.

ETXTBSY

MAP_DENYWRITE a été réclamé mais fd est ouvert en écriture.

L’accès à une zone de projection peut déclencher les signaux suivants :

SIGSEGV

Tentative d’écriture dans une zone en lecture seule.

SIGBUS

Tentative d’accès à une portion de la zone qui ne correspond pas au fichier (par exemple après la fin du fichier, y compris lorsqu’un autre fichier l’a tronqué).

Sur les systèmes POSIX sur lesquels mmap(), msync() et munmap() sont disponibles, la constante symbolique _POSIX_MAPPED_FILES est définie dans <unistd.h> comme étant une valeur supérieure à 0. (Voir aussi sysconf(3).)

SVr4, BSD 4.4, POSIX.1-2001.

Sous Linux, il n’y a aucune garantie comme celle suggérée sous MAP_NORESERVE. Par défaut, tout processus peut être tué à tout moment lorsque le système s’exécute en dehors de de l’espace mémoire.

Dans les noyaux antérieurs au 2.6.7, l’attribut MAP_POPULATE n’a d’effet que si prot a la valeur PROT_NONE.

getpagesize(2), mincore(2), mlock(2), mmap2(2), mremap(2), msync(2), remap_file_pages(2), setrlimit(2), shm_open(3)
B.O. Gallmeister, POSIX.4, O’Reilly, pp. 119-124 et 365-369.

Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 14 octobre 1996 et révisée le 14 août 2006.

L’équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 2 mmap ». N’hésitez pas à signaler à l’auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.