Provided by: manpages-pl-dev_0.7-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

        Uwaga! To tłumaczenie może być nieaktualne!

       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.

INFORMACJE O TŁUMACZENIU

       Powyższe tłumaczenie pochodzi z nieistniejącego już Projektu Tłumaczenia  Manuali  i  może
       nie  być  aktualne.  W  razie  zauważenia  różnic  między  powyższym opisem a rzeczywistym
       zachowaniem opisywanego programu lub  funkcji,  prosimy  o  zapoznanie  się  z  oryginalną
       (angielską) wersją strony podręcznika za pomocą polecenia:

              man --locale=C 3 dbopen

       Prosimy  o  pomoc  w  aktualizacji stron man - więcej informacji można znaleźć pod adresem
       http://sourceforge.net/projects/manpages-pl/.