INOTIFY(7)

NOM
inotify - Surveillance d'événements sur le système de fichier

DESCRIPTION
L'API inotify fournit un mécanisme pour la surveillance d'événements sur le système de fichiers. Inotify peut être utilisé pour surveiller des fichiers individuels ou pour surveiller des répertoires. Lorsqu'un répertoire est surveillé, inotify renverra les événements du répertoire lui-même et des fichiers qu'il contient. Les appels système suivants sont utilisés avec cette API : inotify_init(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 faisant référence à une instance inotify. inotify_add_watch(2) manipule une « liste de surveillance » associée à une instance inotify. Chaque élément (« surveillant ») de la liste de surveillance spécifie le nom du chemin d'un fichier ou d'un répertoire, avec un ensemble d'événements que le noyau doit surveiller pour le fichier référencé par ce nom de chemin. inotify_add_watch(2) peut soit créer un nouvel élément surveillant, soit modifier un élément existant. Chaque surveillant a un « descripteur de surveillant » unique, un entier renvoyé par inotify_add_watch(2) lorsque le surveillant est créé. inotify_rm_watch(2) supprime un élément d'une liste de surveillance inotify. Lorsque tous les descripteurs de fichier référençant une instance inotify ont été fermés, l'objet sous-jacent et ses ressources sont libérés afin de pouvoir être réutilisés par le noyau ; tous les surveillants associés sont automatiquement libérés. Pour déterminer quels événements sont survenus, une application lit (read(2)) le descripteur de fichier. Si aucun événement n'est survenu, en supposant que l'on ait un descripteur de fichier bloquant, une lecture (read(2)) bloquera jusqu'à ce qu'au moins un événement survienne. Chaque lecture réussie renvoie un tampon contenant une ou plusieurs structures comme la suivante :
struct inotify_event {
    int      wd;       /* Descripteur de surveillant */
    uint32_t mask;     /* Masque d'événement */
    uint32_t cookie;   /* Cookie unique associant des événements
                          en relation (pour rename(2)) */
    uint32_t len;      /* Taille du champ 'name' */
    char     name[];   /* Nom optionnel terminé par un octet nul */
};
wd identifie le surveillant pour lequel survient cet événement. C'est l'un des descripteurs de surveillant renvoyés par un précédent appel à inotify_add_watch(2). mask contient des bits qui décrivent l'événement qui est survenu (voir plus loin). cookie est un entier unique qui connecte les événements en relation. Actuellement, il n'est utilisé que pour renommer les événements permettant à la paire résultante des événements IN_MOVE_FROM et IN_MOVE_TO d'être connectée par l'application. Le champ name n'est présent que lorsqu'un événement est renvoyé pour un fichier appartenant au répertoire surveillé ; il identifie le chemin relatif du fichier dans le répertoire surveillé. Le nom du chemin est terminé avec un octet nul et peut inclure d'autres octets nuls pour aligner les lectures ultérieures sur une frontière d'adresse convenable. Le champ len totalise tous les octets de name, y compris les octets nuls ; la longueur de chaque structure inotify_event est donc sizeof(inotify_event)+len. Le comportement lorsque le tampon fourni à read(2) est trop petit pour renvoyer les informations sur le prochain événement dépend de la version du noyau : dans les noyaux précédents le 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 de inotify_add_watch(2) et le champ mask de la structure inotify_event renvoyée lors de la lecture (read(2)) d'un descripteur de fichier inotify sont tous les deux des masques de bits qui identifient les événements inotify. Les bits suivants peuvent être spécifiés dans mask lors d'un appel à inotify_add_watch(2) et être renvoyés dans le champ mask lors d'un appel à read(2) :
Bit | Description
IN_ACCESS | On a accédé au fichier (lecture) (*)
IN_ATTRIB | Les métadonnées ont changées (permissions, horodatages,
 | attributs étendus, etc.) (*)
IN_CLOSE_WRITE | Un fichier ouvert en écriture a été fermé (*)
IN_CLOSE_NOWRITE | Un fichier pas ouvert en écriture a été fermé (*)
IN_CREATE | Un fichier/répertoire a été créé dans le répertoire surveillé (*)
IN_DELETE | Un fichier/répertoire a été supprimé du répertoire surveillé (*)
IN_DELETE_SELF | Le fichier/répertoire surveillé a été supprimé
IN_MODIFY | Le fichier a été modifié (*)
IN_MOVE_SELF | Le fichier/répertoire surveillé a été déplacé
IN_MOVED_FROM | Le fichier a été déplacé hors du répertoire surveillé (*)
IN_MOVED_TO | Le fichier a été déplacé vers le répertoire surveillé (*)
IN_OPEN | Le fichier a été ouvert (*)

Lors de la surveillance d'un répertoire, les événements précédents marqués d'un astérisque (*) peuvent survenir pour des fichiers appartenant au répertoire, auquel cas le champ name dans la structure inotify_event renvoyée identifie le nom du fichier dans le répertoire.

La macro IN_ALL_EVENTS est définie comme un masque de bits de tous les événements précédents. Cette macro peut être utilisée comme argument mask lors d'un appel à inotify_add_watch(2). Il y a deux autres macros bien pratiques : IN_MOVE qui est équivalente à IN_MOVED_FROM|IN_MOVED_TO, et IN_CLOSE qui est équivalente à IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.

Les bits supplémentaires suivants peuvent également être spécifiés dans mask lors d'un appel à inotify_add_watch() :
Bit | Description
IN_DONT_FOLLOW | Ne pas déréférencer pathname si c'est un lien symbolique
 | (Depuis Linux 2.6.15)
IN_MASK_ADD | Ajouter (OU) les événements au masque de surveillance
 | pour ce chemin s'il existe déjà (plutôt que de remplacer le masque)
IN_ONESHOT | Surveiller pathname pour un événement, puis le retirer
 | de la liste de surveillance.
IN_ONLYDIR | Ne surveiller pathname que si c'est un répertoire
 | (Depuis Linux 2.6.15)

Les bits suivants peuvent être positionnés dans le champ mask renvoyé par read(2) :
Bit | Description
IN_IGNORED | Le surveillant a été retiré explicitement (inotify_rm_watch(2))
 | ou automatiqueemnt (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 | La file d'événements a débordé (wd vaut -1 pour cet événement)
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 noyau consommé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 une limite haute du nombre d'événements qui peuvent être mis en file d'attente dans l'instance inotify correspondante. Les événement en excès sont rejetés mais l'événement IN_Q_OVERFLOW est toujours généré.

/proc/sys/fs/inotify/max_user_instances
    Spécifie la limite haute du nombre d'instances inotify qui peuvent être crées par UID réel.

/proc/sys/fs/inotify/max_user_watches
    Spécifie une limite sur le nombre de surveillants qui peuvent être associés à chaque instance inotify.

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

CONFORMITÉ
Cet appel système est spécifique à Linux.

NOTES
Les descripteurs de fichiers inotify peuvent être surveillés avec select(2), poll(2) et epoll(7). Si des événements inotify successifs produits sur un descripteur de fichier inotify sont identiques (mêmes wd, mask, cookie et name), ils sont fusionnés en un seul événement. Les événements renvoyés par une lecture sur un descripteur de fichier inotify forment une file ordonnée. Ainsi, par exemple, il est garanti que si un répertoire est renommé, les événements seront produits dans le bon ordre sur le descripteur de fichier inotify. L'ioctl(2) FIONREAD renvoie le nombre d'octets disponibles à la lecture sur un descripteur de fichier inotify. La surveillance inotify sur les répertoires n'est pas récursive : pour surveiller les sous-répertoires d'un répertoire, vous devez créer des surveillants supplémentaires.

BOGUES
Dans les noyaux précédant le 2.6.16, l'attribut IN_ONESHOT de mask ne fonctionnait pas.

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

TRADUCTION

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 21 juillet 2006 et révisée le 22 décembre 2007.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 7 inotify ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.