Provided by: manpages-fr_3.32d0.2p4-1_all bug

NOM

       rtld-audit - API d'audit pour l'editeur de liens dynamique

SYNOPSIS

       #define _GNU_SOURCE /* Consultez feature_test_macros(7) */

       #include <link.h>

DESCRIPTION

       L'editeur  de  liens  dynamique  GNU (l'editeur de liens a l'execution)
       fournit une API d'audit qui permet a une  application  d'etre  notifiee
       quand  differents  evenements  lies  a  l'edition de liens surviennent.
       Cette  API  est  tres  similaire  a  l'interface  d'audit  fournie  par
       l'editeur  de  liens  Solaris. Les constantes et prototypes necessaires
       sont definis en incluant <link.h>.

       Pour utiliser cette interface, le  programmeur  cree  une  bibliotheque
       partagee  qui  implemente  un  ensemble  standard de noms de fonctions.
       Toutes les fonctions n'ont pas a etre implementees :  dans  la  plupart
       des cas, si le programmeur n'est pas interesse dans une certaine classe
       d'evenements d'audit, alors aucune implementation n'a  a  etre  fournie
       pour la fonction d'audit correspondante.

       Pour utiliser l'interface d'audit, la variable d'environnement LD_AUDIT
       doit etre definie avec une liste de bibliotheques  partagees,  separees
       par  des  << deux-points >>,  qui  peuvent  implementer  l'API  (ou une
       partie) d'audit. Quand un evenement pouvant etre surveille survient, la
       fonction  correspondante  est  appelee  dans  chaque bibliotheque, dans
       l'ordre ou sont listees les bibliotheques.

   la_version()

       unsigned int la_version(unsigned int version);

       Il  s'agit  de  la  seule  fonction  qui  doit  etre  definie  par  une
       bibliotheque  d'audit :  elle  effectue  la presentation initiale entre
       l'editeur de liens et la bibliotheque d'audit. Lorsque  cette  fonction
       est appelee, l'editeur de liens passe, dans version, la version la plus
       importante  de  l'interface  d'audit  qui  soit  prise  en  charge  par
       l'editeur  de  liens.  Si  necessaire,  la  bibliotheque  d'audit  peut
       verifier que cette version suffit a ses besoins.

       En retour, cette fonction  doit  renvoyer  la  version  de  l'interface
       d'audit  que  cette  bibliotheque d'audit va utiliser (renvoyer version
       est permis). Si la valeur de retour est 0 ou une version  superieure  a
       celle  prise  en  charge  par l'editeur de liens, alors la bibliotheque
       d'audit est ignoree.

   la_objsearch()

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

       L'editeur de liens appelle cette fonction pour informer la bibliotheque
       d'audit  qu'il  va  se  mettre  a  la  recherche d'un objet partage. Le
       parametre name  est  le  nom  de  fichier  ou  le  chemin  dans  lequel
       s'effectue  la  recherche.  cookie  identifie  l'objet  partage  qui  a
       declenche la recherche. flag est l'une des valeurs suivantes :

       LA_SER_ORIG      Il  s'agit  du  nom  de  depart   de   la   recherche.
                        Generalement   ce   nom   provient  d'une  entree  ELF
                        DT_NEEDED  ou  est  le  parametre  filename  fourni  a
                        dlopen(3).

       LA_SER_LIBPATH   name  a  ete  cree  en utilisant un repertoire indique
                        dans LD_LIBRARY_PATH.

       LA_SER_RUNPATH   name a ete cree en  utilisant  un  repertoire  indique
                        dans une liste ELF DT_RPATH ou DT_RUNPATH.

       LA_SER_CONFIG    name   a   ete   trouve   par   le  cache  ldconfig(8)
                        (/etc/ld.so.cache).

       LA_SER_DEFAULT   name a ete  trouve  par  une  recherche  dans  un  des
                        repertoires par defaut.

       LA_SER_SECURE    name  est  specifique a un objet sur (pas utilise sous
                        Linux).

       la_objsearch() renvoie comme valeur de retour le chemin  que  l'editeur
       de  liens  devrait  utiliser pour les operations suivantes. Si NULL est
       renvoye, alors le chemin est ignore par la suite. Les bibliotheques qui
       ne  cherche  qu'a  observer les chemins de recherche devraient renvoyer
       name.

   la_activity()

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

       L'editeur de liens appelle cette fonction pour informer la bibliotheque
       d'audit  d'activites sur la table des liens. cookie identifie l'objet a
       la tete de la table. Quand l'editeur de liens appelle  cette  fonction,
       flag vaut l'une des valeurs suivantes :

       LA_ACT_ADD         De nouveaux objets sont ajoutes a la table.

       LA_ACT_DELETE      Des objets sont retires d ela table.

       LA_ACT_CONSISTENT  L'activite  sur la table est terminee : la table est
                          de nouveau coherente.

   la_objopen()

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

       L'editeur de liens appelle cette fonction quand un nouvel objet partage
       est  charge.  Le  parametre map est un pointeur vers la structure d'une
       table de liens qui decrit l'objet. Le champ lmid prend une des  valeurs
       suivantes :

       LM_ID_BASE       La table fait partie de l'espace de noms de depart.

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

       cookie est un pointeur vers un identifiant pour un objet. L'identifiant
       est fourni aux appels suivants des fonctions de la bibliotheque d'audit
       afin d'identifier l'objet. L'identifiant est  initialise  pour  pointer
       vers  la  table  de  l'objet, mais la bibliotheque d'audit peut changer
       l'identifiant pour une autre valeur qu'elle prefererait  utiliser  pour
       identifier l'objet.

       la_objopen()  renvoie  comme valeur de retour un masque de bits cree en
       combinant zero ou plusieurs constantes  avec  un  OU  binaire,  ce  qui
       permet   a  la  bibliotheque  d'audit  de  selectionner  les  objets  a
       surveiller avec les fonctions la_symbind*() :

       LA_FLG_BINDTO    Surveiller les associations de symboles a 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 a surveiller pour cet objet.

   la_objclose()

       unsigned int la_objclose(uintptr_t *cookie);

       L'editeur de liens appelle cette fonction apres l'execution du code  de
       finalisation  pour  l'objet  (s'il  y  en a), et avant que l'objet soit
       decharge. Le parametre cookie  est  l'identifiant  obtenu  par  l'appel
       precedent a la_objopen().

       Dans  l'implementation  actuelle,  la valeur renvoyee par la_objclose()
       est ignoree.

   la_preinit()

       void la_preinit(uintptr_t *cookie);

       L'editeur de liens appelle cette fonction apres  que  tous  les  objets
       partages   ont  ete  charges,  avant  que  le  controle  soit  donne  a
       l'application (c'est-a-dire avant l'appel a 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'editeur  de  liens appelle une de ces fonctions quand une association
       de symbole survient entre deux objets  partages  qui  ont  ete  marques
       comme etant surveilles par la_objopen(). La fonction la_symbind32() est
       utilisee pour les plate-formes 32 bits ; la fonction la_symbind64() est
       utilisee pour les plate-formes 64 bits.

       Le  parametre  sym  est  un pointeur vers une structure qui fournit des
       informations sur le symbole en cours d'association. La definition de la
       structure  se  trouve  dans  <elf.h>. Parmi les champs de la structure,
       st_value indique l'adresse a laquelle le symbole est associe.

       Le parametre ndx fournit l'index du symbole dans la table des  symboles
       de l'objet partage associe.

       Le parametre refcook identifie l'objet partage qui cree la reference du
       symbole ;  il  s'agit  du  meme  identifiant  fourni  a   la   fonction
       la_objopen()  qui  a  renvoye  LA_FLG_BINDFROM.  Le  parametre  defcook
       identifie l'objet partage qui defini le symbole reference ;  il  s'agit
       du  meme  identifiant  fourni  a la fonction la_objopen() qui a renvoye
       LA_FLG_BINDTO.

       Le parametre symname  pointe  vers  une  chaine  contenant  le  nom  du
       symbole.

       Le parametre flags est un masque de bits qui peut a la fois fournir des
       informations sur le symbole et etre utilise pour modifier  encore  plus
       la  surveillance  de  cette entree de la PLT (Procedure Linkage Table).
       L'editeur de liens dynamique peut fournir les  bits  suivants  dans  ce
       parametre :

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

       LA_SYMB_ALTVALUE      Un  appel precedent a la_symbind*() a renvoye une
                             autre valeur pour ce symbole.

       Par  defaut,  si  la  bibliotheque  d'audit  implemente  les  fonctions
       la_pltenter()  et  la_pltexit()  (voir ci-dessous), alors ces fonctions
       sont appelees, apres la_symbind(), pour les entrees de la PLT, a chaque
       fois  que  le symbole est reference. Les drapeaux suivants peuvent etre
       fournis en les combinant avec un OU binaire dans *flags  pour  modifier
       ce comportement par defaut :

       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 a
       laquelle le controle doit etre donne apres que la fonction se  termine.
       Si  la  bibliotheque  d'audit  ne  fait qu'observer les associations de
       symboles, elle devrait renvoyer  sym->st_name.  Une  valeur  differente
       peut  etre renvoyee si la bibliotheque souhaite rediriger le controle a
       un autre endroit.

   la_pltenter()
       Le nom et les types des parametres de cette fonction  dependent  de  la
       plate-forme  materielle.  (la  definition  appropriee  est  fournie par
       <link.h>.) Voici la definition 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 int *framesizep);

       Cette fonction est appelee juste avant l'appel d'une entree de la  PLT,
       entre  deux  objets partages ayant ete marques pour la notification des
       associations.

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

       Le parametre regs pointe vers une structure (definie dans <link.h>) qui
       contient les valeurs des registres a  utiliser  pour  l'appel  a  cette
       entree de la PLT.

       Le  parametre  flags  pointe  vers  une  masque de bits qui, comme pour
       la_symbind*(), fournit des informations pour cette entree de la PLT  et
       peut  etre  utilise  pour  modifier  la facon dont elle sera surveillee
       ulterieurement.

       Le parametre framesizep pointe vers un long int qui peut  etre  utilise
       pour  definir explicitement la taille de la trame utilisee pour l'appel
       a cette entree de la PLT. Si differents appels a la_pltenter() pour  ce
       symbole   renvoient  differentes  valeurs,  alors  la  valeur  maximale
       renvoyee est utilisee. La fonction la_pltenter() n'est appelee  que  si
       ce pointeur est explicitement definit avec une valeur convenable.

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

   la_pltexit()
       Le  nom  et  les types des parametres de cette fonction dependent de la
       plate-forme materielle.  (la  definition  appropriee  est  fournie  par
       <link.h>.) Voici la definition 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 appelee quand une entree de la PLT, creee entre deux
       objets  partages  ayant  ete   marques   pour   la   notification   des
       associations,  se  termine.  La fonction est appelee juste avant que le
       controle soit rendu a l'appelant de l'entree de la PLT.

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

       Le  parametre  inregs pointe vers une structure (definie dans <link.h>)
       qui contient les valeurs des registres utilises pour  l'appel  a  cette
       entree  de  la  PLT.  Le  parametre  outregs  pointe vers une structure
       (definie dans <link.h>) qui contient les valeurs de retour de l'appel a
       cette  entree  de  la  PLT.  Ces  valeurs  peuvent  etre  modifiees par
       l'appelant et les modifications  seront  visibles  pour  l'appelant  de
       l'entree de la PLT.

       Dans l'implementation GNU actuelle, la valeur de retour de la_pltexit()
       est ignoree.

