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

NAZWA

       dbopen - metody dostpu do baz danych

SK/LADNIA

       #include <sys/types.h>
       #include <limits.h>
       #include <db.h>

       DB *
       dbopen(const char *plik, int znaczniki, int tryb, DBTYPE rodzaj,
            const void *info_otw);

OPIS

       dbopen jest funkcj biblioteczn stanowic interfejs do plikow baz danych.
       Obslugiwane formaty plikow to: btree, rozproszony (hashed)  i  uniksowy
       zorientowany  na pliki.  Format btree stanowi reprezentacj posortoanej,
       zrownowaonej  struktury  drzewa.   Format  rozproszony  (hashed)   jest
       rozszerzalnym, dynamicznym schematem mieszania.  Format plaskiego pliku
       jest plikiem  stanowicym  strumie  bajtow  z  rekordami  o  stalej  lub
       zmiennej   dlugoci.    Informacje   o   formatach   i  specyficzne  dla
       poszczegolnych formatow plikow s szczegolowo  opisane  na  odpowiednich
       stronach podrcznika: btree(3), hash(3) i recno(3).

       dbopen  otwiera  plik  do  odczytu  i/lub  do  zapisu.   Pliki, ktorych
       zachowywanie na dysku nie jest  zamierzone,  mog  by  tworzone  poprzez
       ustawienie parametru plik na NULL.

       Argumenty  znaczniki i tryb s takie same jak w funkcji open(2), jednake
       brane  pod  uwag  s  jedynie  znaczniki  O_CREAT,   O_EXCL,   O_EXLOCK,
       O_NONBLOCK,  O_RDONLY,  O_RDWR,  O_SHLOCK  i O_TRUNC.  (Naley zauway, e
       otwarcie pliku bazy danych jako O_WRONLY nie jest moliwe.)

       Argument rodzaj jest typu  DBTYPE  (ktory  jest  zdefiniowany  w  pliku
       naglowkowym  <db.h>)  i  mona  przybiera  wartoci DB_BTREE, DB_HASH lub
       DB_RECNO.

       Argument info_otw jest wskanikiem do struktury specyficznej dla  metody
       dostpu,  opisanej  n  stronie  podrcznika  danej  metody  dostpu.  Jeli
       info_otw jest rowne NULL, kada z metod dostpu bdzie korzysta z  wartoci
       domylnych, wlaciwych dla systemy i tej metody dostpu.

       dbopen  przy pomylnym zakoczeniu zwraca wskanik do struktury DB, a NULL
       w przypadku bldu.  Struktura DB jest zdefiniowana w  pliku  naglowkowym
       <db.h> i zawiera co najmniej nastpujce pola:

       typedef struct {
              DBTYPE type;
              int (*close)(const DB *db);
              int (*del)(const DB *db, const DBT *klucz, u_int znaczniki);
              int (*fd)(const DB *db);
              int (*get)(const DB *db, DBT *klucz, DBT *dane, u_int znaczniki);
              int (*put)(const DB *db, DBT *klucz, const DBT *dane,
                   u_int znaczniki);
              int (*sync)(const DB *db, u_int znaczniki);
              int (*seq)(const DB *db, DBT *klucz, DBT *dane, u_int znaczniki);
       } DB;

       Elementy te opisuj rodzaj bazy danych i zestaw funkcji wykonyjcych rone
       operacje.  Funkcje te bior jako argument wskanik do  struktury  takiej,
       jak  zwracana  przez  dbopen  i,  czasami, jeden lub wicej wskanikow do
       struktur klucz/dane oraz warto znacznika.

       type   Rodzaj wlaciwej metody dostpu (i format plikow).

       close  Wskanik do funkcji zrzucajcej zbuforowane  informacje  ma  dysk,
              zwalniajcej przydzielone zasoby i zamykajcej podlegle pliki.  Ze
              wzgldu na to, e pary klucz/dane  mog  by  buforowane  w  pamici,
              niepomylne  zrzucenie  buforow  pliku za pomoc funkcji close lub
              sync ,oe prowadzi do niespojnoci lub utraty informacji.  Funkcje
              close  zwracaj  -1  w  przypadku  bldu  (ustawiajc errno), a 0 w
              przypadku zakoczenia pomylnego.

       del    Wskanik do funkcji usuwajcej pary klucz/dane z bazy danych.

              Parametr znacznik moe mie jedn z nastpujcych wartoci:

              R_CURSOR
                     Usuwa rekord wskazywany przez kursor.  Kursor musi  zosta
                     wczeniej zainicjalizowany.

              Funkcje  delete zwracaj -1 w przypadku bldu (ustawiajc errno), 0
              w przypadku pomylnego zakoczenia,  a  1  gdy  podany  klucz  nie
              wystpuje w pliku.

       fd     Wskanik  do  funkcji  zwracajcej  deskryptor  pliku odpowiadajcy
              uywanej  bazie  danych.   Dla  wszystkich  procesow  wywolujcych
              dbopen   dla  tej  samej  nazwy  pliku  plik  zostanie  zwrocony
              deskryptor pliku wskazujcy na ten sam  plik.   Tego  deskryptora
              pliku  mona  bezpiecznie  uywa jako argumentu funkcji blokujcych
              fcntl(2) i flock(2).  Deskryptor pliku nie  musi  by  zwizany  z
              ktorymkolwiek   z   plikow  uywanych  przez  dan  metod  dostpu.
              Deskryptor pliku nie jest dostpny dla  baz  danych  zawartych  w
              pamici.   Funkcje  fd  zwracaj  -1  w  przypadku bldu (ustawiajc
              errno), a deskryptor pliku w przypadku pomylnego zakoczenia.

       get    Wskanik do funkcji stanowicej interfejs dla pobierania danych  z
              bazy  wedlug klucza.  Adres i rozmiar danych zwizanych z podanym
              kluczem klucz s zwracane w strukturze  wskazywanej  przez  dane.
              Funkcje  get  zwracaj -1 w przypadku bldu (ustawiajc errno), 0 w
              przypadku  pomylnego  zakoczenia,  a  1  gdy  podany  klucz  nie
              wystpuje w pliku.

       put    Wskanik do funkcji przechowujcej pary klucz/dane w bazie danych.

              Parametr znacznik moe mie jedn z nastpujcych wartoci:

              R_CURSOR
                     Zastpuje  par  klucz/dane wskazywan przez kursor.  Kursor
                     musi zosta wczeniej zainicjalizowany.

              R_IAFTER
                     Dolcza dane  bezporednio  po  danych  wskazywanych  przez
                     klucz,  tworzc now par klucz/dane.  Numer rekordu dodanej
                     pary  klucz/dane  jest  zwracany  w   strukturze   klucz.
                     (Dotyczy jedynie metody dostpu DB_RECNO.)

              R_IBEFORE
                     Wstawia  dane bezporednio przed danymi wskazywanymi przez
                     klucz,  tworzc  now  par   klucz/dane.    Numer   rekordu
                     wstawionej  pary  klucz/dane  jest  zwracany w strukturze
                     klucz.  (Dotyczy jedynie metody dostpu DB_RECNO.)

              R_NOOVERWRITE
                     Wprowadza now par klucz/dane tylko gdy klucz wczeniej nie
                     istnial.

              R_SETCURSOR
                     Przechowuje  par  klucz/dane,  ustawiajc lub inicjalizujc
                     pozycj kursora  tak,  aby  na  ni  wskazywala.   (Dotyczy
                     jedynie metod dostpu DB_BTREE i DB_RECNO.)

              R_SETCURSOR  jest  dostpne  jedynie  dla metod dostpu DB_BTREE i
              DB_RECNO, gdy zaklada, e klucze maj ustalon, niezmienn kolejno.

              R_IAFTER  i  R_IBEFORE  s  dostpne  jedynie  dla  metody  dostpu
              DB_RECNO,  gdy  kade  z  nich  zaklada, e metoda dostpu umoliwia
              tworzenie nowych kluczy.  Jest to prawda  jedynie  w  przypadku,
              gdy  klucze  s  uporzdkowane  i  niezalene,  na  przyklad numery
              rekordow.

              Domylne zachowanie funkcji put polega na wprowadzeniu nowej pary
              klucz/dane, zastpujc uprzednio istniejcy klucz.

              Funkcje  put  zwracaj -1 w przypadku bldu (ustawiajc errno), 0 w
              przypadku pomylnego zakoczenia, a 1 gdy ustawiony jest  znacznik
              R_NOOVERWRITE, a klucz ju istnieje w pliku.

       seq    Wskanik   do  funkcji  stanowicej  interfejs  dla  sekwencyjnego
              pobierania danych z bazy.  Adres i dlugo  klucza  s  zwracane  w
              strukturze  wskazywanej przez klucz, za adres i rozmiar danych s
              zwracane w strukturze wskazywanej przez dane.

              Sekwencyjne pobieranie par klucz/dane moe si rozpocz w  dowolnym
              momencie,  a  wywolania  funkcji  del,  get, put, i sync nie maj
              wplywu  na  pozycj  ``kursora''.   Zmiany  bazy  danych  podczas
              sekwencyjnego  czytania  bd  odwzorowane  podczas odczytow, tzn.
              rekordy wstawione za  kursorem  nie  bd  zwrocone,  podczas  gdy
              rekordy wstawione przed kursorem zostan zwrocone.

              Warto znacznik musi by ustawiona jako jedna z poniszych wartoci:

              R_CURSOR
                     Zwracane s dane stowarzyszone z podanym kluczem.  Roni si
                     to od funkcji get tym, e rownie ustawia lub  inicjalizuje
                     kursor  w  pozycji  klucza.   (Naley zauway, e dla metody
                     dostpu DB_BTREE, zwracany klucz nie musi by identyczny  z
                     kluczem   podanym.    Zwracany  klucz  jest  najmniejszym
                     kluczem wikszym lub rownym podanemu kluczowi, dopuszczajc
                     czciowe dopasowywanie klucza i przeszukiwanie zakresow.)

              R_FIRST
                     Zwracana  jest pierwsza para klucz/dane wystpujca w bazie
                     danych. Kursor jest ustawiany lub inicjalizowany tak,  by
                     wskazywal t par.

              R_LAST Zwracana  jest ostatnia para klucz/dane wystpujca w bazie
                     danych. Kursor jest ustawiany lub inicjalizowany tak,  by
                     wskazywal  t par.  (Dotyczy jedynie metod dostpu DB_BTREE
                     i DB_RECNO.)

              R_NEXT Pobiera par klucz/dane znajdujc si bezporednio po pozycji
                     kursora.   Jeli  kursor  nie  zostal  jeszcze  ustawiony,
                     zachowuje si tak samo jak znacznik R_FIRST.

              R_PREV Pobiera par  klucz/dane  znajdujc  si  bezporednio  przed
                     pozycj   kursora.    Jeli   kursor   nie  zostal  jeszcze
                     ustawiony, zachowuje si tak  samo  jak  znacznik  R_LAST.
                     (Dotyczy jedynie metod dostpu DB_BTREE i DB_RECNO.)

              R_LAST  i  R_PREV  s dostpne jedynie dla metod dostpu DB_BTREE i
              DB_RECNO, gdy zakladaj, e klucze maj ustalon, niezmienn kolejno.

              Funkcje seq zwracaj -1 w przypadku bldu (ustawiajc errno),  0  w
              przypadku  pomylnego  zakoczenia,  a  1  gdy  brak  w bazie pary
              klucz/dane mniejszej lub wikszej ni podany lub  aktualny  klucz.
              Dla metody dostpu DB_RECNO, gdy plik bazy danych jest specjalnym
              plikiem znakowym, a adna pelna para klucz/dane nie jest w  danej
              chwili dostpna, funkcja seq zwraca 2.

       sync   Wskanik  do  funkcji  zrzucajcej zbuforowane informacje na dysk.
              Jeli baza danych znajduje si wylcznie w pamici, to funkcja  sync
              nic nie robi i koczy si zawsze pomylnie.

              Warto znacznika moe by jedn z nastpujcych wartoci:

              R_RECNOSYNC
                     Jeli  uywana jest metoda DB_RECNO, ten znacznik powoduje,
                     e funkcja sync dotyczy pliku btree stanowicego baz  pliku
                     numerow  rekordow,  nie za samego pliku numerow rekordow.
                     (Wicej informacji znajduje si w  opisie  pola  bfname  na
                     stronie podrcznika recno(3).)

              Funkcje  sync zwracaj -1 w przypadku bldu (ustawiajc errno), 0 w
              przypadku pomylnego zakoczenia.

