.\" -*- nroff -*-
.\" Copyright 1995 Yggdrasil Computing, Incorporated.
.\" written by Adam J. Richter (adam@yggdrasil.com),
.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com).
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.\" Modified by David A. Wheeler <dwheeler@dwheeler.com> 2000-11-28.
.\" Applied patch by Terran Melconian, aeb, 2001-12-14
.\"
.\" Traducido por Miguel Pérez Ibars <mpi79470@alu.um.es> el 10-julio-2004
.\"
.TH DLOPEN 3 "14 diciembre 2001" "Linux" "Manual del Programador de Linux"
.SH NOMBRE
dlclose, dlerror, dlopen, dlsym \- Interfaz de programación con el cargador de enlace dinámico
.SH SINOPSIS
.B #include <dlfcn.h>
.sp
.BI "void *dlopen(const char *" filename ", int " flag );
.br
.BI "const char *dlerror(void);"
.br
.BI "void *dlsym(void *" handle ", char *" symbol );
.br
.BI "int dlclose(void *" handle );
.sp
Símbolos especiales:
.BR "_init" ", " "_fini" .
.SH DESCRIPCIÓN
.B dlopen
carga una biblioteca dinámica del fichero dado por la cadena terminada
en null
.I filename
y devuelve un "manejador" (handle) opaco para la biblioteca dinámica.
Si
.I filename
no es una ruta absoluta (es decir, no comienza por "/"), se busca
el fichero en las siguientes localizaciones:
.RS
.PP
Una lista de directorios separados por puntos en la 
variable de entorno \fBLD_LIBRARY_PATH\fP del usuario.
.PP
La lista de bibliotecas puestas en caché en \fI/etc/ld.so.cache\fP.
.PP
\fI/lib\fP, seguido de \fI/usr/lib\fP.
.RE
.PP
Si
.I filename
es un puntero NULL, el manejador devuelto es para el programa principal.
.PP
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
.B 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.
.PP
.I flag
debe ser o bien
.BR 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
.BR RTLD_NOW ,
lo que significa que se deben resolver todos los símbolos no definidos
antes de que
.B dlopen
regrese, y falla si esto no puede hacerse.
Opcionalmente,
.B RTLD_GLOBAL
puede añadirse a
.IR 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.
.PP
Si la biblioteca exporta una rutina llamada
.BR _init ,
ese código se ejecuta antes de que dlopen regrese.
Si la misma biblioteca se carga dos veces con
.BR 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
.B dlclose
no se haya invocado sobre ella tantas veces como
.B dlopen
se haya ejecutado con éxito sobre la misma.
.PP
Si
.B 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
.BR dlerror() .
.B dlerror
devuelve NULL si no ha ocurrido ningún error desde la inicialización o desde
que fue llamada por última vez. (Llamar a
.B dlerror()
dos veces consecutivas, siempre provocará que la segunda llamada devuelva
NULL.)

.B 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ó,
.B dlsym
devuelve NULL; sin embargo, la manera correcta de comprobar un error de
.B dlsym
es guardar el resultado de
.B 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
.B dlerror
en una variable, porque si se llama otra vez a
.B dlerror
devolverá NULL.
.PP
Hay dos pseudo-manejadores especiales,
.B RTLD_DEFAULT
y
.BR 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"
(\fIwrapper\fR) alrededor de una función en otra biblioteca
compartida.
.PP
.B dlclose
decrementa la cuenta de referencias sobre el manejador de biblioteca dinámica
.IR 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
.BR _fini ,
esa rutina es llamada justo antes de que la biblioteca sea descargada.
.SH "VALOR DEVUELTO"
.B dlclose
devuelve 0 en caso de éxito y un valor distinto de cero en caso de error.
.SH EJEMPLO
.B Carga la biblioteca matemática e imprime el coseno de 2.0:
.RS
.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 ("libm.so", RTLD_LAZY);
    if (!handle) {
        fprintf (stderr, "%s\en", dlerror());
        exit(1);
    }

    cosine = dlsym(handle, "cos");
    if ((error = dlerror()) != NULL)  {
        fprintf (stderr, "%s\en", error);
        exit(1);
    }

    printf ("%f\en", (*cosine)(2.0));
    dlclose(handle);
    return 0;
}
.if t .ft P
.fi
.RE
.PP
Si este programa estuviera en un fichero llamado "foo.c", podría construir
el programa con la siguiente orden:
.RS
.LP
gcc -rdynamic -o foo foo.c -ldl
.RE
.SH OBSERVACIONES
Los símbolos RTLD_DEFAULT y RTLD_NEXT están definidos por
.I <dlfcn.h>
sólo cuando se definió _GNU_SOURCE antes de incluir dicho fichero
cabecera.
.SH HISTORIA
La interfaz estándar dlopen viene de SunOS.
.\" .SH ACKNOWLEDGEMENTS
.\" The Linux dlopen implementation was primarily written by
.\" Eric Youngdale with help from Mitch D'Souza, David Engel,
.\" Hongjiu Lu, Andreas Schwab and others.
.\" The manual page was written by Adam Richter.
.SH "VÉASE TAMBIÉN"
.BR ld (1),
.BR ld.so (8),
.BR ldconfig (8),
.BR ldd (1),
.B ld.so.info