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 (à moins qu'elle ne soit interrompue par un signal, auquel cas l'appel échouera avec l'erreur EINTR ; voir signal(7). 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 antérieurs au 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) :

    IN_ACCESS
        On a accédé au fichier (lecture) (*)
    IN_ATTRIB
        Les métadonnées ont changées, par exemple, les permissions, les horodatages, les attributs étendus, le compeur de liens (depuis Linux 2.6.25), UID, GID, 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() :

    IN_DONT_FOLLOW (Depuis Linux 2.6.15)
        Ne pas déréférencer pathname si c'est un lien symbolique
    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 (Depuis Linux 2.6.15)
        Ne surveiller pathname que si c'est un répertoire

Les bits suivants peuvent être positionnés 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
        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 fichier inotify peuvent être surveillés avec 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, la notification d'E/S pilotées par signal est disponible pour les descripteurs de fichier inotify ; voir 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 fichier 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 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 antérieurs au 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 17 juillet 2008.

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.