Чтение событий из файлового дескриптора inotify¶

Чтобы определить, что события произошли, приложение должно прочитать (read(2)) файловый дескриптор inotify. Если событий не было, то предполагая, что это блокирующий файловый дескриптор, вызов read(2) заблокирует работу до возникновения, по крайней мере, одного события (если не будет прерван сигналом; в этом случае вызов завершается с ошибкой EINTR, смотрите signal(7)).

При успешном выполнении read(2) возвращает буфер с одной или более структурами следующего вида:

struct inotify_event {


    int      wd;       /* дескриптор наблюдаемого */


    uint32_t mask;     /* маска, описывающая событие */


    uint32_t cookie;   /* уникальный cookie, связывающий относящиеся


                          друг к другу события (для rename(2)) */


    uint32_t len;      /* размер поля name */


    char     name[];   /* необязательное имя, завершающееся null */
};

В wd указывается сторожок, к которому относится событие. Это один из дескрипторов сторожка, полученный из вызова inotify_add_watch(2).

В mask содержатся биты, описывающие возникшее событие (смотрите ниже).

Значение cookie — это уникальное целое, которое объединяет связанные события. В настоящее время используется только для событий переименования и позволяет приложению объединить возвращаемые IN_MOVED_FROM и IN_MOVED_TO в пару событий. Для остальных типов событий значение cookie равно 0.

The name field is present only when an event is returned for a file inside a watched directory; it identifies the filename within the watched directory. This filename is null-terminated, and may include further null bytes ('\0') to align subsequent reads to a suitable address boundary.

Поле len содержит количество всех байт в name, включая байты null; длина каждой структуры inotify_event равна sizeof(struct inotify_event)+len.

The behavior when the buffer given to read(2) is too small to return information about the next event depends on the kernel version: before Linux 2.6.21, read(2) returns 0; since Linux 2.6.21, read(2) fails with the error EINVAL. Specifying a buffer of size

sizeof(struct inotify_event) + NAME_MAX + 1

будет достаточно для чтения, по крайней мере, одного события.

События inotify¶

В аргументе inotify_add_watch(2) mask и поле mask структуры inotify_event, возвращаемых при чтении файлового дескриптора inotify, содержатся битовые маски, определяющие события inotify. Следующие биты могут быть заданы в mask при вызове inotify_add_watch(2) и возвращены в поле mask, возвращаемом read(2):

Наблюдение inotify ведётся за inode: при наблюдении за файлом (но не когда наблюдение ведётся за каталогом, содержащим файл) событие может генерироваться при активности по любой ссылке на файл (находящейся в том же или в другом каталоге).

При наблюдении за каталогом:

•

события, помеченные звёздочкой (*), могут возникать как для самого каталога, так и для файлов в каталоге; и

•

события, помеченные знаком плюс (+), могут возникать только для объектов внутри каталога (но не самого каталога).

Замечание: при слежении за каталогом события не генерируются для файлов каталога, если событие возникает по пути (т. е., по ссылке), который находится вне отслеживаемого каталога.

Когда события генерируются для объектов внутри отслеживаемого каталога, поле name, возвращаемое в структуре inotify_event, хранит имя файла внутри этого каталога.

Макрос IN_ALL_EVENTS определён как битовая маска всех перечисленных выше событий. Данный макрос можно использовать в качестве аргумента mask в вызове inotify_add_watch(2).

Дополнительно, два удобных макроса:

Также, при вызове inotify_add_watch(2) в mask могут быть указаны следующие биты:

Следующие биты могут быть установлены в поле mask при возврате из read(2):

Примеры¶

Предположим, приложение следит за всеми событиями для каталога dir и файла dir/myfile. В примере ниже показаны некоторые события, которые будут сгенерированы для этих двух объектов.

Предположим, приложение следит за всеми событиями для каталогов dir1 и dir2 и файла dir1/myfile. В примере ниже показаны некоторые события, которые могут быть сгенерированы.

Предположим, что dir1/xx и dir2/yy только ссылки на один файл и приложение следит за dir1, dir2, dir1/xx и dir2/yy. При выполнение следующих вызовов в порядке, указанном ниже, будут сгенерированы следующие события:

Предположим, приложение следит за каталогом dir и пустым каталогом dir/subdir. В примере ниже показаны некоторые события, которые могут быть сгенерированы.

