Provided by:
manpages-es_1.55-10_all 
NOMBRE
dlclose, dlerror, dlopen, dlsym - Interfaz de programacion con el
cargador de enlace dinamico
SINOPSIS
#include <dlfcn.h>
void *dlopen(const char *filename, int flag);
const char *dlerror(void);
void *dlsym(void *handle, char *symbol);
int dlclose(void *handle);
Simbolos especiales: _init, _fini.
DESCRIPCI'ON
dlopen carga una biblioteca dinamica del fichero dado por la cadena
terminada en null filename y devuelve un "manejador" (handle) opaco
para la biblioteca dinamica. Si filename no es una ruta absoluta (es
decir, no comienza por "/"), se busca el fichero en las siguientes
localizaciones:
Una lista de directorios separados por puntos en la variable de
entorno LD_LIBRARY_PATH del usuario.
La lista de bibliotecas puestas en cache en /etc/ld.so.cache.
/lib, seguido de /usr/lib.
Si filename es un puntero NULL, el manejador devuelto es para el
programa principal.
Las referencias externas en la biblioteca se resuelven usando las
bibliotecas en esa lista de dependencias de bibliotecas y en cualquier
otra biblioteca previamente abierta con la opcion RTLD_GLOBAL. Si el
ejecutable fue enlazado con la opcion "-rdynamic", los simbolos
globales del ejecutable tambien se utilizaran para resolver referencias
en una biblioteca cargada dinamicamente.
flag debe ser o bien RTLD_LAZY, lo que significa que los simbolos no
definidos se resolveran cuando se ejecute el codigo de la biblioteca
dinamica, o RTLD_NOW, lo que significa que se deben resolver todos los
simbolos no definidos antes de que dlopen regrese, y falla si esto no
puede hacerse. Opcionalmente, RTLD_GLOBAL puede anadirse a flag,
mediante una operacion OR, en cuyo caso los simbolos externos definidos
en la biblioteca se hacen disponibles para las bibliotecas cargadas
posteriormente.
Si la biblioteca exporta una rutina llamada _init, ese codigo se
ejecuta antes de que dlopen regrese. Si la misma biblioteca se carga
dos veces con dlopen(), se devuelve el mismo manejador. La biblioteca
dl mantiene contadores de referencias para los manejadores de ficheros
dinamicos, por lo que una biblioteca dinamica no se descargara hasta
que dlclose no se haya invocado sobre ella tantas veces como dlopen se
haya ejecutado con exito sobre la misma.
Si dlopen falla por alguna razon se devuelve NULL. Se puede extraer
una cadena que describa el error mas reciente que ocurrio en cualquiera
de las rutinas dl (dlopen, dlsyn o dlclose) en un formato entendible
por el usuario con la funcion dlerror(). dlerror devuelve NULL si no
ha ocurrido ningun error desde la inicializacion o desde que fue
llamada por ultima vez. (Llamar a dlerror() dos veces consecutivas,
siempre provocara que la segunda llamada devuelva NULL.)
dlsym toma el manejador de una biblioteca dinamica devuelto por dlopen
y el nombre del simbolo terminado en null y devuelve la direccion donde
se ha cargado ese simbolo. Si el simbolo no se encontro, dlsym devuelve
NULL; sin embargo, la manera correcta de comprobar un error de dlsym es
guardar el resultado de dlerror en una variable y comprobar si el valor
guardado es distinto de NULL. Esto es asi porque el valor del simbolo
podria ser realmente NULL. Tambien es necesario guardar los resultados
de dlerror en una variable, porque si se llama otra vez a dlerror
devolvera NULL.
Hay dos pseudo-manejadores especiales, RTLD_DEFAULT y RTLD_NEXT. El
primero buscara la primera ocurrencia del simbolo deseado usando el
orden de busqueda de bibliotecas por defecto. El segundo, que solo se
puede usar desde dentro de una biblioteca dinamica, buscara la
siguiente ocurrencia de una funcion en el orden de busqueda tras la
biblioteca actual. Esto nos permite proporcionar un "envoltorio"
(wrapper) alrededor de una funcion en otra biblioteca compartida.
dlclose decrementa la cuenta de referencias sobre el manejador de
biblioteca dinamica handle. Si la cuenta de referencias llega a cero y
ninguna biblioteca cargada usa los simbolos en ella, la biblioteca
dinamica se descarga. Si la biblioteca dinamica exporta una rutina
llamada _fini, esa rutina es llamada justo antes de que la biblioteca
sea descargada.
VALOR DEVUELTO
dlclose devuelve 0 en caso de exito y un valor distinto de cero en caso
de error.
EJEMPLO
Carga la biblioteca matem'atica e imprime el coseno de 2.0:
#include <stdio.h>
#include <dlfcn.h>
int main(int argc, char **argv) {
void *handle;
double (*cosine)(double);
char *error;
handle = dlopen ("libm.so", RTLD_LAZY);
if (!handle) {
fprintf (stderr, "%s\n", dlerror());
exit(1);
}
cosine = dlsym(handle, "cos");
if ((error = dlerror()) != NULL) {
fprintf (stderr, "%s\n", error);
exit(1);
}
printf ("%f\n", (*cosine)(2.0));
dlclose(handle);
return 0;
}
Si este programa estuviera en un fichero llamado "foo.c", podria
construir el programa con la siguiente orden:
gcc -rdynamic -o foo foo.c -ldl
OBSERVACIONES
Los simbolos RTLD_DEFAULT y RTLD_NEXT estan definidos por <dlfcn.h>
solo cuando se definio _GNU_SOURCE antes de incluir dicho fichero
cabecera.
HISTORIA
La interfaz estandar dlopen viene de SunOS.
V'EASE TAMBI'EN
ld(1), ld.so(8), ldconfig(8), ldd(1), ld.so.info