inotify   Début   Suivant   Sommaire   Préc.page.lue   Accueil
Section: Manuel du programmeur Linux (7)
Updated: 15 mai 2008
Sommaire  



NOM   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
inotify - Surveillance d'événements sur le système de fichier  



DESCRIPTION   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
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   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
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   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
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   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
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É   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
Cet appel système est spécifique à Linux.  



NOTES   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
Les descripteurs de fichiers 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 fichiers 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 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 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   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
Dans les noyaux précédant le 2.6.16, l'attribut IN_ONESHOT de mask ne fonctionnait pas.  



VOIR AUSSI   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil
inotify_add_watch(2), inotify_init(2), inotify_rm_watch(2), read(2), stat(2), Documentation/filesystems/inotify.txt.  



TRADUCTION   Début   Précédent   Suivant   Sommaire   Préc.page.lue   Accueil

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 6 juin 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.


 



Sommaire   Début   Suivant   Sommaire   Préc.page.lue   Accueil
NOM
DESCRIPTION
Événements inotify
Interfaces /proc
VERSIONS
CONFORMITÉ
NOTES
BOGUES
VOIR AUSSI
TRADUCTION

Ce document a été créé par man2html suivi de man2html.pl, le 17/10/2008 17:50:26, en utilisant les pages de 'man'.
 

Valid HTML 4.01 Transitional