Provided by: manpages-fr_4.15.0-9_all 
NOM
fanotify – Surveiller les événements des systèmes de fichiers
DESCRIPTION
L’interface de programmation fanotify permet la notification et l’interception des
événements du système de fichiers. La recherche de virus et la gestion de stockage
hiérarchisé font partie des cas d’utilisation. Dans l’interface originelle seul un
ensemble limité d’événements était pris en charge. En particulier, les événements de
création, de suppression ou de déplacement n’étaient pas pris en charge. La prise en
charge de ces évènements a été ajoutée dans Linux 5.1. Consultez inotify(7) pour plus de
précisions sur l’interface qui ne notifiait pas ces évènements avant Linux 5.1.
La capacité de surveiller tous les objets d’un système de fichiers monté, la capacité de
décider des droits d’accès et la possibilité de lire ou modifier les fichiers avant qu’ils
ne soient accédés par d’autres applications font partie des capacités supplémentaires à
celles de l’interface de programmation inotify(7).
Les appels système suivants sont utilisés avec cette interface de programmation :
fanotify_init(2), fanotify_mark(2), read(2), write(2) et close(2).
fanotify_init(), fanotify_mark() et groupes de notification
L’appel système fanotify_init(2) crée et initialise un groupe de notifications fanotify et
renvoie un descripteur de fichier le référençant.
Un groupe de notifications fanotify est un objet interne au noyau qui contient une liste
de fichiers, répertoires et points de montage pour lesquels des événements seront créés.
Pour chaque entrée dans un groupe de notifications fanotify, deux masques binaires sont
présents : le masque mark et le masque ignore. Le masque mark définit les activités de
fichier pour lesquelles un événement doit être créé. Le masque ignore définit les
activités pour lesquelles aucun événement ne doit être créé. Avoir ces deux types de
masque permet à un point de montage ou à un répertoire d’être marqué pour recevoir des
événements, tout en ignorant en même temps les événements pour des objets spécifiques dans
ce point de montage ou répertoire.
L’appel système fanotify_mark(2) ajoute un fichier, répertoire ou point de montage à un
groupe de notifications et indique les événements qui doivent être signalés (ou ignorés),
ou supprime ou modifie une telle entrée.
Le masque ignore peut servir pour un cache de fichier. Les événements intéressants pour un
cache de fichier sont la modification et la fermeture d’un fichier. Ainsi, le répertoire
ou point de montage en cache va être marqué pour recevoir ces événements. Après la
réception du premier événement informant qu’un fichier a été modifié, l’entrée
correspondante du cache sera désactivée. Aucun autre événement de modification pour ce
fichier ne sera utile jusqu’à sa fermeture. Ainsi, l’événement de modification peut être
ajouté au masque ignore. Lors de la réception d’un événement de fermeture, l’événement de
modification peut être supprimé du masque ignore et l’entrée de cache de fichier peut être
mise à jour.
Les entrées des groupes de notification fanotify font référence aux fichiers et
répertoires à l’aide de leur numéro d’inœud et aux montages à l’aide de leur identifiant
de montage. Si les fichiers ou répertoires sont renommés ou déplacés dans le même montage,
les entrées correspondantes survivent. Si les fichiers ou répertoires sont supprimés ou
déplacés dans un autre montage ou si les montages sont démontés, les entrées
correspondantes sont supprimées.
La file d’événements
Comme les événements surviennent sur les objets de système de fichiers surveillés par un
groupe de notifications, le système fanotify génère les événements qui sont collectés dans
une file. Ces événements peuvent être lus (en utilisant read(2) ou similaire) à partir du
descripteur de fichier fanotify renvoyé par fanotify_init(2).
Deux types d’événements sont créés : les événements de notification et les événements de
permission. Les événements de notification sont surtout informatifs et ne nécessitent pas
d’action à prendre par l’application qui les reçoit à part pour la fermeture du
descripteur de fichier valable passé dans l’événement (voir ci-dessous). Les événements de
permission sont des demandes à l’application qui les reçoit pour décider si les droits
d’accès à un fichier doivent être attribués. Pour ces événements, le destinataire doit
écrire une réponse qui décide d’attribuer l’accès ou non.
Un événement est supprimé de la file d’événements du groupe fanotify quand il a été lu.
Les événements de permission qui ont été lus sont gardés dans une liste interne du groupe
fanotify jusqu’à ce qu’une décision d’attribution de droits ait été prise en écrivant dans
le descripteur de fichier fanotify ou que le descripteur de fichier fanotify soit fermé.
Lecture d’événements fanotify
Appeler read(2) pour le descripteur de fichier renvoyé par fanotify_init(2) bloque (si
l’attribut FAN_NONBLOCK n’est pas indiqué dans l’appel de fanotify_init(2)) jusqu’à ce
qu’un événement de fichier survienne ou que l’appel soit interrompu par un signal
(consultez signal(7)).
L’utilisation d’un des attributs FAN_REPORT_FID et FAN_REPORT_DIR_FID dans
fanotify_init(2) influence quelles structures sont renvoyées à l’écouteur d’évènement pour
chaque évènement. Les évènements rapportés à un groupe initialisé avec un de ces attributs
utiliseront des gestionnaires de fichiers pour identifier des objets du système de
fichiers au lieu de descripteurs de fichier.
Après un read(2) réussi, le tampon de lecture contient une ou plus des structures
suivantes :
struct fanotify_event_metadata {
__u32 event_len;
__u8 vers;
__u8 reserved;
__u16 metadata_len;
__aligned_u64 mask;
__s32 fd;
__s32 pid;
};
Dans le cas d’un groupe fanotify qui identifie des objets de système de fichiers par des
gestionnaires de fichiers, sont attendus un ou plusieurs enregistrements d’informations
supplémentaires de la structure détaillée ci-dessous qui suit la structure générique
fanotify_event_metadata dans le tampon de lecture :
struct fanotify_event_info_header {
__u8 info_type;
__u8 pad;
__u16 len;
};
struct fanotify_event_info_fid {
struct fanotify_event_info_header hdr;
__kernel_fsid_t fsid;
unsigned char file_handle[0];
};
Pour des raisons de performances, une grande taille de tampon (par exemple 4096 octets)
est conseillée pour que plusieurs événements puissent être récupérés en une seule lecture.
La valeur de retour de read(2) est le nombre d’octets placés dans le tampon, ou -1 en cas
d’erreur (mais consultez BOGUES).
Les champs de la structure fanotify_event_metadata sont les suivants.
event_len
C’est la taille des données pour l’événement actuel et la position du prochain
événement dans le tampon. À moins que le groupe identifie des objets du système de
fichiers par des gestionnaires de fichiers, la valeur d’event_len est toujours
FAN_EVENT_METADATA_LEN. Pour un groupe qui identifie les objets du système de
fichiers par des gestionnaires de fichiers, event_len inclut aussi des
enregistrements d’identificateur de fichier de taille variable.
vers Ce champ contient un numéro de version pour la structure. Il doit être comparé à
FANOTIFY_METADATA_VERSION pour vérifier que les structures renvoyées pendant
l’exécution correspondent aux structures définies à la compilation. En cas d’erreur
de correspondance, l’application devrait arrêter d’essayer d’utiliser le
descripteur de fichier fanotify.
reserved
Ce champ n’est pas utilisé.
metadata_len
C’est la taille de la structure. Le champ a été introduit pour faciliter
l’implémentation d’en-têtes facultatifs par type d’événement. Aucun en-tête
facultatif n’existe dans l’implémentation actuelle.
mask C’est un masque binaire décrivant l’événement (voir ci-dessous).
fd C’est un descripteur de fichier ouvert pour l’objet actuellement accédé ou FAN_NOFD
si un dépassement de file est survenu. Avec un groupe fanotify qui identifie les
objets de système d’exploitation par des gestionnaires de fichiers, les
applications doivent escompter que cette valeur soit FAN_NOFD pour chaque évènement
qu’elles reçoivent. Le descripteur de fichier peut être utilisé pour accéder au
contenu du fichier ou répertoire surveillé. L’application qui lit est responsable
de la fermeture de ce descripteur de fichier.
Lors d’un appel de fanotify_init(2), l’appelant pourrait indiquer (à l’aide de
l’argument event_f_flags) plusieurs attributs d’état de fichier à définir dans la
description de fichier ouverte qui correspond à ce descripteur de fichier. De plus,
l’attribut d’état de fichier FMODE_NONOTIFY (interne au noyau) est défini dans la
description de fichier ouverte. L’attribut supprime la création d’événement
fanotify. Ainsi, quand le destinataire de l’événement fanotify accède au fichier ou
répertoire notifié en utilisant ce descripteur de fichier, aucun événement
supplémentaire n’est créé.
pid Si l’attribut FAN_REPORT_TID était réglé dans fanotify_init(2), c’est l’identifiant
(TID) du thread qui a provoqué cet évènement. Sinon, c’est le PID du processus qui
a provoqué cet évènement.
Un programme écoutant les événements fanotify peut comparer ce PID au PID renvoyé par
getpid(2) pour déterminer si l’événement est provoqué par l’écoutant lui-même ou par un
autre processus accédant au fichier.
Le masque binaire mask indique les événements survenus pour un seul objet de système de
fichiers. Plusieurs bits pourraient être définis dans ce masque si plus d’un événement est
survenu pour l’objet de système de fichiers surveillé. En particulier, les événements
consécutifs pour le même objet de système de fichiers et originaires du même processus
pourraient être fusionnés dans un seul événement, mais deux événements de permission ne
sont jamais fusionnés dans une entrée de file.
Les bits pouvant apparaître dans mask sont les suivants.
FAN_ACCESS
Un fichier ou un répertoire (mais consultez BOGUES) a été accédé (en lecture).
FAN_OPEN
Un fichier ou un répertoire a été ouvert.
FAN_OPEN_EXEC
Un fichier a été ouvert dans le but d’être exécuté. Consultez NOTES dans
fanotify_mark(2) pour plus de détails.
FAN_ATTRIB
Une métadonnée de fichier ou d’un répertoire a été modifiée.
FAN_CREATE
Un fichier enfant ou un répertoire a été créé dans le répertoire surveillé.
FAN_DELETE
Un fichier enfant ou un répertoire a été supprimé dans le répertoire surveillé.
FAN_DELETE_SELF
Un fichier ou un répertoire a été supprimé.
FAN_MOVED_FROM
Un fichier ou un répertoire a été déplacé du répertoire surveillé.
FAN_MOVED_TO
Un fichier ou un répertoire a été déplacé du répertoire parent surveillé.
IN_MOVE_SELF
Un fichier ou un répertoire surveillé a été déplacé.
FAN_MODIFY
Un fichier a été modifié.
FAN_CLOSE_WRITE
Un fichier qui était ouvert en écriture (O_WRONLY ou O_RDWR) a été fermé.
FAN_CLOSE_NOWRITE
Un fichier ou un répertoire, qui était ouvert en lecture seule (O_RDONLY), a été
fermé.
FAN_Q_OVERFLOW
La file d’événements a dépassé la limite de 16384 entrées. Cette limite peut être
écrasée en indiquant l’attribut FAN_UNLIMITED_QUEUE lors de l’appel de
fanotify_init(2).
FAN_ACCESS_PERM
Une application veut lire un fichier ou répertoire, par exemple en utilisant
read(2) ou readdir(2). Le lecteur doit écrire une réponse (telle que décrite
ci-dessous) qui détermine si le droit d’accès à l’objet de système de fichiers sera
attribué.
FAN_OPEN_PERM
Une application veut ouvrir un fichier ou un répertoire. Le lecteur doit écrire une
réponse qui détermine si le droit d’ouvrir l’objet de système de fichiers sera
attribué.
FAN_OPEN_PERM
Une application veut ouvrir un fichier pour une exécution. Le lecteur doit écrire
une réponse qui détermine si le droit d’ouvrir l’objet de système de fichiers sera
attribué. Consultez NOTES dans fanotify_mark(2) pour plus de détails.
Pour vérifier tous les événements fermés, le masque binaire suivant pourrait être
utilisé :
FAN_CLOSE
Un fichier a été fermé. C’est un synonyme de :
FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
Pour vérifier tous les événements de déplacement, le masque binaire suivant pourrait être
utilisé :
FAN_MOVE
Un fichier ou un répertoire a été déplacé. C’est un synonyme de :
FAN_MOVED_FROM | FAN_MOVED_TO
Les bits suivants peuvent apparaître dans mask seulement conjointement avec d’autres bits
de type d’évènement :
FAN_ONDIR
Les évènements décrits dans le mask se sont déroulés dans un objet de répertoire.
Le rapport d’évènements dans des répertoires requiert le réglage de cet attribut
dans le masque mark. Consultez fanotify_mark(2) pour plus de détails. L’attribut
FAN_ONDIR est rapporté dans un masque d’évènement seulement si le groupe fanotify
identifie les objets de système d’exploitation avec des gestionnaires de fichiers.
Les champs de la structure fanotify_event_info_fid sont les suivants.
hdr C’est une structure de type fanotify_event_info_header. C’est un en-tête générique
qui contient des informations utilisées pour décrire un enregistrement
d’informations supplémentaires attaché à l’évènement. Par exemple, quand un
descripteur de fichier fanotify est créé en utilisant FAN_REPORT_FID, un
enregistrement unique est supposé être attaché à l’évènement avec la valeur de
champ info_type de FAN_EVENT_INFO_TYPE_FID. Quand un descripteur de fichier
fanotify est créé en utilisant la combinaison de FAN_REPORT_FID et
FAN_REPORT_DIR_FID, il peut y avoir deux enregistrements d’informations attachés à
l’évènement : un avec une valeur de champ info_type de FAN_EVENT_INFO_TYPE_DFID,
identifiant un objet de répertoire parent, et un avec une valeur de champ info_type
de FAN_EVENT_INFO_TYPE_FID, identifiant un objet non répertoire. Le
fanotify_event_info_header contient un champ len. La valeur de len est la taille de
l’enregistrement d’informations supplémentaires incluant le
fanotify_event_info_header lui-même. La taille totale de tous les enregistrements
d’informations supplémentaires n’est pas supposée être supérieure à
( event_len - metadata_len ).
fsid C’est un identifiant unique du système de fichiers contenant l’objet associé avec
l’évènement. C’est une structure de type __kernel_fsid_t et elle contient la même
valeur que f_fsid lors de l’appel statfs(2).
file_handle
C’est une structure de taille variable de type struct gestionnaire_fichier. C’est
un gestionnaire opaque qui correspond à un objet précis de système de fichiers
comme renvoyé par name_to_handle_at(2). Il peut être utilisé uniquement pour
identifier un fichier d’un système de fichiers et peut être passé comme argument à
open_by_handle_at(2). Remarquez que pour les évènements de modification d’entrée de
répertoire FAN_CREATE, FAN_DELETE et FAN_MOVE, gestionnaire_fichier identifie le
répertoire modifié et non l’objet enfant créé/supprimé/déplacé. Si la valeur du
champ info_type est FAN_EVENT_INFO_TYPE_DFID_NAME, le gestionnaire de fichiers est
suivi par un octet NULL final qui identifie le nom d’entrée de répertoire
créé/supprimé/déplacé. Pour les autres évènements tels que FAN_OPEN, FAN_ATTRIB,
FAN_DELETE_SELF et FAN_MOVE_SELF, si la valeur du champ info_type est
FAN_EVENT_INFO_TYPE_FID, le gestionnaire_fichier identifie l’objet corrélé à
l’évènement. Si la valeur du champ info_type est FAN_EVENT_INFO_TYPE_DFID, le
gestionnaire_fichier identifie l’objet de répertoire corrélé à l’évènement ou le
répertoire parent d’un objet non répertoire corrélé à l’évènement. Si la valeur du
champ info_type est FAN_EVENT_INFO_TYPE_DFID_NAME, le gestionnaire_fichier
identifie le même objet de répertoire qui aurait été rapporté avec
FAN_EVENT_INFO_TYPE_DFID et le gestionnaire de fichiers est suivi par un octet
NULL final qui identifie le nom de l’entrée de répertoire dans ce répertoire ou
« . » pour identifier l’objet du répertoire.
Les macros suivantes sont fournies pour itérer sur un tampon contenant les métadonnées
d’événement fanotify renvoyées par read(2) à partir d’un descripteur de fichier fanotify.
FAN_EVENT_OK(meta, len)
Cette macro compare la taille restante len du tampon meta à la taille de la
structure de métadonnées et au champ event_len de la première structure de
métadonnées du tampon.
FAN_EVENT_NEXT(meta, len)
Cette macro utilise la taille indiquée dans le champ event_len de la structure de
métadonnées pointée par meta pour calculer l’adresse de la prochaine structure de
métadonnées qui suit meta. len est le nombre d’octets de métadonnées qui restent
actuellement dans le tampon. La macro renvoie un pointeur vers la prochaine
structure de métadonnées qui suit meta et réduit len du nombre d’octets dans la
structure de métadonnées qui a été sautée (c’est-à-dire qu’elle soustrait
meta->event_len de len).
De plus, il existe :
FAN_EVENT_METADATA_LEN
Cette macro renvoie la taille (en octet) de la structure fanotify_event_metadata.
C’est la taille minimale (et actuellement la seule taille) de métadonnées
d’événements.
Surveiller un descripteur de fichier fanotify pour les événements
Quand un événement fanotify survient, le descripteur de fichier fanotify est indiqué comme
lisible lorsque passé à epoll(7), poll(2) ou select(2).
Traitement des événements de permission
Pour les événements de permission, l’application doit écrire (avec write(2)) une structure
de la forme suivante sur le descripteur de fichier fanotify :
struct fanotify_response {
__s32 fd;
__u32 response;
};
Les membres de cette structure sont les suivants :
fd C’est le descripteur de fichier de la structure fanotify_event_metadata.
response
Ce champ indique si les droits doivent être attribués ou non. Cette valeur doit
être soit FAN_ALLOW pour permettre l’opération de fichier, soit FAN_DENY pour
refuser l’opération de fichier.
Si l’accès est refusé, l’appel de l’application requérante recevra une erreur EPERM. De
plus, si le groupe de notifications a été créé avec l’attribut FAN_ENABLE_AUDIT, alors
l’attribut FAN_AUDIT peut être défini dans le champ response. Dans ce cas, le sous-système
d’audit journalisera l’information à propos de la décision d’accès aux journaux d’audit.
Fermeture du descripteur de fichier fanotify
Quand tous les descripteurs de fichier se référant au groupe de notifications fanotify
sont fermés, le groupe fanotify est libéré et ses ressources sont libérées pour être
réutilisées par le noyau. Lors de l’appel de close(2), les événements de permission
restants seront définis à permis.
/proc/[pid]/fdinfo
Le fichier /proc/[pid]/fdinfo/[fd] contient des renseignements sur les marques fanotify
pour le descripteur de fichier fd du processus pid. Consultez proc(5) pour plus de
précisions.
ERREURS
En plus des erreurs habituelles de read(2), les erreurs suivantes peuvent survenir lors de
la lecture d’un descripteur de fichier fanotify.
EINVAL Le tampon est trop petit pour contenir l’événement.
EMFILE La limite par processus du nombre de fichiers ouverts a été atteinte. Consultez la
description de RLIMIT_NOFILE dans getrlimit(2).
ENFILE La limite du nombre de fichiers ouverts sur le système a été atteinte. Consultez
/proc/sys/fs/file-max dans proc(5).
ETXTBSY
Cette erreur est renvoyée par read(2) si O_RDWR ou O_WRONLY ont été indiqués dans
l’argument event_f_flags lors de l’appel fanotify_init(2) et qu’un événement est
survenu pour un fichier surveillé actuellement en cours d’exécution.
En plus des erreurs habituelles de write(2), les erreurs suivantes peuvent survenir lors
de l’écriture sur un descripteur de fichier fanotify.
EINVAL Les droits d’accès fanotify ne sont pas activés dans la configuration du noyau ou
la valeur de response dans la structure de réponse n’est pas valable.
ENOENT Le descripteur de fichier fd dans la structure de réponse n’est pas valable. Cela
pourrait survenir quand une réponse pour l’événement de permission a déjà été
écrite.
VERSIONS
L’interface de programmation fanotify a été introduite dans la version 2.6.36 du noyau
Linux et activée dans la version 2.6.37. La prise en charge de fdinfo a été ajoutée dans
la version 3.8.
CONFORMITÉ
L’interface de programmation fanotify est spécifique à Linux.
NOTES
L’interface de programmation fanotify n’est disponible que si le noyau a été construit
avec l’option de configuration CONFIG_FANOTIFY activée. De plus, le traitement de
permission fanotify n’est disponible que si l’option de configuration
CONFIG_FANOTIFY_ACCESS_PERMISSIONS est activée.
Limites et réserves
Fanotify ne signale que les événements déclenchés par un programme en espace utilisateur à
l’aide d’une interface de programmation de système de fichiers. Par conséquent, elle
n’intercepte pas les événements qui surviennent sur les systèmes de fichiers en réseau.
L'interface fanotify ne signale pas les accès ni les modifications de fichier qui
pourraient survenir à cause de mmap(2), msync(2) ou munmap(2).
Les événements pour répertoire ne sont créés que si le répertoire lui-même est ouvert, lu
et fermé. Ajouter, supprimer ou modifier les enfants d’un répertoire marqué ne crée pas
d’événement pour le répertoire surveillé lui-même.
La surveillance fanotify des répertoires n'est pas récursive : pour surveiller les
sous-répertoires, des marques supplémentaires doivent être créées. L’évènement FAN_CREATE
peut être utilisé pour détecter quand un sous-répertoire a été créé dans un répertoire
marqué. Une marque supplémentaire doit être définie dans le sous-répertoire nouvellement
créé. Cette approche crée une situation de compétition, parce qu’elle peut perdre les
évènements qui se produisent dans le nouveau sous-répertoire avant qu’une marque soit
ajoutée dans ce sous-répertoire. La surveillance des montages offre la capacité de
surveiller un arbre entier de répertoires sans ce problème de chronologie. La surveillance
de système de fichiers offre la capacité de surveiller tout montage d’une instance de
système de fichiers sans situation de compétition.
La file d'événements peut déborder. Dans ce cas, les événements sont perdus.
BOGUES
Avant Linux 3.19, fallocate(2) ne créait pas d'événement fanotify. Depuis Linux 3.19, les
appels à fallocate(2) créent des événements FAN_MODIFY.
Dans Linux 3.17, les bogues suivants existent :
– Dans Linux, un objet du système de fichiers pourrait être accessible par de multiples
chemins. Par exemple, une partie d'un système de fichiers pourrait être remontée avec
l'option --bind de mount(8). Un écoutant ayant marqué un montage ne sera notifié que
des événements déclenchés pour un objet du système de fichiers utilisant le même
montage. Tout autre événement passera inaperçu.
– Quand un événement est créé, aucune vérification n’est effectuée pour voir si
l’identifiant utilisateur du processus recevant a le droit de lire ou écrire le fichier
avant de passer un descripteur de fichier pour ce fichier. Cela pose un risque de
sécurité quand la capacité CAP_SYS_ADMIN est définie pour un programme exécuté par les
utilisateurs ordinaires.
– Si un appel de read(2) traite plusieurs événements de la file fanotify et qu’une erreur
survient, la valeur de retour sera la taille totale des événements copiés correctement
dans le tampon d’espace utilisateur avant que l’erreur ne survienne. La valeur de
retour ne sera pas -1 et errno ne sera pas définie. Ainsi, l’application lisant n’a
aucun moyen de détecter l’erreur.
EXEMPLES
Les deux programmes ci-dessous montrent l’utilisation de l’API de fanotify.
Exemple de programme : fanotify_example.c
Le programme suivant montre l’utilisation de l’interface de programmation fanotify avec
les informations d’évènements d’objet passées sous la forme d’un descripteur de fichier.
Il marque le point de montage passé en argument de ligne de commande et attend les
événements de type FAN_OPEN_PERM et FAN_CLOSE_WRITE. Quand un événement de permission
survient, une réponse FAN_ALLOW est donnée.
La sortie suivante de session d’interpréteur de commande montre un exemple de l’exécution
de ce programme. Cette session concerne l’édition du fichier /home/utilisateur/temp/notes.
Avant d’ouvrir le fichier, un événement FAN_OPEN_PERM est survenu. Après la fermeture du
fichier, un événement FAN_CLOSE_WRITE est survenu. L’exécution du programme se termine
quand l’utilisateur appuie sur la touche Entrée.
# ./fanotify_exemple /home
Appuyer sur la touche Entrée pour quitter.
En écoute d’événements.
FAN_OPEN_PERM : Fichier /home/utilisateur/temp/notes
FAN_CLOSE_WRITE : Fichier /home/utilisateur/temp/notes
Arrêt de l’écoute d’événements.
Source du programme : fanotify_example.c
#define _GNU_SOURCE /* Nécessaire pour obtenir la définition de O_LARGEFILE */
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <poll.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/fanotify.h>
#include <unistd.h>
/* Lire tous les événements fanotify disponibles à partir du descripteur
de fichier « fd » */
static void
handle_events(int fd)
{
const struct fanotify_event_metadata *metadata;
struct fanotify_event_metadata buf[200];
ssize_t len;
char path[PATH_MAX];
ssize_t path_len;
char procfd_path[PATH_MAX];
struct fanotify_response response;
/* Boucler tant que les événements peuvent être lus à partir du
descripteur de fichier fanotify */
for (;;) {
/* Lire certains événements */
len = read(fd, buf, sizeof(buf));
if (len == -1 && errno != EAGAIN) {
perror("read");
exit(EXIT_FAILURE);
}
/* Vérifier si la fin des données disponibles est atteinte */
if (len <= 0)
break;
/* Pointer vers le premier événement du tampon */
metadata = buf;
/* Boucler sur tous les événements du tampon */
while (FAN_EVENT_OK(metadata, len)) {
/* Vérifier que les structures au moment de l’exécution et
de la compilation correspondent */
if (metadata->vers != FANOTIFY_METADATA_VERSION) {
fprintf(stderr,
"Non correspondance de version de métadonnées fanotify.\n");
exit(EXIT_FAILURE);
}
/* metadata->fd contient soit FAN_NOFD, indiquant un
dépassement de file, soit un descripteur de fichier
(un entier positif).
Ici, le dépassement de file est simplement ignoré. */
if (metadata->fd >= 0) {
/* Traiter l’événement de permission d’ouverture */
if (metadata->mask & FAN_OPEN_PERM) {
printf("FAN_OPEN_PERM : ");
/* Permettre d’ouvrir le fichier */
response.fd = metadata->fd;
response.response = FAN_ALLOW;
write(fd, &response, sizeof(response));
}
/* Traiter l’événement de fermeture de fichier ouvert
en écriture */
if (metadata->mask & FAN_CLOSE_WRITE)
printf("FAN_CLOSE_WRITE : ");
/* Récupérer et afficher le chemin du fichier accédé */
snprintf(procfd_path, sizeof(procfd_path),
"/proc/self/fd/%d", metadata->fd);
path_len = readlink(procfd_path, path,
sizeof(path) - 1);
if (path_len == -1) {
perror("readlink");
exit(EXIT_FAILURE);
}
path[path_len] = '\0';
printf("File %s\n", path);
/* Fermer le descripteur de fichier de l’événement */
close(metadata->fd);
}
/* Avancer au prochain événement */
metadata = FAN_EVENT_NEXT(metadata, len);
}
}
}
int
main(int argc, char *argv[])
{
char buf;
int fd, poll_num;
nfds_t nfds;
struct pollfd fds[2];
/* Vérifier qu’un point de montage est fourni */
if (argc != 2) {
fprintf(stderr, "Utilisation : %s MONTAGE\n", argv[0]);
exit(EXIT_FAILURE);
}
printf("Appuyer sur la touche Entrée pour quitter.\n");
/* Créer le descripteur de fichier pour accéder à l’interface de
programmation fanotify */
fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK,
O_RDONLY | O_LARGEFILE);
if (fd == -1) {
perror("fanotify_init");
exit(EXIT_FAILURE);
}
/* Marquer le montage pour :
— les événements de permission avant d’ouvrir les fichiers
— les événements de notification après fermeture de descripteur
de fichier ouvert en écriture */
if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT,
FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD,
argv[1]) == -1) {
perror("fanotify_mark");
exit(EXIT_FAILURE);
}
/* Préparer pour la scrutation (polling) */
nfds = 2;
fds[0].fd = STDIN_FILENO; /* Entrée de console */
fds[0].events = POLLIN;
fds[1].fd = fd; /* Entrée fanotify */
fds[1].events = POLLIN;
/* Boucle en attente d’arrivée d’événements */
printf("En écoute d’événements.\n");
while (1) {
poll_num = poll(fds, nfds, -1);
if (poll_num == -1) {
if (errno == EINTR) /* Interrompu par un signal */
continue; /* Redémarrage de poll() */
perror("poll"); /* Erreur inattendue */
exit(EXIT_FAILURE);
}
if (poll_num > 0) {
if (fds[0].revents & POLLIN) {
/* Entrée de console disponible :
effacer l’entrée standard et quitter */
while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\n')
continue;
break;
}
if (fds[1].revents & POLLIN) {
/* Des événements fanotify sont disponibles */
handle_events(fd);
}
}
}
printf("Arrêt de l’écoute d’événements.\n");
exit(EXIT_SUCCESS);
}
Exemple de programme : fanotify_fid.c
Le second programme est un exemple d’utilisation de fanotify avec un groupe qui identifie
des objets avec des gestionnaires de fichier. Le programme marque l’objet de système de
fichiers qui est passé comme argument de ligne de commande et attend jusqu’à ce qu’un
évènement de type FAN_CREATE se produise. Le masque d’évènement indique quel type d’objet
de système de fichiers, soit un fichier ou un répertoire, est créé. Une fois que tous les
évènements du tampon ont été lus et traités de la manière appropriée, le programme se
termine.
Les sessions d’interpréteur de commande suivantes montrent deux invocations différentes
avec des actions différentes réalisées sur l’objet désiré.
La première session montre une marque placée sur /home/utilisateur. Cela est suivi par la
création d’un fichier normal, /home/utilisateur/fichiertest.txt. Cela aboutit à un
évènement FAN_CREATE généré et rapporté à l’objet de répertoire surveillé parent du
fichier et à la création du nom de fichier. L’exécution du programme se termine une fois
que tous les évènements capturés du tampon ont été traités.
# ./fanotify_fid /home/user
Écoute de tous les évènements.
FAN_CREATE (fichier créé) :
Répertoire /home/utilisateur a été modifié.
Entrée 'fichiertest.txt' n’est pas un sous-répertoire.
Tous les évènements ont été traités avec succès. Fin du programme.
$ touch /home/utilisateur/fichiertest.txt # Dans un autre terminal
La première session montre une marque placée sur /home/utilisateur. C’est suivi par la
création d’un répertoire, /home/utilisateur/réptest. Cette action spécifique aboutit à la
génération d’un évènement FAN_CREATE et est rapporté avec l’attribut FAN_ONDIR défini et
avec la création du nom de répertoire.
# ./fanotify_fid /home/user
Écoute de tous les évènements.
FAN_CREATE | FAN_ONDIR (sous_répertoire créé) :
Répertoire /home/utilisateur a été modifié.
Entrée 'réptest' est un sous-répertoire.
Tous les évènements ont été traités avec succès. Fin du programme.
$ mkdir -p /home/utilisateur/réptest # Dans un autre terminal
Source du programme : fanotify_fid.c
#define _GNU_SOURCE
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/fanotify.h>
#include <unistd.h>
#define BUF_SIZE 256
int
main(int argc, char *argv[])
{
int fd, ret, event_fd, mount_fd;
ssize_t len, path_len;
char path[PATH_MAX];
char procfd_path[PATH_MAX];
char events_buf[BUF_SIZE];
struct file_handle *file_handle;
struct fanotify_event_metadata *metadata;
struct fanotify_event_info_fid *fid;
const char *file_name;
struct stat sb;
if (argc != 2) {
fprintf(stderr, "nb d’arguments de ligne de commande non valable.\n");
exit(EXIT_FAILURE);
}
mount_fd = open(argv[1], O_DIRECTORY | O_RDONLY);
if (mount_fd == -1) {
perror(argv[1]);
exit(EXIT_FAILURE);
}
/* Créer un descripteur de fichier avec FAN_REPORT_DFID_NAME sous
forme d’attribut de façon que le programme puisse recevoir des
évènements fid avec des noms de répertoire d’entrée */
fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME, 0);
if (fd == -1) {
perror("fanotify_init");
exit(EXIT_FAILURE);
}
/* Placer une marque sur un objet de système de fichiers
fourni dans argv[1]. */
ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
FAN_CREATE | FAN_ONDIR,
AT_FDCWD, argv[1]);
if (ret == -1) {
perror("fanotify_mark");
exit(EXIT_FAILURE);
}
printf("En écoute d’événements.\n");
/* Lire les évènements dans la file dans le tampon */
len = read(fd, events_buf, sizeof(events_buf));
if (len == -1 && errno != EAGAIN) {
perror("read");
exit(EXIT_FAILURE);
}
/* Traiter tous les événements du tampon */
for (metadata = (struct fanotify_event_metadata *) events_buf;
FAN_EVENT_OK(metadata, len);
metadata = FAN_EVENT_NEXT(metadata, len)) {
fid = (struct fanotify_event_info_fid *) (metadata + 1);
file_handle = (struct file_handle *) fid->handle;
/* Assurer que l’info d’évènement soit du type correct */
if (fid->hdr.info_type == FAN_EVENT_INFO_TYPE_FID ||
fid->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID) {
file_name = NULL;
} else if (fid->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
file_name = file_handle->f_handle +
file_handle->handle_bytes;
} else {
fprintf(stderr, "Type inattendu d’évènement reçu.\n");
exit(EXIT_FAILURE);
}
if (metadata->mask == FAN_CREATE)
printf("FAN_CREATE (file created):\n");
if (metadata->mask == (FAN_CREATE | FAN_ONDIR))
printf("FAN_CREATE | FAN_ONDIR (sous_répertoire créé) :\n");
/* metadata->fd est défini à FAN_NOFD quand le groupe identifie
les objets avec des gestionnaires de fichiers. Pour obtenir un
descripteur de fichier pour l’objet de fichier correspondant à
à un évènement, utiliser struct gestionnaire_fichier qui est
fourni dans le fanotify_event_info_fid conjointement avec l’appel
système open_by_handle_at(2). Une vérification pour ESTALE est
faite pour supporter la situation où le gestionnaire de fichiers
pour l’objet ait été détruit avant cet appel système. */
event_fd = open_by_handle_at(mount_fd, file_handle, O_RDONLY);
if (event_fd == -1) {
if (errno == ESTALE) {
printf("Le gestionnaire de fichiers n’est plus valable, "
"le fichier a été supprimé\n");
continue;
} else {
perror("open_by_handle_at");
exit(EXIT_FAILURE);
}
}
snprintf(procfd_path, sizeof(procfd_path), "/proc/self/fd/%d",
event_fd);
/* Retrouver et afficher le chemin de l’entrée modifiée */
path_len = readlink(procfd_path, path, sizeof(path) - 1);
if (path_len == -1) {
perror("readlink");
exit(EXIT_FAILURE);
}
path[path_len] = '\0';
printf("\Le répertoire '%s' a été modifié\n", path);
if (file_name) {
ret = fstatat(event_fd, file_name, &sb, 0);
if (ret == -1) {
if (errno != ENOENT) {
perror("fstatat");
exit(EXIT_FAILURE);
}
printf("\tL’entrée '%s' n’existe pas\n", file_name);
} else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
printf("\tL’entrée '%s' est un sous-répertoire\n", file_name);
} else {
printf("\tL’entrée '%s' n’est pas un sous-répertoire\n",
file_name);
}
}
/* Fermer le descripteur de fichier de l’événement */
close(event_fd);
}
printf("Tous les évènements traités avec succès, fin du programme.\n");
exit(EXIT_SUCCESS);
}
VOIR AUSSI
fanotify_init(2), fanotify_mark(2), inotify(7)
COLOPHON
Cette page fait partie de la publication 5.13 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-Paul Guillonneau
<guillonneau.jeanpaul@free.fr>
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⟩.