Provided by: manpages-fr_4.13-4_all bug

NOM

       fanotify – Surveiller les événements des systèmes de fichiers

DESCRIPTION

       L’interface  de  programmation  fanotify  permet  la  notification  et  l’interception des
       événements du système de fichiers. La  recherche  de  virus  et  la  gestion  de  stockage
       hiérarchisé  font  partie  des  cas  d’utilisation.  Dans  l’interface  originelle seul un
       ensemble limité d’événements était pris en  charge.  En  particulier,  les  événements  de
       création,  de  suppression  ou  de  déplacement  n’étaient pas pris en charge. La prise en
       charge de ces évènements a été ajoutée dans Linux 5.1. Consultez inotify(7) pour  plus  de
       précisions sur l’interface qui ne notifiait pas ces évènements avant Linux 5.1.

       La  capacité  de surveiller tous les objets d’un système de fichiers monté, la capacité de
       décider des droits d’accès et la possibilité de lire ou modifier les fichiers avant qu’ils
       ne  soient  accédés  par d’autres applications font partie des capacités supplémentaires à
       celles de l’interface de programmation inotify(7).

       Les appels  système  suivants  sont  utilisés  avec  cette  interface  de  programmation :
       fanotify_init(2), fanotify_mark(2), read(2), write(2) et close(2).

   fanotify_init(), fanotify_mark() et groupes de notification
       L’appel système fanotify_init(2) crée et initialise un groupe de notifications fanotify et
       renvoie un descripteur de fichier le référençant.

       Un groupe de notifications fanotify est un objet interne au noyau qui contient  une  liste
       de  fichiers,  répertoires,  système  de  fichiers et points de montages pour lesquels des
       événements seront créés.

       Pour chaque entrée dans un groupe de notifications fanotify, deux  masques  binaires  sont
       présents :  le  masque  mark  et le masque ignore. Le masque mark définit les activités de
       fichier pour lesquelles un  événement  doit  être  créé.  Le  masque  ignore  définit  les
       activités  pour  lesquelles  aucun  événement  ne  doit être créé. Avoir ces deux types de
       masque permet à un système de fichiers, un point de montage  ou  à  un  répertoire  d’être
       marqué  pour  recevoir  des événements, tout en ignorant en même temps les événements pour
       des objets spécifiques dans ce point de montage ou répertoire.

       L’appel système fanotify_mark(2) ajoute un fichier, répertoire,  système  de  fichiers  ou
       point  de  montage à un groupe de notifications et indique les événements qui doivent être
       signalés (ou ignorés), ou supprime ou modifie une telle entrée.

       Le masque ignore peut servir pour un cache de fichier. Les événements intéressants pour un
       cache  de  fichier sont la modification et la fermeture d’un fichier. Ainsi, le répertoire
       ou point de montage en cache va  être  marqué  pour  recevoir  ces  événements.  Après  la
       réception   du   premier  événement  informant  qu’un  fichier  a  été  modifié,  l’entrée
       correspondante du cache sera désactivée. Aucun autre événement  de  modification  pour  ce
       fichier  ne  sera utile jusqu’à sa fermeture. Ainsi, l’événement de modification peut être
       ajouté au masque ignore. Lors de la réception d’un événement de fermeture, l’événement  de
       modification peut être supprimé du masque ignore et l’entrée de cache de fichier peut être
       mise à jour.

       Les  entrées  des  groupes  de  notification  fanotify  font  référence  aux  fichiers  et
       répertoires  à  l’aide de leur numéro d’inœud et aux montages à l’aide de leur identifiant
       de montage. Si les fichiers ou répertoires sont renommés ou déplacés dans le même montage,
       les  entrées  correspondantes  survivent. Si les fichiers ou répertoires sont supprimés ou
       déplacés  dans  un  autre  montage  ou  si  les  montages  sont  démontés,   les   entrées
       correspondantes sont supprimées.

   La file d’événements
       Comme  les  événements surviennent sur les objets de système de fichiers surveillés par un
       groupe de notifications, le système fanotify génère les événements qui sont collectés dans
       une  file. Ces événements peuvent être lus (en utilisant read(2) ou similaire) à partir du
       descripteur de fichier fanotify renvoyé par fanotify_init(2).

       Deux types d’événements sont créés : les événements de notification et les  événements  de
       permission.  Les événements de notification sont surtout informatifs et ne nécessitent pas
       d’action à prendre  par  l’application  qui  les  reçoit  à  part  pour  la  fermeture  du
       descripteur de fichier valable passé dans l’événement (voir ci-dessous). Les événements de
       permission sont des demandes à l’application qui les reçoit pour  décider  si  les  droits
       d’accès  à  un  fichier  doivent être attribués. Pour ces événements, le destinataire doit
       écrire une réponse qui décide d’attribuer l’accès ou non.

       Un événement est supprimé de la file d’événements du groupe fanotify quand il  a  été  lu.
       Les  événements de permission qui ont été lus sont gardés dans une liste interne du groupe
       fanotify jusqu’à ce qu’une décision d’attribution de droits ait été prise en écrivant dans
       le descripteur de fichier fanotify ou que le descripteur de fichier fanotify soit fermé.

   Lecture d’événements fanotify
       Appeler  read(2)  pour  le  descripteur de fichier renvoyé par fanotify_init(2) bloque (si
       l’attribut FAN_NONBLOCK n’est pas indiqué dans l’appel  de  fanotify_init(2))  jusqu’à  ce
       qu’un  événement  de  fichier  survienne  ou  que  l’appel  soit  interrompu par un signal
       (consultez signal(7)).

       L’utilisation   d’un   des   attributs   FAN_REPORT_FID   et    FAN_REPORT_DIR_FID    dans
       fanotify_init(2) influence quelles structures sont renvoyées à l’écouteur d’évènement pour
       chaque évènement. Les évènements rapportés à un groupe initialisé avec un de ces attributs
       utiliseront  des  gestionnaires  de  fichiers  pour  identifier  des  objets du système de
       fichiers au lieu de descripteurs de fichier.

       Après un appel réussi à
              read(2), le tampon de lecture contient une ou plus des structures suivantes :

           struct fanotify_event_metadata {
               __u32 event_len;
               __u8 vers;
               __u8 reserved;
               __u16 metadata_len;
               __aligned_u64 mask;
               __s32 fd;
               __s32 pid;
           };

       Dans le cas d’un groupe fanotify qui identifie des objets de système de fichiers  par  des
       gestionnaires  de  fichiers,  sont attendus un ou plusieurs enregistrements d’informations
       supplémentaires de la structure détaillée  ci-dessous  qui  suit  la  structure  générique
       fanotify_event_metadata dans le tampon de lecture :

           struct fanotify_event_info_header {
               __u8 info_type;
               __u8 pad;
               __u16 len;
           };

           struct fanotify_event_info_fid {
               struct fanotify_event_info_header hdr;
               __kernel_fsid_t fsid;
               unsigned char file_handle[0];
           };

       Pour  des  raisons  de performances, une grande taille de tampon (par exemple 4096 octets)
       est conseillée pour que plusieurs événements puissent être récupérés en une seule lecture.

       La valeur de retour de read(2) est le nombre d’octets placés dans le tampon, ou -1 en  cas
       d’erreur (mais consultez BOGUES).

       Les champs de la structure fanotify_event_metadata sont les suivants.

       event_len
              C’est  la  taille  des  données  pour l’événement actuel et la position du prochain
              événement dans le tampon. À moins que le groupe identifie des objets du système  de
              fichiers  par  des  gestionnaires  de  fichiers, la valeur d’event_len est toujours
              FAN_EVENT_METADATA_LEN. Pour un groupe qui  identifie  les  objets  du  système  de
              fichiers   par   des   gestionnaires   de  fichiers,  event_len  inclut  aussi  des
              enregistrements d’identificateur de fichier de taille variable.

       vers   Ce champ contient un numéro de version pour la structure. Il doit  être  comparé  à
              FANOTIFY_METADATA_VERSION  pour  vérifier  que  les  structures  renvoyées  pendant
              l’exécution correspondent aux structures définies à la compilation. En cas d’erreur
              de   correspondance,   l’application   devrait   arrêter  d’essayer  d’utiliser  le
              descripteur de fichier fanotify.

       reserved
              Ce champ n’est pas utilisé.

       metadata_len
              C’est la  taille  de  la  structure.  Le  champ  a  été  introduit  pour  faciliter
              l’implémentation   d’en-têtes  facultatifs  par  type  d’événement.  Aucun  en-tête
              facultatif n’existe dans l’implémentation actuelle.

       mask   C’est un masque binaire décrivant l’événement (voir ci-dessous).

       fd     C’est un descripteur de fichier ouvert pour l’objet actuellement accédé ou FAN_NOFD
              si  un  dépassement  de file est survenu. Avec un groupe fanotify qui identifie les
              objets  de  système  d’exploitation  par  des  gestionnaires   de   fichiers,   les
              applications doivent escompter que cette valeur soit FAN_NOFD pour chaque évènement
              qu’elles reçoivent. Le descripteur de fichier peut être  utilisé  pour  accéder  au
              contenu  du  fichier ou répertoire surveillé. L’application qui lit est responsable
              de la fermeture de ce descripteur de fichier.

              Lors d’un appel de fanotify_init(2), l’appelant  pourrait  indiquer  (à  l’aide  de
              l’argument  event_f_flags)  plusieurs attributs d’état de fichier à définir dans la
              description de fichier ouverte qui correspond à ce descripteur de fichier. De plus,
              l’attribut  d’état  de fichier FMODE_NONOTIFY (interne au noyau) est défini dans la
              description  de  fichier  ouverte.  L’attribut  supprime  la  création  d’événement
              fanotify. Ainsi, quand le destinataire de l’événement fanotify accède au fichier ou
              répertoire  notifié  en  utilisant  ce  descripteur  de  fichier,  aucun  événement
              supplémentaire n’est créé.

       pid    Si l’attribut FAN_REPORT_TID était réglé dans fanotify_init(2), c’est l’identifiant
              (TID) du thread qui a provoqué cet évènement. Sinon, c’est le PID du processus  qui
              a provoqué cet évènement.

       Un  programme  écoutant  les  événements  fanotify peut comparer ce PID au PID renvoyé par
       getpid(2) pour déterminer si l’événement est provoqué par l’écoutant lui-même  ou  par  un
       autre processus accédant au fichier.

       Le  masque  binaire  mask indique les événements survenus pour un seul objet de système de
       fichiers. Plusieurs bits pourraient être définis dans ce masque si plus d’un événement est
       survenu  pour  l’objet  de  système  de fichiers surveillé. En particulier, les événements
       consécutifs pour le même objet de système de fichiers et  originaires  du  même  processus
       pourraient  être  fusionnés  dans un seul événement, mais deux événements de permission ne
       sont jamais fusionnés dans une entrée de file.

       Les bits pouvant apparaître dans mask sont les suivants.

       FAN_ACCESS
              Un fichier ou un répertoire (mais consultez BOGUES) a été accédé (en lecture).

       FAN_OPEN
              Un fichier ou un répertoire a été ouvert.

       FAN_OPEN_EXEC
              Un fichier  a  été  ouvert  dans  le  but  d’être  exécuté.  Consultez  NOTES  dans
              fanotify_mark(2) pour plus de détails.

       FAN_ATTRIB
              Une métadonnée de fichier ou d’un répertoire a été modifiée.

       FAN_CREATE
              Un fichier enfant ou un répertoire a été créé dans le répertoire surveillé.

       FAN_DELETE
              Un fichier enfant ou un répertoire a été supprimé dans le répertoire surveillé.

       FAN_DELETE_SELF
              Un fichier ou un répertoire a été supprimé.

       FAN_MOVED_FROM
              Un fichier ou un répertoire a été déplacé du répertoire surveillé.

       FAN_MOVED_TO
              Un fichier ou un répertoire a été déplacé du répertoire parent surveillé.

       IN_MOVE_SELF
              Un fichier ou un répertoire surveillé a été déplacé.

       FAN_MODIFY
              Un fichier a été modifié.

       FAN_CLOSE_WRITE
              Un fichier qui était ouvert en écriture (O_WRONLY ou O_RDWR) a été fermé.

       FAN_CLOSE_NOWRITE
              Un  fichier  ou  un répertoire, qui était ouvert en lecture seule (O_RDONLY), a été
              fermé.

       FAN_Q_OVERFLOW
              La file d’événements a dépassé la limite de 16384 entrées. Cette limite  peut  être
              écrasée   en   indiquant   l’attribut   FAN_UNLIMITED_QUEUE   lors  de  l’appel  de
              fanotify_init(2).

       FAN_ACCESS_PERM
              Une application veut lire un  fichier  ou  répertoire,  par  exemple  en  utilisant
              read(2)  ou  readdir(2).  Le  lecteur  doit  écrire  une réponse (telle que décrite
              ci-dessous) qui détermine si le droit d’accès à l’objet de système de fichiers sera
              attribué.

       FAN_OPEN_PERM
              Une application veut ouvrir un fichier ou un répertoire. Le lecteur doit écrire une
              réponse qui détermine si le droit d’ouvrir l’objet  de  système  de  fichiers  sera
              attribué.

       FAN_OPEN_PERM
              Une  application  veut ouvrir un fichier pour une exécution. Le lecteur doit écrire
              une réponse qui détermine si le droit d’ouvrir l’objet de système de fichiers  sera
              attribué. Consultez NOTES dans fanotify_mark(2) pour plus de détails.

       Pour  vérifier  tous  les  événements  fermés,  le  masque  binaire  suivant pourrait être
       utilisé :

       FAN_CLOSE
              Un fichier a été fermé. C’est un synonyme de :

                  FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE

       Pour vérifier tous les événements de déplacement, le masque binaire suivant pourrait  être
       utilisé :

       FAN_MOVE
              Un fichier ou un répertoire a été déplacé. C’est un synonyme de :

                  FAN_MOVED_FROM | FAN_MOVED_TO

       Les  bits suivants peuvent apparaître dans mask seulement conjointement avec d’autres bits
       de type d’évènement :

       FAN_ONDIR
              Les évènements décrits dans le mask se sont déroulés dans un objet  de  répertoire.
              Le  rapport  d’évènements  dans des répertoires requiert le réglage de cet attribut
              dans le masque mark. Consultez fanotify_mark(2) pour plus  de  détails.  L’attribut
              FAN_ONDIR  est  rapporté dans un masque d’évènement seulement si le groupe fanotify
              identifie les objets de système d’exploitation avec des gestionnaires de fichiers.

       Les champs de la structure fanotify_event_info_fid sont les suivants.

       hdr    C’est une structure de type fanotify_event_info_header. C’est un en-tête  générique
              qui   contient   des   informations   utilisées   pour  décrire  un  enregistrement
              d’informations  supplémentaires  attaché  à  l’évènement.  Par  exemple,  quand  un
              descripteur   de   fichier  fanotify  est  créé  en  utilisant  FAN_REPORT_FID,  un
              enregistrement unique est supposé être attaché à  l’évènement  avec  la  valeur  de
              champ  info_type  de  FAN_EVENT_INFO_TYPE_FID.  Quand  un  descripteur  de  fichier
              fanotify  est   créé   en   utilisant   la   combinaison   de   FAN_REPORT_FID   et
              FAN_REPORT_DIR_FID,  il peut y avoir deux enregistrements d’informations attachés à
              l’évènement : un avec une valeur de champ  info_type  de  FAN_EVENT_INFO_TYPE_DFID,
              identifiant un objet de répertoire parent, et un avec une valeur de champ info_type
              de   FAN_EVENT_INFO_TYPE_FID,   identifiant   un   objet   non    répertoire.    Le
              fanotify_event_info_header contient un champ len. La valeur de len est la taille de
              l’enregistrement       d’informations       supplémentaires       incluant       le
              fanotify_event_info_header  lui-même.  La taille totale de tous les enregistrements
              d’informations   supplémentaires   n’est   pas   supposée   être    supérieure    à
              ( event_len - metadata_len ).

       fsid   C’est  un  identifiant unique du système de fichiers contenant l’objet associé avec
              l’évènement. C’est une structure de type __kernel_fsid_t et elle contient  la  même
              valeur que f_fsid lors de l’appel statfs(2).

       file_handle
              C’est  une  structure de taille variable de type struct gestionnaire_fichier. C’est
              un gestionnaire opaque qui correspond à un objet  précis  de  système  de  fichiers
              comme  renvoyé  par  name_to_handle_at(2).  Il  peut  être  utilisé uniquement pour
              identifier un fichier d’un système de fichiers et peut être passé comme argument  à
              open_by_handle_at(2). Remarquez que pour les évènements de modification d’entrée de
              répertoire FAN_CREATE, FAN_DELETE et FAN_MOVE,  gestionnaire_fichier  identifie  le
              répertoire  modifié  et  non  l’objet enfant créé/supprimé/déplacé. Si la valeur du
              champ info_type est FAN_EVENT_INFO_TYPE_DFID_NAME, le gestionnaire de fichiers  est
              suivi  par  un  octet  NULL  final  qui  identifie  le  nom  d’entrée de répertoire
              créé/supprimé/déplacé. Pour les autres évènements tels  que  FAN_OPEN,  FAN_ATTRIB,
              FAN_DELETE_SELF   et   FAN_MOVE_SELF,   si   la   valeur  du  champ  info_type  est
              FAN_EVENT_INFO_TYPE_FID,  le  gestionnaire_fichier  identifie  l’objet  corrélé   à
              l’évènement.  Si  la  valeur  du  champ  info_type est FAN_EVENT_INFO_TYPE_DFID, le
              gestionnaire_fichier identifie l’objet de répertoire corrélé à  l’évènement  ou  le
              répertoire  parent d’un objet non répertoire corrélé à l’évènement. Si la valeur du
              champ  info_type   est   FAN_EVENT_INFO_TYPE_DFID_NAME,   le   gestionnaire_fichier
              identifie   le   même   objet   de   répertoire   qui   aurait  été  rapporté  avec
              FAN_EVENT_INFO_TYPE_DFID et le gestionnaire de fichiers  est  suivi  par  un  octet
              NULL final  qui  identifie  le  nom de l’entrée de répertoire dans ce répertoire ou
              « . » pour identifier l’objet du répertoire.

       Les macros suivantes sont fournies pour itérer sur un  tampon  contenant  les  métadonnées
       d’événement fanotify renvoyées par read(2) à partir d’un descripteur de fichier fanotify.

       FAN_EVENT_OK(meta, len)
              Cette  macro  compare  la  taille  restante  len  du  tampon meta à la taille de la
              structure de métadonnées  et  au  champ  event_len  de  la  première  structure  de
              métadonnées du tampon.

       FAN_EVENT_NEXT(meta, len)
              Cette  macro  utilise la taille indiquée dans le champ event_len de la structure de
              métadonnées pointée par meta pour calculer l’adresse de la prochaine  structure  de
              métadonnées  qui  suit  meta. len est le nombre d’octets de métadonnées qui restent
              actuellement dans le tampon.  La  macro  renvoie  un  pointeur  vers  la  prochaine
              structure  de  métadonnées  qui  suit meta et réduit len du nombre d’octets dans la
              structure  de  métadonnées  qui  a  été  sautée  (c’est-à-dire  qu’elle   soustrait
              meta->event_len de len).

       De plus, il existe :

       FAN_EVENT_METADATA_LEN
              Cette  macro  renvoie la taille (en octet) de la structure fanotify_event_metadata.
              C’est  la  taille  minimale  (et  actuellement  la  seule  taille)  de  métadonnées
              d’événements.

   Surveiller un descripteur de fichier fanotify pour les événements
       Quand un événement fanotify survient, le descripteur de fichier fanotify est indiqué comme
       lisible lorsque passé à epoll(7), poll(2) ou select(2).

   Traitement des événements de permission
       Pour les événements de permission, l’application doit écrire (avec write(2)) une structure
       de la forme suivante sur le descripteur de fichier fanotify :

           struct fanotify_response {
               __s32 fd;
               __u32 response;
           };

       Les membres de cette structure sont les suivants :

       fd     C’est le descripteur de fichier de la structure fanotify_event_metadata.

       response
              Ce  champ  indique  si  les droits doivent être attribués ou non. Cette valeur doit
              être soit FAN_ALLOW pour permettre  l’opération  de  fichier,  soit  FAN_DENY  pour
              refuser l’opération de fichier.

       Si l’accès est refusé, l’appel d’application faisant la demande recevra une erreur EPERM.

   Fermeture du descripteur de fichier fanotify
       Quand  tous  les  descripteurs  de fichier se référant au groupe de notifications fanotify
       sont fermés, le groupe fanotify est libéré et  ses  ressources  sont  libérées  pour  être
       réutilisées  par  le  noyau.  Lors  de  l’appel  de close(2), les événements de permission
       restants seront définis à permis.

   /proc/[pid]/fdinfo
       Le fichier /proc/[pid]/fdinfo/[fd] contient des renseignements sur  les  marques  fanotify
       pour  le  descripteur  de  fichier  fd  du  processus  pid. Consultez proc(5) pour plus de
       précisions.

