NOM
inotify - Contrôler les événements des systèmes de fichiers
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(2) (ou inotify_init1(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 se référant à cette instance inotify. L’appel système plus
récent inotify_init1(2) est comme inotify_init(2), mais fournit des
fonctionnalités supplémentaires.
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(2) 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(2) 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(2) se bloquera jusqu’à ce qu’au moins un événement ait
lieu (à moins qu’elle ne soit interrompue par un signal, auquel cas
l’appel échouera avec l’erreur EINTR ; voir signal(7)).
Chaque lecture (avec read(2)) 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 optionnel 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(2).
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.
Le comportement lorsque le tampon donné à read(2) est trop petit pour
renvoyer l’information sur le prochain événement dépend de la version
du noyau : avant 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 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(2) et
peuvent être renvoyés via le champ mask retourné par read(2) :
IN_ACCESS Accès au fichier (lecture) (*).
IN_ATTRIB Modification des métadonnées, par exemple, les
permissions, les horodatages, les attributs
étendus, le compteur de liens (depuis
Linux 2.6.25), UID, GID, 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(2).
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(2) :
IN_DONT_FOLLOW (depuis Linux 2.6.15)
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 (depuis Linux 2.6.15)
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(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 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 maximale du nombre de « watches » qui
peuvent être créées par identifiant utilisateur réel.
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
(IN_DONT_FOLLOW, IN_MASK_ADD et IN_ONLYDIR ont été ajouté dans la
version 2.5).
CONFORMITÉ
L’API inotify est spécifique Linux.
NOTES
Les descripteurs de fichier inotify peuvent être contrôlés en utilisant
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, il est possible d’être notifié par des signaux
pour des entrées-sorties des 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 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 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 si
l’événement le plus ancien n’a toujours pas été lu (mais consultez la
section BOGUES).
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(2) 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.
BOGUES
Dans les noyaux antérieurs à 2.6.16, l’attribut IN_ONESHOT de mask ne
fonctionne pas.
Avant le noyau 2.6.25, le code du noyau qui était sensé regrouper deux
événements successifs (c’est-à-dire que les deux événements les plus
récents pouvaient être fusionnés si le plus ancien des deux n’avait
toujours pas été lu) vérifiait à la place si l’événement le plus récent
pouvait être fusionné à l’événement non lu le plus ancien.
VOIR AUSSI
inotify_add_watch(2), inotify_init(2), inotify_init1(2),
inotify_rm_watch(2), read(2), stat(2),
Documentation/filesystems/inotify.txt.
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
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, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Julien Cristau <jcristau@debian.org> et l’équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou 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> ».