Manpages

Limites et réserves
L’interface inotify ne fournit aucun renseignement sur l’utilisateur ou le processus qui a déclenché l’événement inotify. En particulier, un processus en train de surveiller des événements à l’aide d’inotify ne dispose d’aucun moyen facile pour distinguer les événements qu’il déclenche lui-même de ceux qui ont été déclenchés par d’autres processus.

Inotify ne signale que les événements déclenchés par un programme en espace utilisateur à l’aide de l’interface de programmation de système de fichiers. Par conséquent, elle n’intercepte pas les événements qui surviennent sur les systèmes de fichiers en réseau (les applications doivent avoir recours à la scrutation (polling) pour intercepter ce type d’événements). De plus, divers pseudo-systèmes de fichiers comme /proc, /sys et /dev/pts ne sont pas surveillables avec inotify.

L’interface inotify ne signale pas les accès ni les modifications de fichier qui pourraient survenir à cause de mmap(2), msync(2) ou munmap(2).

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

L’interface inotify identifie les événements à l’aide de descripteurs de surveillance. L’application est responsable de mettre en cache une correspondance (si nécessaire) entre les descripteurs de fichier et les chemins. Soyez vigilants aux renommages de répertoire qui pourraient affecter plusieurs chemins en cache.

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.

Si la surveillance concerne une arborescence dans son intégralité, et si un nouveau sous-répertoire est créé dans ce répertoire ou si un répertoire existant est renommé dans cette arborescence, soyez conscient qu’au moment où vous créez un élément de surveillance pour le nouveau sous-répertoire, de nouveaux fichiers (et sous-répertoires) peuvent déjà exister 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 (et, si nécessaire, ajouter des éléments de surveillance pour tous les sous-répertoires qu’il contient).

Remarquez que la file d’événements peut déborder. Dans ce cas, des événements sont perdus. Les applications robustes devraient gérer correctement la possibilité de perdre des événements. Par exemple, la reconstruction de tout ou partie du cache de l’application pourrait être nécessaire (une approche simple, mais éventuellement coûteuse, est de fermer le descripteur de fichier inotify, vider le cache, créer un nouveau descripteur de fichier inotify et recréer les éléments de surveillance et les entrées du cache pour les objets à surveiller).

Si un système de fichiers est monté par dessus un répertoire surveillé, aucun événement n’est généré, pas plus que pour les objets se trouvant directement sous le nouveau point de montage. Si le système de fichiers est par la suite démonté, les événements seront créés pour le répertoire et les objets qu’il contient.

Traitement des événements rename()
Comme noté précédemment, la paire d’événements IN_MOVED_FROM et IN_MOVED_TO générée par rename(2) peut être assemblée à l’aide de la valeur de cookie partagé. Cependant, la tâche d’assemblage peut poser quelques problèmes.

Ces deux événements sont normalement consécutifs dans le flux d’événements disponibles lors de la lecture depuis le descripteur de fichiers inotify. Cependant, ce n’est pas garanti. Si plusieurs processus déclenchent des événements pour des objets surveillés, alors (rarement) un nombre arbitraire d’autres événements pourrait apparaître entre les événements IN_MOVED_FROM et IN_MOVED_TO. De plus, il n’est pas garanti que la paire d’événements soit insérée de façon atomique dans la file : il pourrait y avoir un bref intervalle au cours duquel IN_MOVED_FROM est apparu, mais pas IN_MOVED_TO.

L’assemblage de la paire d’événements IN_MOVED_FROM et IN_MOVED_TO générés par rename(2) pose donc intrinsèquement un risque de situation de compétition (n’oubliez pas que si un objet est renommé en dehors d’un répertoire surveillé, un événement IN_MOVED_TO pourrait ne même pas être envoyé). Des approches heuristiques (par exemple supposer que les événements sont toujours consécutifs) permettent d’assurer un assemblage dans la plupart des cas, mais manqueront forcément certains cas, forçant l’application à percevoir les événements IN_MOVED_FROM et IN_MOVED_TO comme indépendants. Si les descripteurs de surveillance sont détruits et recréés par conséquent, alors ces descripteurs de surveillance seront incohérents avec les descripteurs de surveillance dans tous les événements en attente (la recréation du descripteur de fichier inotify et la reconstruction du cache pourrait être utile dans ce cas).

Les applications devraient aussi considérer la possibilité que l’événement IN_MOVED_FROM soit le dernier événement ayant pu entrer dans le tampon renvoyé pour l’appel actuel de read(2) et l’événement IN_MOVED_TO accompagnant pourrait n’être récupéré que lors de l’appel read(2) suivant, ce qui devrait être fait avec un (léger) délai pour permettre que l’insertion de la paire d’événements IN_MOVED_FROM-IN_MOVED_TO ne soit pas atomique et aussi qu’il n’y ait pas d’événement IN_MOVED_TO.

BOGUES

