Provided by: manpages-pt-dev_20040726-4_all bug

NOME

       dlclose,   dlerror,   dlopen,  dlsym  -  Interface  de  programacao  do
       carregador de bibliotecas dinamicas.

SINOPSE

       #include <dlfcn.h>

       void *dlopen (const char *filename, int flag);
       const char *dlerror(void);
       void *dlsym(void *handle, char *symbol);
       int dlclose (void *handle);

       Special symbols: _init, _fini.

DESCRI,C~AO

       dlopen Carrega uma biblioteca dinamica do arquivo designado pela string
       filename  e retorna um "handle" para a biblioteca.  Se filename nao for
       um path absoluto (nao comecar com "/"), o arquivo  sera  procurado  nos
       seguintes locais:

              Uma   lista  de  diretorios  separados  por  ponto-e-virgula  na
              variavel de ambiente LD_LIBRARY_PATH

              A lista de bibliotecas em /etc/ld.so.cache.

              /usr/lib e /lib.

       Se filename for NULL, o handle designara o programa principal.

       As  referencias  externas  da  biblioteca  sao  definidas   usando   as
       bibliotecas  na  lista de dependencias desta biblioteca ou de quaisquer
       outras bibliotecas abertas como flag RTLD_GLOBAL .  Se o executavel foi
       linkado  com  o  flag  "-rdynamic",  os  simbolos globais no executavel
       tambem serao usados para definir referencias numa biblioteca  carregada
       dinamicamente.

       flag  pode  ser  RTLD_LAZY, que faz que os simbolos nao definidos sejam
       pesquisados durante a execucao, ou  RTLD_NOW,  que  faz  que  todos  os
       simbolos  nao  definidos  sejam pesquisados antes que dlopen retorne, e
       falhe se nao puder faze-lo.  A opcao RTLD_GLOBAL pode ser  acrescentada
       (com  OR)  a  flag, o que faz com que os simbolos externos definidos na
       biblioteca  sejam  disponibilizados  para  as  bibliotecas   carregadas
       posteriormente.

       Se  a  biblioteca  exportar  uma rotina chamada _init, este codigo sera
       executado antes do retorno de dlopen.   Se  uma  mesma  biblioteca  for
       carregada  duas  vezes,  sera retornado o mesmo handle. A biblioteca dl
       mantem uma contagem de links, e a biblioteca nao sera dealocada ate que
       dlclose  seja  chamada  o  mesmo  numero de vezes que dlopen tenha sido
       usada com sucesso.

       Se dlopen falhar por qualquer motivo, ela retornara NULL. Uma  mensagem
       de  texto  descrevendo o erro mais recente gerado pelas funcoes dlopen,
       dlsym ou dlclose pode ser obtida com dlerror().  dlerror  retorna  NULL
       se  nao  tiver  ocorrido nenhum erro desde a inicializacao ou desde que
       ela foi chamada pela ultima vez. Chamar dlerror() duas  vezes  seguidas
       sempre  fara  com  que  a  segunda  chamada retorne NULL.  dlsym pega o
       handle de uma biblioteca e o noe do simbolo e retorna o  endereco  onde
       este  simbolo  se  encontra.  Se  o simbolo nao for encontrado, retorna
       NULL. O modo certo de identificar um erro do dlsym e gravar o resultado
       de  dlerror  em  uma variavel e ver se o resultado e NULL.  Isto ocorre
       porque o valor do simbolo pode ser NULL. Tambem e necessario  armazenar
       o  resultado  de  dlerror  em  uma  variavel porque, se esta funcao for
       chamada novamente, ela retornara NULL.

       dlclose decrementa a contagem do handle da biblioteca dinamica. Se esta
       contagem  chegar  a  zero e nao houver outra biblioteca usando simbolos
       desta biblioteca, ela e descarregada.  Se  houver  uma  rotina  chamada
       _fini,  ela  sera  executada  imediatamente  antes  de a biblioteca ser
       descarregada.

EXEMPLOS

       Carregar a biblioteca de matem'atica e calcular o coseno de 2.0:
              #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);
              }

              Se este  programa  estivesse  num  arquivo  chamado  "foo.c",  o
              programa seria compilado com o comando

                     gcc -rdynamic -o foo foo.c -ldl

       Idem, mas fazendo checagem de erros a cada passo:
              #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, "%s0, error);
                      exit(1);
                  }

                  printf ("%f\n", (*cosine)(2.0));
                  dlclose(handle);
              }

CR'EDITOS

       A interface dlopen surgiu no Solaris. A implementacao 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.

VER TAMB'EM

       ld(1), ld.so(8), ldconfig(8), ldd(1), ld.so.info.

TRADUZIDO POR LDP-BR em 21/08/2000.

       Paulo       Cesar       Mendes       <drpc@ism.com.br>       (traducao)
       xxxxxxxxxxxxxxxxxxxxxxxxx <xxx@xxxxxx.xxx.xx> (revisao)