Linux repositories inspector

fanotify_init(2) - Russkiy

Linux
2019-08-02

man-pages-ru

Russian man pages from the Linux Documentation Project

manpages-dev

Manual pages about using GNU/Linux for development

man-pages

Linux kernel and C library user-space interface documentation

ИМЯ

fanotify_init - создаёт и инициализирует группу fanotify

ОБЗОР

#include <fcntl.h>
#include <sys/fanotify.h>
int fanotify_init(unsigned int flags, unsigned int event_f_flags);

ОПИСАНИЕ

Обзор программного интерфейса fanotify смотрите в fanotify(7).
Вызов fanotify_init() инициализирует новую группу fanotify и возвращает файловый дескриптор очереди событий, связанной с группой.
В файловом дескрипторе, используемом в fanotify_mark(2), задаются файлы, каталоги, точки монтирования и файловые системы, для которых должны создаваться события fanotify. Эти события можно получить с помощью чтения файлового дескриптора. Одни события носят уведомительный характер, показывая что к файлу был получен доступ. Другие события можно использовать для разрешения приложению доступа к файлу или каталогу. Доступ к объектам файловой системы разрешается посредством записи в файловый дескриптор.
Несколько программ могут использовать интерфейс fanotify к одним и тем же файлам одновременно.
В текущей реализации количество групп fanotify ограничено 128 на пользователя. Это значение нельзя изменить.
Для вызова fanotify_init() требуется мандат CAP_SYS_ADMIN. Это требование может быть облегчено в будущих версиях программного интерфейса. Поэтому ниже показаны определённые дополнительные проверки возможностей, которые были реализованы.
Аргумент flags содержит многобитовое поле, определяющее класс уведомления, запрашиваемый приложением, а также однобитовые поля, задающие поведение файлового дескриптора.
Если на события доступа зарегистрировалось несколько слушателей, то класс уведомления используется для установления порядка слушателей при получении событий.
В flags может быть указан только один из следующих классов уведомления:
FAN_CLASS_PRE_CONTENT
Это значение позволяет принимать уведомляющие события об обращении к файлу, и события доступа, запрашивающие доступ к файлу. Он предназначен для слушателей событий, которым требуется доступ к файлам до того, как в них будут содержаться окончательные данные. Этот класс уведомления может быть использован, например, в программах управления иерархического хранения.
FAN_CLASS_CONTENT
Это значение позволяет принимать уведомляющие события об обращении к файлу, и события доступа, запрашивающие доступ к файлу. Он предназначен для слушателей событий, которым требуется доступ к файлам после того, как они содержат окончательные данные. Этот класс уведомления может быть использован, например, в программах обнаружения вредоносного кода.
FAN_REPORT_FID (начиная с Linux 5.1)
Это значение позволяет получать события, которые содержат дополнительную информацию о нижележащем объекте файловой системы, относящемся к событию. Дополнительная структура содержит информацию об объекте, которая добавляется к структуре общих метаданных событий. Файловый дескриптор, используемый для представления объекта, заменяется в событии файловым описателем. Он предназначен для приложений, которым для работы с файлами удобней использовать файловый описатель, а не файловый дескриптор. Также, его можно использовать в приложениях, которым интересны события об элементах каталога, например таких как FAN_CREATE, FAN_ATTRIB, FAN_MOVE и FAN_DELETE. Заметим, что использование событий изменения каталога не поддерживается при слежении за точкой монтирования. Использование FAN_CLASS_CONTENT или FAN_CLASS_PRE_CONTENT с этим флагом не допускается и приводит к ошибке EINVAL. Дополнительную информацию смотрите в fanotify(7).
FAN_CLASS_NOTIF
Значение по умолчанию. Его не нужно указывать. Это значение позволяет принимать только события о доступе к файлу. Право на доступ к файлу задать невозможно.
Слушатели с различными классами уведомлений будут принимать события в таком порядке: FAN_CLASS_PRE_CONTENT, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF. Порядок уведомления слушателей в этом классе уведомления не определён.
Дополнительно в flags могут быть установлены следующие биты:
FAN_CLOEXEC
Устанавливать флаг close-on-exec (FD_CLOEXEC) для нового файлового дескриптора. Смотрите описание флага O_CLOEXEC в open(2).
FAN_NONBLOCK
Включить неблокирующий флаг (O_NONBLOCK) для файлового дескриптора. Чтение из такого файлового дескриптора не вызовет блокирования. Если данные отсутствуют, то read(2) завершается ошибкой EAGAIN.
FAN_UNLIMITED_QUEUE
Снять ограничение в 16384 события в очереди событий. Для использования этого флага требуется мандат CAP_SYS_ADMIN.
FAN_UNLIMITED_MARKS
Снять ограничение в 8192 метки. Для использования этого флага требуется мандат CAP_SYS_ADMIN.
FAN_REPORT_TID (начиная с Linux 4.20)
Хранить ID нити (TID) вместо ID процесса (PID) в поле pid структуры struct fanotify_event_metadata, передаваемой в read(2) (смотрите fanotify(7)).
В аргументе event_f_flags задаются флаги состояния файла, которые будут установлены на открытые файловые описатели, создаваемые для событий fanotify. Подробней об этих флагах смотрите описание значений flags в open(2). Аргумент event_f_flags включает многобитовое поле для режима доступа. Это поел может иметь следующие значения:
O_RDONLY
Это значение разрешает доступ только на чтение.
O_WRONLY
Это значение разрешает доступ только на запись.
O_RDWR Это значение разрешает доступ на чтение и запись.
В event_f_flags могут быть установлены дополнительные биты. Наиболее полезные значения:
O_LARGEFILE
Включить поддержку файлов более 2 ГБ. Если не удастся установить этот флаг, то при попытке открыть большой файл, отслеживаемый группой fanotify на 32-битной системе, возвращается ошибка EOVERFLOW.
O_CLOEXEC (начиная с Linux 3.18)
Включить флаг close-on-exec для нового открытого файлового дескриптора. Смотрите описание флага O_CLOEXEC в open(2) для того, чтобы узнать как это может пригодиться.
Также доступны следующие флаги: O_APPEND, O_DSYNC, O_NOATIME, O_NONBLOCK и O_SYNC. Указание любых других флагов в event_f_flagsприводит к ошибке EINVAL (но смотрите ДЕФЕКТЫ).

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При успешном выполнении fanotify_init() возвращает новый файловый дескриптор. При ошибке возвращается -1, и errno устанавливается в соответствующее значение.