Avant Linux 3.19, fallocate(2) ne créait pas d’événements inotify. Depuis Linux 3.19, les appels à fallocate(2) créent des événements IN_MODIFY.

Dans les noyaux antérieurs à 2.6.16, l’attribut IN_ONESHOT de mask ne fonctionne pas.

Tel que conçu et implémenté à l’origine, l’attribut IN_ONESHOT ne forçait pas à générer un appel IN_IGNORED lorsque la surveillance était supprimée après un événement. Cependant, en conséquence involontaire d’autres modifications, depuis Linux 2.6.36, un événement IN_IGNORED est généré dans ce cas.

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.

Quand un descripteur de surveillance est supprimé en appelant inotify_rm_watch(2) (ou parce qu’un fichier de surveillance est supprimé ou que le système de fichiers qui le contient est démonté), tous les événements non lus en attente pour ce descripteur de fichier restent disponibles en lecture. Comme les descripteurs de surveillance sont ensuite alloués avec inotify_add_watch(2), le noyau boucle sur l’intervalle des descripteurs de surveillance possibles (O à INT_MAX) de façon incrémentielle. Lors de l’allocation d’un descripteur de surveillance libre, aucune vérification n’est effectuée pour voir si ce numéro de descripteur de surveillance a des événements non lus en attente dans la file inotify. Ainsi, un descripteur de surveillance pourrait être réalloué même quand des événements non lus en attente existent pour une incarnation précédente de ce numéro de descripteur de surveillance, avec comme résultat que l’application pourrait alors lire ces événements et les interpréter comme appartenant au fichier associé au descripteur de surveillance nouvellement recyclé. En pratique, la probabilité d’être victime de ce bogue devrait être extrêmement basse, puisqu’il nécessite qu’une application boucle sur INT_MAX descripteurs de surveillance, relâche un descripteur de surveillance tout en laissant des événements non lus pour ce descripteur de fichier dans la file et ensuite recycle ce descripteur de surveillance. Pour cette raison, et parce qu’il n’y a eu aucun rapports de bogue à propos de réelles applications, dans Linux 3.15, aucune modification de noyau n’a encore été faite pour éliminer ce bogue éventuel.

EXEMPLES

Le programme suivant montre l’utilisation de l’interface de programmation inotify. Il marque les répertoires passés en arguments de ligne de commande et attend les événements de type IN_OPEN, IN_CLOSE_NOWRITE et IN_CLOSE_WRITE.

La sortie suivante a été enregistrée lors de la modification du fichier /home/utilisateur/temp/toto et de l’affichage du contenu du répertoire /tmp. Avant d’ouvrir le fichier et le répertoire, un événement IN_OPEN est survenu. Après la fermeture du fichier, un événement IN_CLOSE_WRITE est survenu. Après la fermeture du répertoire, un événement IN_CLOSE_NOWRITE est survenu. L’exécution du programme s’est terminée quand l’utilisateur a appuyé sur la touche Entrée.

Exemple de sortie

$ ./a.out /tmp /home/utilisateur/temp

Appuyer sur la touche Entrée pour quitter.
En écoute d’événements.
IN_OPEN : /home/utilisateur/temp/toto [fichier]
IN_CLOSE_WRITE : /home/utilisateur/temp/toto [fichier]
IN_OPEN : /tmp/ [répertoire]
IN_CLOSE_NOWRITE : /tmp/ [répertoire]


Arrêt de l’écoute d’événements.

Source du programme

#include <errno.h>
#include <poll.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/inotify.h>
#include <unistd.h>
#include <string.h>

/* Lire tous les événements inotify disponibles à partir du
     descripteur de fichier « fd ».
   wd est le tableau des descripteurs de surveillance pour
     les répertoires en argv.
   argc est la taille de wd et argv.
   argv est la liste des répertoires surveillés.
   L’entrée 0 de wd et argv n’est pas utilisée. */