CONFORMIT'E

       Cette API n'est pas standard, mais est tres proche  de  l'API  Solaris,
       decrite  dans  le guide Solaris Linker and Libraries Guide, au chapitre
       Runtime Linker Auditing Interface.

NOTES

       Notez les differences suivantes avec  l'API  d'audit  de  l'editeur  de
       liens Solaris :

       *  L'interface  Solaris  la_objfilter()  n'est  pas prise en charge par
          l'implementation GNU.

       *  Les fonctions Solaris la_symbind32() et la_pltexit() ne  fournissent
          pas de parametre symname.

       *  La  fonction Solaris la_pltexit() ne fournit pas de parametre inregs
          ou outregs (mais fournit une parametre  retval  avec  la  valeur  de
          retour de la fonction).

EXEMPLE

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

       unsigned int
       la_version(unsigned int version)
       {
           printf("la_version(): %d\n", version);

           return version;
       }

       char *
       la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag)
       {
           printf("la_objsearch(): name = %s; cookie = %x", 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 = %x; 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=%x\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(): %x\n", cookie);

           return 0;
       }

       void
       la_preinit(uintptr_t *cookie)
       {
           printf("la_preinit(): %x\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 = %d; flags = 0x%x", ndx, *flags);
           printf("; refcook = %x; defcook = %x\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 = %d; flags = 0x%x", ndx, *flags);
           printf("; refcook = %x; defcook = %x\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 int *framesizep)
       {
           printf("la_i86_gnu_pltenter(): %s (%p)\n", symname, sym->st_value);

           return sym->st_value;
       }

BOGUES

       Dans  les versions de la glibc jusqu'a la version 2.9 (inclue), fournit
       plus d'une bibliotheque d'audit dans LD_AUDIT  provoquait  un  crash  a
       l'execution. Cela a ete corrige dans la version 2.10.

VOIR AUSSI

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

COLOPHON

       Cette  page  fait  partie  de  la  publication 3.32 du projet man-pages
       Linux. Une description du projet et des instructions pour signaler  des
       anomalies       peuvent       etre       trouvees      a      l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis 2010, cette traduction est maintenue a l'aide  de  l'outil  po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'equipe   de   traduction
       francophone       au       sein        du        projet        perkamon
       <URL:http://perkamon.alioth.debian.org/>.

       Nicolas   Francois   et   l'equipe   francophone   de   traduction   de
       Debian (2006-2009).

       Veuillez  signaler  toute  erreur   de   traduction   en   ecrivant   a
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous pouvez toujours avoir acces a la version anglaise de  ce  document
       en utilisant la commande << man -L C <section> <page_de_man> >>.