fanotify_init(2) System Calls Manual fanotify_init(2)
NOM
fanotify_init - Créer et initialiser un groupe fanotify
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#include <fcntl.h> /* Définition des constantes O_* */
#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 fa-
notify(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 fano-
tify_mark(2) pour indiquer les fichiers, les répertoires, les points de
montage et les systèmes de fichiers pour lesquels les événements fano-
tify 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 fi-
chier ou répertoire. Le droit d’accéder aux objets de système de fi-
chiers 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.
Le nombre de groupes fanotify par utilisateur est limité. Voir fano-
tify(7) pour des détails sur cette limite.
L’argument flags contient un champ multibit définissant la classe de
notification de l’application écoutant et d’autres champs monobit indi-
quant 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 écou-
tants 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 de
l'accès à un fichier et des événements de décisions de permis-
sion d'accès à un fichier. 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 sto-
ckage hiérarchisé. L'utilisation de cet attribut exige la capa-
cité CAP_SYS_ADMIN.
FAN_CLASS_CONTENT
Cette valeur permet de recevoir des événements notifiant l'accès
à un fichier et des événements de décisions de permission d'ac-
cès à un fichier. 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 utili-
sée par exemple par des programmes de détection de logiciels
malveillants. L'utilisation de cet attribut exige la capacité
CAP_SYS_ADMIN.
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 du nombre d'événements pour la file d’événe-
ments. Voir fanotify(7) pour des détails sur cette limite.
L’utilisation de cet attribut nécessite la capacité CAP_SYS_AD-
MIN.
FAN_UNLIMITED_MARKS
Supprimer la limite du nombre de marques fanotify par utilisa-
teur. Voir fanotify(7) pour des détails sur cette limite. L’uti-
lisation 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'utilisation de cet at-
tribut exige la capacité CAP_SYS_ADMIN.
FAN_ENABLE_AUDIT (depuis Linux 4.15)
Activer la génération d'entrées de journal d'audit sur des ten-
tatives d'accès effectuées par des événements de droits. La ré-
ponse de l'événement de droits doit être marquée par l'attribut
FAN_AUDIT pour qu'une entrée de journal d'audit soit générée.
L'utilisation de cet attribut exige la capacité CAP_AUDIT_WRITE.
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 fi-
chiers sous-jacent corrélé à un événement. Un enregistrement
supplémentaire de type FAN_EVENT_INFO_TYPE_FID enferme les in-
formations sur l'objet et est inclus dans la structure générique
des métadonnées de l'événement. Le descripteur de fichier uti-
lisé pour représenter l'objet lié à un événement est remplacé
par un identificateur de fichier. Il est conçu pour les applica-
tions qui trouvent que l'utilisation d'un identificateur de fi-
chier 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 telles que
FAN_CREATE, FAN_DELETE, FAN_MOVE et FAN_RENAME, ou à des événe-
ments tels que FAN_ATTRIB, FAN_DELETE_SELF et FAN_MOVE_SELF.
Tous les événements ci-dessus exigent un groupe fanotify identi-
fiant les objets de système de fichiers par des identificateurs
de fichier. Remarquez que sans l'attribut FAN_REPORT_TARGET_FID,
pour les événements de modification d'entrée de répertoire, il
existe un enregistrement d'informations qui identifie le réper-
toire 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 EIN-
VAL. 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 attri-
but contiendront (voir les exceptions ci-dessous) des informa-
tions 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 la structure générique des méta-
donné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 de
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’identifica-
teur de fichier au moment où l'événement est reçu. S'il est as-
socié à l'attribut FAN_REPORT_FID, il se peut que deux enregis-
trements soient signalés avec des évènements qui se produisent
sur un objet non répertoire, un pour identifier l'objet non ré-
pertoire lui-même, et un pour identifier l’objet répertoire pa-
rent. Remarquez que dans certains cas, un objet de 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 fano-
tify(7) pour des détails supplémentaires.
FAN_REPORT_NAME (depuis Linux 5.9)
Les événements des groupes fanotify initialisés avec cet attri-
but 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_RE-
PORT_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 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 de système
de fichiers de répertoire suivi d'un nom qui identifie une en-
trée dans ce répertoire. Pour les événements de modification
d'entrée de répertoire FAN_CREATE, FAN_DELETE et FAN_MOVE, le
nom signalé est celui de l'entrée de répertoire créée/effa-
cée/déplacée. L'événement FAN_RENAME peut contenir deux enregis-
trements d'information. L'un, de type
FAN_EVENT_INFO_TYPE_OLD_DFID_NAME, identifie l'ancienne entrée
de répertoire. L’autre, de type
FAN_EVENT_INFO_TYPE_NEW_DFID_NAME, identifie la nouvelle entrée
de répertoire. Pour les autres événements qui se produisent sur
un objet répertoire, l’identificateur rapporté 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éper-
toire, l’identificateur de fichier signalé est celui de l'objet
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 fi-
chier 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'enregistre-
ment 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 de système de fi-
chiers 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).
FAN_REPORT_TARGET_FID (depuis Linux 5.17)
Les événements des groupes fanotify initialisés avec cet attri-
but contiendront des informations supplémentaires sur l'enfant
corrélé aux événements de modification d'entrée de répertoire.
Cet attribut doit être fourni en association avec les attributs
FAN_REPORT_FID, FAN_REPORT_DIR_FID et FAN_REPORT_NAME. Sans
cela, l'erreur EINVAL sera renvoyée. Pour les événements de mo-
dification d'entrée de répertoire FAN_CREATE, FAN_DELETE,
FAN_MOVE et FAN_RENAME, un enregistrement supplémentaire de type
FAN_EVENT_INFO_TYPE_FID est signalé en plus des enregistrements
d'information de type FAN_EVENT_INFO_TYPE_DFID,
FAN_EVENT_INFO_TYPE_DFID_NAME, FAN_EVENT_INFO_TYPE_OLD_DFID_NAME
et FAN_EVENT_INFO_TYPE_NEW_DFID_NAME. L'enregistrement supplé-
mentaire comprend un identifiant de fichier qui identifie l'ob-
jet enfant de système de fichier auquel se rapporte l'entrée de
répertoire.
FAN_REPORT_DFID_NAME_TARGET
C'est un synonyme de (FAN_REPORT_DFID_NAME|FAN_RE-
PORT_FID|FAN_REPORT_TARGET_FID).
FAN_REPORT_PIDFD (depuis Linux 5.15)
Les événements des groupes fanotify initialisés avec cet attri-
but contiendront des informations supplémentaires dans la struc-
ture générique fanotify_event_metadata. Cet enregistrement d’in-
formations sera de type FAN_EVENT_INFO_TYPE_PIDFD et contiendra
un pidfd pour le processus responsable de la génération d'un
événement. Un pidfd renvoyé dans cet objet enregistrement n'est
pas différent du pidfd renvoyé lors d'un appel pidfd_open(2).
Cet enregistrement sert aux applications qui veulent déterminer
de manière fiable si le processus responsable de la génération
d'un événement a été recyclé ou terminé. L'utilisation de l'at-
tribut FAN_REPORT_TID avec FAN_REPORT_PIDFD n'est pas prise en
charge actuellement et si on essaie de faire cela, une erreur
EINVAL sera renvoyée. Cette limite est actuellement imposée par
l'API de pidfd car elle ne gère actuellement que la création de
pidfds pour des leaders de groupes de threads. La création de
pidfds pour autre chose que les leaders de groupes de thread
pourra être gérée dans l'avenir, annulant cette exception. Pour
plus de détails sur l'enregistrement d'informations, voir fano-
tify(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 attri-
buts, consultez la description des valeurs de flags dans open(2).
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 fi-
chier. 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_NOA-
TIME, 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 fi-
chier. En cas d'erreur, il renvoie -1 et errno contient le code d'er-
reur.
ERREURS
EINVAL Une valeur incorrecte a été passée dans flags ou event_f_flags.
FAN_ALL_INIT_FLAGS (obsolète depuis Linux 4.20) définit tous les
bits permis pour flags.
EMFILE Le nombre de groupes fanotify pour cet utilisateur dépasse la
limite. Voir fanotify(7) pour des détails sur cette limite.
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 pro-
grammation 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é
requise.
VERSIONS
fanotify_init() a été introduit dans Linux 2.6.36 et activé dans Li-
nux 2.6.37.
Avant Linux 5.13, l'appel à fanotify_init() exigeait la capacité
CAP_SYS_ADMIN. Depuis Linux 5.13, les utilisateurs peuvent appeler fa-
notify_init() sans la capacité CAP_SYS_ADMIN, pour créer et initialiser
un groupe fanotify avec des fonctionnalités limitées.
Les limites imposées à l'écoutant d'un événement créé par un utilisa-
teur
sans la capacité CAP_SYS_ADMIN sont les suivantes :
• L'utilisateur ne peut pas demander une file d'attente d'évé-
nements illimitée en utilisant FAN_UNLIMITED_QUEUE.
• L'utilisateur ne peut pas demander un nombre illimité de
marques en utilisant FAN_UNLIMITED_MARKS.
• L'utilisateur ne peut pas demander à utiliser des classes de
notification FAN_CLASS_CONTENT ou FAN_CLASS_PRE_CONTENT. Cela
signifie que l'utilisateur ne peut pas de demander des événe-
ments de droits.
• L'utilisateur doit créer un groupe qui identifie l'objet sys-
tème de fichiers par des identificateurs de fichier, par
exemple en fournissant l'attribut FAN_REPORT_FID.
• L'utilisateur est limité aux inœuds de marques. La possibi-
lité de marquer un point de montage ou un système de fichiers
à l'aide de fanotify_mark(), à travers l'utilisation de
FAN_MARK_MOUNT ou de FAN_MARK_FILESYSTEM, n'est pas autori-
sée.
• L'objet événement de la file d'attente d'événements est li-
mité en termes d'information disponible pour l'utilisateur
non privilégié. Un utilisateur ne recevra pas non plus le pid
qui a généré l'événement, sauf si le processus qui écoute a
lui-même généré l'événement.
STANDARDS
Cet appel système est spécifique à Linux.
BOGUES
Le bogue suivant était présent avant Linux 3.18 :
• O_CLOEXEC est ignoré lorsqu'il est passé dans event_f_flags.
Le bogue suivant était présent avant Linux 3.14 :
• l’argument event_f_flags n’est pas vérifié pour les attributs incor-
rects. Les attributs qui ne sont conçus que pour une utilisation in-
terne, 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)
TRADUCTION
La traduction française de cette page de manuel a été créée par Chris-
tophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <ste-
phan.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.cou-
lon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centra-
liens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <si-
mon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@de-
bian.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
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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⟩.
Pages du manuel de Linux 6.03 5 février 2023 fanotify_init(2)
Generated by dwww version 1.15 on Sat Jun 29 01:43:18 CEST 2024.