Nom

dlclose, dlerror, dlopen, dlsym - Interface de programmation pour le chargeur de bibliothèques dynamiques.

Résumé

#include <dlfcn.h> void * dlopen (const char * filename , int flag ); const char * dlerror(void); void * dlsym (void * handle , char * symbol ); int dlclose (void * handle ); Symboles spéciaux : _init , _fini .

Description

dlopen charge une bibliothèque dynamique depuis le fichier dont le nom est fourni dans la chaîne filename (terminée par un caractère nul) et renvoie un descripteur opaque ( handle ) représentant la bibliothèque dynamique. Si le nom filename n'est pas un chemin absolu (commençant pas un "/"), le fichier est recherché aux endroits suivants :

La liste des répertoires (séparés par des deux-points) contenue dans la variable d'environnement LD_LIBRARY_PATH. La liste des bibliothèques mémorisées dans /etc/ld.so.cache. /lib, puis /usr/lib.

Si l'argument filename est un pointeur NULL, le descripteur renvoyé correspond au programme principal.

Les références externes de la bibliothèque sont résolues en utilisant les bibliothèqujes mentionnées dans sa liste de dépendances, et toutes les autres bibliothèques éventuellement ouvertes auparavant avec l'attribut RTLD_GLOBAL . Si l'édition des liens de l'exécutable a été faite avec l'option "-rdynamic", alors ses symboles globaux seront également employés pour résoudre les références de la bibliothèque chargée dynamiquement.

L'attribut flag doit être soit RTLD_LAZY , indiquant que la résolution des symboles aura lieu lorsque le code sera exécuté, soit RTLD_NOW , demandant la résolution de tous les symboles indéfinis avant le retour de dlopen et l'échec de cette routine si c'est impossible. En option, on peut ajouter (avec un OU binaire) l'attribut RTLD_GLOBAL rendant les symboles externes de la bibliothèque disponible pour les bibliothèques chargées ultérieurement.

Si la bibliothèque exporte une routine nommée _init , alors ce code sera exécuté avant le retour de dlopen() . Au cas où vous voudriez éviter le lien avec les fichiers de démarrage du système, vous pouvez préciser le paramètre "-nostartfiles" sur la ligne de commande de gcc.

Si la même bibliothèque est chargée deux fois avec dlopen() , le même descripteur sera renvoyé. Un compte du nombre de chargements est toutefois conservé afin d'éviter de la décharger avant que la fonction dlclose() n'ait été appelée autant de fois que dlopen() a réussi.

Si dlopen() échoue pour une raison quelconque, elle renvoie NULL. Une chaîne de caractères en clair, décrivant la dernière erreur rencontrée dans une routine dlopen(), dlsym() ou dlclose() peut être récupérée en appelant dlerror() . La fonction dlerror() renvoie NULL si aucune erreur ne s'est produite depuis l'initialisation ou depuis sa dernière invocation (si on appelle deux fois de suite dlerror (), le second appel donnera toujours NULL). La fonction dlsym() prend un descripteur de bibliothèque dynamique renvoyée par dlopen () et un nom de symbole terminé par un caractère nul, et renvoie l'adresse où ce symbole a été chargé. Si le symbole n'est pas trouvé, dlsym() renvoie NULL. Toutefois la bonne manière de vérifier si une erreur s'est produite dans dlsym() est d'examiner le résultat de dlerror() (en le sauvegardant dans une variable). En effet, le symbole peut avoir légitimement la valeur NULL sans qu'une erreur ne se soit produite. Le fait de sauvegarder le résultat de dlerror() dans une variable pour examiner s'il est NULL est indispensable, car un second appel pour afficher l'erreur renverrait toujours NULL.

Il y a deux pseudo-handles spéciaux RTLD_DEFAULT et RTLD_NEXT . le premier recherche la première occurrence du symbole désiré en utilisant l'ordre de recherche des bibliothèques par défaut. Le second, qui ne peut servir que pour une bibliothèque dynamique, recherchera l'occurrence suivante, d'une fonction à partir de la bibliothèque en cours. Ceci permet de fournir un encadrement pour une fonction se trouvant dans une autre bibliothèque partagée.

La fonction dlclose() décrémente le nombre de références sur la bibliothèque dynamique dont le descripteur est handle . Si ce nombre descend à zéro et si aucune autre bibliothèque n'emploie des symboles exportés par celle-ci, elle est déchargée. Si la bibliothèque exporte une routine nommée _fini , alors elle est appelée juste avant le déchargement.

Valeur renvoyée

dlclose renvoie zéro si elle réussi ou une valeur non-nulle en cas d'erreur.

Exemple

Charger la bibliothèque mathématique et afficher le cosinus de 2.0 :

.nf .if t .ft CW #include <stdio.h> #include <dlfcn.h> int main(int argc, char **argv) { void *handle; double (*cosine)(double); char *error; handle = dlopen ("/lib/libm.so", RTLD_LAZY); if (!handle) { fputs (dlerror(), stderr); exit(1); } cosine = dlsym(handle, "cos"); if ((error = dlerror()) != NULL) { fprintf (stderr, "%sen", error); exit(1); } printf ("%fen", (*cosine)(2.0)); dlclose(handle); } .if t .ft P .fi

Supposons que le programme s'appelle "foo.c", on doit le compiler ainsi :

gcc -rdynamic -o foo foo.c -ldl

Une bibliothèque (disons bar.c) qui exporte _init() et _fini() sera compilée comme suit :

gcc -shared -nostartfiles -o bar bar.c

Notes

Les symboles RTLD_DEFAULT et RTLD_NEXT sont définis dans <dlfcn.h> seulement si _GNU_SOURCE a été définie avant l'inclusion.

Historique

L'interface standard dlopen provient de SunOS.

Voir aussi

ld (1), ld.so (8), ldconfig (8), ldd (1), ld.so.info

Traduction

Christophe Blaess, 2000-2003.