Provided by:
manpages-fr_3.32d0.2p4-1_all 
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> >>.