Provided by: manpages-fr-dev_4.18.1-1_all 
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 fanotify(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 fanotify_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 montages 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 attributs 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épertoire, 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 systèmes de fichiers
soient identifiés par des identificateurs de fichier, tels que FAN_CREATE,
FAN_ATTRIB, FAN_MOVE et FAN_DELETE_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'importe 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, positionner 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 parent. 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épertoires ne seront pas ignorés. Si l'attribut
FAN_EVENT_ON_CHILD est positionné avec FAN_MARK_IGNORE, les événements sur les
enfants 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éation 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'attribut 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 modifié.
C'est pourquoi l'attribut FAN_MARK_IGNORE exige l'attribut
FAN_MARK_IGNORED_SURV_MODIFY sur une marque d'inœud de montage, 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é positionné. 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_MODIFY).
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 pression 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 utiliser 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 montage 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’épuiser 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 objets 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 identifie 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é effacé d'un répertoire
parent marqué. Un groupe fanotify qui identifie 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, marqué 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 fichiers 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 identificateurs 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 identifie 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 fournies par les
événements FAN_MOVED_FROM et FAN_MOVED_TO mais il est représenté par un seul
événement ayant jusqu'à deux enregistrements. 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épertoire, 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, marqué 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écessaire.
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épertoire 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énement n’est créé pour les enfants des sous-répertoires des
répertoires 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 modifications 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épertoires 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_MOVED_FROM|FAN_MOVED_TO).
L’objet de système de fichiers à marquer est déterminé par le descripteur 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 interpré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 openat(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 fanotify_fd.
EBADF pathname est relatif mais dirfd n'est ni AT_FDWCD ni un descripteur 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_EVICTABLE 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'attribut 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 fanotify_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 plusieurs 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_IGNORED_SURV_MODIFY.
EISDIR flags contient FAN_MARK_IGNORE mais pas FAN_MARK_IGNORED_SURV_MODIFY, et dirfd et
pathname indiquent un répertoire.
ENODEV Le système de fichiers indiqué par dirfd et pathname n'est associé à 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 identificateurs 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 descripteur 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 programmation 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’indiquent 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é initialisé 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 fichiers 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
identificateurs 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 objets de système de fichiers par des identificateurs de fichier.
VERSIONS
fanotify_mark() a été introduit dans Linux 2.6.36 et activé dans Linux 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 directe 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 dynamiques de Linux, un
utilisateur doit s'attendre aussi à recevoir un événement associé quand un objet ELF a été
ouvert avec succès en utilisant 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 incorrectes 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 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⟩.