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

NOM

       inotify - Contrôler les événements des systèmes de fichiers

DESCRIPTION

       L'API inotify fournit un mécanisme pour contrôler les événements au niveau des systèmes de
       fichiers. Inotify peut être  utilisé  pour  contrôler  des  fichiers  individuels  ou  des
       répertoires.  Quand un répertoire est contrôlé, inotify va signaler des événements pour le
       répertoire lui-même et pour les fichiers de ce répertoire.

       Les  appels  système  suivants  sont  utilisés  avec  cette  API :   inotify_init(2)   (ou
       inotify_init1(2)), inotify_add_watch(2), inotify_rm_watch(2), read(2) et close(2).

       inotify_init(2) crée une instance inotify et renvoie un descripteur de fichier se référant
       à  cette  instance  inotify.  L'appel  système  plus  récent  inotify_init1(2)  est  comme
       inotify_init(2), mais fournit des fonctionnalités supplémentaires.

       inotify_add_watch(2)  manipule  la  « liste  de  surveillance »  associée  à  une instance
       inotify. Chaque élément (« watch ») de la liste de surveillance spécifie  le  chemin  d'un
       fichier ou d'un répertoire, avec un ensemble d'événements que le noyau doit contrôler pour
       le fichier  indiqué  par  ce  chemin.  inotify_add_watch(2)  crée  un  nouvel  élément  de
       surveillance  ou  modifie un élément existant. Chaque élément a un unique « descripteur de
       surveillance », un entier renvoyé par inotify_add_watch(2) lorsque cet élément est créé.

       inotify_rm_watch(2) retire un élément d'une liste de surveillance inotify.

       Quand tous les descripteurs de fichier se référant à une instance inotify ont été  fermés,
       l'objet  sous-jacent  et  ses  ressources sont libérés pour être réutilisés par le noyau ;
       tous les éléments de surveillance associés sont automatiquement libérés.

       Pour déterminer quels événements ont eu lieu, une application  va  lire  avec  read(2)  le
       descripteur  de fichier inotify. Si aucun événement n'a eu lieu, alors, en supposant qu'il
       s'agisse d'un descripteur de fichier bloquant, read(2) se bloquera jusqu'à ce qu'au  moins
       un  événement  ait  lieu  (à  moins  qu'elle ne soit interrompue par un signal, auquel cas
       l'appel échouera avec l'erreur EINTR ; consultez signal(7)).

       Chaque lecture (avec read(2)) réussie renvoie un tampon contenant  une  ou  plusieurs  des
       structures suivantes :

           struct inotify_event {
               int      wd;       /* Descripteur d'élément de surveillance */
               uint32_t mask;     /* Masque d'événements */
               uint32_t cookie;   /* Cookie unique d'association des
                                     événements (pour rename(2)) */
               uint32_t len;      /* Taille du champ name */
               char     name[];   /* Nom optionnel terminé par un nul */
           };

       wd identifie l'élément de surveillance pour lequel cet événement a lieu. Il s'agit de l'un
       des descripteurs de fichier renvoyés par un précédent appel à inotify_add_watch(2).

       mask contient des bits qui décrivent l'événement qui a eu lieu (voir ci-dessous).

       cookie est un entier unique qui relie les événements. Ce n'est  actuellement  utilisé  que
       pour  les  événements  de  renommage,  et  permet  à la paire d'événements IN_MOVE_FROM et
       IN_MOVE_TO en résultant d'être associés par l'application.

       Le champ name n'est présent que lorsqu'un événement est renvoyé pour un  fichier  au  sein
       d'un  répertoire  surveillé.  Il  identifie le chemin du fichier par rapport au répertoire
       surveillé. Ce chemin est terminé par un caractère nul et peut inclure d'autres octets nuls
       pour ajuster des lectures successives à une limite d'adressage convenable.

       Le  champ len compte tous les octets de name, incluant les caractères nuls. La longueur de
       chaque structure inotify_event vaut donc sizeof(inotify_event)+len.

       Le  comportement  lorsque  le  tampon  donné  à  read(2)  est  trop  petit  pour  renvoyer
       l'information  sur  le  prochain  événement  dépend de la version du noyau : avant 2.6.21,
       read(2) renvoie 0 ; depuis le noyau 2.6.21, read(2) échoue avec l'erreur EINVAL.

   Événements inotify
       L'argument  mask  passé  à  inotify_add_watch(2)  et  le  champ  mask  de   la   structure
       inotify_event renvoyés lors de la lecture avec read(2) d'un descripteur de fichier inotify
       sont tous deux des bits de masquage identifiant les événements inotify. Les bits  suivants
       peuvent  être  définis  dans  l'argument  mask  lors  de l'appel à inotify_add_watch(2) et
       peuvent être renvoyés via le champ mask retourné par read(2) :

           IN_ACCESS         Accès au fichier (lecture) (*).
           IN_ATTRIB         Modification des métadonnées,  par  exemple,  les  permissions,  les
                             horodatages,  les  attributs  étendus,  le compteur de liens (depuis
                             Linux 2.6.25), UID, GID, etc. (*).
           IN_CLOSE_WRITE    Fichier ouvert en écriture fermé (*).
           IN_CLOSE_NOWRITE  Fichier non ouvert en écriture fermé (*).
           IN_CREATE         Fichier/rép. créé dans le répertoire surveillé (*).
           IN_DELETE         Fichier/répertoire supprimé dans le répertoire surveillé (*).
           IN_DELETE_SELF    Fichier/répertoire surveillé supprimé.
           IN_MODIFY         Fichier modifié (*).
           IN_MOVE_SELF      Fichier/répertoire surveillé déplacé.
           IN_MOVED_FROM     Fichier déplacé hors du répertoire surveillé (*).
           IN_MOVED_TO       Fichier déplacé dans le répertoire surveillé (*).
           IN_OPEN           Fichier ouvert (*).

       Lors de la surveillance d'un répertoire, les événements  marqués  par  un  astérisque  (*)
       ci-dessus  peuvent  avoir  lieu  pour des fichiers du répertoire, auquel cas le champ name
       dans la structure inotify_event renvoyée identifie le nom du fichier dans ce répertoire.

       La macro IN_ALL_EVENTS est définie comme un bit de masquage de tous les événements décrits
       ci-dessus.  Cette  macro  peut  être  utilisée  comme  l'argument  mask  lors de l'appel à
       inotify_add_watch(2).

       Deux    macros    supplémentaires    sont    disponibles :    IN_MOVE,    équivalent     à
       IN_MOVED_FROM|IN_MOVED_TO, et IN_CLOSE, équivalent à IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.

       Les  bits  supplémentaires  suivants  peuvent  être  indiqués dans l'argument mask lors de
       l'appel à inotify_add_watch(2) :

           IN_DONT_FOLLOW (depuis Linux 2.6.15)
                             Ne pas déréférencer pathname s'il s'agit d'un lien symbolique.
           IN_EXCL_UNLINK (depuis Linux 2.6.36)
                             Par défaut, lors de la surveillance  d'événements  sur  les  entrées
                             d'un  répertoire,  des  événements  sont créés pour ces entrées même
                             après  leur  suppression  du  répertoire.  De  nombreux   événements
                             inintéressants  pour certaines applications peuvent ainsi être créés
                             (par exemple, lors de la surveillance  de  /tmp,  où  de  nombreuses
                             applications  créent  des  fichiers  temporaires  donc les noms sont
                             immédiatement  supprimés).  Indiquer   IN_EXCL_UNLINK   modifie   le
                             comportement  par  défaut,  de  telle sorte qu'aucun événement n'est
                             créé  pour  ces  entrées  après  leur  suppression   du   répertoire
                             surveillé.
           IN_MASK_ADD       Ajouter  les événements au masque de surveillance de ce fichier s'il
                             existe déjà (au lieu de remplacer le masque).
           IN_ONESHOT        Surveiller pathname jusqu'au premier événement, puis le supprimer de
                             la liste de surveillance
           IN_ONLYDIR (depuis Linux 2.6.15)
                             Ne surveiller pathname que si c'est un répertoire.

       Les bits suivants peuvent avoir été définis dans le champ mask renvoyé par read(2) :

           IN_IGNORED        Le  surveillant  a été retiré explicitement (inotify_rm_watch(2)) ou
                             automatiquement (le fichier a été effacé, ou le système de  fichiers
                             a été démonté)
           IN_ISDIR          Le sujet de cet événement est un répertoire.
           IN_Q_OVERFLOW     Queue des événements surchargée (wd vaut alors -1).
           IN_UNMOUNT        Le système de fichiers contenant l'objet surveillé a été démonté.

   Interfaces /proc
       Les  interfaces  suivantes  peuvent  être utilisées pour limiter la quantité de mémoire du
       noyau utilisée par inotify :

       /proc/sys/fs/inotify/max_queued_events
              La  valeur  dans  ce  fichier   est   utilisée   lorsqu'une   application   appelle
              inotify_init(2)  pour  définir  la  limite  maximale  du  nombre des événements qui
              peuvent entrer dans la file d'attente de  l'instance  inotify  correspondante.  Les
              événements  au-delà  de  cette limite sont annulés, mais un événement IN_Q_OVERFLOW
              est systématiquement généré.

       /proc/sys/fs/inotify/max_user_instances
              Cela spécifie la limite maximale du nombre d'instances  inotify  qui  peuvent  être
              créées par identifiant utilisateur réel.

       /proc/sys/fs/inotify/max_user_watches
              Cela  spécifie  la limite maximale du nombre de « watches » qui peuvent être créées
              par identifiant utilisateur réel.

