Provided by: manpages-fr-dev_3.32d0.2p4-1_all bug

NOM

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

SYNOPSIS

       #include <sys/mman.h>

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

DESCRIPTION

       mmap() crée une  nouvelle  projection  dans  l'espace  d'adressage  virtuel  du  processus
       appelant.  L'adresse  de  démarrage  de  la nouvelle projection est indiquée dans addr. Le
       paramètre length indique la longueur de la projection.

       Si addr est NULL, le noyau choisit l'adresse à laquelle démarrer la projection ; c'est  la
       méthode  la  plus  portable pour créer une nouvelle projection. Si addr n'est pas NULL, le
       noyau le considère comme une indication sur  l'endroit  où  placer  la  projection ;  sous
       Linux,  elle  sera  placée  à  une  frontière  de  page  proche.  L'adresse de la nouvelle
       projection est renvoyée comme résultat de l'appel.

       Le contenu d'une projection de fichier (par opposition à  une  projection  anonyme ;  voir
       ci-dessous MAP_ANONYMOUS) est initialisé avec length octets à partir de la position offset
       dans le fichier (ou autre objet) correspondant au descripteur de fichier fd.  offset  doit
       être un multiple de la taille de page, renvoyée par sysconf(_SC_PAGE_SIZE).

       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 détermine si les modifications de la projection  sont  visibles  depuis
       les  autres processus projetant la même région, et si les modifications sont appliquées au
       fichier sous-jacent. Ce comportement est déterminé en incluant exactement une des  valeurs
       suivantes dans flags :

       MAP_SHARED Partager  la  projection. Les modifications de la projection sont visibles dans
                  les autres processus qui projettent ce fichier, et sont appliquées  au  fichier
                  sous-jacent.  En  revanche, ce dernier n'est pas nécessairement mis à jour tant
                  qu'on n'a pas appelé msync(2) ou munmap().

       MAP_PRIVATE
                  Créer une projection privée, utilisant la méthode de copie  à  l'écriture.  Les
                  modifications de la projection ne sont pas visibles depuis les autres processus
                  projetant le même fichier, et ne modifient pas le fichier  lui-même.  Il  n'est
                  pas  précisé  si les changements effectués dans le fichier après l'appel mmap()
                  seront visibles.

       Ces deux attributs sont décrits dans POSIX.1-2001.

       De plus, zéro ou plus des valeurs suivantes peuvent être incluses dans flags (avec  un  OU
       binaire) :

       MAP_32BIT (depuis Linux 2.4.20, 2.6)
              Placer  la  projection dans les deux premiers gigaoctets de l'espace d'adressage du
              processus. Cet attribut n'est pris en charge que sous x86-64, pour  les  programmes
              64 bits.  Il  a été ajouté pour permettre à la pile d'un thread d'être allouée dans
              les deux premiers gigaoctets de mémoire,  afin  d'améliorer  les  performances  des
              changements  de  contexte  sur  les  premiers  processeurs 64 bits. Les processeurs
              x86-64 modernes n'ont plus ces problèmes de performance, donc l'utilisation de  cet
              attribut  n'est  pas  nécessaire  sur ces systèmes. L'attribut MAP_32BIT est ignoré
              quand MAP_FIXED est positionné.

       MAP_ANON
              Synonyme de MAP_ANONYMOUS. Déconseillé.

       MAP_ANONYMOUS
              La projection n'est supportée par aucun fichier ; son contenu est initialisé  à  0.
              Les  arguments  fd  et  offset  sont ignorés ; cependant, certaines implémentations
              demandent que fd soit -1  si  MAP_ANONYMOUS  (ou  MAP_ANON)  est  utilisé,  et  les
              applications  portables  doivent  donc  s'en  assurer.  Cet  attribut,  utilisé  en
              conjonction de MAP_SHARED, n'est implémenté que depuis Linux 2.4.

       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 par déni
              de service.)

       MAP_EXECUTABLE
              Cet attribut est ignoré.

       MAP_FILE
              Attribut pour compatibilité. Ignoré.

       MAP_FIXED
              Ne pas considérer addr comme une indication : n'utiliser  que  l'adresse  indiquée.
              addr  doit  être  un multiple de la taille de page. Si la zone mémoire indiquée par
              addr et len recouvre des pages d'une projection existante, la partie recouverte  de
              la  projection existante sera ignorée. Si l'adresse indiquée ne peut être utilisée,
              mmap() échouera. Il est déconseillé  d'utiliser  cette  option,  car  requérir  une
              adresse fixe pour une projection n'est pas portable.

       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_HUGETLB (depuis Linux 2.6.32)
              Allouer la projection à l'aide de « pages immenses ». Consultez le  fichier  source
              du noyau Documentation/vm/hugetlbpage.txt pour plus d'informations.

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

       MAP_NONBLOCK (depuis Linux 2.5.46)
              N'a de sens qu'en conjonction  avec  MAP_POPULATE.  Ne  pas  effectuer  de  lecture
              anticipée :  créer  seulement  les  entrées  de  tables de page pour les pages déjà
              présentes en RAM. Depuis Linux 2.6.23, cet attribut fait que MAP_POPULATE n'a aucun
              effet.  Un  jour  la  combinaison  de  MAP_POPULATE  et  MAP_NONBLOCK  pourra  être
              implémentée de nouveau.

       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  les  zones  soumises  à  une
              copie-en-écriture. Sans réservation, on peut recevoir un signal SIGSEGV durant  une
              écriture,  s'il  n'y a plus de place disponible. Consultez également la description
              du fichier /proc/sys/vm/overcommit_memory dans la page  proc(5).  Dans  les  noyaux
              antérieurs  à  2.6,  cet  attribut n'avait d'effet que pour les projections privées
              modifiables.

       MAP_POPULATE (depuis Linux 2.5.46)
              Remplit les tables de pages pour une projection. Pour une  projection  de  fichier,
              ceci  s'effectue  par  une  lecture anticipée du fichier. Les accès ultérieurs à la
              projection ne seront pas bloqués par des fautes de pages. MAP_POPULATE  n'est  géré
              pour les projections privées que depuis Linux 2.6.23.

       MAP_STACK (depuis Linux 2.6.27)
              Alloue la projection à une adresse qui convient pour la pile d'un processus ou d'un
              thread. Cet  attribut  n'a  pour  l'instant  aucun  effet,  mais  est  utilisé  par
              l'implémentation  des  threads  de  la  glibc  de  telle  sorte  que  si  certaines
              architectures nécessitent un traitement particulier pour l'allocation de  la  pile,
              leur  prise  en  charge  par la suite par la glibc pourra être implémentée de façon
              transparente.

       MAP_UNINITIALIZED (depuis Linux 2.6.33)
              N'efface pas les pages anonymes. Cet attribut n'a pour l'instant un effet que si le
              noyau  a  été  configuré avec l'option CONFIG_MMAP_ALLOW_UNINITIALIZED. À cause des
              implications sur la sécurité, cette option n'est normalement  active  que  sur  des
              périphériques  embarqués  (c'est-à-dire avec des périphériques avec lesquels il est
              possible d'avoir un contrôle total de la mémoire utilisateur).

       Parmi les attributs ci-dessus, seul MAP_FIXED est spécifié dans  POSIX.1-2001.  Cependant,
       la plupart des systèmes gèrent aussi MAP_ANONYMOUS (ou son synonyme MAP_ANON).

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

       La mémoire obtenue par mmap  est  préservée  au  travers  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.

   munmap()
       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  addr doit être un multiple de la taille de page. Toutes 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.

   Modifications d'horodatage pour les projections supportées par un fichier
       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(2)
       suivant avec attribut MS_SYNC ou MS_ASYNC.

VALEUR RENVOYÉE

       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).

