Linux Certif

Toute la documentation sur la certification Linux LPI

inotify

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

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 28 novembre 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.