Manpages

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 [AT] ism.br> (tradução) xxxxxxxxxxxxxxxxxxxxxxxxx <xxx [AT] xxxxxx.xx> (revisão)