Provided by:
manpages-pl-dev_20060617-3_all 
NAZWA
dbopen - metody dostpu do baz danych
SK/LADNIA
#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 stanowic interfejs do plikow baz danych.
Obslugiwane formaty plikow to: btree, rozproszony (hashed) i uniksowy
zorientowany na pliki. Format btree stanowi reprezentacj posortoanej,
zrownowaonej struktury drzewa. Format rozproszony (hashed) jest
rozszerzalnym, dynamicznym schematem mieszania. Format plaskiego pliku
jest plikiem stanowicym strumie bajtow z rekordami o stalej lub
zmiennej dlugoci. Informacje o formatach i specyficzne dla
poszczegolnych formatow plikow s szczegolowo opisane na odpowiednich
stronach podrcznika: btree(3), hash(3) i recno(3).
dbopen otwiera plik do odczytu i/lub do zapisu. Pliki, ktorych
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), jednake
brane pod uwag s jedynie znaczniki O_CREAT, O_EXCL, O_EXLOCK,
O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK i O_TRUNC. (Naley zauway, e
otwarcie pliku bazy danych jako O_WRONLY nie jest moliwe.)
Argument rodzaj jest typu DBTYPE (ktory jest zdefiniowany w pliku
naglowkowym <db.h>) i mona przybiera wartoci DB_BTREE, DB_HASH lub
DB_RECNO.
Argument info_otw jest wskanikiem do struktury specyficznej dla metody
dostpu, opisanej n stronie podrcznika danej metody dostpu. Jeli
info_otw jest rowne NULL, kada z metod dostpu bdzie korzysta z wartoci
domylnych, wlaciwych dla systemy i tej metody dostpu.
dbopen przy pomylnym zakoczeniu zwraca wskanik do struktury DB, a NULL
w przypadku bldu. Struktura DB jest zdefiniowana w pliku naglowkowym
<db.h> i zawiera co najmniej nastpujce 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 wykonyjcych rone
operacje. Funkcje te bior jako argument wskanik do struktury takiej,
jak zwracana przez dbopen i, czasami, jeden lub wicej wskanikow do
struktur klucz/dane oraz warto znacznika.
type Rodzaj wlaciwej metody dostpu (i format plikow).
close Wskanik do funkcji zrzucajcej zbuforowane informacje ma dysk,
zwalniajcej przydzielone zasoby i zamykajcej podlegle pliki. Ze
wzgldu na to, e pary klucz/dane mog by buforowane w pamici,
niepomylne zrzucenie buforow pliku za pomoc funkcji close lub
sync ,oe prowadzi do niespojnoci lub utraty informacji. Funkcje
close zwracaj -1 w przypadku bldu (ustawiajc errno), a 0 w
przypadku zakoczenia pomylnego.
del Wskanik do funkcji usuwajcej pary klucz/dane z bazy danych.
Parametr znacznik moe mie jedn z nastpujcych wartoci:
R_CURSOR
Usuwa rekord wskazywany przez kursor. Kursor musi zosta
wczeniej zainicjalizowany.
Funkcje delete zwracaj -1 w przypadku bldu (ustawiajc errno), 0
w przypadku pomylnego zakoczenia, a 1 gdy podany klucz nie
wystpuje w pliku.
fd Wskanik do funkcji zwracajcej deskryptor pliku odpowiadajcy
uywanej bazie danych. Dla wszystkich procesow wywolujcych
dbopen dla tej samej nazwy pliku plik zostanie zwrocony
deskryptor pliku wskazujcy na ten sam plik. Tego deskryptora
pliku mona bezpiecznie uywa jako argumentu funkcji blokujcych
fcntl(2) i flock(2). Deskryptor pliku nie musi by zwizany z
ktorymkolwiek z plikow uywanych przez dan metod dostpu.
Deskryptor pliku nie jest dostpny dla baz danych zawartych w
pamici. Funkcje fd zwracaj -1 w przypadku bldu (ustawiajc
errno), a deskryptor pliku w przypadku pomylnego zakoczenia.
get Wskanik do funkcji stanowicej interfejs dla pobierania danych z
bazy wedlug klucza. Adres i rozmiar danych zwizanych z podanym
kluczem klucz s zwracane w strukturze wskazywanej przez dane.
Funkcje get zwracaj -1 w przypadku bldu (ustawiajc errno), 0 w
przypadku pomylnego zakoczenia, a 1 gdy podany klucz nie
wystpuje w pliku.
put Wskanik do funkcji przechowujcej pary klucz/dane w bazie danych.
Parametr znacznik moe mie jedn z nastpujcych wartoci:
R_CURSOR
Zastpuje par klucz/dane wskazywan przez kursor. Kursor
musi zosta wczeniej zainicjalizowany.
R_IAFTER
Dolcza dane bezporednio po danych wskazywanych przez
klucz, tworzc now par klucz/dane. Numer rekordu dodanej
pary klucz/dane jest zwracany w strukturze klucz.
(Dotyczy jedynie metody dostpu DB_RECNO.)
R_IBEFORE
Wstawia dane bezporednio przed danymi wskazywanymi przez
klucz, tworzc now par klucz/dane. Numer rekordu
wstawionej pary klucz/dane jest zwracany w strukturze
klucz. (Dotyczy jedynie metody dostpu DB_RECNO.)
R_NOOVERWRITE
Wprowadza now par klucz/dane tylko gdy klucz wczeniej nie
istnial.
R_SETCURSOR
Przechowuje par klucz/dane, ustawiajc lub inicjalizujc
pozycj kursora tak, aby na ni wskazywala. (Dotyczy
jedynie metod dostpu DB_BTREE i DB_RECNO.)
R_SETCURSOR jest dostpne jedynie dla metod dostpu DB_BTREE i
DB_RECNO, gdy zaklada, e klucze maj ustalon, niezmienn kolejno.
R_IAFTER i R_IBEFORE s dostpne jedynie dla metody dostpu
DB_RECNO, gdy kade z nich zaklada, e metoda dostpu umoliwia
tworzenie nowych kluczy. Jest to prawda jedynie w przypadku,
gdy klucze s uporzdkowane i niezalene, na przyklad numery
rekordow.
Domylne zachowanie funkcji put polega na wprowadzeniu nowej pary
klucz/dane, zastpujc uprzednio istniejcy klucz.
Funkcje put zwracaj -1 w przypadku bldu (ustawiajc errno), 0 w
przypadku pomylnego zakoczenia, a 1 gdy ustawiony jest znacznik
R_NOOVERWRITE, a klucz ju istnieje w pliku.
seq Wskanik do funkcji stanowicej interfejs dla sekwencyjnego
pobierania danych z bazy. Adres i dlugo 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 moe si rozpocz w dowolnym
momencie, a wywolania funkcji del, get, put, i sync nie maj
wplywu na pozycj ``kursora''. Zmiany bazy danych podczas
sekwencyjnego czytania bd odwzorowane podczas odczytow, tzn.
rekordy wstawione za kursorem nie bd zwrocone, podczas gdy
rekordy wstawione przed kursorem zostan zwrocone.
Warto znacznik musi by ustawiona jako jedna z poniszych wartoci:
R_CURSOR
Zwracane s dane stowarzyszone z podanym kluczem. Roni si
to od funkcji get tym, e rownie ustawia lub inicjalizuje
kursor w pozycji klucza. (Naley zauway, e dla metody
dostpu DB_BTREE, zwracany klucz nie musi by identyczny z
kluczem podanym. Zwracany klucz jest najmniejszym
kluczem wikszym lub rownym podanemu kluczowi, dopuszczajc
czciowe dopasowywanie klucza i przeszukiwanie zakresow.)
R_FIRST
Zwracana jest pierwsza para klucz/dane wystpujca w bazie
danych. Kursor jest ustawiany lub inicjalizowany tak, by
wskazywal t par.
R_LAST Zwracana jest ostatnia para klucz/dane wystpujca w bazie
danych. Kursor jest ustawiany lub inicjalizowany tak, by
wskazywal t par. (Dotyczy jedynie metod dostpu DB_BTREE
i DB_RECNO.)
R_NEXT Pobiera par klucz/dane znajdujc si bezporednio po pozycji
kursora. Jeli kursor nie zostal jeszcze ustawiony,
zachowuje si tak samo jak znacznik R_FIRST.
R_PREV Pobiera par klucz/dane znajdujc si bezporednio przed
pozycj kursora. Jeli kursor nie zostal jeszcze
ustawiony, zachowuje si tak samo jak znacznik R_LAST.
(Dotyczy jedynie metod dostpu DB_BTREE i DB_RECNO.)
R_LAST i R_PREV s dostpne jedynie dla metod dostpu DB_BTREE i
DB_RECNO, gdy zakladaj, e klucze maj ustalon, niezmienn kolejno.
Funkcje seq zwracaj -1 w przypadku bldu (ustawiajc errno), 0 w
przypadku pomylnego zakoczenia, a 1 gdy brak w bazie pary
klucz/dane mniejszej lub wikszej ni podany lub aktualny klucz.
Dla metody dostpu DB_RECNO, gdy plik bazy danych jest specjalnym
plikiem znakowym, a adna pelna para klucz/dane nie jest w danej
chwili dostpna, funkcja seq zwraca 2.
sync Wskanik do funkcji zrzucajcej zbuforowane informacje na dysk.
Jeli baza danych znajduje si wylcznie w pamici, to funkcja sync
nic nie robi i koczy si zawsze pomylnie.
Warto znacznika moe by jedn z nastpujcych wartoci:
R_RECNOSYNC
Jeli uywana jest metoda DB_RECNO, ten znacznik powoduje,
e funkcja sync dotyczy pliku btree stanowicego baz pliku
numerow rekordow, nie za samego pliku numerow rekordow.
(Wicej informacji znajduje si w opisie pola bfname na
stronie podrcznika recno(3).)
Funkcje sync zwracaj -1 w przypadku bldu (ustawiajc errno), 0 w
przypadku pomylnego zakoczenia.
Pary KLUCZ/DANE
Dostp do wszystkich rodzajow plikow jest oparty na parach klucz/dane.
Zarowno klucze, jak i dane s reprezentowane za pomoc nastpujcej
struktury danych:
typedef struct {
void *data;
size_t size;
} DBT;
Elementy stryktury DBT s zdefiniowane nastpujco:
data Wskanik do lacucha bajtow.
size Dlugo lacucha bajtow.
Lacuchy bajtowe klucza i danych zasadniczo mog wskazywa na lacuchy o
nieograniczonej dlugoci, ale dowolne dwa z nich musz si mieci
jednoczenie w dostpnej pamici. Naley zauway, e metody dostpu nie daj
ednych gwarancji dotyczcych wyrownania lacuchow bajtowych.
B/LDY
Funkcja dbopen moe zawie i ustawi w errno dowolny z bldow okrelonych
dla funkcji bibliotecznych open(2) i malloc(3) lub jeden z nastpujcych:
[EFTYPE]
Plik jest nieprawidlowo sformatowany.
[EINVAL]
Podano parametr (funkcj mieszajc, bajt wyrownania, itp.)
niezgodny z aktualn specyfikacj pliku, lub ktory nie ma sensu
dla funkcji (na przyklad, uycie kursora bez uprzedniej
inicjalizacji) lub wystpuje niezgodno wersji pomidzy plikiem i
oprogramowaniem.
Funkcje close mog zawie i ustawi w errno dowolny z bldow okrelonych 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 bldow
okrelonych 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 pamici.
Funkcje sync mog zawie i ustawi w errno dowolny z bldow okrelonych dla
funkcji bibliotecznej fsync(2).
ZOBACZ TAKE
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 skrotem od ``data base thang'', ktory byl uywany tylko
dlatego, e nikt nie wymylil sensownej, jeszcze nie uywanej nazwy.
Interfejs wykorzystujcy deskryptory plikow staonowi obejcie i bdzie w
przyszloci usunity.
adna z metod dostpu nie zapewnia jakiejkolwiek formy dostpu
rownoleglego, blokowania ani transakcji.
INFORMACJE O T/LUMACZENIU
Powysze tlumaczenie pochodzi z nieistniejcego ju Projektu Tlumaczenia
Manuali i moe nie by aktualne. W razie zauwaenia ronic midzy powyszym
opisem a rzeczywistym zachowaniem opisywanego programu lub funkcji,
prosimy o zapoznanie si z oryginaln (angielsk) wersj strony podrcznika.