INOTIFY

Index

NOM
DESCRIPTION
1. Événements inotify
2. Interfaces /proc
NOTES
VERSIONS
BOGUES
CONFORMITÉ
VOIR AUSSI
TRADUCTION

NOM

inotify - Contrôler les événements des systèmes de fichiers

DESCRIPTION

L'API inotify fournit un mécanisme pour contrôler les événements au niveau des systèmes de fichiers. Inotify peut être utilisé pour contrôler des fichiers individuels ou des répertoires. Quand un répertoire est contrôlé, 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(), inotify_add_watch(), inotify_rm_watch(), read() et close().
inotify_init(2) crée une instance inotify et renvoie un descripteur de fichier se référant à cette instance inotify.
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 contrôler pour le fichier indiqué par ce chemin. inotify_add_watch() 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() 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() se bloquera jusqu'à ce qu'au moins un événement ait lieu.
Chaque lecture (avec read()) 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 optionel 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().
mask contient des bits qui décrivent l'événement qui a eu lieu (voyez 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_MOVE_FROM et IN_MOVE_TO en résultant d'être associés par l'application.
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 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(inotify_event)+len.

Événements inotify

L'argument mask passé à inotify_add_watch(2) et le champ mask de la structure inotify_event renvoyés lors de la lecture avec read(2) d'un descripteur de fichier inotify sont tous deux des bits de masquage identifiant les événements inotify. Les bits suivants peuvent être définis dans l'argument mask lors de l'appel à inotify_add_watch() et peuvent être renvoyés via le champ mask retourné par read() :

Bit	Description
IN_ACCESS	Accès au fichier (lecture) (*)
IN_ATTRIB	Changement des métadonnées (permissions, dates,
	attributs étendus, etc.) (*)
IN_CLOSE_WRITE	Fichier ouvert en écriture fermé (*)
IN_CLOSE_NOWRITE	Fichier non ouvert en écriture fermé (*)
IN_CREATE	Fichier/rép. créé dans le répertoire surveillé (*)
IN_DELETE	Fichier/répertoire supprimé dans le répertoire
	surveillé (*)
IN_DELETE_SELF	Fichier/répertoire surveillé supprimé
IN_MODIFY	Fichier modifié (*)
IN_MOVE_SELF	Fichier/répertoire surveillé déplacé
IN_MOVED_FROM	Fichier déplacé hors du répertoire surveillé (*)
IN_MOVED_TO	Fichier déplacé dans le répertoire surveillé (*)
IN_OPEN	Fichier ouvert (*)

Lors de la surveillance d'un répertoire, les événements marqués par un astérisque (*) ci-dessus peuvent avoir lieu pour des fichiers du répertoire, auquel cas le champ name dans la structure inotify_event renvoyée identifie le nom du fichier dans ce répertoire.
La macro IN_ALL_EVENTS est définie comme un bit de masquage de tous les événements décrits ci-dessus. Cette macro peut être utilisée comme l'argument mask lors de l'appel à inotify_add_watch().
Deux macros supplémentaires sont disponibles : IN_MOVE, équivalent à IN_MOVED_FROM|IN_MOVED_TO, et IN_CLOSE, équivalent à IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.
Les bits supplémentaires suivants peuvent être indiqués dans l'argument mask lors de l'appel à inotify_add_watch() :

Bit	Description
IN_DONT_FOLLOW	Ne pas déréférencer pathname s'il s'agit d'un lien
	symbolique
IN_MASK_ADD	Ajouter les événements au masque de
	surveillance de ce fichier
	s'il existe déjà (au lieu de remplacer le masque)
IN_ONESHOT	Surveiller pathname jusqu'au premier événement, puis
	le supprimer de la liste de surveillance
IN_ONLYDIR	Ne surveiller pathname que si c'est un répertoire

Les bits suivants peuvent avoir été définis dans le champ mask renvoyé par read() :

Bit	Description
IN_IGNORED	Élément de surveillance supprimé explicitement
	(inotify_rm_watch()) ou automatiquement (fichier
	supprimé ou système de fichier démonté)
IN_ISDIR	Le sujet de cet événement est un répertoire
IN_Q_OVERFLOW	Queue des événements surchargée (wd vaut alors -1)
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 du noyau utilisé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 la limite maximale du nombre des événements qui peuvent entrer dans la file d'attente de l'instance inotify correspondante. Les événements au-delà de cette limite sont annulés, mais un événement IN_Q_OVERFLOW est systématiquement généré.
/proc/sys/fs/inotify/max_user_instances: Cela spécifie la limite maximale du nombre d'instances inotify qui peuvent être créées par identifiant utilisateur réel.
/proc/sys/fs/inotify/max_user_watches: Cela spécifie la limite du nombre d'éléments de surveillance qui peuvent être associés avec chaque instance inotify.

NOTES

Les descripteurs de fichier inotify peuvent être contrôlés en utilisant select(2), poll(2) et epoll(7).
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.
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() FIONREAD renvoie le nombre d'octets disponibles pour la lecture d'un descripteur de fichier inotify.
La surveillance inotify des répertoires n'est pas récursive : pour surveiller les sous-répertoires d'un répertoire, des éléments de surveillance supplémentaires doivent être créés.

VERSIONS

Inotify a été inclus dans le noyau Linux 2.6.14. Les interfaces bibliothèque nécessaires ont été ajoutées à glibc dans la version 2.4.

BOGUES

Dans les noyaux antérieurs à 2.6.16, l'attribut IN_ONESHOT de mask ne fonctionne pas.
Sous glibc 2.4, les définitions pour IN_DONT_FOLLOW, IN_MASK_ADD et IN_ONLYDIR ne se trouvent pas dans <sys/inotify.h>.

CONFORMITÉ

L'API inotify est spécifique Linux.

VOIR AUSSI

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

TRADUCTION

Cette page de manuel a été traduite et mise à jour par Christophe Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par Alain Portal <aportal AT univ-montp2 DOT fr> jusqu'en 2006.
La traduction de cette page de manuel est basée sur les traductions disponibles sur http://manpagesfr.free.fr/, mais est gérée par l'équipe francophone de traduction de Debian au travers de la liste de discussion debian-l10n-french.
Veuillez signaler toute erreur de traduction par un rapport de bogue sur le paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « man -L C <section> <page_de_man> ».

Création : octobre 2007