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