NOM¶

SYNOPSIS¶

int fanotify_init(unsigned int flags, unsigned int event_f_flags);

DESCRIPTION¶

fanotify_init() initialise un nouveau groupe fanotify et renvoie un descripteur de fichier pour la file d’événements associée au groupe.

Le descripteur de fichier est utilisé dans les appels de fanotify_mark(2) pour indiquer les fichiers, les répertoires, les points de montage et les systèmes de fichiers pour lesquels les événements fanotify seront créés. Ces événements sont reçus en lisant le descripteur de fichier. Certains événements ne sont qu’informatifs, indiquant qu’il y a eu un accès au fichier. D’autres événements peuvent être utilisés pour déterminer si une autre application a le droit d’accéder à un fichier ou répertoire. Le droit d’accéder aux objets de système de fichiers est accordé en écrivant dans le descripteur de fichier.

Plusieurs programmes peuvent utiliser l’interface fanotify en même temps pour surveiller les mêmes fichiers.

Dans l’implémentation actuelle, le nombre de groupes fanotify par utilisateur est limité à 128. Cette limite ne peut pas être écrasée.

Appeler fanotify_init() nécessite la capacité CAP_SYS_ADMIN. Cette contrainte pourrait être levée dans les prochaines versions de l’interface de programmation. Par conséquent, certaines vérifications supplémentaires de capacité ont été mises en place comme indiqué ci-dessous.

L’argument flags contient un champ multibit définissant la classe de notification de l’application écoutant et d’autres champs monobits indiquant le comportement du descripteur de fichier.

Si plusieurs écoutants d’événements de permission existent, la classe de notification est utilisée pour établir l’ordre dans lequel les écoutants reçoivent les événements.

Une seule des classes de notification suivantes peut être indiquée dans flags.

FAN_CLASS_PRE_CONTENT

Cette valeur permet de recevoir des événements notifiant qu’un fichier a été accédé et les événements de décisions de permission si un fichier peut être accédé. Elle est conçue pour les écoutants d’événement qui doivent accéder aux fichiers avant qu’ils ne contiennent leurs données finales. Cette classe de notification pourrait être utilisée par exemple par des gestionnaires de stockage hiérarchisé.

FAN_CLASS_CONTENT

Cette valeur permet de recevoir des événements notifiant qu’un fichier a été accédé et les événements de décisions de permission si un fichier peut être accédé. Elle est conçue pour les écoutants d’événement qui doivent accéder aux fichiers quand ils contiennent déjà leur contenu final. Cette classe de notification pourrait être utilisée par exemple par des programmes de détection de logiciels malveillants.

FAN_REPORT_FID (depuis Linux 5.1)

Cette valeur permet la réception d'événements qui contiennent des valeurs complémentaires sur l'objet du système de fichiers sous-jacent corrélé à un événement. Une structure supplémentaire enferme les informations sur l'objet et sont incluses dans toute la structure générique des métadonnées de l'événement. Le descripteur de fichier utilisé pour représenter l'objet lié à un événement est remplacé par un identificateur de fichier. Il est conçu pour les applications qui trouvent que l'utilisation d’un identificateur de fichier pour identifier un objet convient mieux qu'un descripteur de fichier. De plus, il peut être utilisé par des applications qui s'intéressent aux événements d'entrée dans le répertoire, telles que FAN_CREATE, FAN_ATTRIB, FAN_MOVE et FAN_DELETE par exemple. Remarquez que l'utilisation des événements de modification d'un répertoire n'est pas prise en charge lorsqu'on surveille un point de montage. L'utilisation de FAN_CLASS_CONTENT ou de FAN_CLASS_PRE_CONTENT n'est pas autorisée avec cet attribut et donnera une erreur EINVAL. Voir fanotify(7) pour des informations supplémentaires.

FAN_CLASS_NOTIF

C’est la valeur par défaut. Elle n’a pas besoin d’être indiquée. Cette valeur ne permet de recevoir que des événements notifiant qu’un fichier a été accédé. Les décisions de permission avant que le fichier ne soit accédé ne sont pas possibles.

Les écoutants avec différentes classes de notification recevront les événements dans l’ordre FAN_CLASS_PRE_CONTENT, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF. L’ordre de notification pour les écoutants dans la même classe de notification n’est pas défini.

