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