VERSIONS

       Inotify a été inclus dans le noyau Linux 2.6.13. Les interfaces  bibliothèque  nécessaires
       ont  été  ajoutées  à glibc dans la version 2.4 (IN_DONT_FOLLOW, IN_MASK_ADD et IN_ONLYDIR
       ont été ajoutées dans la version 2.5).

CONFORMITÉ

       L'API inotify est spécifique Linux.

NOTES

       Les descripteurs de fichier inotify peuvent être contrôlés en utilisant select(2), poll(2)
       et  epoll(7).  Lorsqu'un événement est disponible, le descripteur de fichier indique qu'il
       est accessible en lecture.

       Depuis  Linux 2.6.25,  il  est  possible  d'être  notifié  par  des   signaux   pour   des
       entrées-sorties  des  descripteurs de fichier inotify ; consultez la discussion de F_SETFL
       (pour la configuration de l'attribut O_ASYNC), F_SETOWN, et  F_SETSIG  dans  fcntl(2).  La
       structure siginfo_t (décrite dans sigaction(2)) qui est passée au gestionnaire de signal a
       les champs suivants définis : si_fd est défini avec le numéro de descripteur  de  fichiers
       inotify ; si_signo est défini avec le numéro du signal ; si_code est défini avec POLL_IN ;
       et si_band est défini avec POLLIN.

       Si deux événements inotify de sortie successifs produits sur  le  descripteur  de  fichier
       inotify  sont  identiques (wd, mask, cookie, et name identiques), alors ils sont fusionnés
       en un seul événement si l'événement le plus ancien n'a toujours pas été lu (mais consultez
       la section BOGUES).

       Les événements renvoyés lors de la lecture d'un descripteur de fichier inotify forment une
       file ordonnée. Ainsi, par exemple, il est garanti que lors du renommage  d'un  répertoire,
       les  événements  seront  produits  dans  l'ordre  convenable sur le descripteur de fichier
       inotify.

       L'ioctl(2)  FIONREAD  renvoie  le  nombre  d'octets  disponibles  pour  la  lecture   d'un
       descripteur de fichier inotify.

   Limites et réserves
       La  surveillance  inotify  des  répertoires  n'est  pas  récursive :  pour  surveiller les
       sous-répertoires, des éléments de surveillance supplémentaires doivent  être  créés.  Cela
       peut être assez long pour les répertoires contenant une grande arborescence.

       L'interface  inotify ne fournit aucune information sur l'utilisateur ou le processus qui a
       déclenché l'événement inotify.

       Veuillez noter que la file d'événements peut déborder. Dans ce cas,  des  événements  sont
       perdus.  Les applications robustes doivent gérer correctement la possibilité de perdre des
       événements.

       L'interface inotify identifie les fichiers affectés par leur nom. Cependant, au moment  où
       l'application  traite un événement inotify, ce nom de fichier peut avoir déjà été supprimé
       ou renommé.

       Si on supervise un répertoire dans son intégralité, et si un nouveau  sous-répertoire  est
       créé  dans  ce  répertoire, faites bien attention qu'au moment ou vous créez un élément de
       surveillance sur le nouveau sous-répertoire, de nouveaux fichiers peuvent avoir  déjà  été
       créés  dans le sous-répertoire. Ainsi, vous devriez analyser le contenu du sous-répertoire
       immédiatement après avoir ajouté l'élément de surveillance.

BOGUES

       Dans les noyaux antérieurs à 2.6.16, l'attribut IN_ONESHOT de mask ne fonctionne pas.

       Avant le noyau 2.6.25, le  code  du  noyau  qui  était  sensé  regrouper  deux  événements
       successifs (c'est-à-dire que les deux événements les plus récents pouvaient être fusionnés
       si le plus ancien des  deux  n'avait  toujours  pas  été  lu)  vérifiait  à  la  place  si
       l'événement le plus récent pouvait être fusionné à l'événement non lu le plus ancien.

VOIR AUSSI

       inotify_add_watch(2),  inotify_init(2),  inotify_init1(2),  inotify_rm_watch(2),  read(2),
       stat(2), Documentation/filesystems/inotify.txt.

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

       Christophe  Blaess  <URL:http://www.blaess.fr/christophe/>   (1996-2003),   Alain   Portal
       <URL:http://manpagesfr.free.fr/>  (2003-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> ».