Ubuntu Manpage: inotify - Surveiller les événements des systèmes de fichiers

NOM

       inotify - Surveiller les événements des systèmes de fichiers

DESCRIPTION

L'API inotify fournit un mécanisme pour surveiller les événements au niveau des systèmes
de fichiers. Inotify peut être utilisé pour surveiller des fichiers individuels ou des
répertoires. Quand un répertoire est surveillé, 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 surveiller
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_MOVED_FROM et
IN_MOVED_TO en résultant d'être associés par l'application. Pour tous les autres types
d'événements, cookie est mis à 0.

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
(« \0 ») 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(structinotify_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. Indiquer
un tampon de taille

sizeof(struct inotify_event) + NAME_MAX + 1

est suffisant pour lire au moins un événement.

É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 ou GID. (*).
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 Généré pour le répertoire contenant l'ancien nom quand un fichier
est renommé.
IN_MOVED_TO Généré pour le répertoire contenant le nouveau nom quand un fichier
est renommé.
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 surveillé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 aucun renseignement sur l'utilisateur ou le processus qui a
déclenché l'événement inotify. En particulier, un processus en train de surveiller des
événements à l'aide d'inotify ne dispose d'aucun moyen facile pour distinguer les
événements qu'il déclenche lui-même de ceux qui ont été déclenchés par d'autres processus.

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 la surveillance concerne 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

       inotifywait(1),  inotifywatch(1), inotify_add_watch(2), inotify_init(2), inotify_init1(2),
       inotify_rm_watch(2), read(2), stat(2)

       Documentation/filesystems/inotify.txt dans les sources du noyau Linux

COLOPHON

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

TRADUCTION

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

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