Provided by: manpages-fr-dev_4.13-4_all 
NOM
fanotify_init - Créer et initialiser un groupe fanotify
SYNOPSIS
#include <fcntl.h>
#include <sys/fanotify.h>
int fanotify_init(unsigned int flags, unsigned int event_f_flags);
DESCRIPTION
Pour un aperçu de l’interface de programmation fanotify, consultez fanotify(7).
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_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)).
FAN_REPORT_FID (depuis Linux 5.1)
Cette valeur permet la réception d'événements qui contiennent des informations complémentaires sur
l'objet du système de fichiers sous-jacent corrélé à un événement. Un enregistrement
supplémentaire de type FAN_EVENT_INFO_TYPE_FID enferme les informations sur l'objet et est inclus
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 supervisant un répertoire ou un système de fichiers qui s'intéressent
aux modifications d'entrée de répertoire, tels que FAN_CREATE, FAN_DELETE et FAN_MOVE, ou à des
événements tels que FAN_ATTRIB, FAN_DELETE_SELF et FAN_MOVE_SELF. Tous les événements ci-dessus
exigent un groupe fanotify identifiant les objets du système de fichiers par des identificateurs
de fichier. Remarquez que pour que les événements de modification de l'entrée d'un répertoire,
l’identificateur de fichier signalé identifie le répertoire modifié et non l'objet enfant
créé/supprimé/déplacé. 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_REPORT_DIR_FID (depuis Linux 5.9)
Les événements des groupes fanotify initialisés avec cet attribut contiendront (voir les
exceptions ci-dessous) des informations supplémentaires sur l'objet d'un répertoire corrélé à un
événement. Un enregistrement supplémentaire de type FAN_EVENT_INFO_TYPE_DFID enferme les
informations sur l'objet répertoire et est inclus dans toute la structure générique des
métadonnées de l'événement. Pour des événements qui arrivent sur un objet qui n'est pas un
répertoire, la structure supplémentaire inclut un identificateur de fichier qui identifie l'objet
système de fichiers du répertoire parent. Remarquez qu'il n'y a pas de garantie que l'objet
système de fichiers du répertoire ne se trouve à l'emplacement décrit par l’information
d’identificateur de fichier au moment où l'événement est reçu. S'il est associé à l'attribut
FAN_REPORT_FID, il se peut que deux événements soient signalés avec ceux qui se produisent sur un
objet non répertoire, un pour identifier l'objet non répertoire lui-même, et un pour identifier le
répertoire parent. Remarquez que dans certains cas, un objet système de fichiers n'a pas de
parent, par exemple quand un événement se produit sur un fichier non lié mais ouvert. Dans ce cas,
avec l'attribut FAN_REPORT_FID l'événement sera signalé avec un seul enregistrement pour
identifier l'objet non répertoire, puisqu'il n'y a pas de répertoire associé à l'événement. Sans
l'attribut FAN_REPORT_FID, aucun événement ne sera signalé. Voir fanotify(7) pour des détails
supplémentaires.
FAN_REPORT_NAME (depuis Linux 5.9)
Les événements des groupes fanotify initialisés avec cet attribut contiendront des informations
supplémentaires sur le nom de l'entrée de répertoire corrélé à un événement. Cet attribut doit
être fourni en association avec l'attribut FAN_REPORT_DIR_FID. Le fait de fournir cette valeur
d'attribut sans FAN_REPORT_DIR_FID aboutira à l'erreur EINVAL. Cet attribut peut être combiné à
l'attribut FAN_REPORT_FID. Un enregistrement supplémentaire de type FAN_EVENT_INFO_TYPE_DFID_NAME,
qui enferme les informations sur l'entrée de répertoire, est inclus dans toute la structure
générique des métadonnées de l'événement et remplace l'enregistrement des informations
supplémentaires de type FAN_EVENT_INFO_TYPE_DFID. L'enregistrement supplémentaire inclut un
identificateur de fichier qui identifie un objet système de fichiers de répertoire suivi d'un nom
qui identifie une entrée dans ce répertoire. Pour que les événements de modification de l'entrée
d'un répertoire FAN_CREATE, FAN_DELETE et FAN_MOVE, le nom signalé est celui de l'entrée de
répertoire créée/effacée/déplacée. Pour les autres événements qui se produisent sur un objet
répertoire, l’identificateur rapporté est celui est celui de l'objet répertoire lui-même et le nom
signalé est « . ». Pour les autres événements qui se produisent sur un objet non répertoire,
l’identificateur de fichier signalé est celui de l'objet du répertoire parent et le nom signalé
est celui de l'entrée d'un répertoire où se situait l'objet au moment de l'événement. La raison
derrière cette logique est que l’identificateur de fichier du répertoire signalé peut être passé à
open_by_handle_at(2) pour récupérer un descripteur de fichier de répertoire ouvert et que ce
descripteur de fichier ainsi que le nom signalé puissent être utilisés pour appeler fstatat(2). La
même règle qui s'applique au type d'enregistrement FAN_EVENT_INFO_TYPE_DFID s'applique aussi au
type d'enregistrement FAN_EVENT_INFO_TYPE_DFID_NAME : si un objet non répertoire n'a pas de
parent, soit l'événement ne sera pas signalé, soit il le sera sans les informations d'entrée de
répertoire. Remarquez qu'il n'existe pas de garantie que l'objet système de fichiers se trouve à
l'endroit décrit par les informations de l'entrée de répertoire au moment où l'événement est reçu.
Voir fanotify(7) pour des détails supplémentaires.
FAN_REPORT_DFID_NAME
C'est un synonyme de (FAN_REPORT_DIR_FID|FAN_REPORT_NAME).
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
S'il réussit, fanotify_init() renvoie un nouveau descripteur de fichier. En cas d'erreur, il renvoie -1
et errno contient le code d'erreur.
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
fanotify_init() a été introduit dans la version 2.6.36 du noyau Linux et activé dans la version 2.6.37.
CONFORMITÉ
Cet appel système est spécifique à Linux.
BOGUES
Le bogue suivant était présent dans les noyaux Linux avant la version 3.18 :
– 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
fanotify_mark(2), fanotify(7)
COLOPHON
Cette page fait partie de la publication 5.10 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@laposte.net>, Thierry Vignaud
<tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard
<fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau
<jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François
<nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard
<simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot
<david@tilapin.org> et Jean-Philippe MENGUAL <jpmengual@debian.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@lists.debian.org.
Linux 1 novembre 2020 FANOTIFY_INIT(2)