ERREURS

       En plus des erreurs habituelles de read(2), les erreurs suivantes peuvent survenir lors de
       la lecture d’un descripteur de fichier fanotify.

       EINVAL Le tampon est trop petit pour contenir l’événement.

       EMFILE La  limite par processus du nombre de fichiers ouverts a été atteinte. Consultez la
              description de RLIMIT_NOFILE dans getrlimit(2).

       ENFILE La limite du nombre de fichiers ouverts sur le système a  été  atteinte.  Consultez
              /proc/sys/fs/file-max dans proc(5).

       ETXTBSY
              Cette  erreur  est renvoyée par read(2) si O_RDWR ou O_WRONLY ont été indiqués dans
              l’argument event_f_flags lors de l’appel fanotify_init(2) et  qu’un  événement  est
              survenu pour un fichier surveillé actuellement en cours d’exécution.

       En  plus  des erreurs habituelles de write(2), les erreurs suivantes peuvent survenir lors
       de l’écriture sur un descripteur de fichier fanotify.

       EINVAL Les droits d’accès fanotify ne sont pas activés dans la configuration du  noyau  ou
              la valeur de response dans la structure de réponse n’est pas valable.

       ENOENT Le  descripteur  de fichier fd dans la structure de réponse n’est pas valable. Cela
              pourrait survenir quand une réponse pour  l’événement  de  permission  a  déjà  été
              écrite.

