Provided by: manpages-pl-dev_20060617-1_all bug

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