fanotify_init(2) System Calls Manual fanotify_init(2) NOM fanotify_init - Creer et initialiser un groupe fanotify BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include /* Definition des constantes O_* */ #include int fanotify_init(unsigned int flags, unsigned int event_f_flags); DESCRIPTION Pour un apercu de l'interface de programmation fanotify, consultez fanotify(7). fanotify_init() initialise un nouveau groupe fanotify et renvoie un descripteur de fichier pour la file d'evenements associee au groupe. Le descripteur de fichier est utilise dans les appels de fanotify_mark(2) pour indiquer les fichiers, les repertoires, les points de montage et les systemes de fichiers pour lesquels les evenements fanotify seront crees. Ces evenements sont recus en lisant le descripteur de fichier. Certains evenements ne sont qu'informatifs, indiquant qu'il y a eu un acces au fichier. D'autres evenements peuvent etre utilises pour determiner si une autre application a le droit d'acceder a un fichier ou repertoire. Le droit d'acceder aux objets de systeme de fichiers est accorde en ecrivant dans le descripteur de fichier. Plusieurs programmes peuvent utiliser l'interface fanotify en meme temps pour surveiller les memes fichiers. Le nombre de groupes fanotify par utilisateur est limite. Voir fanotify(7) pour des details sur cette limite. L'argument flags contient un champ multibit definissant la classe de notification de l'application ecoutant et d'autres champs monobit indiquant le comportement du descripteur de fichier. Si plusieurs ecoutants d'evenements de permission existent, la classe de notification est utilisee pour etablir l'ordre dans lequel les ecoutants recoivent les evenements. Une seule des classes de notification suivantes peut etre indiquee dans flags. FAN_CLASS_PRE_CONTENT Cette valeur permet de recevoir des evenements notifiant de l'acces a un fichier et des evenements de decisions de permission d'acces a un fichier. Elle est concue pour les ecoutants d'evenement qui doivent acceder aux fichiers avant qu'ils ne contiennent leurs donnees finales. Cette classe de notification pourrait etre utilisee par exemple par des gestionnaires de stockage hierarchise. L'utilisation de cet attribut exige la capacite CAP_SYS_ADMIN. FAN_CLASS_CONTENT Cette valeur permet de recevoir des evenements notifiant l'acces a un fichier et des evenements de decisions de permission d'acces a un fichier. Elle est concue pour les ecoutants d'evenement qui doivent acceder aux fichiers quand ils contiennent deja leur contenu final. Cette classe de notification pourrait etre utilisee par exemple par des programmes de detection de logiciels malveillants. L'utilisation de cet attribut exige la capacite CAP_SYS_ADMIN. FAN_CLASS_NOTIF C'est la valeur par defaut. Elle n'a pas besoin d'etre indiquee. Cette valeur ne permet de recevoir que des evenements notifiant qu'un fichier a ete accede. Les decisions de permission avant que le fichier ne soit accede ne sont pas possibles. Les ecoutants avec differentes classes de notification recevront les evenements dans l'ordre FAN_CLASS_PRE_CONTENT, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF. L'ordre de notification pour les ecoutants dans la meme classe de notification n'est pas defini. Les bits suivants peuvent de plus etre definis dans flags. FAN_CLOEXEC Placer l'attribut << close-on-exec >> (FD_CLOEXEC) sur le nouveau descripteur de fichier. Consultez la description de l'attribut O_CLOEXEC dans open(2). FAN_NONBLOCK Activer l'attribut non bloquant (O_NONBLOCK) pour le descripteur de fichier. La lecture du descripteur de fichier ne bloquera pas. A la place, si aucune donnee n'est disponible, read(2) echouera avec l'erreur EAGAIN. FAN_UNLIMITED_QUEUE Supprimer la limite du nombre d'evenements pour la file d'evenements. Voir fanotify(7) pour des details sur cette limite. L'utilisation de cet attribut necessite la capacite CAP_SYS_ADMIN. FAN_UNLIMITED_MARKS Supprimer la limite du nombre de marques fanotify par utilisateur. Voir fanotify(7) pour des details sur cette limite. L'utilisation de cet attribut necessite la capacite CAP_SYS_ADMIN. FAN_REPORT_TID (depuis Linux 4.20) Signaler l'ID d'un thread (TID) au lieu de l'ID du processus (PID) dans le champ pid de la struct fanotify_event_metadata fournie a read(2) (voir fanotify(7)). L'utilisation de cet attribut exige la capacite CAP_SYS_ADMIN. FAN_ENABLE_AUDIT (depuis Linux 4.15) Activer la generation d'entrees de journal d'audit sur des tentatives d'acces effectuees par des evenements de droits. La reponse de l'evenement de droits doit etre marquee par l'attribut FAN_AUDIT pour qu'une entree de journal d'audit soit generee. L'utilisation de cet attribut exige la capacite CAP_AUDIT_WRITE. FAN_REPORT_FID (depuis Linux 5.1) Cette valeur permet la reception d'evenements qui contiennent des informations complementaires sur l'objet du systeme de fichiers sous-jacent correle a un evenement. Un enregistrement supplementaire de type FAN_EVENT_INFO_TYPE_FID enferme les informations sur l'objet et est inclus dans la structure generique des metadonnees de l'evenement. Le descripteur de fichier utilise pour representer l'objet lie a un evenement est remplace par un identificateur de fichier. Il est concu pour les applications qui trouvent que l'utilisation d'un identificateur de fichier pour identifier un objet convient mieux qu'un descripteur de fichier. De plus, il peut etre utilise par des applications supervisant un repertoire ou un systeme de fichiers qui s'interessent aux modifications d'entree de repertoire telles que FAN_CREATE, FAN_DELETE, FAN_MOVE et FAN_RENAME, ou a des evenements tels que FAN_ATTRIB, FAN_DELETE_SELF et FAN_MOVE_SELF. Tous les evenements ci-dessus exigent un groupe fanotify identifiant les objets de systeme de fichiers par des identificateurs de fichier. Remarquez que sans l'attribut FAN_REPORT_TARGET_FID, pour les evenements de modification d'entree de repertoire, il existe un enregistrement d'informations qui identifie le repertoire modifie et non l'objet enfant cree/supprime/deplace. L'utilisation de FAN_CLASS_CONTENT ou de FAN_CLASS_PRE_CONTENT n'est pas autorisee avec cet attribut et donnera une erreur EINVAL. Voir fanotify(7) pour des informations supplementaires. FAN_REPORT_DIR_FID (depuis Linux 5.9) Les evenements des groupes fanotify initialises avec cet attribut contiendront (voir les exceptions ci-dessous) des informations supplementaires sur l'objet d'un repertoire correle a un evenement. Un enregistrement supplementaire de type FAN_EVENT_INFO_TYPE_DFID enferme les informations sur l'objet repertoire et est inclus dans la structure generique des metadonnees de l'evenement. Pour des evenements qui arrivent sur un objet qui n'est pas un repertoire, la structure supplementaire inclut un identificateur de fichier qui identifie l'objet de systeme de fichiers du repertoire parent. Remarquez qu'il n'y a pas de garantie que l'objet systeme de fichiers du repertoire ne se trouve a l'emplacement decrit par l'information d'identificateur de fichier au moment ou l'evenement est recu. S'il est associe a l'attribut FAN_REPORT_FID, il se peut que deux enregistrements soient signales avec des evenements qui se produisent sur un objet non repertoire, un pour identifier l'objet non repertoire lui-meme, et un pour identifier l'objet repertoire parent. Remarquez que dans certains cas, un objet de systeme de fichiers n'a pas de parent, par exemple quand un evenement se produit sur un fichier non lie mais ouvert. Dans ce cas, avec l'attribut FAN_REPORT_FID l'evenement sera signale avec un seul enregistrement pour identifier l'objet non repertoire, puisqu'il n'y a pas de repertoire associe a l'evenement. Sans l'attribut FAN_REPORT_FID, aucun evenement ne sera signale. Voir fanotify(7) pour des details supplementaires. FAN_REPORT_NAME (depuis Linux 5.9) Les evenements des groupes fanotify initialises avec cet attribut contiendront des informations supplementaires sur le nom de l'entree de repertoire correle a un evenement. Cet attribut doit etre fourni en association avec l'attribut FAN_REPORT_DIR_FID. Le fait de fournir cette valeur d'attribut sans FAN_REPORT_DIR_FID aboutira a l'erreur EINVAL. Cet attribut peut etre combine a l'attribut FAN_REPORT_FID. Un enregistrement supplementaire de type FAN_EVENT_INFO_TYPE_DFID_NAME, qui enferme les informations sur l'entree de repertoire, est inclus dans la structure generique des metadonnees de l'evenement et remplace l'enregistrement des informations supplementaires de type FAN_EVENT_INFO_TYPE_DFID. L'enregistrement supplementaire inclut un identificateur de fichier qui identifie un objet de systeme de fichiers de repertoire suivi d'un nom qui identifie une entree dans ce repertoire. Pour les evenements de modification d'entree de repertoire FAN_CREATE, FAN_DELETE et FAN_MOVE, le nom signale est celui de l'entree de repertoire creee/effacee/deplacee. L'evenement FAN_RENAME peut contenir deux enregistrements d'information. L'un, de type FAN_EVENT_INFO_TYPE_OLD_DFID_NAME, identifie l'ancienne entree de repertoire. L'autre, de type FAN_EVENT_INFO_TYPE_NEW_DFID_NAME, identifie la nouvelle entree de repertoire. Pour les autres evenements qui se produisent sur un objet repertoire, l'identificateur rapporte est celui de l'objet repertoire lui-meme et le nom signale est << . >>. Pour les autres evenements qui se produisent sur un objet non repertoire, l'identificateur de fichier signale est celui de l'objet repertoire parent et le nom signale est celui de l'entree d'un repertoire ou se situait l'objet au moment de l'evenement. La raison derriere cette logique est que l'identificateur de fichier du repertoire signale peut etre passe a open_by_handle_at(2) pour recuperer un descripteur de fichier de repertoire ouvert et que ce descripteur de fichier ainsi que le nom signale puissent etre utilises pour appeler fstatat(2). La meme regle qui s'applique au type d'enregistrement FAN_EVENT_INFO_TYPE_DFID s'applique aussi au type d'enregistrement FAN_EVENT_INFO_TYPE_DFID_NAME : si un objet non repertoire n'a pas de parent, soit l'evenement ne sera pas signale, soit il le sera sans les informations d'entree de repertoire. Remarquez qu'il n'existe pas de garantie que l'objet de systeme de fichiers se trouve a l'endroit decrit par les informations de l'entree de repertoire au moment ou l'evenement est recu. Voir fanotify(7) pour des details supplementaires. FAN_REPORT_DFID_NAME C'est un synonyme de (FAN_REPORT_DIR_FID|FAN_REPORT_NAME). FAN_REPORT_TARGET_FID (depuis Linux 5.17) Les evenements des groupes fanotify initialises avec cet attribut contiendront des informations supplementaires sur l'enfant correle aux evenements de modification d'entree de repertoire. Cet attribut doit etre fourni en association avec les attributs FAN_REPORT_FID, FAN_REPORT_DIR_FID et FAN_REPORT_NAME. Sans cela, l'erreur EINVAL sera renvoyee. Pour les evenements de modification d'entree de repertoire FAN_CREATE, FAN_DELETE, FAN_MOVE et FAN_RENAME, un enregistrement supplementaire de type FAN_EVENT_INFO_TYPE_FID est signale en plus des enregistrements d'information de type FAN_EVENT_INFO_TYPE_DFID, FAN_EVENT_INFO_TYPE_DFID_NAME, FAN_EVENT_INFO_TYPE_OLD_DFID_NAME et FAN_EVENT_INFO_TYPE_NEW_DFID_NAME. L'enregistrement supplementaire comprend un identifiant de fichier qui identifie l'objet enfant de systeme de fichier auquel se rapporte l'entree de repertoire. FAN_REPORT_DFID_NAME_TARGET C'est un synonyme de (FAN_REPORT_DFID_NAME|FAN_REPORT_FID|FAN_REPORT_TARGET_FID). FAN_REPORT_PIDFD (depuis Linux 5.15) Les evenements des groupes fanotify initialises avec cet attribut contiendront des informations supplementaires dans la structure generique fanotify_event_metadata. Cet enregistrement d'informations sera de type FAN_EVENT_INFO_TYPE_PIDFD et contiendra un pidfd pour le processus responsable de la generation d'un evenement. Un pidfd renvoye dans cet objet enregistrement n'est pas different du pidfd renvoye lors d'un appel pidfd_open(2). Cet enregistrement sert aux applications qui veulent determiner de maniere fiable si le processus responsable de la generation d'un evenement a ete recycle ou termine. L'utilisation de l'attribut FAN_REPORT_TID avec FAN_REPORT_PIDFD n'est pas prise en charge actuellement et si on essaie de faire cela, une erreur EINVAL sera renvoyee. Cette limite est actuellement imposee par l'API de pidfd car elle ne gere actuellement que la creation de pidfds pour des leaders de groupes de threads. La creation de pidfds pour autre chose que les leaders de groupes de thread pourra etre geree dans l'avenir, annulant cette exception. Pour plus de details sur l'enregistrement d'informations, voir fanotify(7). L'argument event_f_flags definit les attributs d'etat de fichier qui seront definis sur les descriptions de fichiers ouverts qui sont creees pour les evenements fanotify. Pour plus de precisions sur ces attributs, consultez la description des valeurs de flags dans open(2). event_f_flags contient un champ multibit pour le mode d'acces. Ce champ peut prendre une des valeurs suivantes : O_RDONLY Cette valeur permet l'acces en lecture seule. O_WRONLY Cette valeur permet l'acces en ecriture seule. O_RDWR Cette valeur permet l'acces en lecture et ecriture. Des bits supplementaires peuvent etre definis dans event_f_flags. Les valeurs les plus utiles sont les suivantes : O_LARGEFILE Activer la prise en charge de fichiers depassant 2 Go. Sans cet attribut, une erreur EOVERFLOW surviendra lors d'une tentative d'ouverture d'un gros fichier surveille par un groupe fanotify sur un systeme 32 bits. O_CLOEXEC (depuis Linux 3.18) Activer l'attribut << close-on-exec >> pour le descripteur de fichier. Consultez la description de l'attribut O_CLOEXEC dans open(2) pour savoir pourquoi cela peut etre utile. Les valeurs suivantes sont aussi permises : O_APPEND, O_DSYNC, O_NOATIME, O_NONBLOCK et O_SYNC. Indiquer n'importe quel autre attribut dans event_f_flags provoque l'erreur EINVAL (mais consultez BOGUES). VALEUR RENVOYEE S'il reussit, fanotify_init() renvoie un nouveau descripteur de fichier. En cas d'erreur, il renvoie -1 et errno contient le code d'erreur. ERREURS EINVAL Une valeur incorrecte a ete passee dans flags ou event_f_flags. FAN_ALL_INIT_FLAGS (obsolete depuis Linux 4.20) definit tous les bits permis pour flags. EMFILE Le nombre de groupes fanotify pour cet utilisateur depasse la limite. Voir fanotify(7) pour des details sur cette limite. EMFILE La limite du nombre de descripteurs de fichiers par processus a ete atteinte. ENOMEM Echec d'allocation memoire pour le groupe de notification. ENOSYS Ce noyau n'implemente pas fanotify_init(). L'interface de programmation fanotify n'est disponible que si le noyau a ete configure avec CONFIG_FANOTIFY. EPERM L'operation n'est pas permise car l'appelant n'a pas la capacite requise. VERSIONS Avant Linux 5.13, l'appel a fanotify_init() exigeait la capacite CAP_SYS_ADMIN. Depuis Linux 5.13, les utilisateurs peuvent appeler fanotify_init() sans la capacite CAP_SYS_ADMIN, pour creer et initialiser un groupe fanotify avec des fonctionnalites limitees. Les limites imposees a l'ecoutant d'un evenement cree par un utilisateur sans la capacite CAP_SYS_ADMIN sont les suivantes : - L'utilisateur ne peut pas demander une file d'attente d'evenements illimitee en utilisant FAN_UNLIMITED_QUEUE. - L'utilisateur ne peut pas demander un nombre illimite de marques en utilisant FAN_UNLIMITED_MARKS. - L'utilisateur ne peut pas demander a utiliser des classes de notification FAN_CLASS_CONTENT ou FAN_CLASS_PRE_CONTENT. Cela signifie que l'utilisateur ne peut pas de demander des evenements de droits. - L'utilisateur doit creer un groupe qui identifie l'objet systeme de fichiers par des identificateurs de fichier, par exemple en fournissant l'attribut FAN_REPORT_FID. - L'utilisateur est limite aux inoeuds de marques. La possibilite de marquer un point de montage ou un systeme de fichiers a l'aide de fanotify_mark(), a travers l'utilisation de FAN_MARK_MOUNT ou de FAN_MARK_FILESYSTEM, n'est pas autorisee. - L'objet evenement de la file d'attente d'evenements est limite en termes d'information disponible pour l'utilisateur non privilegie. Un utilisateur ne recevra pas non plus le pid qui a genere l'evenement, sauf si le processus qui ecoute a lui-meme genere l'evenement. STANDARDS Linux. HISTORIQUE Linux 2.6.37. BOGUES Le bogue suivant etait present avant Linux 3.18 : - O_CLOEXEC est ignore lorsqu'il est passe dans event_f_flags. Le bogue suivant etait present avant Linux 3.14 : - l'argument event_f_flags n'est pas verifie pour les attributs incorrects. Les attributs qui ne sont concus que pour une utilisation interne, comme FMODE_EXEC, peuvent etre definis et seront donc definis pour les descripteurs de fichier renvoyes lors de la lecture depuis le descripteur de fichier fanotify. VOIR AUSSI fanotify_mark(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_init(2)