Ubuntu Manpage: dbopen - metody dostępu do baz danych

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/.

4.4 Berkeley Distribution                          1994-01-02                                          DBOPEN(3)