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

NAZWA

       dbopen - metody dostępu do baz danych

SKŁADNIA

       #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ą  stanowiącą interfejs do plików baz
       danych.  Obsługiwane formaty plików to: btree, rozproszony  (hashed)  i
       uniksowy  zorientowany  na  pliki.   Format btree stanowi reprezentację
       posortoanej,  zrównoważonej  struktury  drzewa.    Format   rozproszony
       (hashed)  jest  rozszerzalnym, dynamicznym schematem mieszania.  Format
       płaskiego pliku jest plikiem stanowiącym strumień bajtów z rekordami  o
       stałej lub zmiennej długości.  Informacje o formatach i specyficzne dla
       poszczególnych formatów plików są szczegółowo opisane  na  odpowiednich
       stronach podręcznika: btree(3), hash(3) i recno(3).

       dbopen  otwiera  plik  do  odczytu  i/lub  do  zapisu.   Pliki, których
       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),
       jednakże  brane  pod  uwagę  są  jedynie  znaczniki  O_CREAT,   O_EXCL,
       O_EXLOCK,  O_NONBLOCK,  O_RDONLY,  O_RDWR, O_SHLOCK i O_TRUNC.  (Należy
       zauważyć,  że  otwarcie  pliku  bazy  danych  jako  O_WRONLY  nie  jest
       możliwe.)

       Argument  rodzaj  jest  typu  DBTYPE  (który  jest zdefiniowany w pliku
       nagłówkowym <db.h>) i można przybierać wartości DB_BTREE,  DB_HASH  lub
       DB_RECNO.

       Argument info_otw jest wskaźnikiem do struktury specyficznej dla metody
       dostępu, opisanej n stronie podręcznika danej  metody  dostępu.   Jeśli
       info_otw  jest  równe  NULL,  każda  z metod dostępu będzie korzystać z
       wartości domyślnych, właściwych dla systemy i tej metody dostępu.

       dbopen przy pomyślnym zakończeniu zwraca wskaźnik do  struktury  DB,  a
       NULL  w  przypadku  błędu.   Struktura  DB  jest  zdefiniowana  w pliku
       nagłówkowym <db.h> i zawiera co najmniej następujące 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  wykonyjących
       różne  operacje.   Funkcje te biorą jako argument wskaźnik do struktury
       takiej,  jak  zwracana  przez  dbopen  i,  czasami,  jeden  lub  więcej
       wskaźników do struktur klucz/dane oraz wartość znacznika.

       type   Rodzaj właściwej metody dostępu (i format plików).

       close  Wskaźnik  do funkcji zrzucającej zbuforowane informacje ma dysk,
              zwalniającej przydzielone zasoby i zamykającej  podległe  pliki.
              Ze  względu  na  to,  że  pary  klucz/dane mogą być buforowane w
              pamięci, niepomyślne zrzucenie buforów pliku za  pomocą  funkcji
              close  lub  sync  ,oże  prowadzić  do  niespójności  lub  utraty
              informacji.   Funkcje  close  zwracają  -1  w  przypadku   błędu
              (ustawiając errno), a 0 w przypadku zakończenia pomyślnego.

       del    Wskaźnik do funkcji usuwającej pary klucz/dane z bazy danych.

              Parametr znacznik może mieć jedną z następujących wartości:

              R_CURSOR
                     Usuwa rekord wskazywany przez kursor.  Kursor musi zostać
                     wcześniej zainicjalizowany.

              Funkcje delete zwracają -1 w przypadku błędu (ustawiając errno),
              0  w  przypadku pomyślnego zakończenia, a 1 gdy podany klucz nie
              występuje w pliku.

       fd     Wskaźnik do funkcji zwracającej deskryptor  pliku  odpowiadający
              używanej  bazie  danych.   Dla  wszystkich procesów wywołujących
              dbopen  dla  tej  samej  nazwy  pliku  plik  zostanie   zwrócony
              deskryptor  pliku  wskazujący na ten sam plik.  Tego deskryptora
              pliku  można   bezpiecznie   używać   jako   argumentu   funkcji
              blokujących  fcntl(2) i flock(2).  Deskryptor pliku nie musi być
              związany z którymkolwiek z plików używanych  przez  daną  metodę
              dostępu.   Deskryptor  pliku  nie  jest  dostępny dla baz danych
              zawartych w pamięci.  Funkcje fd zwracają -1 w  przypadku  błędu
              (ustawiając  errno),  a  deskryptor pliku w przypadku pomyślnego
              zakończenia.

       get    Wskaźnik do funkcji stanowiącej interfejs dla pobierania  danych
              z  bazy  według  klucza.   Adres  i  rozmiar danych związanych z
              podanym kluczem klucz są zwracane w strukturze wskazywanej przez
              dane.   Funkcje  get  zwracają  -1 w przypadku błędu (ustawiając
              errno), 0 w przypadku pomyślnego zakończenia,  a  1  gdy  podany
              klucz nie występuje w pliku.

       put    Wskaźnik  do  funkcji  przechowującej  pary  klucz/dane  w bazie
              danych.

              Parametr znacznik może mieć jedną z następujących wartości:

              R_CURSOR
                     Zastępuje  parę  klucz/dane  wskazywaną   przez   kursor.
                     Kursor musi zostać wcześniej zainicjalizowany.

              R_IAFTER
                     Dołącza  dane  bezpośrednio  po danych wskazywanych przez
                     klucz,  tworząc  nową  parę  klucz/dane.   Numer  rekordu
                     dodanej pary klucz/dane jest zwracany w strukturze klucz.
                     (Dotyczy jedynie metody dostępu DB_RECNO.)

              R_IBEFORE
                     Wstawia dane bezpośrednio przed danymi wskazywanymi przez
                     klucz,  tworząc  nową  parę  klucz/dane.   Numer  rekordu
                     wstawionej pary klucz/dane  jest  zwracany  w  strukturze
                     klucz.  (Dotyczy jedynie metody dostępu DB_RECNO.)

              R_NOOVERWRITE
                     Wprowadza  nową parę klucz/dane tylko gdy klucz wcześniej
                     nie istniał.

              R_SETCURSOR
                     Przechowuje parę klucz/dane, ustawiając lub inicjalizując
                     pozycję  kursora  tak,  aby  na nią wskazywała.  (Dotyczy
                     jedynie metod dostępu DB_BTREE i DB_RECNO.)

              R_SETCURSOR jest dostępne jedynie dla metod dostępu  DB_BTREE  i
              DB_RECNO,  gdyż  zakłada,  że  klucze  mają ustaloną, niezmienną
              kolejność.

              R_IAFTER i R_IBEFORE są  dostępne  jedynie  dla  metody  dostępu
              DB_RECNO, gdyż każde z nich zakłada, że metoda dostępu umożliwia
              tworzenie nowych kluczy.  Jest to prawda  jedynie  w  przypadku,
              gdy  klucze  są  uporządkowane  i niezależne, na przykład numery
              rekordów.

              Domyślne zachowanie funkcji put  polega  na  wprowadzeniu  nowej
              pary klucz/dane, zastępując uprzednio istniejący klucz.

              Funkcje  put zwracają -1 w przypadku błędu (ustawiając errno), 0
              w przypadku pomyślnego  zakończenia,  a  1  gdy  ustawiony  jest
              znacznik R_NOOVERWRITE, a klucz już istnieje w pliku.

       seq    Wskaźnik  do  funkcji  stanowiącej  interfejs  dla sekwencyjnego
              pobierania danych z bazy.  Adres i długość 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  może  się  rozpocząć  w
              dowolnym momencie, a wywołania funkcji del, get, put, i sync nie
              mają wpływu na pozycję ``kursora''.  Zmiany bazy danych  podczas
              sekwencyjnego  czytania  będą odwzorowane podczas odczytów, tzn.
              rekordy wstawione za kursorem nie  będą  zwrócone,  podczas  gdy
              rekordy wstawione przed kursorem zostaną zwrócone.

              Wartość  znacznik  musi  być  ustawiona  jako jedna z poniższych
              wartości:

              R_CURSOR
                     Zwracane są dane stowarzyszone z podanym kluczem.   Różni
                     się  to  od  funkcji  get  tym,  że  również  ustawia lub
                     inicjalizuje kursor w pozycji klucza.  (Należy  zauważyć,
                     że  dla  metody dostępu DB_BTREE, zwracany klucz nie musi
                     być identyczny z kluczem podanym.   Zwracany  klucz  jest
                     najmniejszym   kluczem   większym   lub  równym  podanemu
                     kluczowi, dopuszczając częściowe dopasowywanie  klucza  i
                     przeszukiwanie zakresów.)

              R_FIRST
                     Zwracana  jest  pierwsza  para  klucz/dane  występująca w
                     bazie danych. Kursor jest  ustawiany  lub  inicjalizowany
                     tak, by wskazywał tę parę.

              R_LAST Zwracana  jest  ostatnia  para  klucz/dane  występująca w
                     bazie danych. Kursor jest  ustawiany  lub  inicjalizowany
                     tak,  by  wskazywał  tę  parę.   (Dotyczy  jedynie  metod
                     dostępu DB_BTREE i DB_RECNO.)

              R_NEXT Pobiera parę klucz/dane znajdującą  się  bezpośrednio  po
                     pozycji   kursora.    Jeśli  kursor  nie  został  jeszcze
                     ustawiony, zachowuje się tak samo jak znacznik R_FIRST.

              R_PREV Pobiera parę klucz/dane znajdującą się bezpośrednio przed
                     pozycją   kursora.    Jeśli  kursor  nie  został  jeszcze
                     ustawiony, zachowuje się tak samo  jak  znacznik  R_LAST.
                     (Dotyczy jedynie metod dostępu DB_BTREE i DB_RECNO.)

              R_LAST i R_PREV są dostępne jedynie dla metod dostępu DB_BTREE i
              DB_RECNO, gdyż zakładają, że klucze  mają  ustaloną,  niezmienną
              kolejność.

              Funkcje  seq zwracają -1 w przypadku błędu (ustawiając errno), 0
              w przypadku pomyślnego zakończenia, a 1 gdy brak  w  bazie  pary
              klucz/dane mniejszej lub większej niż podany lub aktualny klucz.
              Dla  metody  dostępu  DB_RECNO,  gdy  plik  bazy   danych   jest
              specjalnym  plikiem  znakowym, a żadna pełna para klucz/dane nie
              jest w danej chwili dostępna, funkcja seq zwraca 2.

       sync   Wskaźnik do funkcji zrzucającej zbuforowane informacje na  dysk.
              Jeśli  baza  danych znajduje się wyłącznie w pamięci, to funkcja
              sync nic nie robi i kończy się zawsze pomyślnie.

              Wartość znacznika może być jedną z następujących wartości:

              R_RECNOSYNC
                     Jeśli  używana  jest  metoda   DB_RECNO,   ten   znacznik
                     powoduje,   że   funkcja   sync   dotyczy   pliku   btree
                     stanowiącego bazę pliku numerów rekordów, nie zaś  samego
                     pliku  numerów rekordów.  (Więcej informacji znajduje się
                     w opisie pola bfname na stronie podręcznika recno(3).)

              Funkcje sync zwracają -1 w przypadku błędu (ustawiając errno), 0
              w przypadku pomyślnego zakończenia.

