Provided by:
manpages-pl-dev_20060617-1_all 
NAZWA
dlclose, dlerror, dlopen, dlsym - interfejs programisty dla dynamicznie
konsolidującego loadera
SKŁADNIA
#include <dlfcn.h>
void *dlopen(const char *filename, int flag);
const char *dlerror(void);
void *dlsym(void *handle, char *symbol);
int dlclose(void *handle);
Symbole specjalne: _init, _fini.
OPIS
dlopen ładuje bibliotekę dynamiczną z pliku, o nazwie zawartej w
zakończonym znakiem NUL łańcuchu filename i zwraca nieprzezroczysty
"uchwyt" dla tej biblioteki dynamicznej. Jeśli filename nie jest
ścieżką absolutną (np. nie rozpoczyna się od "/"), to plik jest
poszukiwany w następujących miejscach:
Rozdzielonej dwukropkami liście katalogów, zdefiniowanej w
zmiennej środowiskowej LD_LIBRARY_PATH.
Liście bibliotek podanej w /etc/ld.so.cache.
/lib, a potem w /usr/lib.
Jeśli filename jest wskaźnikiem NULL, to zwracany uchwyt wskazuje na
program główny.
Zewnętrzne odniesienia biblioteki są rozstrzygane przy użyciu bibliotek
z listy zależności danej biblioteki, oraz przy użyciu wszystkich innych
bibliotek, otwartych wcześniej ze znacznikiem RTLD_GLOBAL. Jeśli plik
wykonywalny był skonsolidowany z opcją "-rdynamic", to globalne symbole
pliku wykonywalnego będą także używane do rozstrzygania odniesień
dynamicznie załadowanych bibliotek.
flag powinna być albo RTLD_LAZY, oznaczającym rozwiązywanie
niezdefiniowanych symboli podczas wywoływania biblioteki dynamicznej,
albo RTLD_NOW, oznaczającym rozwiązanie wszystkich niezdefiniowanych
symboli zanim dlopen powróci i nie powiedzie się, jeśli nie można tego
dokonać. Ewentualnie można wykonać operację OR na parametrze flag, i
symbolu RTLD_GLOBAL, oznaczającym, że symbole zewnętrzne, zdefiniowane
w bibliotece będą udostępniane kolejno ładowanym bibliotekom.
Jeśli biblioteka eksportuje funkcję o nazwie _init, to jej kod jest
wykonywany przed powrotem dlopen. Jeśli ta sama biblioteka jest
załadowana przez dlopen() dwukrotnie, to zwracany jest ten sam uchwyt.
Biblioteka dl obsługuje liczniki dowiązań dla uchwytów plików
dynamicznych, tak więc biblioteka dynamiczna nie będzie zdealokowana
nim tylokrotnie nie zostanie wywołana funkcja dlclose, ilokrotnie użyto
dlopen.
Jeśli dlopen z jakiejś przyczyny zawiedzie, to zwraca NULL. Czytelny
dla człowieka napis, zawierający opis ostatniego błędu, który pojawił
się w którejś z funkcji dl (dlopen, dlsym lub dlclose), można wyciągnąć
przy użyciu dlerror(). dlerror zwraca NULL, jeśli od czasu
inicjalizacji lub poprzedniego wywołania dlerror nie wystąpił błąd.
(Wywołanie dlerror() dwa razy pod rząd zawsze spowoduje, że drugie
wywołanie zwróci NULL.)
dlsym pobiera "uchwyt" biblioteki dynamicznej, zwrócony przez dlopen i
zakończoną znakiem NUL nazwę symbolu. Zwraca adres, pod którym
załadowany jest ten symbol. Jeśli symbol nie zostanie znaleziony, to
dlsym zwraca NULL; jednak prawidłowym sposobem sprawdzenia czy podczas
wykonania dlsym wystąpił błąd, jest zapisanie wyniku dlerror do
zmiennej i sprawdzenie, czy wartość ta nie jest równa NULL. Jest tak
dlatego, że wartość symbolu może w rzeczywistości wynosić NULL.
Konieczne jest też zachowywanie wyników dlerror, gdyż ponowne wywołanie
dlerror zwróci NULL.
Istnieją dwa specialne pseudo-uchwyty: RTLD_DEFAULT i RTLD_NEXT.
Pierwszy z nich znajdzie pierwsze wystąpienie żądanego symbolu
korzystając z domyślnego dla biblioteki kolejności poszukiwania. Drugi
z nich, przydatny tylko wewnątrz bibliotek dynamicznych, znajdzie
następne wystąpienie funkcji dla kolejności poszukiwania obowiązującej
po załadowaniu bieżącej biblioteki. Pozwala to zastąpienie funkcji w
innej bibliotece dzielonej.
dlclose zmniejsza o jeden licznik odniesień w uchwycie bibliotek
dynamicznych handle. Jeśli licznik spada do zera a inne załadowane
biblioteki nie używają jej symboli, to biblioteka dynamiczna jest
zwalniana. Jeśli biblioteka dynamiczna eksportuje funkcję o nazwie
_fini, to jest ona wykonywana bezpośrednio przed zwolnieniem tej
biblioteki.
WARTOŚĆ ZWRACANA
dlclose zwraca 0 przy pomyślnym zakończeniu, z wartość niezerową w
przypadku błędu.
PRZYKŁAD
Załadowanie biblioteki matematycznej i wypisanie cosinusa liczby 2.0:
#include <stdio.h>
#include <dlfcn.h>
int main(int argc, char **argv) {
void *handle;
double (*cosine)(double);
char *error;
handle = dlopen ("libm.so", RTLD_LAZY);
if (!handle) {
fprintf(stderr, "%s\n", dlerror());
exit(1);
}
cosine = dlsym(handle, "cos");
if ((error = dlerror()) != NULL) {
fprintf (stderr, "%s\n", error);
exit(1);
}
printf ("%f\n", (*cosine)(2.0));
dlclose(handle);
return 0;
}
Gdyby ten program znajdował się w pliku o nazwie "foo.c", można by go
zbudować za pomocą następującego polecenia:
gcc -rdynamic -o foo foo.c -ldl
UWAGI
Symbole RTLD_DEFAULT i RTLD_NEXT są zdefiniowane w <dlfcn.h> tylko
wtedy, gdy _GNU_SOURCE było zdefiniowane przed jego włączeniem.
Standard interfejsu dlopen pochodzi z SunOS.
ZOBACZ TAKŻE
ld(1), ld.so(8), ldconfig(8), ldd(1), ld.so.info