Linux Certif

Toute la documentation sur la certification Linux LPI

dbopen

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.