Provided by: manpages-fr_4.18.1-1_all bug

NOM

       rtld-audit - API d'audit pour l'éditeur de liens dynamique

SYNOPSIS

       #define _GNU_SOURCE             /* See feature_test_macros(7) */
       #include <link.h>

DESCRIPTION

       L'éditeur  de  liens  dynamique  GNU  (l'éditeur  de  liens à l'exécution) fournit une API
       d'audit qui permet à une application d'être notifiée quand différents  événements  liés  à
       l'édition de liens surviennent. Cette API est très similaire à l'interface d'audit fournie
       par l'éditeur de liens Solaris. Les constantes et prototypes nécessaires sont  définis  en
       incluant <link.h>.

       Pour  utiliser  cette  interface,  le  programmeur  crée  une  bibliothèque  partagée  qui
       implémente un ensemble standard de noms de fonctions. Toutes les  fonctions  n'ont  pas  à
       être  implémentées :  dans  la plupart des cas, si le programmeur n'est pas intéressé dans
       une certaine classe d'événements d'audit, alors aucune implémentation n'a à  être  fournie
       pour la fonction d'audit correspondante.

       Pour  utiliser l'interface d'audit, la variable d'environnement LD_AUDIT doit être définie
       avec une liste de bibliothèques partagées, séparées par des « deux-points »,  qui  peuvent
       implémenter  l'API  (ou  une  partie)  d'audit.  Quand un événement pouvant être surveillé
       survient, la fonction correspondante est appelée dans chaque bibliothèque, dans l'ordre où
       sont listées les bibliothèques.

   la_version()

       unsigned int la_version(unsigned int version);

       This  is  the  only  function that must be defined by an auditing library: it performs the
       initial handshake between the dynamic linker and the auditing library. When invoking  this
       function,  the  dynamic  linker  passes,  in  version, the highest version of the auditing
       interface that the linker supports.

       A typical implementation of this function simply returns the constant  LAV_CURRENT,  which
       indicates  the version of <link.h> that was used to build the audit module. If the dynamic
       linker does not support this version of the audit interface, it will  refuse  to  activate
       this audit module. If the function returns zero, the dynamic linker also does not activate
       this audit module.

       In order to enable backwards compatibility with older dynamic linkers, an audit module can
       examine  the version argument and return an earlier version than LAV_CURRENT, assuming the
       module can adjust its implementation to match the requirements of the previous version  of
       the  audit  interface.  The  la_version  function  should  not return the value of version
       without further checks because it could correspond to an interface that does not match the
       <link.h> definitions used to build the audit module.

   la_objsearch()

       char *la_objsearch(const char *name, uintptr_t *cookie,
                          unsigned int flag);

       L'éditeur  de  liens appelle cette fonction pour informer la bibliothèque d'audit qu'il va
       se mettre à la recherche d'un objet partagé. Le paramètre name est le nom de fichier ou le
       chemin  dans  lequel  s'effectue  la  recherche.  cookie  identifie  l'objet partagé qui a
       déclenché la recherche. flag est l'une des valeurs suivantes :

       LA_SER_ORIG      Il s'agit du nom de départ de la recherche. Généralement ce nom  provient
                        d'une  entrée  ELF  DT_NEEDED  ou  est  le  paramètre  filename  fourni à
                        dlopen(3).

       LA_SER_LIBPATH   name a été créé en utilisant un répertoire indiqué dans LD_LIBRARY_PATH.

       LA_SER_RUNPATH   name a été créé en utilisant un répertoire indiqué  dans  une  liste  ELF
                        DT_RPATH ou DT_RUNPATH.

       LA_SER_CONFIG    name a été trouvé par le cache ldconfig(8) (/etc/ld.so.cache).

       LA_SER_DEFAULT   name a été trouvé par une recherche dans un des répertoires par défaut.

       LA_SER_SECURE    name est spécifique à un objet sûr (pas utilisé sous Linux).

       la_objsearch()  renvoie  comme  valeur  de retour le chemin que l'éditeur de liens devrait
       utiliser pour les opérations suivantes. Si NULL est renvoyé, alors le  chemin  est  ignoré
       par  la  suite.  Les  bibliothèques  qui ne cherche qu'à observer les chemins de recherche
       devraient renvoyer name.

   la_activity()

       void la_activity( uintptr_t *cookie, unsigned int flag);

       L'éditeur  de  liens  appelle  cette  fonction  pour  informer  la  bibliothèque   d'audit
       d'activités  sur la table des liens. cookie identifie l'objet à la tête de la table. Quand
       l'éditeur de liens appelle cette fonction, flag vaut l'une des valeurs suivantes :

       LA_ACT_ADD         De nouveaux objets sont ajoutés à la table.

       LA_ACT_DELETE      Des objets sont retirés d ela table.

       LA_ACT_CONSISTENT  L'activité sur  la  table  est  terminée :  la  table  est  de  nouveau
                          cohérente.

   la_objopen()

       unsigned int la_objopen(struct link_map *map, Lmid_t lmid,
                               uintptr_t *cookie);

       L'éditeur  de  liens  appelle  cette fonction quand un nouvel objet partagé est chargé. Le
       paramètre map est un pointeur vers la structure d'une table de liens qui  décrit  l'objet.
       Le champ lmid prend une des valeurs suivantes :

       LM_ID_BASE       La table fait partie de l'espace de noms de départ.

       LM_ID_NEWLM      La table fait partie d'un nouvel espace de noms demandé avec dlmopen(3).

       cookie  est  un  pointeur  vers un identifiant pour un objet. L'identifiant est fourni aux
       appels suivants des fonctions  de  la  bibliothèque  d'audit  afin  d'identifier  l'objet.
       L'identifiant  est  initialisé pour pointer vers la table de l'objet, mais la bibliothèque
       d'audit peut changer l'identifiant pour une autre valeur qu'elle préférerait utiliser pour
       identifier l'objet.

       la_objopen()  renvoie  comme  valeur de retour un masque de bits créé en combinant zéro ou
       plusieurs constantes avec un OU binaire, ce  qui  permet  à  la  bibliothèque  d'audit  de
       sélectionner les objets à surveiller avec les fonctions la_symbind*() :

       LA_FLG_BINDTO    Surveiller les associations de symboles à cet objet.

       LA_FLG_BINDFROM  Surveiller les associations de symboles provenant de cet objet.

       Une valeur de retour de 0 pour la_objopen() indique qu'aucune association de symbole n'est
       à surveiller pour cet objet.

   la_objclose()

       unsigned int la_objclose(uintptr_t *cookie);

       L'éditeur de liens appelle cette fonction après l'exécution du code de  finalisation  pour
       l'objet  (s'il  y  en  a),  et  avant  que  l'objet soit déchargé. Le paramètre cookie est
       l'identifiant obtenu par l'appel précédent à la_objopen().

       Dans l'implémentation actuelle, la valeur renvoyée par la_objclose() est ignorée.

   la_preinit()

       void la_preinit(uintptr_t *cookie);

       L'éditeur de liens appelle cette fonction après que  tous  les  objets  partagés  ont  été
       chargés,  avant  que  le contrôle soit donné à l'application (c'est-à-dire avant l'appel à
       main()). Notez que main() peut  encore  charger  des  objets  dynamiquement  en  utilisant
       dlopen(3).

   la_symbind*()

       uintptr_t la_symbind32(Elf32_Sym *sym, unsigned int ndx,
                              uintptr_t *refcook, uintptr_t *defcook,
                              unsigned int *flags, const char *symname);
       uintptr_t la_symbind64(Elf64_Sym *sym, unsigned int ndx,
                              uintptr_t *refcook, uintptr_t *defcook,
                              unsigned int *flags, const char *symname);

       L'éditeur  de liens appelle une de ces fonctions quand une association de symbole survient
       entre deux objets partagés qui ont été marqués comme étant surveillés par la_objopen(). La
       fonction   la_symbind32()  est  utilisée  pour  les  plate-formes  32 bits ;  la  fonction
       la_symbind64() est utilisée pour les plate-formes 64 bits.

       Le paramètre sym est un pointeur vers une structure qui fournit des  informations  sur  le
       symbole  en  cours  d'association.  La  définition de la structure se trouve dans <elf.h>.
       Parmi les champs de la structure, st_value indique l'adresse à  laquelle  le  symbole  est
       associé.

       Le  paramètre ndx fournit l'index du symbole dans la table des symboles de l'objet partagé
       associé.

       Le paramètre refcook identifie l'objet partagé qui  crée  la  référence  du  symbole ;  il
       s'agit   du   même   identifiant   fourni   à  la  fonction  la_objopen()  qui  a  renvoyé
       LA_FLG_BINDFROM. Le paramètre defcook identifie l'objet  partagé  qui  défini  le  symbole
       référencé ;  il s'agit du même identifiant fourni à la fonction la_objopen() qui a renvoyé
       LA_FLG_BINDTO.

       Le paramètre symname pointe vers une chaîne contenant le nom du symbole.

       Le paramètre flags est un masque de bits qui peut à la fois fournir des  informations  sur
       le symbole et être utilisé pour modifier encore plus la surveillance de cette entrée de la
       PLT (Procedure Linkage Table). L'éditeur de liens dynamique peut fournir les bits suivants
       dans ce paramètre :

       LA_SYMB_DLSYM         L'association provient d'un appelle à dlsym(3).

       LA_SYMB_ALTVALUE      Un  appel  précédent à la_symbind*() a renvoyé une autre valeur pour
                             ce symbole.

       Par  défaut,  si  la  bibliothèque  d'audit  implémente  les  fonctions  la_pltenter()  et
       la_pltexit()  (voir  ci-dessous),  alors  ces fonctions sont appelées, après la_symbind(),
       pour les entrées de la PLT, à chaque fois que  le  symbole  est  référencé.  Les  drapeaux
       suivants  peuvent  être  fournis  en  les  combinant  avec  un OU binaire dans *flags pour
       modifier ce comportement par défaut :

       LA_SYMB_NOPLTENTER    Ne pas appeler la_pltenter() pour ce symbole.

       LA_SYMB_NOPLTEXIT     Ne pas appeler la_pltexit() pour ce symbole.

       La valeur de retour de la_symbind32()  et  la_symbind64()  est  l'adresse  à  laquelle  le
       contrôle  doit  être donné après que la fonction se termine. Si la bibliothèque d'audit ne
       fait qu'observer les associations de symboles, elle devrait  renvoyer  sym->st_value.  Une
       valeur  différente  peut être renvoyée si la bibliothèque souhaite rediriger le contrôle à
       un autre endroit.

   la_pltenter()
       Le nom et les  types  des  paramètres  de  cette  fonction  dépendent  de  la  plate-forme
       matérielle.  (la définition appropriée est fournie par <link.h>.) Voici la définition pour
       la plate-forme x86-32 :

       Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
                        uintptr_t *refcook, uintptr_t *defcook,
                        La_i86_regs *regs, unsigned int *flags,
                        const char *symname, long *framesizep);

       Cette fonction est appelée juste avant l'appel d'une entrée de la PLT, entre  deux  objets
       partagés ayant été marqués pour la notification des associations.

       Les paramètres sym, ndx, refcook, defcook et symname sont comme pour la_symbind*().

       Le  paramètre  regs  pointe  vers  une  structure (définie dans <link.h>) qui contient les
       valeurs des registres à utiliser pour l'appel à cette entrée de la PLT.

       Le paramètre flags pointe vers une masque de bits qui, comme pour  la_symbind*(),  fournit
       des  informations  pour cette entrée de la PLT et peut être utilisé pour modifier la façon
       dont elle sera surveillée ultérieurement.

       The framesizep argument points to a long int buffer that can be used to explicitly set the
       frame  size  used  for the call to this PLT entry. If different la_pltenter()  invocations
       for this symbol return different values, then the maximum  returned  value  is  used.  The
       la_pltexit() function is called only if this buffer is explicitly set to a suitable value.

       La valeur de retour de la_pltenter() est comme pour la_symbind*().

   la_pltexit()
       Le  nom  et  les  types  des  paramètres  de  cette  fonction  dépendent de la plate-forme
       matérielle. (la définition appropriée est fournie par <link.h>.) Voici la définition  pour
       la plate-forme x86-32 :

       unsigned int la_i86_gnu_pltexit(Elf32_Sym *sym, unsigned int ndx,
                        uintptr_t *refcook, uintptr_t *defcook,
                        const La_i86_regs *inregs, La_i86_retval *outregs,
                        const char *symname);

       Cette  fonction  est  appelée quand une entrée de la PLT, créée entre deux objets partagés
       ayant été marqués pour la notification des  associations,  se  termine.  La  fonction  est
       appelée juste avant que le contrôle soit rendu à l'appelant de l'entrée de la PLT.

       Les paramètres sym, ndx, refcook, defcook et symname sont comme pour la_symbind*().

       Le  paramètre  inregs  pointe  vers une structure (définie dans <link.h>) qui contient les
       valeurs des registres utilisés pour l'appel à cette entrée de la PLT. Le paramètre outregs
       pointe  vers  une  structure (définie dans <link.h>) qui contient les valeurs de retour de
       l'appel à cette entrée de la PLT. Ces valeurs peuvent être modifiées par l'appelant et les
       modifications seront visibles pour l'appelant de l'entrée de la PLT.

       Dans l'implémentation GNU actuelle, la valeur de retour de la_pltexit() est ignorée.

