Provided by: manpages-es_1.55-10_all bug

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