Интерфейс /proc¶

Для ограничения потребления inotify памяти ядра, можно использовать следующие интерфейсы:

/proc/sys/fs/inotify/max_queued_events

Значение в этом файле используется когда приложение вызывает inotify_init(2) для установки верхнего порога количества событий, которые могут поместиться в очередь соответствующего экземпляра inotify. События, превысившие это ограничение, отбрасываются, но событие IN_Q_OVERFLOW генерируется всегда.

/proc/sys/fs/inotify/max_user_instances

В этом файле задаётся ограничение на количество экземпляров inotify, которые могут быть созданы для одного реального идентификатора пользователя.

/proc/sys/fs/inotify/max_user_watches

В этом файле задаётся ограничение на количество сторожков, которые могут быть созданы для одного реального идентификатора пользователя.

Ограничения и подводные камни¶

Программный интерфейс inotify не предоставляет информацию о пользователе или процессе, из-за которого возникло событие. В частности, для процесса, отслеживающего события через inotify, нет простого способа определить, возникли события из-за его действий или из-за действий других процессов.

Inotify сообщает только о событиях, которые возникли из-за пользовательских программ, использовавших программный интерфейс файловой системы. То есть, не возникает событий для файловых систем, доступных по сети (приложения должны использовать старый метод опроса файловой системы для слежения за такими событиями). Кроме того, различные псевдо-файловый системы, такие как /proc, /sys и /dev/pts, не отслеживаются через inotify.

Программный интерфейс inotify не сообщает о доступе и изменениях, которые могут произойти из-за mmap(2), msync(2) и munmap(2).

Программный интерфейс inotify в качестве идентификаторов объектов использует имена файлов. Однако, в момент обработки приложением события inotify, имя файла может быть уже удалено или переименовано.

Программный интерфейс inotify различает события по их дескрипторам сторожков. Приложение само должно кэшировать сопоставление (если нужно) дескрипторов сторожков и имён. Имейте в виду, что переименование каталога может повлиять на несколько кэшированных путей.

Отслеживание каталогов через inotify ведётся не рекурсивно: чтобы отслеживать подкаталоги, нужно создать дополнительные сторожки. Это может занять много времени при большом дереве каталога.

Если отслеживается полное дерево каталога и создаётся новый каталог в этом дереве или существующий каталог переименовывается в этом дереве, учтите, что на момент создания сторожка за новым подкаталогом, в подкаталоге могут уже существовать новые файлы (и подкаталоги). Поэтому вам может потребоваться сканировать содержимое подкаталога сразу после добавления сторожка (и, если нужно, рекурсивно добавить сторожки для всех подкаталогов, которые в нём есть).

Заметим, что очередь событий может переполниться. В этом случае события теряются. Корректные приложения должны учитывать возможность пропажи событий. Например, может потребоваться перестроить часть или весь кэш приложения (один простой, но, возможно, затратный способ, это закрыть файловый дескриптор inotify, опустошить кэш, создать новый файловый дескриптор inotify и затем пересоздать сторожки и записи в кэше для отслеживаемых объектов).

Если файловая система смонтирована поверх отслеживаемого каталога, то событие не генерируются, а также не генерируются события для объектов, находящихся в новой точке монтирования на первом уровне. Если в дальнейшем файловая система отмонтируется, то события начнут генерироваться для каталога и содержащихся в нём объектов.

Работа с событиями rename()¶

Как указывалось выше, из событий IN_MOVED_FROM и IN_MOVED_TO, генерируемых rename(2), можно определить пару по их одинаковому значению cookie. Однако, с этой задачей есть несколько проблем.

Эти два события, обычно, стоят друг за другом в потоке событий, если читать из файлового дескриптора inotify. Однако, это не гарантируется. Если несколько процессов создают события для отслеживаемых объектов, то (в редких случаях) произвольное количество других событий может появиться между событиями IN_MOVED_FROM и IN_MOVED_TO. Кроме того, не гарантируется, что пара событий вставляется в очередь атомарно: может существовать короткий интервал, в котором IN_MOVED_FROM уже появилось, а IN_MOVED_TO ещё нет.

