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

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)