VERSIONS

       L’interface  de  programmation  fanotify  a été introduite dans la version 2.6.36 du noyau
       Linux et activée dans la version 2.6.37. La prise en charge de fdinfo a été  ajoutée  dans
       la version 3.8.

CONFORMITÉ

       L’interface de programmation fanotify est spécifique à Linux.

NOTES

       L’interface  de  programmation  fanotify  n’est disponible que si le noyau a été construit
       avec l’option  de  configuration  CONFIG_FANOTIFY  activée.  De  plus,  le  traitement  de
       permission    fanotify    n’est    disponible    que    si   l’option   de   configuration
       CONFIG_FANOTIFY_ACCESS_PERMISSIONS est activée.

   Limites et réserves
       Fanotify ne signale que les événements déclenchés par un programme en espace utilisateur à
       l’aide  d’une  interface  de  programmation  de  système de fichiers. Par conséquent, elle
       n’intercepte pas les événements qui surviennent sur les systèmes de fichiers en réseau.

       L'interface fanotify ne signale  pas  les  accès  ni  les  modifications  de  fichier  qui
       pourraient survenir à cause de mmap(2), msync(2) ou munmap(2).

       Les  événements pour répertoire ne sont créés que si le répertoire lui-même est ouvert, lu
       et fermé. Ajouter, supprimer ou modifier les enfants d’un répertoire marqué  ne  crée  pas
       d’événement pour le répertoire surveillé lui-même.

       La  surveillance  fanotify  des  répertoires  n'est  pas  récursive :  pour surveiller les
       sous-répertoires, des marques supplémentaires doivent être créées. L’évènement  FAN_CREATE
       peut  être  utilisé  pour  détecter quand un sous-répertoire a été créé dans un répertoire
       marqué. Une marque supplémentaire doit être définie dans le  sous-répertoire  nouvellement
       créé.  Cette  approche  crée  une  situation de compétition, parce qu’elle peut perdre les
       évènements qui se produisent dans le nouveau  sous-répertoire  avant  qu’une  marque  soit
       ajoutée  dans  ce  sous-répertoire.  La  surveillance  des  montages  offre la capacité de
       surveiller un arbre entier de répertoires sans ce problème de chronologie. La surveillance
       de  système  de  fichiers  offre  la capacité de surveiller tout montage d’une instance de
       système de fichiers sans situation de compétition.

       La file d'événements peut déborder. Dans ce cas, les événements sont perdus.