static void
handle_events(int fd, int *wd, int argc, char* argv[])
{
    /* Certains systèmes ne peuvent pas lire de variables entières
       si elles ne sont pas alignées correctement. Sur d’autres
       systèmes, un alignement incorrect pourrait diminuer les
       performances. Par conséquent, le tampon utilisé pour lire
       le descripteur de fichier inotify devrait avoir le même
       alignement que struct inotify_event. */

    char buf[4096]
        __attribute__ ((aligned(__alignof__(struct inotify_event))));
    const struct inotify_event *event;
    int i;
    ssize_t len;
    char *ptr;

    /* Boucler tant que les événements peuvent être lus à partir du
       descripteur de fichier inotify */

    for (;;) {

        /* Lire certains événements. */

        len = read(fd, buf, sizeof buf);
        if (len == -1 && errno != EAGAIN) {
            perror("read");
            exit(EXIT_FAILURE);
        }

        /* If the nonblocking read() found no events to read, then
           it returns -1 with errno set to EAGAIN. In that case,
           we exit the loop. */

        if (len <= 0)
            break;

        /* Boucler sur tous les événements du tampon */

        for (ptr = buf; ptr < buf + len;
                ptr += sizeof(struct inotify_event) + event->len) {

            event = (const struct inotify_event *) ptr;

            /* Afficher le type d’événement */

            if (event->mask & IN_OPEN)
                printf("IN_OPEN : ");
            if (event->mask & IN_CLOSE_NOWRITE)
                printf("IN_CLOSE_NOWRITE : ");
            if (event->mask & IN_CLOSE_WRITE)
                printf("IN_CLOSE_WRITE : ");

            /* Afficher le nom du répertoire surveillé */

            for (i = 1; i < argc; ++i) {
                if (wd[i] == event->wd) {
                    printf("%s/", argv[i]);
                    break;
                }
            }

            /* Afficher le nom du fichier */

            if (event->len)
                printf("%s", event->name);

            /* Afficher le type d’objet de système de fichiers */

            if (event->mask & IN_ISDIR)
                printf(" [répertoire]\n");
            else
                printf(" [fichier]\n");
        }
    }
}

int
main(int argc, char* argv[])
{
    char buf;
    int fd, i, poll_num;
    int *wd;
    nfds_t nfds;
    struct pollfd fds[2];

    if (argc < 2) {
        printf("Utilisation : %s CHEMIN [CHEMIN ...]\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    printf("Appuyer sur la touche Entrée pour quitter.\n");

    /* Créer le descripteur de fichier pour accéder à l’interface de
       programmation inotify */

    fd = inotify_init1(IN_NONBLOCK);
    if (fd == -1) {
        perror("inotify_init1");
        exit(EXIT_FAILURE);
    }

    /* Allouer la mémoire pour les descripteurs de surveillance */

    wd = calloc(argc, sizeof(int));
    if (wd == NULL) {
        perror("calloc");
        exit(EXIT_FAILURE);
    }

    /* Marquer les répertoires pour les événements :
       - un fichier a été ouvert ;
       - un fichier a été fermé

    for (i = 1; i < argc; i++) {
        wd[i] = inotify_add_watch(fd, argv[i],
                                  IN_OPEN | IN_CLOSE);
        if (wd[i] == -1) {
            fprintf(stderr, "Cannot watch ’%s’: %s\n",
                    argv[i], strerror(errno));
            exit(EXIT_FAILURE);
        }
    }

    /* Préparer pour la scrutation (polling) */

    nfds = 2;

    /* Entrée de console */

    fds[0].fd = STDIN_FILENO;
    fds[0].events = POLLIN;

    /* Entrée d’Inotify */

    fds[1].fd = fd;
    fds[1].events = POLLIN;

    /* Attendre les événements ou une entrée du terminal */

    printf("En écoute d’événements.\n");
    while (1) {
        poll_num = poll(fds, nfds, -1);
        if (poll_num == -1) {
            if (errno == EINTR)
                continue;
            perror("poll");
            exit(EXIT_FAILURE);
        }

        if (poll_num > 0) {

            if (fds[0].revents & POLLIN) {

                /* Entrée de console disponible.
                   Vider l’entrée standard et quitter */

                while (read(STDIN_FILENO, &buf, 1) > 0 && buf != ’\n’)
                    continue;
                break;
            }

            if (fds[1].revents & POLLIN) {

                /* Des événements inotify sont disponibles */

                handle_events(fd, wd, argc, argv);
            }
        }
    }

    printf("Arrêt de l’écoute d’événements.\n");

    /* Fermer le descripteur de fichier inotify */

    close(fd);

    free(wd);
    exit(EXIT_SUCCESS);
}

VOIR AUSSI

inotifywait(1), inotifywatch(1), inotify_add_watch(2), inotify_init(2), inotify_init1(2), inotify_rm_watch(2), read(2), stat(2), fanotify(7)

Documentation/filesystems/inotify.txt dans les sources du noyau Linux

COLOPHON

Cette page fait partie de la publication 5.07 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page, peuvent être trouvées à l’adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION

La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>;, Stéphan Rafin <stephan.rafin [AT] laposte.net>, Thierry Vignaud <tvignaud [AT] mandriva.com>, François Micaux, Alain Portal <aportal [AT] univ-montp2.fr>, Jean-Philippe Guérard <fevrier [AT] tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon [AT] wanadoo.fr>, Julien Cristau <jcristau [AT] debian.org>, Thomas Huriaux <thomas.huriaux [AT] gmail.com>, Nicolas François <nicolas.francois [AT] centraliens.net>, Florentin Duneau <fduneau [AT] gmail.com>, Simon Paillard <simon.paillard [AT] resel.fr>, Denis Barbier <barbier [AT] debian.org> et David Prévot <david [AT] tilapin.org>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n’y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à <debian-l10n-french [AT] lists.org>.