Provided by:
manpages-es_1.55-3_all 
NOMBRE
dlclose, dlerror, dlopen, dlsym - Interfaz de programación con el
cargador de enlace dinámico
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);
Símbolos especiales: _init, _fini.
DESCRIPCIÓN
dlopen carga una biblioteca dinámica del fichero dado por la cadena
terminada en null filename y devuelve un "manejador" (handle) opaco
para la biblioteca dinámica. 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 caché 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 opción RTLD_GLOBAL. Si el
ejecutable fue enlazado con la opción "-rdynamic", los símbolos
globales del ejecutable también se utilizarán para resolver referencias
en una biblioteca cargada dinámicamente.
flag debe ser o bien RTLD_LAZY, lo que significa que los símbolos no
definidos se resolverán cuando se ejecute el código de la biblioteca
dinámica, o RTLD_NOW, lo que significa que se deben resolver todos los
símbolos no definidos antes de que dlopen regrese, y falla si esto no
puede hacerse. Opcionalmente, RTLD_GLOBAL puede añadirse a flag,
mediante una operación OR, en cuyo caso los símbolos externos definidos
en la biblioteca se hacen disponibles para las bibliotecas cargadas
posteriormente.
Si la biblioteca exporta una rutina llamada _init, ese código 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
dinámicos, por lo que una biblioteca dinámica no se descargará hasta
que dlclose no se haya invocado sobre ella tantas veces como dlopen se
haya ejecutado con éxito sobre la misma.
Si dlopen falla por alguna razón se devuelve NULL. Se puede extraer
una cadena que describa el error más reciente que ocurrió en cualquiera
de las rutinas dl (dlopen, dlsyn o dlclose) en un formato entendible
por el usuario con la función dlerror(). dlerror devuelve NULL si no
ha ocurrido ningún error desde la inicialización o desde que fue
llamada por última vez. (Llamar a dlerror() dos veces consecutivas,
siempre provocará que la segunda llamada devuelva NULL.)
dlsym toma el manejador de una biblioteca dinámica devuelto por dlopen
y el nombre del símbolo terminado en null y devuelve la dirección donde
se ha cargado ese símbolo. Si el símbolo no se encontró, 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 así porque el valor del símbolo
podría ser realmente NULL. También es necesario guardar los resultados
de dlerror en una variable, porque si se llama otra vez a dlerror
devolverá NULL.
Hay dos pseudo-manejadores especiales, RTLD_DEFAULT y RTLD_NEXT. El
primero buscará la primera ocurrencia del símbolo deseado usando el
orden de búsqueda de bibliotecas por defecto. El segundo, que sólo se
puede usar desde dentro de una biblioteca dinámica, buscará la
siguiente ocurrencia de una función en el orden de búsqueda tras la
biblioteca actual. Esto nos permite proporcionar un "envoltorio"
(wrapper) alrededor de una función en otra biblioteca compartida.
dlclose decrementa la cuenta de referencias sobre el manejador de
biblioteca dinámica handle. Si la cuenta de referencias llega a cero y
ninguna biblioteca cargada usa los símbolos en ella, la biblioteca
dinámica se descarga. Si la biblioteca dinámica 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 éxito y un valor distinto de cero en caso
de error.
EJEMPLO
Carga la biblioteca matemática 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", podría
construir el programa con la siguiente orden:
gcc -rdynamic -o foo foo.c -ldl
OBSERVACIONES
Los símbolos RTLD_DEFAULT y RTLD_NEXT están definidos por <dlfcn.h>
sólo cuando se definió _GNU_SOURCE antes de incluir dicho fichero
cabecera.
HISTORIA
La interfaz estándar dlopen viene de SunOS.
VÉASE TAMBIÉN
ld(1), ld.so(8), ldconfig(8), ldd(1), ld.so.info