1. Manuals
  2. Tumbleweed
  3. man-pages-fr
  4. fanotify_mark(2)

Scroll to navigation

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 path);

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.

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.
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.
Remove either all marks for filesystems, all marks for mounts, or all marks for directories and files from the fanotify group. If flags contains FAN_MARK_MOUNT, all marks for mounts are removed from the group. If flags contains FAN_MARK_FILESYSTEM, all marks for filesystems are removed from the group. Otherwise, all marks for directories and files are removed. No flag other than, and at most one of, the flags FAN_MARK_MNTNS, FAN_MARK_MOUNT, or FAN_MARK_FILESYSTEM can be used in conjunction with FAN_MARK_FLUSH. mask is ignored.

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).

If path is a symbolic link, mark the link itself, rather than the file to which it refers. (By default, fanotify_mark() dereferences path if it is a symbolic link.)
Si l’objet de système de fichiers à marquer n’est pas un répertoire, l’erreur ENOTDIR surviendra.
Mark the mount namespace specified by path. If path does not represent a mount namespace (e.g. /proc/pid/ns/mnt), the call fails with the error EINVAL. An fanotify group that was initialized with flag FAN_REPORT_MNT is required.
Mark the mount specified by path. If path is not itself a mount point, the mount containing path will be marked. All directories, subdirectories, and the contained files of the mount will be monitored. The events which require that filesystem objects are identified by file handles, such as FAN_CREATE, FAN_ATTRIB, FAN_MOVE, and FAN_DELETE_SELF, cannot be provided as a mask when flags contains FAN_MARK_MOUNT. Attempting to do so will result in the error EINVAL being returned. Use of this flag requires the CAP_SYS_ADMIN capability.
Mark the filesystem specified by path. The filesystem containing path will be marked. All the contained files and directories of the filesystem from any mount point will be monitored. Use of this flag requires the CAP_SYS_ADMIN capability.
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.
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.
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.
C'est un synonyme de (FAN_MARK_IGNORE|FAN_MARK_IGNORED_SURV_MODIFY).
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 :

Créer un événement quand un fichier ou un répertoire (mais consultez BOGUES) est accédé (en lecture).
Créer un événement quand un fichier est modifié (en écriture).
Créer un événement quand un fichier modifiable en écriture est fermé.
Créer un événement quand soit un fichier, soit un répertoire, en lecture seule, est fermé.
Créer un événement quand soit un fichier, soit un répertoire est ouvert.
Créer un événement quand un fichier est ouvert pour être exécuté. Voir les NOTES pour plus de détails.
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.
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.
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.
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.
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.
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.
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.
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.
Create an event when a mount was attached to or detached from a marked mount namespace, respectively. An attempt to set this flag on an inode, mount, or filesystem mark will result in the error EINVAL. An fanotify group that was initialized with flag FAN_REPORT_MNT and the mark flag FAN_MARK_MNTNS are required. An additional information record of type FAN_EVENT_INFO_TYPE_MNT is returned with the event. See fanotify(7) for additional details.
Create an event when a filesystem error leading to inconsistent filesystem metadata is detected. An additional information record of type FAN_EVENT_INFO_TYPE_ERROR is returned for each event in the read buffer. An fanotify group that identifies filesystem objects by file handles is required. Events of such type are dependent on support from the underlying filesystem. At the time of writing, only the ext4 filesystem reports FAN_FS_ERROR events. See fanotify(7) for additional details.
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.
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.
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.
Create an event before read or write access to a file range, that provides an opportunity for the event listener to modify the content of the file before access to the content in the specified range. An additional information record of type FAN_EVENT_INFO_TYPE_RANGE is returned for each event in the read buffer. An fanotify file descriptor created with FAN_CLASS_PRE_CONTENT is required.
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)).
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 :

Un fichier est fermé (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE).
Un fichier ou un répertoire a été déplacé (FAN_MOVED_FROM|FAN_MOVED_TO).

