fanotify_mark(2) System Calls Manual fanotify_mark(2) NOM fanotify_mark - Ajouter, supprimer ou modifier une marque fanotify sur un objet de systeme de fichiers BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include int fanotify_mark(int fanotify_fd, unsigned int flags, uint64_t mask, int dirfd, const char *_Nullable pathname); DESCRIPTION Pour un apercu de l'interface de programmation fanotify, consultez fanotify(7). fanotify_mark() ajoute, supprime ou modifie une marque fanotify sur un objet de systeme de fichiers. L'appelant doit avoir le droit de lecture sur l'objet de systeme de fichiers a marquer. L'argument fanotify_fd est un descripteur de fichier renvoye par fanotify_init(2). flags est un masque de bits decrivant la modification a realiser. Il doit contenir exactement une des valeurs suivantes. FAN_MARK_ADD Les evenements dans mask seront ajoutes au masque de marque (ou au masque ignore). mask doit etre non vide sinon l'erreur EINVAL surviendra. FAN_MARK_REMOVE Les evenements dans l'argument mask seront supprimes du masque de marque (ou du masque ignore). mask doit etre non vide sinon l'erreur EINVAL surviendra. FAN_MARK_FLUSH Supprimer toutes les marques de systemes de fichiers, de montages ou de repertoires et fichiers du groupe fanotify. Si flags contient FAN_MARK_MOUNT, toutes les marques de montage seront supprimees du groupe. Si flags contient FAN_MARK_FILESYSTEM, toutes les marques de systemes de fichiers seront supprimees du groupe. Sinon, toutes les marques des repertoires et fichiers seront supprimees. Aucun autre attribut et au plus un des attributs FAN_MARK_MOUNT ou FAN_MARK_FILESYSTEM peut etre utilise avec FAN_MARK_FLUSH. mask est ignore. Si aucune des valeurs precedentes n'est indiquee, ou si plus d'une est indiquee, l'appel echoue avec l'erreur EINVAL. De plus, zero ou plus des valeurs suivantes peuvent etre incluses dans flags (avec une operation OU bit a bit). FAN_MARK_DONT_FOLLOW Si pathname est un lien symbolique, marquer le lien lui-meme, plutot que le fichier pointe (par defaut, fanotify_mark() dereference pathname si c'est un lien symbolique). FAN_MARK_ONLYDIR Si l'objet de systeme de fichiers a marquer n'est pas un repertoire, l'erreur ENOTDIR surviendra. FAN_MARK_MOUNT Marquer le point de montage indique par pathname. Si pathname n'est pas un point de montage lui-meme, le point de montage contenant pathname sera marque. Tous les repertoires, sous-repertoires et fichiers contenus dans le point de montage seront surveilles. Les evenements qui exigent que les objets de systemes de fichiers soient identifies par des identificateurs de fichier, tels que FAN_CREATE, FAN_ATTRIB, FAN_MOVE et FAN_DELETE_SELF, ne peuvent pas etre fournis comme mask quand flags contient FAN_MARK_MOUNT. Une telle tentative renverra l'erreur EINVAL. L'utilisation de cet attribut exige la capacite CAP_SYS_ADMIN. FAN_MARK_FILESYSTEM (depuis Linux 4.20) Marquer le systeme de fichiers indique par pathname. Le systeme de fichiers contenant pathname sera marque. Tous les fichiers et repertoires contenus dans le systeme de fichiers issus de n'importe quel point de montage seront surveilles. L'utilisation de cet attribut exige la capacite CAP_SYS_ADMIN. FAN_MARK_IGNORED_MASK Les evenements de mask ne seront pas ajoutes ou supprimes 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 evenements positionnes dans le masque ignore n'est pas defini et depend 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 repertoire parent ne ferait pas ignorer les evenements sur le fichier, meme avec l'attribut FAN_EVENT_ON_CHILD dans le masque de marquage du repertoire parent. Quand le masque ignore est mis a jour avec l'attribut FAN_MARK_IGNORED_MASK sur une marque precedemment mise a jour avec l'attribut FAN_MARK_IGNORE, la mise a jour echoue avec l'erreur EEXIST. FAN_MARK_IGNORE (depuis Linux 6.0) Cet attribut a le meme effet que de positionner l'attribut FAN_MARK_IGNORED_MASK. Les evenements du mask seront ajoutes ou supprimes du masque ignore. Contrairement a l'attribut FAN_MARK_IGNORED_MASK, cet attribut a egalement 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 positionne avec FAN_MARK_IGNORE, les evenements sur les repertoires ne seront pas ignores. Si l'attribut FAN_EVENT_ON_CHILD est positionne avec FAN_MARK_IGNORE, les evenements sur les enfants seront ignores. Par exemple, une marque sur un repertoire associe a un masque avec l'evenement FAN_CREATE et l'attribut FAN_ONDIR et un masque ignore avec un evenement FAN_CREATE et sans l'attribut FAN_ONDIR ne gardera que les evenements de creation de sous-repertoires. Lors de l'utilisation de l'attribut FAN_MARK_IGNORE pour ajouter a un masque ignore une marque de montage, de systeme de fichiers ou d'inoeud de repertoire, l'attribut FAN_MARK_IGNORED_SURV_MODIFY doit etre indique. Un oubli de faire cela donne une erreur EINVAL ou EISDIR. FAN_MARK_IGNORED_SURV_MODIFY Le masque ignore survivra aux evenements de modification. Si cet attribut n'est pas positionne, le masque ignore est efface quand un evenement de modification se produit sur l'objet marque. Ne pas utiliser cet attribut se fait generalement pour supprimer des evenements (comme FAN_OPEN) sur un fichier specifique, jusqu'a ce que le contenu de ce dernier ne soit modifie. Il est beaucoup moins utile de supprimer des evenements sur tout un systeme de fichiers ou un montage, ou bien sur tous les fichiers d'un repertoire, jusqu'a ce qu'un contenu de fichier ne soit modifie. C'est pourquoi l'attribut FAN_MARK_IGNORE exige l'attribut FAN_MARK_IGNORED_SURV_MODIFY sur une marque d'inoeud de montage, de systeme de fichiers ou de repertoire. Cet attribut ne peut pas etre supprime d'une marque une fois qu'il a ete positionne. Quand le masque ignore est mis a jour sans cet attribut sur une marque precedemment mise a jour avec les attributs FAN_MARK_IGNORE et FAN_MARK_IGNORED_SURV_MODIFY, la mise a jour echoue 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'inoeud est creee avec cet attribut, l'objet inoeud ne sera pas associe au cache de l'inoeud, permettant ainsi a l'objet inoeud d'etre supprime du cache d'inoeud quand la pression sur la memoire du systeme est elevee. La suppression de l'objet inoeud provoque aussi la perte de la marque suppressible. Quand le masque d'un inoeud suppressible est mis a jour sans utiliser l'attribut FAN_MARK_EVICATBLE, l'inoeud marque est epingle dans le cache d'inoeuds et la marque n'est plus suppressible. Quand le masque d'une marque d'inoeud non suppressible est mis a jour avec l'attribut FAN_MARK_EVICTABLE, la marque d'inoeud reste non suppressible et la mise a jour echoue avec l'erreur EEXIST. Les montages et les systemes de fichiers ne sont pas des objets suppressibles, donc si on essaie de creer une marque de montage ou de systeme de fichiers avec l'attribut FAN_MARK_EVICTABLE, une erreur EINVAL se produira. Par exemple, les marques d'inoeud peuvent etre utilisees en combinaison avec les marques de montage pour reduire la quantite d'evenements issus d'endroits sans interet. L'ecouteur d'evenements lit les evenements, verifie si le chemin indique dans l'evenement est digne d'interet et si ce n'est pas le cas, il positionne une marque avec un masque ignore sur le repertoire. Les marques d'inoeud suppressibles permettent d'utiliser cette methode pour un grand nombre de repertoires sans l'inconvenient de l'epinglage de tous les inoeuds et d'epuiser la memoire du systeme. mask definit les evenements a ecouter (ou a ignorer). C'est un masque de bits constitue par les valeurs suivantes : FAN_ACCESS Creer un evenement quand un fichier ou un repertoire (mais consultez BOGUES) est accede (en lecture). FAN_MODIFY Creer un evenement quand un fichier est modifie (en ecriture). FAN_CLOSE_WRITE Creer un evenement quand un fichier modifiable en ecriture est ferme. FAN_CLOSE_NOWRITE Creer un evenement quand soit un fichier, soit un repertoire, en lecture seule, est ferme. FAN_OPEN Creer un evenement quand soit un fichier, soit un repertoire est ouvert. FAN_OPEN_EXEC (depuis Linux 5.0) Creer un evenement quand un fichier est ouvert pour etre execute. Voir les NOTES pour plus de details. FAN_ATTRIB (depuis Linux 5.1) Creer un evenement quand les metadonnees d'un fichier ou d'un repertoire ont change. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier est necessaire. FAN_CREATE (depuis Linux 5.1) Creer un evenement quand un fichier ou un repertoire a ete cree dans un repertoire parent marque. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier est necessaire. FAN_DELETE (depuis Linux 5.1) Creer un evenement quand un fichier ou un repertoire a ete efface d'un repertoire parent marque. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier est necessaire. FAN_DELETE_SELF (depuis Linux 5.1) Creer un evenement quand un fichier, ou meme un repertoire, marque est efface. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier est necessaire. FAN_FS_ERROR (depuis Linux 5.16) Creer un evenement quand une erreur du systeme de fichiers conduisant a une incoherence des metadonnees du systeme de fichiers est detectee. Un enregistrement supplementaire de type FAN_EVENT_INFO_TYPE_ERROR est renvoye pour chaque evenement du tampon de lecture. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier est necessaire. Les evenements de ce type dependent de la prise en charge par le systeme de fichiers sous-jacent. A l'heure ou nous ecrivons, seul le systeme de fichiers ext4 signale les evenements FAN_FS_ERROR. Voir fanotify(7) pour des details supplementaires. FAN_MOVED_FROM (depuis Linux 5.1) Creer un evenement quand un fichier ou un repertoire a ete deplace depuis un repertoire parent marque. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier est necessaire. FAN_MOVED_TO (depuis Linux 5.1) Creer un evenement quand un fichier ou un repertoire est deplace vers un repertoire parent marque. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier est necessaire. FAN_RENAME (depuis Linux 5.17) Cet evenement contient les memes informations que celles fournies par les evenements FAN_MOVED_FROM et FAN_MOVED_TO mais il est represente par un seul evenement ayant jusqu'a deux enregistrements. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichiers est necessaire. Si l'objet de systeme de fichiers a marquer n'est pas un repertoire, l'erreur ENOTDIR sera generee. FAN_MOVE_SELF (depuis Linux 5.1) Creer un evenement quand un fichier, ou meme un repertoire, marque a ete deplace. Un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier est necessaire. FAN_OPEN_PERM Creer un evenement quand une permission d'ouvrir un fichier ou un repertoire est demandee. Un descripteur de fichier fanotify cree avec FAN_CLASS_PRE_CONTENT ou FAN_CLASS_CONTENT est necessaire. FAN_OPEN_EXEC_PERM (depuis Linux 5.0) Creer un evenement quand une permission d'ouvrir un fichier en execution est demandee. Un descripteur de fichier fanotify cree avec FAN_CLASS_PRE_CONTENT ou FAN_CLASS_CONTENT est necessaire. Voir les NOTES pour des details supplementaires. FAN_ACCESS_PERM Creer un evenement quand une permission de lire un fichier ou un repertoire est demandee. Un descripteur de fichier fanotify cree avec FAN_CLASS_PRE_CONTENT ou FAN_CLASS_CONTENT est necessaire. FAN_ONDIR Creer des evenements pour les repertoires -- par exemple quand opendir(3), readdir(3) (mais voir BOGUES) et closedir(3) sont appeles. Sans cet attribut, les evenements ne sont crees que pour les fichiers. Dans le contexte des evenements d'entree de repertoire tels que FAN_CREATE, FAN_DELETE, FAN_MOVED_FROM et FAN_MOVED_TO, il est necessaire d'indiquer le drapeau FAN_ONDIR afin de creer des evenements quand des entrees de sous-repertoire sont modifiees (a savoir mkdir(2) ou rmdir(2)). FAN_EVENT_ON_CHILD Des evenements pour les enfants directs des repertoires marques seront crees. L'attribut n'a pas d'effet lors du marquage de montages ou de systemes de fichiers. Remarquez qu'aucun evenement n'est cree pour les enfants des sous-repertoires des repertoires marques. De maniere plus specifique, les evenements de modification d'entree d'un repertoire FAN_CREATE, FAN_DELETE, FAN_MOVED_FROM et FAN_MOVED_TO ne sont pas generes pour des modifications effectuees dans les sous-repertoires de repertoires marques. Remarquez que les evenements FAN_DELETE_SELF et FAN_MOVE_SELF ne sont pas generes pour les enfants de repertoires marques. Pour surveiller des arborescences completes de repertoires, le montage ou le systeme de fichiers adequat doit etre marque. Les valeurs composees suivantes sont definies : FAN_CLOSE Un fichier est ferme (FAN_CLOSE_WRITE|FAN_CLOSE_NOWRITE). FAN_MOVE Un fichier ou un repertoire a ete deplace (FAN_MOVED_FROM|FAN_MOVED_TO). L'objet de systeme de fichiers a marquer est determine par le descripteur de fichier dirfd et le chemin indique dans pathname : - si pathname est NULL, dirfd definit l'objet de systeme de fichiers a marquer ; - si pathname est NULL et que dirfd prend la valeur speciale AT_FDCWD, le repertoire de travail actuel est a marquer ; - si pathname est absolu, il definit l'objet de systeme de fichiers a marquer et dirfd est ignore ; - si pathname est relatif et que dirfd n'a pas la valeur AT_FDCWD, alors l'objet de systeme de fichiers a marquer est determine en interpretant pathname comme relatif au repertoire reference par dirfd ; - si pathname est relatif et que dirfd a la valeur AT_FDCWD, alors l'objet de systeme de fichiers a marquer est determine en interpretant pathname par rapport au repertoire de travail actuel (voir openat(2) pour une explication sur la raison d'etre du parametre dirfd). VALEUR RENVOYEE S'il reussit, 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 ete passe dans fanotify_fd. EBADF pathname est relatif mais dirfd n'est ni AT_FDWCD ni un descripteur de fichier valable. EEXIST L'objet de systeme de fichiers indique par dirfd et pathname comporte une marque mise a jour sans l'attribut FAN_MARK_EVICTABLE et l'utilisateur a essaye de mettre a jour la marque avec l'attribut FAN_MARK_EVICTABLE. EEXIST L'objet de systeme de fichiers indique par dirfd et pathname comporte une marque mise a jour avec l'attribut FAN_MARK_IGNORE et l'utilisateur a essaye de mettre a jour la marque avec l'attribut FAN_MARK_IGNORED_MASK. EEXIST L'objet de systeme de fichiers indique par dirfd et pathname comporte une marque mise a jour avec les attributs FAN_MARK_IGNORE et FAN_MARK_IGNORED_SURV_MODIFY et l'utilisateur a essaye de mettre a jour la marque avec l'attribut FAN_MARK_IGNORE. EINVAL Une valeur incorrecte a ete passee dans flags ou mask, ou fanotify_fd n'etait pas un descripteur de fichier fanotify. EINVAL Le descripteur de fichier fanotify a ete ouvert avec FAN_CLASS_NOTIF ou le groupe fanotify identifie des systemes de fichiers par des identificateurs de fichier et le masque contient un attribut pour des evenements de permission (FAN_OPEN_PERM ou FAN_ACCESS_PERM). EINVAL Le groupe a ete initialise sans FAN_REPORT_FID mais un ou plusieurs types d'evenements indiques 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 repertoire. ENODEV Le systeme de fichiers indique par dirfd et pathname n'est associe a aucun systeme de fichiers prenant en charge fsid (comme fuse(4)). tmpfs(5) ne gerait pas fsid avant Linux 5.13. Cette erreur ne peut etre renvoyee qu'avec un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier. ENOENT L'objet de systeme de fichiers indique 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 marque. ENOMEM La memoire necessaire n'a pas pu etre allouee. ENOSPC Le nombre de marques pour cet utilisateur depasse la limite et l'attribut FAN_UNLIMITED_MARKS n'etait pas indique quand le descripteur de fichier fanotify a ete cree avec fanotify_init(2). Voir fanotify(7) pour des details sur cette limite. ENOSYS Ce noyau n'implemente pas fanotify_mark(). L'interface de programmation fanotify n'est disponible que si le noyau a ete configure avec CONFIG_FANOTIFY. ENOTDIR flags contient FAN_MARK_ONLYDIR, et dirfd et pathname n'indiquent pas de repertoire. ENOTDIR mask contient FAN_RENAME et dirfd et pathname n'indiquent pas de repertoire. ENOTDIR flags contient FAN_MARK_IGNORE ou le groupe fanotify a ete initialise avec l'attribut FAN_REPORT_TARGET_FID et mask contient des evenements de modification d'entree de repertoire (comme FAN_CREATE, FAN_DELETE), ou bien des attributs d'evenements de repertoire (comme FAN_ONDIR, FAN_EVENT_ON_CHILD), et dirfd et pathname n'indiquent pas de repertoire. EOPNOTSUPP L'objet indique par pathname est associe a un systeme de fichiers qui ne gere pas l'encodage d'identificateurs de fichier. Cette erreur ne peut etre renvoyee que lorsqu'un groupe fanotify identifie les objets de systemes de fichiers par des identificateurs de fichier. L'appel de name_to_handle_at(2) avec l'attribut AT_HANDLE_FID (depuis Linux 6.5) peut etre utilise comme un test pour verifier si un systeme de fichiers prend en charge le signalement d'evenements avec les identificateurs de fichiers. EPERM L'operation n'est pas permise car l'appelant n'a pas la capacite requise. EXDEV Le systeme de fichiers indique par pathname se trouve dans un sous-volume de systeme de fichiers (comme btrfs(5)) qui utilise un fsid different de son superbloc racine. Cette erreur ne peut etre renvoyee que par un groupe fanotify qui identifie les objets de systeme de fichiers par des identificateurs de fichier. 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 evenements de ces types ne seront renvoyes que lorsque l'execution directe d'un programme se produit. Plus particulierement, cela signifie que les evenements de ces types seront crees pour les fichiers ouverts en utilisant execve(2), execveat(2) ou uselib(2). Les evenements de ces types n'apparaitront pas quand un interpreteur est passe pour interpretation d'un fichier (ou s'il est en cours de lecture). De plus, si une marque a aussi ete placee sur l'editeur de liens dynamiques de Linux, un utilisateur doit s'attendre aussi a recevoir un evenement associe quand un objet ELF a ete ouvert avec succes en utilisant execve(2) ou execveat(2). Par exemple, si le binaire ELF suivant devait etre appele et si une marque FAN_OPEN_EXEC a ete placee sur / : $ /bin/echo toto Dans ce cas, l'application a l'ecoute devrait recevoir des evenements FAN_OPEN_EXEC, respectivement pour le binaire ELF et pour l'interpreteur : /bin/echo /lib64/ld-linux-x86-64.so.2 BOGUES Les bogues suivants etaient presents avant Linux 3.16 : - si flags contient FAN_MARK_FLUSH, dirfd et pathname doivent indiquer un objet de systeme de fichiers valable, meme si cet objet n'est pas utilise. - readdir(2) ne cree pas d'evenement FAN_ACCESS ; - si fanotify_mark() est appele avec FAN_MARK_FLUSH, les valeurs incorrectes de flags ne sont pas verifiees. VOIR AUSSI fanotify_init(2), fanotify(7) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Philippe MENGUAL Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 fanotify_mark(2)