Pary KLUCZ/DANE

       Dostęp  do wszystkich rodzajów plików jest oparty na parach klucz/dane.
       Zarówno klucze, jak i dane są  reprezentowane  za  pomocą  następującej
       struktury danych:

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

       Elementy stryktury DBT są zdefiniowane następująco:

       data   Wskaźnik do łańcucha bajtów.

       size   Długość łańcucha bajtów.

       Łańcuchy  bajtowe klucza i danych zasadniczo mogą wskazywać na łańcuchy
       o nieograniczonej długości, ale dowolne dwa z nich  muszą  się  mieścić
       jednocześnie  w  dostępnej pamięci.  Należy zauważyć, że metody dostępu
       nie dają żednych gwarancji dotyczących wyrównania łańcuchów  bajtowych.

BŁĘDY

       Funkcja  dbopen  może  zawieść  i  ustawić  w  errno  dowolny  z błędów
       określonych dla funkcji bibliotecznych open(2) i malloc(3) lub jeden  z
       następujących:

       [EFTYPE]
              Plik jest nieprawidłowo sformatowany.

       [EINVAL]
              Podano  parametr  (funkcję  mieszającą,  bajt  wyrównania, itp.)
              niezgodny z aktualną specyfikacją pliku, lub który nie ma  sensu
              dla   funkcji   (na  przykład,  użycie  kursora  bez  uprzedniej
              inicjalizacji) lub występuje niezgodność wersji pomiędzy plikiem
              i oprogramowaniem.

       Funkcje  close  mogą  zawieść  i  ustawić  w  errno  dowolny  z  błędów
       określonych 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
       błędów  określonych  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
       pamięci.

       Funkcje  sync  mogą  zawieść  i  ustawić  w  errno  dowolny  z   błędów
       określonych dla funkcji bibliotecznej fsync(2).

ZOBACZ TAKŻE

       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 skrótem od ``data  base  thang'',  który  był  używany
       tylko  dlatego,  że  nikt  nie wymyślił sensownej, jeszcze nie używanej
       nazwy.

       Interfejs wykorzystujący deskryptory plików staonowi obejście i  będzie
       w przyszłości usunięty.

       Żadna   z  metod  dostępu  nie  zapewnia  jakiejkolwiek  formy  dostępu
       równoległego, blokowania ani transakcji.