NOME

       dlclose, dlerror, dlopen, dlsym - Interface de programação do carregador de bibliotecas dinâmicas.

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ÇÃO

       dlopen  Carrega  uma  biblioteca dinâmica do arquivo designado pela string filename e retorna um "handle"
       para a biblioteca.  Se filename não for um path absoluto (não começar com "/"), o arquivo será  procurado
       nos seguintes locais:

              Uma lista de diretórios separados por ponto-e-vírgula na variável de ambiente LD_LIBRARY_PATH

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

              /usr/lib e /lib.

       Se filename for NULL, o handle designará o programa principal.

       As  referências externas da biblioteca são definidas usando as bibliotecas na lista de dependências desta
       biblioteca ou de quaisquer outras bibliotecas abertas como  flag  RTLD_GLOBAL  .   Se  o  executável  foi
       linkado  com  o  flag  "-rdynamic",  os  símbolos  globais no executável também serão usados para definir
       referências numa biblioteca carregada dinamicamente.

       flag pode ser RTLD_LAZY, que faz que os símbolos não definidos sejam pesquisados durante a  execução,  ou
       RTLD_NOW, que faz que todos os símbolos não definidos sejam pesquisados antes que dlopen retorne, e falhe
       se  não  puder  fazê-lo.  A opção RTLD_GLOBAL pode ser acrescentada (com OR) a flag, o que faz com que os
       símbolos  externos  definidos  na  biblioteca  sejam  disponibilizados  para  as  bibliotecas  carregadas
       posteriormente.

       Se a biblioteca exportar uma rotina chamada _init, este código será executado antes do retorno de dlopen.
       Se  uma  mesma biblioteca for carregada duas vezes, será retornado o mesmo handle. A biblioteca dl mantém
       uma contagem de links, e a biblioteca não será dealocada até que dlclose seja chamada o mesmo  número  de
       vezes que dlopen tenha sido usada com sucesso.

       Se  dlopen  falhar por qualquer motivo, ela retornará NULL. Uma mensagem de texto descrevendo o erro mais
       recente gerado pelas funções dlopen, dlsym ou dlclose pode ser obtida  com  dlerror().   dlerror  retorna
       NULL  se  não  tiver  ocorrido nenhum erro desde a inicialização ou desde que ela foi chamada pela última
       vez. Chamar dlerror() duas vezes seguidas sempre fará com que a segunda chamada retorne NULL.  dlsym pega
       o handle de uma biblioteca e o noe do símbolo e retorna o endereço onde este símbolo se  encontra.  Se  o
       símbolo  não  for  encontrado,  retorna  NULL.  O  modo  certo de identificar um erro do dlsym é gravar o
       resultado de dlerror em uma variável e ver se o resultado é NULL.  Isto ocorre porque o valor do  símbolo
       pode  ser  NULL.  Também  é  necessário  armazenar o resultado de dlerror em uma variável porque, se esta
       função for chamada novamente, ela retornará NULL.

       dlclose decrementa a contagem do handle da biblioteca dinâmica. Se esta contagem  chegar  a  zero  e  não
       houver  outra  biblioteca  usando  símbolos  desta  biblioteca,  ela é descarregada. Se houver uma rotina
       chamada _fini, ela será executada imediatamente antes de a biblioteca ser descarregada.

EXEMPLOS

       Carregar a biblioteca de matemática 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ÉDITOS

       A interface dlopen surgiu no Solaris. A implementação 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ÉM

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

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

       Paulo César Mendes <drpc@ism.com.br> (tradução) xxxxxxxxxxxxxxxxxxxxxxxxx <xxx@xxxxxx.xxx.xx> (revisão)

Linux                                              16 May 1995                                         DLOPEN(3)