FANOTIFY_MARK(2) Manuel du programmeur Linux FANOTIFY_MARK(2)

fanotify_mark - Ajouter, supprimer ou modifier une marque fanotify sur un objet de système de fichiers

#include <sys/fanotify.h>
int fanotify_mark(int fanotify_fd, unsigned int flags,
                  uint64_t mask, int dirfd, const char *pathname);

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

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).
Si l’objet de système de fichiers à marquer n’est pas un répertoire, l’erreur ENOTDIR surviendra.
Mark the mount specified by pathname. If pathname is not itself a mount point, the mount containing pathname 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.
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.
Les événements dans mask seront ajoutés ou supprimés du masque ignore.
Le masque ignore survivra aux événements de modification. Si cet attribut n’est pas défini, le masque ignore est effacé quand un événement de modification survient pour le fichier ou répertoire ignorés.

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 systèmes 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 systèmes 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 systèmes 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 systèmes 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 systèmes 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 systèmes 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é a été déplacé. Un groupe fanotify qui identifie les systèmes de fichiers par des identificateurs de fichier est nécessaire.
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.
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).

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 ;
  • If pathname is relative, and dirfd has the value AT_FDCWD, then the filesystem object to be marked is determined by interpreting pathname relative to the current working directory. (See openat(2) for an explanation of why the dirfd argument is useful.)

S'il réussit, fanotify_mark() renvoie 0. En cas d'erreur, il renvoie -1 et remplit errno avec la valeur d'erreur.

Un descripteur de fichier incorrect a été passé dans fanotify_fd.
pathname is relative but dirfd is neither AT_FDCWD nor a valid file descriptor.
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 système de fichiers indiqué par pathname n'est associé à aucun système de fichiers prenant en charge fsid (comme tmpfs(5)). Cette erreur ne peut être renvoyée qu'avec un groupe fanotify qui identifie les systèmes de fichiers par des identificateurs de fichier.
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é.
La mémoire nécessaire n’a pas pu être allouée.
Le nombre de marques dépasse la limite de 8192 et l’attribut FAN_UNLIMITED_MARKS n’était pas indiqué quand le descripteur de fichier fanotify a été créé avec fanotify_init(2).
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 contient FAN_MARK_ONLYDIR, et dirfd et pathname n’indiquent pas de répertoire.
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 systèmes de fichiers par des identificateurs de fichier.
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 systèmes de fichiers par des identificateurs de fichier.

fanotify_mark() a été introduit dans la version 2.6.36 du noyau Linux et activé dans la version 2.6.37.

Cet appel système est spécifique à Linux.

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

Les bogues suivants étaient présents dans les noyaux Linux avant la version 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.

fanotify_init(2), fanotify(7)

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

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.

27 août 2021 Linux