.\" -*- 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.
.\"
.TH DLOPEN 3 "16 May 1995" "Linux" "Linux Programmer's Manual"
.SH NOME
dlclose, dlerror, dlopen, dlsym \- Interface de programao do carregador de bibliotecas dinmicas.
.SH SINOPSE
.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
Special symbols:
.BR "_init" ", " "_fini" ". "
.SH DESCRIO
.B dlopen
Carrega uma biblioteca dinmica do arquivo designado pela string
.I filename
e retorna um "handle" para a biblioteca.
Se
.I filename
no for um path absoluto (no comear com "/"), o arquivo ser procurado nos
seguintes locais:
.RS
.PP
Uma lista de diretrios separados por ponto-e-vrgula na varivel de ambiente
\fBLD_LIBRARY_PATH\fP 
.PP
A lista de bibliotecas em \fI/etc/ld.so.cache\fP.
.PP
\fI/usr/lib\fP e \fI/lib\fP.
.RE
.PP
Se
.I filename
for NULL, o handle designar o programa principal.
.PP
As referncias externas da biblioteca so definidas usando as bibliotecas
na lista de dependncias desta biblioteca ou de quaisquer outras bibliotecas
abertas como flag
.B RTLD_GLOBAL .
Se o executvel foi linkado com o flag "-rdynamic", os smbolos globais no 
executvel tambm sero usados para definir referncias numa biblioteca
carregada dinamicamente.
.PP
.I flag
pode ser
.BR RTLD_LAZY ,
que faz que os smbolos no definidos sejam pesquisados durante a execuo, ou
.BR RTLD_NOW ,
que faz que todos os smbolos no definidos sejam pesquisados antes que
.B dlopen
retorne, e falhe se no puder faz-lo.
A opo 
.B RTLD_GLOBAL
pode ser acrescentada (com OR) a
.IR flag,
o que faz com que os smbolos externos definidos na biblioteca sejam
disponibilizados para as bibliotecas carregadas posteriormente.
.PP
Se a biblioteca exportar uma rotina chamada
.BR _init ,
este cdigo ser executado antes do retorno de dlopen.
Se uma mesma biblioteca for carregada duas vezes, ser retornado o mesmo
handle. A biblioteca dl mantm uma contagem de links, e a biblioteca no
ser dealocada at que
.B dlclose
seja chamada o mesmo nmero de vezes que
.B dlopen
tenha sido usada com sucesso.
.PP
Se
.B dlopen
falhar por qualquer motivo, ela retornar NULL. Uma mensagem de texto descrevendo
o erro mais recente gerado pelas funes dlopen, dlsym ou dlclose pode ser obtida
com
.BR dlerror() .
.B dlerror
retorna NULL se no tiver ocorrido nenhum erro desde a inicializao ou desde que
ela foi chamada pela ltima vez. Chamar
.B dlerror()
duas vezes seguidas sempre far com que a segunda chamada retorne NULL.
.B dlsym
pega o handle de uma biblioteca e o noe do smbolo e retorna o endereo onde este
smbolo se encontra. Se o smbolo no for encontrado, retorna NULL. O modo certo de
identificar um erro do 
.B dlsym
 gravar o resultado de
.B dlerror
em uma varivel e ver se o resultado  NULL.
Isto ocorre porque o valor do smbolo pode ser NULL. Tambm  necessrio armazenar
o resultado de
.B dlerror
em uma varivel porque, se esta funo for chamada novamente, ela retornar NULL.
.PP
.B dlclose
decrementa a contagem do handle da biblioteca dinmica. Se esta contagem chegar a zero
e no houver outra biblioteca usando smbolos desta biblioteca, ela  descarregada. Se
houver uma rotina chamada
.BR _fini ,
ela ser executada imediatamente antes de a biblioteca ser descarregada.
.SH EXEMPLOS
.B Carregar a biblioteca de matemtica e calcular o coseno de 2.0:
.RS
.nf
.if t .ft CW
#include <dlfcn.h>

int main(int argc, char **argv) {
    void *handle = dlopen ("/lib/libm.so", RTLD_LAZY);
    double (*cosine)(double) = dlsym(handle, "cos");
    printf ("%f\\n", (*cosine)(2.0));
    dlclose(handle);
}
.if t .ft P
.fi
.PP
Se este programa estivesse num arquivo chamado "foo.c", o programa seria
compilado com o comando
.RS
.LP
gcc -rdynamic -o foo foo.c -ldl
.RE
.RE
.LP
.B Idem, mas fazendo checagem de erros a cada passo:
.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 ("/lib/libm.so", RTLD_LAZY);
    if (!handle) {
        fputs (dlerror(), stderr);
        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);
}
.if t .ft P
.fi
.RE
.SH CRDITOS
A interface dlopen surgiu no Solaris. A implementao linux
foi escrita por Eric Youngdale, com ajuda de Mitch D'Souza,
David Engel, Hongjiu Lu, Andreas Schwab e outros.
Esta manpage foi escrita por Adam Richter.
.SH VER TAMBM
.BR ld(1) ,
.BR ld.so(8) ,
.BR ldconfig(8) ,
.BR ldd(1) ,
.BR ld.so.info .

.SH TRADUZIDO POR LDP-BR em 21/08/2000.
\&\fR\&\f(CWPaulo Csar Mendes <drpc@ism.com.br> (traduo)\fR
\&\fR\&\f(CWxxxxxxxxxxxxxxxxxxxxxxxxx <xxx@xxxxxx.xxx.xx> (reviso)\fR