ERREURS

       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
              (consultez setrlimit(2)).

       EBADF  fd  n'est  pas  un  descripteur  de  fichier  valable (et MAP_ANONYMOUS n'était pas
              précisé).

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

       EINVAL (depuis Linux 2.6.12) length est nul.

       EINVAL flags ne contient ni MAP_PRIVATE ni MAP_SHARED, ou les contient tous les deux.

       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 projections par processus a été
              dépassé.

       EPERM  L'argument prot a demandé PROT_EXEC mais la zone appartient à  un  fichier  sur  un
              système de fichiers monté sans permission 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 processus l'a tronqué).

CONFORMITÉ

       SVr4, BSD 4.4, POSIX.1-2001.

DISPONIBILITÉ

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

NOTES

       Depuis le noyau 2.4, cet appel système a été remplacé  par  mmap2(2).  De  nos  jours,  la
       fonction mmap() de la glibc appelle mmap2(2) avec la bonne valeur pour offset.

       Sur   certaines   architectures  matérielles  (par  exemple,  i386),  PROT_WRITE  implique
       PROT_READ. Cela dépend de l'architecture si  PROT_READ  implique  PROT_EXEC  ou  non.  Les
       programmes  portables  doivent  toujours indiquer PROT_EXEC s'ils veulent exécuter du code
       dans la projection.

       La manière portable de créer une projection est de spécifier addr à 0 (NULL), et d'omettre
       MAP_FIXED  dans  flags.  Dans  ce  cas,  le  système  choisit l'adresse de la projection ;
       l'adresse est choisie de manière à ne pas entrer en conflit avec une projection  existante
       et  de  ne  pas  être nulle. Si l'attribut MAP_FIXED est indiqué et si addr vaut 0 (NULL),
       l'adresse projetée sera zéro (NULL).

