fanotify_mark(2) System Calls Manual fanotify_mark(2)
NOM
fanotify_mark - Ajouter, supprimer ou modifier une marque fanotify sur
un objet de système de fichiers
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#include <sys/fanotify.h>
int fanotify_mark(int fanotify_fd, unsigned int flags,
uint64_t mask, int dirfd,
const char *_Nullable pathname);
DESCRIPTION
Pour un aperçu de l’interface de programmation fanotify, consultez fa-
notify(7).
fanotify_mark() ajoute, supprime ou modifie une marque fanotify sur un
objet de système de fichiers. L’appelant doit avoir le droit de lecture
sur l’objet de système de fichiers à marquer.
L’argument fanotify_fd est un descripteur de fichier renvoyé par fano-
tify_init(2).
flags est un masque de bits décrivant la modification à réaliser. Il
doit contenir exactement une des valeurs suivantes.
FAN_MARK_ADD
Les événements dans mask seront ajoutés au masque de marque (ou
au masque ignore). mask doit être non vide sinon l’erreur EINVAL
surviendra.
FAN_MARK_REMOVE
Les événements dans l’argument mask seront supprimés du masque
de marque (ou du masque ignore). mask doit être non vide sinon
l’erreur EINVAL surviendra.
FAN_MARK_FLUSH
Supprimer toutes les marques de systèmes de fichiers, de mon-
tages ou de répertoires et fichiers du groupe fanotify. Si flags
contient FAN_MARK_MOUNT, toutes les marques de montage seront
supprimées du groupe. Si flags contient FAN_MARK_FILESYSTEM,
toutes les marques de systèmes de fichiers seront supprimées du
groupe. Sinon, toutes les marques des répertoires et fichiers
seront supprimées. Aucun autre attribut et au plus un des attri-
buts FAN_MARK_MOUNT ou FAN_MARK_FILESYSTEM peut être utilisé
avec FAN_MARK_FLUSH. mask est ignoré.
Si aucune des valeurs précédentes n’est indiquée, ou si plus d’une est
indiquée, l’appel échoue avec l'erreur EINVAL.
De plus, zéro ou plus des valeurs suivantes peuvent être incluses dans
flags (avec une opération OU bit à bit).
FAN_MARK_DONT_FOLLOW
Si pathname est un lien symbolique, marquer le lien lui-même,
plutôt que le fichier pointé (par défaut, fanotify_mark() déré-
férence pathname si c’est un lien symbolique).
FAN_MARK_ONLYDIR
Si l’objet de système de fichiers à marquer n’est pas un réper-
toire, l’erreur ENOTDIR surviendra.
FAN_MARK_MOUNT
Marquer le point de montage indiqué par pathname. Si pathname
n’est pas un point de montage lui-même, le point de montage
contenant pathname sera marqué. Tous les répertoires, sous-ré-
pertoires et fichiers contenus dans le point de montage seront
surveillés. Les événements qui exigent que les objets de sys-
tèmes de fichiers soient identifiés par des identificateurs de
fichier, tels que FAN_CREATE, FAN_ATTRIB, FAN_MOVE et FAN_DE-
LETE_SELF, ne peuvent pas être fournis comme mask quand flags
contient FAN_MARK_MOUNT. Une telle tentative renverra l'erreur
EINVAL. L'utilisation de cet attribut exige la capacité
CAP_SYS_ADMIN.
FAN_MARK_FILESYSTEM (depuis Linux 4.20)
Marquer le système de fichiers indiqué par pathname. Le système
de fichiers contenant pathname sera marqué. Tous les fichiers et
répertoires contenus dans le système de fichiers issus de n'im-
porte quel point de montage seront surveillés. L'utilisation de
cet attribut exige la capacité CAP_SYS_ADMIN.
FAN_MARK_IGNORED_MASK
Les événements de mask ne seront pas ajoutés ou supprimés du
masque ignore. Remarquez que les attributs FAN_ONDIR et
FAN_EVENT_ON_CHILD n'ont aucun effet quand ils sont fournis avec
cet attribut. L’effet du positionnement des attributs FAN_ONDIR
et FAN_EVENT_ON_CHILD dans le masque de marquage des événements
positionnés dans le masque ignore n'est pas défini et dépend de
la version du noyau Linux. En particulier, avant Linux 5.9, po-
sitionner un masque de marquage sur un fichier et une marque
avec un masque ignore sur son répertoire parent ne ferait pas
ignorer les événements sur le fichier, même avec l'attribut
FAN_EVENT_ON_CHILD dans le masque de marquage du répertoire pa-
rent. Quand le masque ignore est mis à jour avec l'attribut
FAN_MARK_IGNORED_MASK sur une marque précédemment mise à jour
avec l'attribut FAN_MARK_IGNORE, la mise à jour échoue avec
l'erreur EEXIST.
FAN_MARK_IGNORE (depuis Linux 6.0)
Cet attribut a le même effet que de positionner l'attribut
FAN_MARK_IGNORED_MASK. Les événements du mask seront ajoutés ou
supprimés du masque ignore. Contrairement à l'attribut
FAN_MARK_IGNORED_MASK, cet attribut a également pour effet que
les attributs FAN_ONDIR et FAN_EVENT_ON_CHILD agissent sur le
masque ignore. En particulier, sauf si l'attribut FAN_ONDIR est
positionné avec FAN_MARK_IGNORE, les événements sur les réper-
toires ne seront pas ignorés. Si l'attribut FAN_EVENT_ON_CHILD
est positionné avec FAN_MARK_IGNORE, les événements sur les en-
fants seront ignorés. Par exemple, une marque sur un répertoire
associé à un masque avec l'événement FAN_CREATE et l'attribut
FAN_ONDIR et un masque ignore avec un événement FAN_CREATE et
sans l'attribut FAN_ONDIR ne gardera que les événements de créa-
tion de sous-répertoires. Lors de l'utilisation de l'attribut
FAN_MARK_IGNORE pour ajouter à un masque ignore une marque de
montage, de système de fichiers ou d'inœud de répertoire, l'at-
tribut FAN_MARK_IGNORED_SURV_MODIFY doit être indiqué. Un oubli
de faire cela donne une erreur EINVAL ou EISDIR.
FAN_MARK_IGNORED_SURV_MODIFY
Le masque ignore survivra aux événements de modification. Si cet
attribut n'est pas positionné, le masque ignore est effacé quand
un événement de modification se produit sur l'objet marqué. Ne
pas utiliser cet attribut se fait généralement pour supprimer
des événements (comme FAN_OPEN) sur un fichier spécifique,
jusqu'à ce que le contenu de ce dernier ne soit modifié. Il est
beaucoup moins utile de supprimer des événements sur tout un
système de fichiers ou un montage, ou bien sur tous les fichiers
d'un répertoire, jusqu'à ce qu'un contenu de fichier ne soit mo-
difié. C'est pourquoi l'attribut FAN_MARK_IGNORE exige l'attri-
but FAN_MARK_IGNORED_SURV_MODIFY sur une marque d'inœud de mon-
tage, de système de fichiers ou de répertoire. Cet attribut ne
peut pas être supprimé d'une marque une fois qu'il a été posi-
tionné. Quand le masque ignore est mis à jour sans cet attribut
sur une marque précédemment mise à jour avec les attributs
FAN_MARK_IGNORE et FAN_MARK_IGNORED_SURV_MODIFY, la mise à jour
échoue avec l'erreur EEXIST.
FAN_MARK_IGNORE_SURV
C'est un synonyme de (FAN_MARK_IGNORE|FAN_MARK_IGNORED_SURV_MO-
DIFY).
FAN_MARK_EVICTABLE (depuis Linux 5.19)
Lorsqu'une marque d'inœud est créée avec cet attribut, l'objet
inœud ne sera pas associé au cache de l'inœud, permettant ainsi
à l'objet inœud d'être supprimé du cache d'inœud quand la pres-
sion sur la mémoire du système est élevée. La suppression de
l'objet inœud provoque aussi la perte de la marque suppressible.
Quand le masque d'un inœud suppressible est mis à jour sans uti-
liser l'attribut FAN_MARK_EVICATBLE, l'inœud marqué est épinglé
dans le cache d'inœuds et la marque n'est plus suppressible.
Quand le masque d'une marque d'inœud non suppressible est mis à
jour avec l'attribut FAN_MARK_EVICTABLE, la marque d'inœud reste
non suppressible et la mise à jour échoue avec l'erreur EEXIST.
Les montages et les systèmes de fichiers ne sont pas des objets
suppressibles, donc si on essaie de créer une marque de montage
ou de système de fichiers avec l'attribut FAN_MARK_EVICTABLE,
une erreur EINVAL se produira. Par exemple, les marques d'inœud
peuvent être utilisées en combinaison avec les marques de mon-
tage pour réduire la quantité d'événements issus d'endroits sans
intérêt. L'écouteur d'événements lit les événements, vérifie si
le chemin indiqué dans l'événement est digne d'intérêt et si ce
n’est pas le cas, il positionne une marque avec un masque ignore
sur le répertoire. Les marques d'inœud suppressibles permettent
d'utiliser cette méthode pour un grand nombre de répertoires
sans l'inconvénient de l’épinglage de tous les inœuds et d’épui-
ser la mémoire du système.
mask définit les événements à écouter (ou à ignorer). C’est un masque
de bits constitué par les valeurs suivantes :
FAN_ACCESS
Créer un événement quand un fichier ou un répertoire (mais
consultez BOGUES) est accédé (en lecture).
FAN_MODIFY
Créer un événement quand un fichier est modifié (en écriture).
FAN_CLOSE_WRITE
Créer un événement quand un fichier modifiable en écriture est
fermé.
FAN_CLOSE_NOWRITE
Créer un événement quand soit un fichier, soit un répertoire, en
lecture seule, est fermé.
FAN_OPEN
Créer un événement quand soit un fichier, soit un répertoire est
ouvert.
FAN_OPEN_EXEC (depuis Linux 5.0)
Créer un événement quand un fichier est ouvert pour être exé-
cuté. Voir les NOTES pour plus de détails.
FAN_ATTRIB (depuis Linux 5.1)
Créer un événement quand les métadonnées d'un fichier ou d'un
répertoire ont changé. Un groupe fanotify qui identifie les ob-
jets de système de fichiers par des identificateurs de fichier
est nécessaire.
FAN_CREATE (depuis Linux 5.1)
Créer un événement quand un fichier ou un répertoire a été créé
dans un répertoire parent marqué. Un groupe fanotify qui identi-
fie les objets de système de fichiers par des identificateurs de
fichier est nécessaire.
FAN_DELETE (depuis Linux 5.1)
Créer un événement quand un fichier ou un répertoire a été ef-
facé d'un répertoire parent marqué. Un groupe fanotify qui iden-
tifie les objets de système de fichiers par des identificateurs
de fichier est nécessaire.
FAN_DELETE_SELF (depuis Linux 5.1)
Créer un événement quand un fichier, ou même un répertoire, mar-
qué est effacé. Un groupe fanotify qui identifie les objets de
système de fichiers par des identificateurs de fichier est né-
cessaire.
FAN_FS_ERROR (depuis Linux 5.16)
Créer un événement quand une erreur du système de fichiers
conduisant à une incohérence des métadonnées du système de fi-
chiers est détectée. Un enregistrement supplémentaire de type
FAN_EVENT_INFO_TYPE_ERROR est renvoyé pour chaque événement du
tampon de lecture. Un groupe fanotify qui identifie les objets
de système de fichiers par des identificateurs de fichier est
nécessaire.
Les événements de ce type dépendent de la prise en charge par le
système de fichiers sous-jacent. À l'heure où nous écrivons,
seul le système de fichiers ext4 signale les événements
FAN_FS_ERROR.
Voir fanotify(7) pour des détails supplémentaires.
FAN_MOVED_FROM (depuis Linux 5.1)
Créer un événement quand un fichier ou un répertoire a été dé-
placé depuis un répertoire parent marqué. Un groupe fanotify qui
identifie les objets de système de fichiers par des identifica-
teurs de fichier est nécessaire.
FAN_MOVED_TO (depuis Linux 5.1)
Créer un événement quand un fichier ou un répertoire est déplacé
vers un répertoire parent marqué. Un groupe fanotify qui identi-
fie les objets de système de fichiers par des identificateurs de
fichier est nécessaire.
FAN_RENAME (depuis Linux 5.17)
Cet événement contient les mêmes informations que celles four-
nies par les événements FAN_MOVED_FROM et FAN_MOVED_TO mais il
est représenté par un seul événement ayant jusqu'à deux enregis-
trements. Un groupe fanotify qui identifie les objets de système
de fichiers par des identificateurs de fichiers est nécessaire.
Si l'objet de système de fichiers à marquer n'est pas un réper-
toire, l'erreur ENOTDIR sera générée.
FAN_MOVE_SELF (depuis Linux 5.1)
Créer un événement quand un fichier, ou même un répertoire, mar-
qué a été déplacé. Un groupe fanotify qui identifie les objets
de système de fichiers par des identificateurs de fichier est
nécessaire.
FAN_OPEN_PERM
Créer un événement quand une permission d’ouvrir un fichier ou
un répertoire est demandée. Un descripteur de fichier fanotify
créé avec FAN_CLASS_PRE_CONTENT ou FAN_CLASS_CONTENT est néces-
saire.
FAN_OPEN_EXEC_PERM (depuis Linux 5.0)
Créer un événement quand une permission d’ouvrir un fichier en
exécution est demandée. Un descripteur de fichier fanotify créé
avec FAN_CLASS_PRE_CONTENT ou FAN_CLASS_CONTENT est nécessaire.
Voir les NOTES pour des détails supplémentaires.
FAN_ACCESS_PERM
Créer un événement quand une permission de lire un fichier ou un
répertoire est demandée. Un descripteur de fichier fanotify créé
avec FAN_CLASS_PRE_CONTENT ou FAN_CLASS_CONTENT est nécessaire.
FAN_ONDIR
Créer des événements pour les répertoires — par exemple quand
opendir(3), readdir(3) (mais voir BOGUES) et closedir(3) sont
appelés. Sans cet attribut, les événements ne sont créés que
pour les fichiers. Dans le contexte des événements d’entrée de
répertoire tels que FAN_CREATE, FAN_DELETE, FAN_MOVED_FROM et
FAN_MOVED_TO, il est nécessaire d'indiquer le drapeau FAN_ONDIR
afin de créer des événements quand des entrées de sous-réper-
toire sont modifiées (à savoir mkdir(2) ou rmdir(2)).
FAN_EVENT_ON_CHILD
Des événements pour les enfants directs des répertoires marqués
seront créés. L’attribut n’a pas d’effet lors du marquage de
montages ou de systèmes de fichiers. Remarquez qu’aucun événe-
ment n’est créé pour les enfants des sous-répertoires des réper-
toires marqués. De manière plus spécifique, les événements de
modification d’entrée d'un répertoire FAN_CREATE, FAN_DELETE,
FAN_MOVED_FROM et FAN_MOVED_TO ne sont pas générés pour des mo-
difications effectuées dans les sous-répertoires de répertoires
marqués. Remarquez que les événements FAN_DELETE_SELF et
FAN_MOVE_SELF ne sont pas générés pour les enfants de réper-
toires marqués. Pour surveiller des arborescences complètes de
répertoires, le montage ou le système de fichiers adéquat doit
être marqué.
Les valeurs composées suivantes sont définies :
FAN_CLOSE
Un fichier est fermé (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE).
FAN_MOVE
Un fichier ou un répertoire a été déplacé (FAN_MO-
VED_FROM|FAN_MOVED_TO).
L’objet de système de fichiers à marquer est déterminé par le descrip-
teur de fichier dirfd et le chemin indiqué dans pathname :
• si pathname est NULL, dirfd définit l’objet de système de fichiers à
marquer ;
• si pathname est NULL et que dirfd prend la valeur spéciale AT_FDCWD,
le répertoire de travail actuel est à marquer ;
• si pathname est absolu, il définit l’objet de système de fichiers à
marquer et dirfd est ignoré ;
• si pathname est relatif et que dirfd n’a pas la valeur AT_FDCWD,
alors l’objet de système de fichiers à marquer est déterminé en in-
terprétant pathname comme relatif au répertoire référencé par
dirfd ;
• si pathname est relatif et que dirfd a la valeur AT_FDCWD, alors
l’objet de système de fichiers à marquer est déterminé en interpré-
tant pathname par rapport au répertoire de travail actuel (voir ope-
nat(2) pour une explication sur la raison d'être du paramètre
dirfd).
VALEUR RENVOYÉE
S'il réussit, fanotify_mark() renvoie 0. En cas d'erreur, il renvoie -1
et remplit errno avec la valeur d'erreur.
ERREURS
EBADF Un descripteur de fichier incorrect a été passé dans fano-
tify_fd.
EBADF pathname est relatif mais dirfd n'est ni AT_FDWCD ni un descrip-
teur de fichier valable.
EEXIST L'objet de système de fichiers indiqué par dirfd et pathname
comporte une marque mise à jour sans l'attribut FAN_MARK_EVIC-
TABLE et l'utilisateur a essayé de mettre à jour la marque avec
l'attribut FAN_MARK_EVICTABLE.
EEXIST L'objet de système de fichiers indiqué par dirfd et pathname
comporte une marque mise à jour avec l'attribut FAN_MARK_IGNORE
et l'utilisateur a essayé de mettre à jour la marque avec l'at-
tribut FAN_MARK_IGNORED_MASK.
EEXIST L'objet de système de fichiers indiqué par dirfd et pathname
comporte une marque mise à jour avec les attributs
FAN_MARK_IGNORE et FAN_MARK_IGNORED_SURV_MODIFY et l'utilisateur
a essayé de mettre à jour la marque avec l'attribut
FAN_MARK_IGNORE.
EINVAL Une valeur incorrecte a été passée dans flags ou mask, ou fano-
tify_fd n'était pas un descripteur de fichier fanotify.
EINVAL Le descripteur de fichier fanotify a été ouvert avec
FAN_CLASS_NOTIF ou le groupe fanotify identifie des systèmes de
fichiers par des identificateurs de fichier et le masque
contient un attribut pour des événements de permission
(FAN_OPEN_PERM ou FAN_ACCESS_PERM).
EINVAL Le groupe a été initialisé sans FAN_REPORT_FID mais un ou plu-
sieurs types d'événements indiqués dans mask en ont besoin.
EINVAL flags contient FAN_MARK_IGNORE et soit FAN_MARK_MOUNT ou
FAN_MARK_FILESYSTEM, mais il ne contient pas FAN_MARK_IGNO-
RED_SURV_MODIFY.
EISDIR flags contient FAN_MARK_IGNORE mais pas FAN_MARK_IGNO-
RED_SURV_MODIFY, et dirfd et pathname indiquent un répertoire.
ENODEV Le système de fichiers indiqué par dirfd et pathname n'est asso-
cié à aucun système de fichiers prenant en charge fsid (comme
fuse(4)). tmpfs(5) ne gérait pas fsid avant Linux 5.13. Cette
erreur ne peut être renvoyée qu'avec un groupe fanotify qui
identifie les objets de système de fichiers par des identifica-
teurs de fichier.
ENOENT L’objet de système de fichiers indiqué par dirfd et pathname
n’existe pas. Cette erreur survient aussi lors d’une tentative
de supprimer une marque d’un objet qui n’est pas marqué.
ENOMEM La mémoire nécessaire n’a pas pu être allouée.
ENOSPC Le nombre de marques pour cet utilisateur dépasse la limite et
l’attribut FAN_UNLIMITED_MARKS n’était pas indiqué quand le des-
cripteur de fichier fanotify a été créé avec fanotify_init(2).
Voir fanotify(7) pour des détails sur cette limite.
ENOSYS Ce noyau n’implémente pas fanotify_mark(). L’interface de pro-
grammation fanotify n'est disponible que si le noyau a été
configuré avec CONFIG_FANOTIFY.
ENOTDIR
flags contient FAN_MARK_ONLYDIR, et dirfd et pathname n’in-
diquent pas de répertoire.
ENOTDIR
mask contient FAN_RENAME et dirfd et pathname n’indiquent pas de
répertoire.
ENOTDIR
flags contient FAN_MARK_IGNORE ou le groupe fanotify a été ini-
tialisé avec l'attribut FAN_REPORT_TARGET_FID et mask contient
des événements de modification d'entrée de répertoire (comme
FAN_CREATE, FAN_DELETE), ou bien des attributs d'événements de
répertoire (comme FAN_ONDIR, FAN_EVENT_ON_CHILD), et dirfd et
pathname n'indiquent pas de répertoire.
EOPNOTSUPP
L'objet indiqué par pathname est associé à un système de fi-
chiers qui ne gère pas l'encodage d’identificateurs de fichier.
Cette erreur ne peut être renvoyée que lorsqu'un groupe fanotify
identifie les objets de systèmes de fichiers par des identifica-
teurs de fichier.
EPERM L’opération n’est pas permise car l’appelant n’a pas la capacité
requise.
EXDEV Le système de fichiers indiqué par pathname se trouve dans un
sous-volume de système de fichiers (comme btrfs(5)) qui utilise
un fsid différent de son superbloc racine. Cette erreur ne peut
être renvoyée que par un groupe fanotify qui identifie les ob-
jets de système de fichiers par des identificateurs de fichier.
VERSIONS
fanotify_mark() a été introduit dans Linux 2.6.36 et activé dans Li-
nux 2.6.37.
STANDARDS
Cet appel système est spécifique à Linux.
NOTES
FAN_OPEN_EXEC et FAN_OPEN_EXEC_PERM
Quand on utilise FAN_OPEN_EXEC ou FAN_OPEN_EXEC_PERM dans le mask, des
événements de ces types ne seront renvoyés que lorsque l'exécution di-
recte d'un programme se produit. Plus particulièrement, cela signifie
que les événements de ces types seront créés pour les fichiers ouverts
en utilisant execve(2), execveat(2) ou uselib(2). Les événements de ces
types n'apparaîtront pas quand un interpréteur est passé pour interpré-
tation d'un fichier (ou s'il est en cours de lecture).
De plus, si une marque a aussi été placée sur l'éditeur de liens dyna-
miques de Linux, un utilisateur doit s'attendre aussi à recevoir un
événement associé quand un objet ELF a été ouvert avec succès en utili-
sant execve(2) ou execveat(2).
Par exemple, si le binaire ELF suivant devait être appelé et si une
marque FAN_OPEN_EXEC a été placée sur / :
$ /bin/echo toto
Dans ce cas, l'application à l'écoute devrait recevoir des événements
FAN_OPEN_EXEC, respectivement pour le binaire ELF et pour l'interpré-
teur :
/bin/echo
/lib64/ld-linux-x86-64.so.2
BOGUES
Les bogues suivants étaient présents avant Linux 3.16 :
• si flags contient FAN_MARK_FLUSH, dirfd et pathname doivent indiquer
un objet de système de fichiers valable, même si cet objet n’est pas
utilisé.
• readdir(2) ne crée pas d’événement FAN_ACCESS ;
• si fanotify_mark() est appelé avec FAN_MARK_FLUSH, les valeurs in-
correctes de flags ne sont pas vérifiées.
VOIR AUSSI
fanotify_init(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_mark(2)
Generated by dwww version 1.15 on Sat Jun 29 01:47:40 CEST 2024.