BOGUES

       Avant Linux 3.19, fallocate(2) ne créait pas d'événement fanotify. Depuis Linux 3.19,  les
       appels à fallocate(2) créent des événements FAN_MODIFY.

       Dans Linux 3.17, les bogues suivants existent :

       –  Dans  Linux,  un objet du système de fichiers pourrait être accessible par de multiples
          chemins. Par exemple, une partie d'un système de fichiers pourrait être  remontée  avec
          l'option  --bind  de  mount(8). Un écoutant ayant marqué un montage ne sera notifié que
          des événements déclenchés pour un objet  du  système  de  fichiers  utilisant  le  même
          montage. Tout autre événement passera inaperçu.

       –  Quand  un  événement  est  créé,  aucune  vérification  n’est  effectuée  pour  voir si
          l’identifiant utilisateur du processus recevant a le droit de lire ou écrire le fichier
          avant  de  passer  un  descripteur  de  fichier pour ce fichier. Cela pose un risque de
          sécurité quand la capacité CAP_SYS_ADMIN est définie pour un programme exécuté par  les
          utilisateurs ordinaires.

       –  Si un appel de read(2) traite plusieurs événements de la file fanotify et qu’une erreur
          survient, la valeur de retour sera la taille totale des événements copiés  correctement
          dans  le  tampon  d’espace  utilisateur  avant  que l’erreur ne survienne. La valeur de
          retour ne sera pas -1 et errno ne sera pas définie.  Ainsi,  l’application  lisant  n’a
          aucun moyen de détecter l’erreur.

