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)