Scroll to navigation

FANOTIFY_INIT(2) Руководство программиста Linux FANOTIFY_INIT(2)

ИМЯ

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_CLASS_NOTIF. Порядок уведомления слушателей в этом классе уведомления не определён.

Дополнительно в flags могут быть установлены следующие биты:

Устанавливать флаг close-on-exec (FD_CLOEXEC) для нового файлового дескриптора. Смотрите описание флага O_CLOEXEC в open(2).
Включить неблокирующий флаг (O_NONBLOCK) для файлового дескриптора. Чтение из такого файлового дескриптора не вызовет блокирования. Если данные отсутствуют, то read(2) завершается ошибкой EAGAIN.
Снять ограничение в 16384 события в очереди событий. Для использования этого флага требуется мандат CAP_SYS_ADMIN.
Снять ограничение в 8192 метки. Для использования этого флага требуется мандат CAP_SYS_ADMIN.
Хранить ID нити (TID) вместо ID процесса (PID) в поле pid структуры struct fanotify_event_metadata, передаваемой в read(2) (смотрите fanotify(7)).
This value allows the receipt of events which contain additional information about the underlying filesystem object correlated to an event. An additional record of type FAN_EVENT_INFO_TYPE_FID encapsulates the information about the object and is included alongside the generic event metadata structure. The file descriptor that is used to represent the object correlated to an event is instead substituted with a file handle. It is intended for applications that may find the use of a file handle to identify an object more suitable than a file descriptor. Additionally, it may be used for applications monitoring a directory or a filesystem that are interested in the directory entry modification events FAN_CREATE, FAN_DELETE, and FAN_MOVE, or in events such as FAN_ATTRIB, FAN_DELETE_SELF, and FAN_MOVE_SELF. All the events above require an fanotify group that identifies filesystem objects by file handles. Note that for the directory entry modification events the reported file handle identifies the modified directory and not the created/deleted/moved child object. The use of FAN_CLASS_CONTENT or FAN_CLASS_PRE_CONTENT is not permitted with this flag and will result in the error EINVAL. See fanotify(7) for additional details.
Events for fanotify groups initialized with this flag will contain (see exceptions below) additional information about a directory object correlated to an event. An additional record of type FAN_EVENT_INFO_TYPE_DFID encapsulates the information about the directory object and is included alongside the generic event metadata structure. For events that occur on a non-directory object, the additional structure includes a file handle that identifies the parent directory filesystem object. Note that there is no guarantee that the directory filesystem object will be found at the location described by the file handle information at the time the event is received. When combined with the flag FAN_REPORT_FID, two records may be reported with events that occur on a non-directory object, one to identify the non-directory object itself and one to identify the parent directory object. Note that in some cases, a filesystem object does not have a parent, for example, when an event occurs on an unlinked but open file. In that case, with the FAN_REPORT_FID flag, the event will be reported with only one record to identify the non-directory object itself, because there is no directory associated with the event. Without the FAN_REPORT_FID flag, no event will be reported. See fanotify(7) for additional details.
Events for fanotify groups initialized with this flag will contain additional information about the name of the directory entry correlated to an event. This flag must be provided in conjunction with the flag FAN_REPORT_DIR_FID. Providing this flag value without FAN_REPORT_DIR_FID will result in the error EINVAL. This flag may be combined with the flag FAN_REPORT_FID. An additional record of type FAN_EVENT_INFO_TYPE_DFID_NAME, which encapsulates the information about the directory entry, is included alongside the generic event metadata structure and substitutes the additional information record of type FAN_EVENT_INFO_TYPE_DFID. The additional record includes a file handle that identifies a directory filesystem object followed by a name that identifies an entry in that directory. For the directory entry modification events FAN_CREATE, FAN_DELETE, and FAN_MOVE, the reported name is that of the created/deleted/moved directory entry. For other events that occur on a directory object, the reported file handle is that of the directory object itself and the reported name is '.'. For other events that occur on a non-directory object, the reported file handle is that of the parent directory object and the reported name is the name of a directory entry where the object was located at the time of the event. The rationale behind this logic is that the reported directory file handle can be passed to open_by_handle_at(2) to get an open directory file descriptor and that file descriptor along with the reported name can be used to call fstatat(2). The same rule that applies to record type FAN_EVENT_INFO_TYPE_DFID also applies to record type FAN_EVENT_INFO_TYPE_DFID_NAME: if a non-directory object has no parent, either the event will not be reported or it will be reported without the directory entry information. Note that there is no guarantee that the filesystem object will be found at the location described by the directory entry information at the time the event is received. See fanotify(7) for additional details.
This is a synonym for (FAN_REPORT_DIR_FID|FAN_REPORT_NAME).

В аргументе event_f_flags задаются флаги состояния файла, которые будут установлены на открытые файловые описатели, создаваемые для событий fanotify. Подробней об этих флагах смотрите описание значений flags в open(2). Аргумент event_f_flags включает многобитовое поле для режима доступа. Это поел может иметь следующие значения:

Это значение разрешает доступ только на чтение.
Это значение разрешает доступ только на запись.
Это значение разрешает доступ на чтение и запись.

В event_f_flags могут быть установлены дополнительные биты. Наиболее полезные значения:

Включить поддержку файлов более 2 ГБ. Если не удастся установить этот флаг, то при попытке открыть большой файл, отслеживаемый группой fanotify на 32-битной системе, возвращается ошибка EOVERFLOW.
Включить флаг 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 устанавливается в соответствующее значение.

ОШИБКИ

В flags или event_f_flags указано некорректное значение. Значение FAN_ALL_INIT_FLAGS (устарело, начиная с версии ядра Linux 4.20) определяет все допустимые биты в flags.
Количество групп fanotify для этого пользователя превышает 128.
Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.
Не удалось выделить память для группы уведомления.
В этом ядре не реализован fanotify_init(). Программный интерфейс fanotify доступен только, если ядро было собрано с параметром CONFIG_FANOTIFY.
Операция запрещена, так как вызывающий не имеет мандата 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.

СМ. ТАКЖЕ

fanotify_mark(2), fanotify(7)

ЗАМЕЧАНИЯ

Эта страница является частью проекта Linux man-pages версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу https://www.kernel.org/doc/man-pages/.

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.

1 ноября 2020 г. Linux