STANDARDS

       Cette API n'est pas standard, mais est très proche de l'API Solaris, décrite dans le guide
       Solaris Linker and Libraries Guide, au chapitre Runtime Linker Auditing Interface.

NOTES

       Notez les différences suivantes avec l'API d'audit de l'éditeur de liens Solaris :

       •  L'interface Solaris la_objfilter() n'est pas prise en charge par l'implémentation GNU.

       •  Les fonctions Solaris la_symbind32() et la_pltexit() ne fournissent  pas  de  paramètre
          symname.

       •  La  fonction  Solaris  la_pltexit() ne fournit pas de paramètre inregs ou outregs (mais
          fournit une paramètre retval avec la valeur de retour de la fonction).

BOGUES

       Dans les versions de  la  glibc  jusqu'à  la  version 2.9  (inclue),  fournit  plus  d'une
       bibliothèque  d'audit  dans LD_AUDIT provoquait un crash à l'exécution. Cela a été corrigé
       dans la version 2.10.

EXEMPLES

       #include <link.h>
       #include <stdio.h>

       unsigned int
       la_version(unsigned int version)
       {
           printf("la_version(): version = %u; LAV_CURRENT = %u\n",
                   version, LAV_CURRENT);

           return LAV_CURRENT;
       }

       char *
       la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag)
       {
           printf("la_objsearch(): name = %s; cookie = %p", name, cookie);
           printf("; flag = %s\n",
                   (flag == LA_SER_ORIG) ? "LA_SER_ORIG" :
                   (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" :
                   (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" :
                   (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" :
                   (flag == LA_SER_CONFIG) ? "LA_SER_CONFIG" :
                   (flag == LA_SER_SECURE) ? "LA_SER_SECURE" :
                   "???");

           return name;
       }

       void
       la_activity (uintptr_t *cookie, unsigned int flag)
       {
           printf("la_activity(): cookie = %p; flag = %s\n", cookie,
                   (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" :
                   (flag == LA_ACT_ADD) ? "LA_ACT_ADD" :
                   (flag == LA_ACT_DELETE) ? "LA_ACT_DELETE" :
                   "???");
       }

       unsigned int
       la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie)
       {
           printf("la_objopen(): loading \"%s\"; lmid = %s; cookie=%p\n",
                   map->l_name,
                   (lmid == LM_ID_BASE) ? "LM_ID_BASE" :
                   (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" :
                   "???",
                   cookie);

           return LA_FLG_BINDTO | LA_FLG_BINDFROM;
       }

       unsigned int
       la_objclose (uintptr_t *cookie)
       {
           printf("la_objclose(): %p\n", cookie);

           return 0;
       }

       void
       la_preinit(uintptr_t *cookie)
       {
           printf("la_preinit(): %p\n", cookie);
       }

       uintptr_t
       la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook,
               uintptr_t *defcook, unsigned int *flags, const char *symname)
       {
           printf("la_symbind32(): symname = %s; sym->st_value = %p\n",
                   symname, sym->st_value);
           printf("        ndx = %u; flags = %#x", ndx, *flags);
           printf("; refcook = %p; defcook = %p\n", refcook, defcook);

           return sym->st_value;
       }

       uintptr_t
       la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook,
               uintptr_t *defcook, unsigned int *flags, const char *symname)
       {
           printf("la_symbind64(): symname = %s; sym->st_value = %p\n",
                   symname, sym->st_value);
           printf("        ndx = %u; flags = %#x", ndx, *flags);
           printf("; refcook = %p; defcook = %p\n", refcook, defcook);

           return sym->st_value;
       }

       Elf32_Addr
       la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
               uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs,
               unsigned int *flags, const char *symname, long *framesizep)
       {
           printf("la_i86_gnu_pltenter(): %s (%p)\n", symname, sym->st_value);

           return sym->st_value;
       }

VOIR AUSSI

       ldd(1), dlopen(3), ld.so(8), ldconfig(8)

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> et David Prévot <david@tilapin.org>

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