Les bits suivants peuvent de plus être définis dans flags.

FAN_CLOEXEC

Placer l'attribut « close-on-exec » (FD_CLOEXEC) sur le nouveau descripteur de fichier. Consultez la description de l'attribut O_CLOEXEC dans open(2).

FAN_NONBLOCK

Activer l’attribut non bloquant (O_NONBLOCK) pour le descripteur de fichier. La lecture du descripteur de fichier ne bloquera pas. À la place, si aucune donnée n’est disponible, read(2) échouera avec l’erreur EAGAIN.

FAN_UNLIMITED_QUEUE

Supprimer la limite de 16384 événements pour la file d’événements. L’utilisation de cet attribut nécessite la capacité CAP_SYS_ADMIN.

FAN_UNLIMITED_MARKS

Supprimer la limite de 8192 marques. L’utilisation de cet attribut nécessite la capacité CAP_SYS_ADMIN.

FAN_REPORT_TID (depuis Linux 4.20)

Signaler l'ID d'un thread (TID) au lieu de l'ID du processus (PID) dans le champ pid de la struct fanotify_event_metadata fournie à read(2) (voir fanotify(7)).

L’argument event_f_flags définit les attributs d’état de fichier qui seront définis sur les descriptions de fichiers ouverts qui sont créées pour les événements fanotify. Pour plus de précisions sur ces attributs, consultez la description des valeurs de flags dans open. event_f_flags contient un champ multibit pour le mode d’accès. Ce champ peut prendre une des valeurs suivantes :

O_RDONLY

Cette valeur permet l’accès en lecture seule.

O_WRONLY

Cette valeur permet l’accès en écriture seule.

O_RDWR

Cette valeur permet l’accès en lecture et écriture.

Des bits supplémentaires peuvent être définis dans event_f_flags. Les valeurs les plus utiles sont les suivantes :

O_LARGEFILE

Activer la prise en charge de fichiers dépassant 2 Go. Sans cet attribut, une erreur EOVERFLOW surviendra lors d’une tentative d’ouverture d’un gros fichier surveillé par un groupe fanotify sur un système 32 bits.

O_CLOEXEC (depuis Linux 3.18)

Activer l'attribut « close-on-exec » pour le descripteur de fichier. Consultez la description de l'attribut O_CLOEXEC dans open(2) pour savoir pourquoi cela peut être utile.

Les valeurs suivantes sont aussi permises : O_APPEND, O_DSYNC, O_NOATIME, O_NONBLOCK et O_SYNC. Indiquer n’importe quel autre attribut dans event_f_flags provoque l’erreur EINVAL (mais consultez BOGUES).

VALEUR RENVOYÉE¶

ERREURS¶

EINVAL

Une valeur incorrecte a été passée dans flags ou event_f_flags. FAN_ALL_INIT_FLAGS (obsolète depuis la version 4.20 du noyau Linux) définit tous les bits permis pour flags.

EMFILE

Le nombre de groupes fanotify pour cet utilisateur dépasse 128.

EMFILE

La limite du nombre de descripteurs de fichiers par processus a été atteinte.

ENOMEM

Échec d’allocation mémoire pour le groupe de notification.

ENOSYS

Ce noyau n’implémente pas fanotify_init(). L’interface de programmation fanotify n'est disponible que si le noyau a été configuré avec CONFIG_FANOTIFY.

EPERM

L’opération n’est pas permise car l’appelant n’a pas la capacité CAP_SYS_ADMIN.

VERSIONS¶

CONFORMITɶ

BOGUES¶

*

O_CLOEXEC est ignoré lorsqu'il est passé dans event_f_flags.

Le bogue suivant était présent dans les noyaux Linux avant la version 3.14 :

*

l’argument event_f_flags n’est pas vérifié pour les attributs incorrects. Les attributs qui ne sont conçus que pour une utilisation interne, comme FMODE_EXEC, peuvent être définis et seront donc définis pour les descripteurs de fichier renvoyés lors de la lecture depuis le descripteur de fichier fanotify.

VOIR AUSSI¶

COLOPHON¶

TRADUCTION¶

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@lists.debian.org.