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

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