Man page 7 : inotify

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

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.

2.1. Événements inotify ▲

2.2. Interfaces /proc ▲

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

L'API inotify est spécifique Linux.

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.

5.1. Limites et réserves ▲

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.

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

Cette page fait partie de la publication 3.52 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/.

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

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