Provided by: manpages-fr-dev_4.23.1-1_all 
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 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.
Le nombre de groupes fanotify par utilisateur est limité. Voir fanotify(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 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 de l'accès à un fichier et
des événements de décisions de permission 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 stockage hiérarchisé. L'utilisation
de cet attribut exige la capacité 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'accè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
utilisé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énements. Voir
fanotify(7) pour des détails sur cette limite. L’utilisation de cet attribut
nécessite la capacité CAP_SYS_ADMIN.
FAN_UNLIMITED_MARKS
Supprimer la limite du nombre de marques fanotify par utilisateur. Voir fanotify(7)
pour des détails sur cette limite. 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'utilisation de cet attribut 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 tentatives 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 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 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
telles que FAN_CREATE, FAN_DELETE, FAN_MOVE et FAN_RENAME, 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 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é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 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 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’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 enregistrements 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 parent. 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 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 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 entré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/effacée/déplacée. L'événement
FAN_RENAME peut contenir deux enregistrements 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épertoire, 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 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 de 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).
FAN_REPORT_TARGET_FID (depuis Linux 5.17)
Les événements des groupes fanotify initialisés avec cet attribut 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 modification 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'objet 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_REPORT_FID|FAN_REPORT_TARGET_FID).
FAN_REPORT_PIDFD (depuis Linux 5.15)
Les événements des groupes fanotify initialisés avec cet attribut contiendront des
informations supplémentaires dans la structure générique fanotify_event_metadata.
Cet enregistrement d’informations 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'attribut 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
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(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 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 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 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é requise.
VERSIONS
Avant Linux 5.13, l'appel à fanotify_init() exigeait la capacité CAP_SYS_ADMIN. Depuis
Linux 5.13, les utilisateurs peuvent appeler fanotify_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 utilisateur
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énements de droits.
- L'utilisateur doit créer un groupe qui identifie l'objet systè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 possibilité 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
autorisée.
- L'objet événement de la file d'attente d'événements est limité 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
Linux.
HISTORIQUE
Linux 2.6.37.
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 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)
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 ⟨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⟩.