BOGUES

       Sous Linux, il n'y a aucune  garantie  comme  celles  indiquées  plus  haut  à  propos  de
       MAP_NORESERVE. Par défaut, n'importe quel processus peut être tué à tout moment lorsque le
       système n'a plus de mémoire.

       Dans les noyaux antérieurs à 2.6.7, le drapeau MAP_POPULATE n'avait d'effet  que  si  prot
       était PROT_NONE.

       SUSv3  indique que mmap() devrait échouer si length est 0. Cependant, avec les versions de
       Linux antérieures à 2.6.12, mmap() réussissait dans ce  cas :  aucune  projection  n'était
       créée,  et  l'appel  renvoyait  addr.  Depuis  le noyau 2.6.12, mmap() échoue avec le code
       d'erreur EINVAL si length est nul.

EXEMPLE

       Le programme suivant affiche la partie du fichier, précisé par le premier argument  de  la
       ligne  de commande, sur la sortie standard. Les octets qui seront affichés sont précisés à
       partir d'un offset (déplacement) et d'une longueur en deuxième et troisième paramètre.  Le
       code  fait  une  projection mémoire des pages nécessaires du fichier puis utilise write(2)
       pour afficher les octets voulus.

       #include <sys/mman.h>
       #include <sys/stat.h>
       #include <fcntl.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <unistd.h>

       #define handle_error(msg) \
           do { perror(msg); exit(EXIT_FAILURE); } while (0)

       int
       main(int argc, char *argv[])
       {
           char *addr;
           int fd;
           struct stat sb;
           off_t offset, pa_offset;
           size_t length;
           ssize_t s;

           if (argc < 3 || argc > 4) {
               fprintf(stderr, "%s fichier offset [longueur]\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           fd = open(argv[1], O_RDONLY);
           if (fd == -1)
               handle_error("open");

           if (fstat(fd, &sb) == -1)           /* Pour obtenir la taille du fichier */
               handle_error("fstat");

           offset = atoi(argv[2]);
           pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) - 1);
               /* l'offset pour mmap() doit être aligné sur une page */

           if (offset >= sb.st_size) {
               fprintf(stderr, "L'offset dépasse la fin du fichier\n");
               exit(EXIT_FAILURE);
           }

           if (argc == 4) {
               length = atoi(argv[3]);
               if (offset + length > sb.st_size)
                   length = sb.st_size - offset;
                       /* Impossible d'afficher les octets en dehors du fichier */

           } else {    /* Pas de paramètre longueur
                          ==> affichage jusqu'à la fin du fichier */
               length = sb.st_size - offset;
           }

           addr = mmap(NULL, length + offset - pa_offset, PROT_READ,
                       MAP_PRIVATE, fd, pa_offset);
           if (addr == MAP_FAILED)
               handle_error("mmap");

           s = write(STDOUT_FILENO, addr + offset - pa_offset, length);
           if (s != length) {
               if (s == -1)
                   handle_error("write");

               fprintf(stderr, "écriture partielle");
               exit(EXIT_FAILURE);
           }

           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

       getpagesize(2),  mincore(2),  mlock(2),  mmap2(2),   mprotect(2),   mremap(2),   msync(2),
       remap_file_pages(2), setrlimit(2), shmat(2), shm_open(3), shm_overview(7)
       B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128–129 et 389–391.

COLOPHON

       Cette  page  fait partie de la publication 3.32 du projet man-pages Linux. Une description
       du projet et des  instructions  pour  signaler  des  anomalies  peuvent  être  trouvées  à
       l'adresse <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis    2010,    cette   traduction   est   maintenue   à   l'aide   de   l'outil   po4a
       <URL:http://po4a.alioth.debian.org/> par l'équipe de traduction  francophone  au  sein  du
       projet perkamon <URL:http://perkamon.alioth.debian.org/>.

       Thierry  Vignaud  (2002),  Alain  Portal  <URL:http://manpagesfr.free.fr/> (2006).  Julien
       Cristau et l'équipe francophone de traduction de Debian (2006-2009).

       Veuillez     signaler     toute     erreur     de     traduction     en     écrivant     à
       <debian-l10n-french@lists.debian.org>   ou   par   un  rapport  de  bogue  sur  le  paquet
       manpages-fr.

       Vous pouvez toujours avoir accès à la version anglaise de  ce  document  en  utilisant  la
       commande « man -L C <section> <page_de_man> ».