Pary KLUCZ/DANE

       Dostp do wszystkich rodzajow plikow jest oparty na  parach  klucz/dane.
       Zarowno  klucze,  jak  i  dane  s  reprezentowane  za  pomoc nastpujcej
       struktury danych:

       typedef struct {
              void *data;
              size_t size;
       } DBT;

       Elementy stryktury DBT s zdefiniowane nastpujco:

       data   Wskanik do lacucha bajtow.

       size   Dlugo lacucha bajtow.

       Lacuchy bajtowe klucza i danych zasadniczo mog wskazywa  na  lacuchy  o
       nieograniczonej   dlugoci,  ale  dowolne  dwa  z  nich  musz  si  mieci
       jednoczenie w dostpnej pamici.  Naley zauway, e metody dostpu  nie  daj
       ednych gwarancji dotyczcych wyrownania lacuchow bajtowych.

B/LDY

       Funkcja  dbopen  moe  zawie i ustawi w errno dowolny z bldow okrelonych
       dla funkcji bibliotecznych open(2) i malloc(3) lub jeden z nastpujcych:

       [EFTYPE]
              Plik jest nieprawidlowo sformatowany.

       [EINVAL]
              Podano  parametr  (funkcj  mieszajc,  bajt   wyrownania,   itp.)
              niezgodny  z  aktualn  specyfikacj pliku, lub ktory nie ma sensu
              dla  funkcji  (na  przyklad,  uycie   kursora   bez   uprzedniej
              inicjalizacji)  lub  wystpuje niezgodno wersji pomidzy plikiem i
              oprogramowaniem.

       Funkcje close mog zawie i ustawi w errno dowolny z bldow okrelonych dla
       funkcji bibliotecznych close(2), read(2), write(2), free(3) i fsync(2).

       Funkcje  del, get, put i seq mog zawie i ustawi w errno dowolny z bldow
       okrelonych dla funkcji  bibliotecznych  read(2),  write(2),  free(3)  i
       malloc(3).

       Funkcje fd mog zawie i ustawi errno na ENOENT dla baz danych w pamici.

       Funkcje  sync mog zawie i ustawi w errno dowolny z bldow okrelonych dla
       funkcji bibliotecznej fsync(2).

ZOBACZ TAKE

       btree(3), hash(3), mpool(3), recno(3)

       LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer,  Michael
       Olson, USENIX proceedings, Winter 1992.

BUGS

       typedef DBT jest skrotem od ``data base thang'', ktory byl uywany tylko
       dlatego, e nikt nie wymylil sensownej, jeszcze nie uywanej nazwy.

       Interfejs wykorzystujcy deskryptory plikow staonowi obejcie i  bdzie  w
       przyszloci usunity.

       adna   z   metod   dostpu   nie  zapewnia  jakiejkolwiek  formy  dostpu
       rownoleglego, blokowania ani transakcji.

INFORMACJE O T/LUMACZENIU

       Powysze tlumaczenie pochodzi z nieistniejcego ju  Projektu  Tlumaczenia
       Manuali  i  moe nie by aktualne. W razie zauwaenia ronic midzy powyszym
       opisem a rzeczywistym zachowaniem  opisywanego  programu  lub  funkcji,
       prosimy o zapoznanie si z oryginaln (angielsk) wersj strony podrcznika.