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