EXEMPLES

       Les deux programmes ci-dessous montrent l’utilisation de l’API de fanotify.

   Exemple de programme : fanotify_example.c
       Le  programme  suivant  montre  l’utilisation de fanotify pour une information d’évènement
       d’objet passé sous la forme d’un descripteur de fichier. Le programme marque le  point  de
       montage  passé  en  argument  de  ligne  de  commande  et  attend  les  événements de type
       FAN_PERM_OPEN et FAN_CLOSE_WRITE. Quand un événement de permission survient,  une  réponse
       FAN_ALLOW est donnée.

       La  sortie suivante de session d’interpréteur de commande montre un exemple de l’exécution
       de ce programme. Cette session concerne l’édition du fichier /home/utilisateur/temp/notes.
       Avant  d’ouvrir  le fichier, un événement FAN_OPEN_PERM est survenu. Après la fermeture du
       fichier, un événement FAN_CLOSE_WRITE est survenu. L’exécution  du  programme  se  termine
       quand l’utilisateur appuie sur la touche Entrée.

           # ./fanotify_exemple /home
           Appuyer sur la touche Entrée pour quitter.
           En écoute d’événements.
           FAN_OPEN_PERM : Fichier /home/utilisateur/temp/notes
           FAN_CLOSE_WRITE : Fichier /home/utilisateur/temp/notes

           Arrêt de l’écoute d’événements.

   Source du programme : fanotify_example.c

       #define _GNU_SOURCE  /* Nécessaire pour obtenir la définition de O_LARGEFILE */
       #include <errno.h>
       #include <fcntl.h>
       #include <limits.h>
       #include <poll.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <sys/fanotify.h>
       #include <unistd.h>

       /* Lire tous les événements fanotify disponibles à partir du descripteur
          de fichier « fd » */

       static void
       handle_events(int fd)
       {
           const struct fanotify_event_metadata *metadata;
           struct fanotify_event_metadata buf[200];
           ssize_t len;
           char path[PATH_MAX];
           ssize_t path_len;
           char procfd_path[PATH_MAX];
           struct fanotify_response response;

           /* Boucler tant que les événements peuvent être lus à partir du
              descripteur de fichier fanotify */

           for (;;) {

               /* Lire certains événements */

               len = read(fd, buf, sizeof(buf));
               if (len == -1 && errno != EAGAIN) {
                   perror("read");
                   exit(EXIT_FAILURE);
               }

               /* Vérifier si la fin des données disponibles est atteinte */

               if (len <= 0)
                   break;

               /* Pointer vers le premier événement du tampon */

               metadata = buf;

               /* Boucler sur tous les événements du tampon */

               while (FAN_EVENT_OK(metadata, len)) {

                   /* Vérifier que les structures au moment de l’exécution et
                      de la compilation correspondent */

                   if (metadata->vers != FANOTIFY_METADATA_VERSION) {
                       fprintf(stderr,
                   "Non correspondance de version de métadonnées fanotify.\n");
                       exit(EXIT_FAILURE);
                   }

                   /* metadata->fd contient soit FAN_NOFD, indiquant un
                      dépassement de file, soit un descripteur de fichier
                      (un entier positif).
                      Ici, le dépassement de file est simplement ignoré. */

                   if (metadata->fd >= 0) {

                       /* Traiter l’événement de permission d’ouverture */

                       if (metadata->mask & FAN_OPEN_PERM) {
                           printf("FAN_OPEN_PERM : ");

                           /* Permettre d’ouvrir le fichier */

                           response.fd = metadata->fd;
                           response.response = FAN_ALLOW;
                           write(fd, &response, sizeof(response));
                       }

                       /* Traiter l’événement de fermeture de fichier ouvert
                          en écriture */

                       if (metadata->mask & FAN_CLOSE_WRITE)
                           printf("FAN_CLOSE_WRITE : ");

                       /* Récupérer et afficher le chemin du fichier accédé */

                       snprintf(procfd_path, sizeof(procfd_path),
                                "/proc/self/fd/%d", metadata->fd);
                       path_len = readlink(procfd_path, path,
                                           sizeof(path) - 1);
                       if (path_len == -1) {
                           perror("readlink");
                           exit(EXIT_FAILURE);
                       }

                       path[path_len] = '\0';
                       printf("File %s\n", path);

                       /* Fermer le descripteur de fichier de l’événement */

                       close(metadata->fd);
                   }

                   /* Avancer au prochain événement */

                   metadata = FAN_EVENT_NEXT(metadata, len);
               }
           }
       }

       int
       main(int argc, char *argv[])
       {
           char buf;
           int fd, poll_num;
           nfds_t nfds;
           struct pollfd fds[2];

           /* Vérifier qu’un point de montage est fourni */

           if (argc != 2) {
               fprintf(stderr, "Utilisation : %s MONTAGE\n", argv[0]);
               exit(EXIT_FAILURE);
           }

           printf("Appuyer sur la touche Entrée pour quitter.\n");

           /* Créer le descripteur de fichier pour accéder à l’interface de
              programmation fanotify */

           fd = fanotify_init(FAN_CLOEXEC | FAN_CLASS_CONTENT | FAN_NONBLOCK,
                              O_RDONLY | O_LARGEFILE);
           if (fd == -1) {
               perror("fanotify_init");
               exit(EXIT_FAILURE);
           }

           /* Marquer le montage pour :
              – les événements de permission avant d’ouvrir les fichiers ;
              – les événements de notification après fermeture de descripteur
                de fichier ouvert en écriture. */

           if (fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT,
                             FAN_OPEN_PERM | FAN_CLOSE_WRITE, AT_FDCWD,
                             argv[1]) == -1) {
               perror("fanotify_mark");
               exit(EXIT_FAILURE);
           }

           /* Préparer pour la scrutation (polling) */

           nfds = 2;

           /* Entrée de console */

           fds[0].fd = STDIN_FILENO;
           fds[0].events = POLLIN;

           /* Entrée de fanotify */

           fds[1].fd = fd;
           fds[1].events = POLLIN;

           /* Boucle en attente d’arrivée d’événements */

           printf("En écoute d’événements.\n");

           while (1) {
               poll_num = poll(fds, nfds, -1);
               if (poll_num == -1) {
                   if (errno == EINTR)     /* Interrompu par un signal */
                       continue;           /* Redémarrage de poll() */

                   perror("poll");         /* Erreur inattendue */
                   exit(EXIT_FAILURE);
               }

               if (poll_num > 0) {
                   if (fds[0].revents & POLLIN) {

                       /* Entrée de console disponible :
                          vider l’entrée standard et quitter */

                       while (read(STDIN_FILENO, &buf, 1) > 0 && buf != '\n')
                           continue;
                       break;
                   }

                   if (fds[1].revents & POLLIN) {

                       /* Des événements fanotify sont disponibles */

                       handle_events(fd);
                   }
               }
           }

           printf("Arrêt de l’écoute d’événements.\n");
           exit(EXIT_SUCCESS);
       }

   Exemple de programme : fanotify_fid.c
       Le  second programme est un exemple d’utilisation de fanotify avec un groupe qui identifie
       des objets avec des gestionnaires de fichier. Le programme marque l’objet  de  système  de
       fichiers  qui  est  passé  comme  argument de ligne de commande et attend jusqu’à ce qu’un
       évènement de type FAN_CREATE se produise. Le masque d’évènement indique quel type  d’objet
       de  système de fichiers, soit un fichier ou un répertoire, est créé. Une fois que tous les
       évènements du tampon ont été lus et traités de la  manière  appropriée,  le  programme  se
       termine.

       Les  sessions  d’interpréteur  de commande suivantes montrent deux invocations différentes
       avec des actions différentes réalisées sur l’objet désiré.

       La première session montre une marque placée sur /home/utilisateur. Cela est suivi par  la
       création  d’un  fichier  normal,  /home/utilisateur/fichiertest.txt.  Cela  aboutit  à  un
       évènement FAN_CREATE généré et rapporté  à  l’objet  de  répertoire  surveillé  parent  du
       fichier  et  à la création du nom de fichier. L’exécution du programme se termine une fois
       que tous les évènements capturés du tampon ont été traités.

           # ./fanotify_fid /home/user
           Écoute de tous les évènements.
           FAN_CREATE (fichier créé) :
                   Répertoire /home/utilisateur a été modifié.
                   Entrée 'fichiertest.txt' n’est pas un sous-répertoire.
           Tous les évènements ont été traités avec succès. Fin du programme.

           $ touch /home/utilisateur/fichiertest.txt   # Dans un autre terminal

       La première session montre une marque placée sur /home/utilisateur.  C’est  suivi  par  la
       création  d’un répertoire, /home/utilisateur/réptest. Cette action spécifique aboutit à la
       génération d’un évènement FAN_CREATE et est rapporté avec l’attribut FAN_ONDIR  défini  et
       avec la création du nom de répertoire.

           # ./fanotify_fid /home/user
           Écoute de tous les évènements.
           FAN_CREATE | FAN_ONDIR (sous_répertoire créé) :
                   Répertoire /home/utilisateur a été modifié.
                   Entrée 'réptest' est un sous-répertoire.
           Tous les évènements ont été traités avec succès. Fin du programme.

           $ mkdir -p /home/utilisateur/réptest      # Dans un autre terminal

   Source du programme : fanotify_fid.c

       #define _GNU_SOURCE
       #include <errno.h>
       #include <fcntl.h>
       #include <limits.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <sys/fanotify.h>
       #include <unistd.h>

       #define BUF_SIZE 256

       int
       main(int argc, char **argv)
       {
           int fd, ret, event_fd, mount_fd;
           ssize_t len, path_len;
           char path[PATH_MAX];
           char procfd_path[PATH_MAX];
           char events_buf[BUF_SIZE];
           struct file_handle *file_handle;
           struct fanotify_event_metadata *metadata;
           struct fanotify_event_info_fid *fid;
           const char *file_name;
           struct stat sb;

           if (argc != 2) {
               fprintf(stderr, "nb d’arguments de ligne de commande non valable.\n");
               exit(EXIT_FAILURE);
           }

           mount_fd = open(argv[1], O_DIRECTORY | O_RDONLY);
           if (mount_fd == -1) {
               perror(argv[1]);
               exit(EXIT_FAILURE);
           }

           /* Créer un descripteur de fichier avec FAN_REPORT_DFID_NAME sous
              forme d’attribut de façon que le programme puisse recevoir des
              évènements fid avec des noms de répertoire d’entrée */

           fd = fanotify_init(FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME, 0);
           if (fd == -1) {
               perror("fanotify_init");
               exit(EXIT_FAILURE);
           }

           /* Placer une marque sur un objet de système de fichiers
              fourni dans argv[1]. */

           ret = fanotify_mark(fd, FAN_MARK_ADD | FAN_MARK_ONLYDIR,
                               FAN_CREATE | FAN_ONDIR,
                               AT_FDCWD, argv[1]);
           if (ret == -1) {
               perror("fanotify_mark");
               exit(EXIT_FAILURE);
           }

           printf("En écoute d’événements.\n");

           /* Lire les évènements de la file d’évènements d’un tampon */

           len = read(fd, events_buf, sizeof(events_buf));
           if (len == -1 && errno != EAGAIN) {
               perror("read");
               exit(EXIT_FAILURE);
           }

           /* Traiter tous les événements du tampon */

           for (metadata = (struct fanotify_event_metadata *) events_buf;
                   FAN_EVENT_OK(metadata, len);
                   metadata = FAN_EVENT_NEXT(metadata, len)) {
               fid = (struct fanotify_event_info_fid *) (metadata + 1);
               file_handle = (struct file_handle *) fid->handle;

               /* Assurer que les infos d’évènements soient du type correct */

               if (fid->hdr.info_type == FAN_EVENT_INFO_TYPE_FID ||
                   fid->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID) {
                   file_name = NULL;
               } else if (fid->hdr.info_type == FAN_EVENT_INFO_TYPE_DFID_NAME) {
                   file_name = file_handle->f_handle +
                               file_handle->handle_bytes;
               } else {
                   fprintf(stderr, "Type inattendu d’évènement reçu.\n");
                   exit(EXIT_FAILURE);
               }

               if (metadata->mask == FAN_CREATE)
                   printf("FAN_CREATE (file created):\n");

               if (metadata->mask == (FAN_CREATE | FAN_ONDIR))
                   printf("FAN_CREATE | FAN_ONDIR (sous_répertoire créé) :\n");

            /* metadata->fd est défini à FAN_NOFD quand le groupe identifie
               les objets avec des gestionnaires de fichiers. Pour obtenir un
               descripteur de fichier pour l’objet de fichier correspondant à
               à un évènement, utiliser struct gestionnaire_fichier qui est
               fourni dans le fanotify_event_info_fid conjointement avec l’appel
               système open_by_handle_at(2). Une vérification pour ESTALE est
               faite pour supporter la situation où le gestionnaire de fichiers
               pour l’objet ait été détruit avant cet appel système. */

               event_fd = open_by_handle_at(mount_fd, file_handle, O_RDONLY);
               if (event_fd == -1) {
                   if (errno == ESTALE) {
                       printf("Le gestionnaire de fichiers n’est plus valable, "
                               "le fichier a été supprimé\n");
                       continue;
                   } else {
                       perror("open_by_handle_at");
                       exit(EXIT_FAILURE);
                   }
               }

               snprintf(procfd_path, sizeof(procfd_path), "/proc/self/fd/%d",
                       event_fd);

               /* Récupérer et afficher le chemin de l’entrée modifiée */

               path_len = readlink(procfd_path, path, sizeof(path) - 1);
               if (path_len == -1) {
                   perror("readlink");
                   exit(EXIT_FAILURE);
               }

               path[path_len] = '\0';
               printf("\Le répertoire '%s' a été modifié\n", path);

               if (file_name) {
                   ret = fstatat(event_fd, file_name, &sb, 0);
                   if (ret == -1) {
                       if (errno != ENOENT) {
                           perror("fstatat");
                           exit(EXIT_FAILURE);
                       }
                       printf("\tL’entrée '%s' n’existe pas\n", file_name);
                   } else if ((sb.st_mode & S_IFMT) == S_IFDIR) {
                       printf("\tL’entrée '%s' est un sous-répertoire\n", file_name);
                   } else {
                       printf("\tL’entrée '%s' n’est pas un sous-répertoire\n",
                               file_name);
                   }
               }

               /* Fermer le descripteur de fichier de cet événement */

               close(event_fd);
           }

           printf("Tous les évènements traités avec succès, fin du programme.\n");
           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

       fanotify_init(2), fanotify_mark(2), inotify(7)

COLOPHON

       Cette page fait partie de la publication 5.10 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/.

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-Paul Guillonneau
       <guillonneau.jeanpaul@free.fr>

       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 ⟨⟩.