ОШИБКИ

EINVAL В flags или event_f_flags указано некорректное значение. Значение FAN_ALL_INIT_FLAGS (устарело, начиная с версии ядра Linux 4.20) определяет все допустимые биты в flags.
EMFILE Количество групп fanotify для этого пользователя превышает 128.
EMFILE Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.
ENOMEM Не удалось выделить память для группы уведомления.
ENOSYS В этом ядре не реализован fanotify_init(). Программный интерфейс fanotify доступен только, если ядро было собрано с параметром CONFIG_FANOTIFY.
EPERM Операция запрещена, так как вызывающий не имеет мандата CAP_SYS_ADMIN.

ВЕРСИИ

Вызов fanotify_init() появился в версии 2.6.36 ядра Linux и был включён в версии 2.6.37.

СООТВЕТСТВИЕ СТАНДАРТАМ

Данный системный вызов есть только в Linux.

ДЕФЕКТЫ

В ядрах Linux до версии 3.18 существовали следующие дефекты:
* При передаче в event_f_flags флаг O_CLOEXEC игнорируется.
В ядрах Linux до версии 3.14 существовали следующие дефекты:
* Значение аргумента event_f_flags не проверяется на корректность флагов. Могут быть установлены флаги, предназначенные только для внутреннего использования, такие как FMODE_EXEC, и в результате будут установлены для файловых дескрипторов при чтении из файлового дескриптора fanotify.

СМОТРИТЕ ТАКЖЕ

⇧ Top