fanotify_init - Créer et initialiser un groupe fanotify
#include <fcntl.h>
#include <sys/fanotify.h>
int fanotify_init(unsigned int flags, unsigned
int event_f_flags);
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).
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.
- 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.
fanotify_init() a été introduit dans la
version 2.6.36 du noyau Linux et activé dans la
version 2.6.37.
Cet appel système est spécifique à Linux.
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.
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/.
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.