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(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 ; consultez
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 (voir 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_MOVED_FROM et
IN_MOVED_TO en résultant d'être associés par
l'application. Pour tous les autres types d'événements,
cookie est mis à 0.
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(structinotify_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. Indiquer un tampon de taille
sizeof(struct inotify_event) + NAME_MAX + 1
est suffisant pour lire au moins un événement.
É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_EXCL_UNLINK (depuis Linux 2.6.36)
- Par défaut, lors de la surveillance
d'événements sur les entrées d'un répertoire, des
événements sont créés pour ces entrées même
après leur suppression du répertoire. De nombreux
événements inintéressants pour certaines applications
peuvent ainsi être créés (par exemple, lors de la
surveillance de /tmp, où de nombreuses applications
créent des fichiers temporaires donc les noms sont immédiatement
supprimés). Indiquer IN_EXCL_UNLINK modifie le comportement
par défaut, de telle sorte qu'aucun événement n'est
créé pour ces entrées après leur suppression du
répertoire surveillé.
- 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.13. 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ées dans la version 2.5).
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 ; consultez 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.
Limites et réserves¶
La surveillance inotify des répertoires n'est pas récursive :
pour surveiller les sous-répertoires, des éléments de
surveillance supplémentaires doivent être créés. Cela peut
être assez long pour les répertoires contenant une grande
arborescence.
L'interface inotify ne fournit aucune information sur l'utilisateur ou le
processus qui a déclenché l'événement inotify.
Veuillez noter que la file d'événements peut déborder. Dans ce
cas, des événements sont perdus. Les applications robustes doivent
gérer correctement la possibilité de perdre des
événements.
L'interface inotify identifie les fichiers affectés par leur nom.
Cependant, au moment où l'application traite un événement
inotify, ce nom de fichier peut avoir déjà été
supprimé ou renommé.
Si on supervise un répertoire dans son intégralité, et si un
nouveau sous-répertoire est créé dans ce répertoire,
faites bien attention qu'au moment ou vous créez un élément de
surveillance sur le nouveau sous-répertoire, de nouveaux fichiers peuvent
avoir déjà été créés dans le
sous-répertoire. Ainsi, vous devriez analyser le contenu du
sous-répertoire immédiatement après avoir ajouté
l'élément de surveillance.
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 dans les sources du noyau Linux
COLOPHON¶
Cette page fait partie de la publication 3.44 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¶
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<
http://po4a.alioth.debian.org/> par l'équipe de traduction
francophone au sein du projet perkamon
<
http://perkamon.alioth.debian.org/>.
Christophe Blaess <
http://www.blaess.fr/christophe/> (1996-2003), Alain
Portal <
http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et
l'équipe francophone de traduction de Debian (2006-2009).
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> ».