Соответствие IN_MOVED_FROM и IN_MOVED_TO паре событий, сгенерированных rename(2), по сути, просто (не забудьте, что если объект переименовывается вне отслеживаемого каталога, то может не быть даже события IN_MOVED_TO). Можно использовать эвристические предположения (например, что события всегда следуют друг за другом), что работает в большинстве случаев, но неминуемо не сработает в некоторых случаях, в которых приложение посчитает события IN_MOVED_FROM и IN_MOVED_TO несвязными. Если в результате дескрипторы сторожков будут уничтожены и пересозданы, то такие дескрипторы будут несогласованны с дескрипторами сторожков для любых ожидающих событий (пересоздание файлового дескриптора inotify и пересборка кэша может быть полезна в этом случае).

Applications should also allow for the possibility that the IN_MOVED_FROM event was the last event that could fit in the buffer returned by the current call to read(2), and the accompanying IN_MOVED_TO event might be fetched only on the next read(2), which should be done with a (small) timeout to allow for the fact that insertion of the IN_MOVED_FROM+IN_MOVED_TO event pair is not atomic, and also the possibility that there may not be any IN_MOVED_TO event.

Пример вывода¶

$ ./a.out /tmp /home/user/temp
Press enter key to terminate.
Listening for events.
IN_OPEN: /home/user/temp/foo [file]
IN_CLOSE_WRITE: /home/user/temp/foo [file]
IN_OPEN: /tmp/ [directory]
IN_CLOSE_NOWRITE: /tmp/ [directory]
Listening for events stopped.

Исходный код программы¶

#include <errno.h>
#include <poll.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/inotify.h>
#include <unistd.h>
#include <string.h>
/* Read all available inotify events from the file descriptor 'fd'.


   wd is the table of watch descriptors for the directories in argv.


   argc is the length of wd and argv.


   argv is the list of watched directories.


   Entry 0 of wd and argv is unused. */
static void
handle_events(int fd, int *wd, int argc, char* argv[])
{


    /* Some systems cannot read integer variables if they are not


       properly aligned. On other systems, incorrect alignment may


       decrease performance. Hence, the buffer used for reading from


       the inotify file descriptor should have the same alignment as


       struct inotify_event. */


    char buf[4096]


        __attribute__ ((aligned(__alignof__(struct inotify_event))));


    const struct inotify_event *event;


    ssize_t len;


    /* Loop while events can be read from inotify file descriptor. */


    for (;;) {


        /* Read some events. */


        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;


        /* Loop over all events in the buffer. */


        for (char *ptr = buf; ptr < buf + len;


                ptr += sizeof(struct inotify_event) + event->len) {


            event = (const struct inotify_event *) ptr;


            /* Print event type. */


            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: ");


            /* Print the name of the watched directory. */


            for (size_t i = 1; i < argc; ++i) {


                if (wd[i] == event->wd) {


                    printf("%s/", argv[i]);


                    break;


                }


            }


            /* Print the name of the file. */


            if (event->len)


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


            /* Print type of filesystem object. */


            if (event->mask & IN_ISDIR)


                printf(" [directory]\n");


            else


                printf(" [file]\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("Usage: %s PATH [PATH ...]\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    printf("Press ENTER key to terminate.\n");


    /* Create the file descriptor for accessing the inotify API. */


    fd = inotify_init1(IN_NONBLOCK);


    if (fd == -1) {


        perror("inotify_init1");


        exit(EXIT_FAILURE);


    }


    /* Allocate memory for watch descriptors. */


    wd = calloc(argc, sizeof(int));


    if (wd == NULL) {


        perror("calloc");


        exit(EXIT_FAILURE);


    }


    /* Mark directories for events


       - file was opened


       - file was closed */


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


        }


    }


    /* Prepare for polling. */


    nfds = 2;


    fds[0].fd = STDIN_FILENO;       /* Console input */


    fds[0].events = POLLIN;


    fds[1].fd = fd;                 /* Inotify input */


    fds[1].events = POLLIN;


    /* Wait for events and/or terminal input. */


    printf("Listening for events.\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) {


                /* Console input is available. Empty stdin and quit. */


                while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\n')


                    continue;


                break;


            }


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


                /* Inotify events are available. */


                handle_events(fd, wd, argc, argv);


            }


        }


    }


    printf("Listening for events stopped.\n");


    /* Close inotify file descriptor. */


    close(fd);


    free(wd);


    exit(EXIT_SUCCESS);
}