The filesystem object to be marked is determined by the file descriptor dirfd and the pathname specified in path:

  • If path is NULL, dirfd defines the filesystem object to be marked.
  • If path is NULL, and dirfd takes the special value AT_FDCWD, the current working directory is to be marked.
  • si path est absolu, il définit l’objet de système de fichiers à marquer et dirfd est ignoré ;
  • If path is relative, and dirfd does not have the value AT_FDCWD, then the filesystem object to be marked is determined by interpreting path relative the directory referred to by dirfd.
  • If path is relative, and dirfd has the value AT_FDCWD, then the filesystem object to be marked is determined by interpreting path relative to the current working directory. (See openat(2) for an explanation of why the dirfd argument is useful.)

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

Un descripteur de fichier incorrect a été passé dans fanotify_fd.
path est relatif mais dirfd n'est ni AT_FDWCD ni un descripteur de fichier valable.
The filesystem object indicated by dirfd and path has a mark that was updated without the FAN_MARK_EVICTABLE flag, and the user attempted to update the mark with FAN_MARK_EVICTABLE flag.
The filesystem object indicated by dirfd and path has a mark that was updated with the FAN_MARK_IGNORE flag, and the user attempted to update the mark with FAN_MARK_IGNORED_MASK flag.
The filesystem object indicated by dirfd and path has a mark that was updated with the FAN_MARK_IGNORE and FAN_MARK_IGNORED_SURV_MODIFY flags, and the user attempted to update the mark only with FAN_MARK_IGNORE flag.
Une valeur incorrecte a été passée dans flags ou mask, ou fanotify_fd n'était pas un descripteur de fichier fanotify.
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).
Le groupe a été initialisé sans FAN_REPORT_FID mais un ou plusieurs types d'événements indiqués dans mask en ont besoin.
flags contient FAN_MARK_IGNORE et soit FAN_MARK_MOUNT ou FAN_MARK_FILESYSTEM, mais il ne contient pas FAN_MARK_IGNORED_SURV_MODIFY.
flags contains FAN_MARK_IGNORE, but does not contain FAN_MARK_IGNORED_SURV_MODIFY, and dirfd and path specify a directory.
The filesystem object indicated by dirfd and path is associated with a filesystem that reports zero fsid (e.g., fuse(4)). This error can be returned only with an fanotify group that identifies filesystem objects by file handles. Since Linux 6.8, this error can be returned when trying to add a mount or filesystem mark.
The filesystem object indicated by dirfd and path does not exist. This error also occurs when trying to remove a mark from an object which is not marked.
La mémoire nécessaire n’a pas pu être allouée.
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.
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.
flags contains FAN_MARK_ONLYDIR, and dirfd and path do not specify a directory.
mask contains FAN_RENAME, and dirfd and path do not specify a directory.
flags contains FAN_MARK_IGNORE, or the fanotify group was initialized with flag FAN_REPORT_TARGET_FID, and mask contains directory entry modification events (e.g., FAN_CREATE, FAN_DELETE), or directory event flags (e.g., FAN_ONDIR, FAN_EVENT_ON_CHILD), and dirfd and path do not specify a directory.
The object indicated by path is associated with a filesystem that does not support the encoding of file handles. This error can be returned only with an fanotify group that identifies filesystem objects by file handles. Calling name_to_handle_at(2) with the flag AT_HANDLE_FID (since Linux 6.5) can be used as a test to check if a filesystem supports reporting events with file handles.
L’opération n’est pas permise car l’appelant n’a pas la capacité requise.
The filesystem object indicated by path resides within a filesystem subvolume (e.g., btrfs(5)) which uses a different fsid than its root superblock. This error can be returned only with an fanotify group that identifies filesystem objects by file handles. Since Linux 6.8, this error will be returned when trying to add a mount or filesystem mark on a subvolume, when trying to add inode marks in different subvolumes, or when trying to add inode marks in a btrfs(5) subvolume and in another filesystem. Since Linux 6.8, this error will also be returned when trying to add marks in different filesystems, where one of the filesystems reports zero fsid (e.g., fuse(4)).

STANDARDS

Linux.

HISTORIQUE

Linux 2.6.37.

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 :

  • If flags contains FAN_MARK_FLUSH, dirfd, and path must specify a valid filesystem object, even though this object is not used.
  • 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 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.

17 mai 2025 Pages du manuel de Linux (non publiées)