Provided by: manpages-pl-dev_4.13-4_all 
NAZWA
dbopen - metody dostępu do baz danych
SKŁADNIA
#include <sys/types.h>
#include <limits.h>
#include <db.h>
#include <fcntl.h>
DB *dbopen(const char *file, int flags, int mode, DBTYPE type,
const void *openinfo);
OPIS
Ważna uwaga: Ta strona podręcznika ekranowego opisuje interfejsy dostarczane przez
bibliotekę glibc aż do wersji 2.1. Od wersji 2.2 glibc już nie zawiera tych interfejsów.
Najprawdopodobniej to, czego szukasz, to API dostarczane przez bibliotekę libdb.
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ę posortowanej, 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 podany w parametrze file do odczytu i/lub do zapisu. Pliki, których
zachowywanie na dysku nie jest zamierzone, mogą być tworzone przez ustawienie parametru
file na NULL.
Argumenty flags i mode 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 oraz
O_TRUNC. (Należy zauważyć, że nie jest możliwe otwarcie pliku bazy danych jako O_WRONLY).
Argument type jest typu DBTYPE (który jest zdefiniowany w pliku nagłówkowym <db.h>) i może
przybierać wartości DB_BTREE, DB_HASH lub DB_RECNO.
Argument openinfo jest wskaźnikiem do struktury specyficznej dla metody dostępu, opisanej
na stronie podręcznika danej metody dostępu. Jeśli openinfo jest równe NULL, to każda z
metod dostępu będzie korzystać z wartości domyślnych, właściwych dla systemu i tej metody
dostępu.
dbopen() po 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 przynajmniej
następujące pola:
typedef struct {
DBTYPE type;
int (*close)(const DB *db);
int (*del)(const DB *db, const DBT *key, unsigned int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, DBT *key, DBT *data,
unsigned int flags);
int (*put)(const DB *db, DBT *key, const DBT *data,
unsigned int flags);
int (*sync)(const DB *db, unsigned int flags);
int (*seq)(const DB *db, DBT *key, DBT *data,
unsigned int flags);
} DB;
Elementy te opisują rodzaj bazy danych i zestaw funkcji wykonują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 może prowadzić do niespójności lub utraty informacji.
Funkcje close zwracają -1 w przypadku błędu (ustawiając errno), a 0 w przypadku
pomyślnego zakończenia.
del Wskaźnik do funkcji usuwającej pary klucz/dane z bazy danych.
Argument flag może mieć jedną z następujących wartości:
R_CURSOR
Usuwa rekord wskazywany przez kursor. Kursor musi zostać wcześniej
zainicjowany.
Funkcje delete zwracają -1 w przypadku błędu (ustawiając errno), 0 w przypadku
pomyślnego zakończenia albo 1, gdy klucz podany w parametrze key 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
file 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 key są zwracane w
strukturze wskazywanej przez data. Funkcje get zwracają -1 w przypadku błędu
(ustawiając errno), 0 w przypadku pomyślnego zakończenia albo 1, gdy podany key nie
występuje w pliku.
put Wskaźnik do funkcji przechowującej pary klucz/dane w bazie danych.
Parametr flag 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 zainicjowany.
R_IAFTER
Dołącza dane bezpośrednio po danych wskazywanych przez key, tworząc nową
parę klucz/dane. Numer rekordu dodanej pary klucz/dane jest zwracany w
strukturze key. (Dotyczy jedynie metody dostępu DB_RECNO).
R_IBEFORE
Wstawia dane bezpośrednio przed danymi wskazywanymi przez key, tworząc nową
parę klucz/dane. Numer rekordu wstawionej pary klucz/dane jest zwracany w
strukturze key. (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 inicjują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 oraz 1, gdy flag jest ustawiony na 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 key, a
adres i rozmiar danych są zwracane w strukturze wskazywanej przez data.
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ść argumentu flag musi być ustawiona na jedną 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 inicjuje 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 inicjowany tak, by wskazywał tę parę.
R_LAST Zwracana jest ostatnia para klucz/dane występująca w bazie danych. Kursor
jest ustawiany lub inicjowany tak, by wskazywał tę parę. (Dotyczy jedynie
metod dostępu DB_BTREE oraz 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 albo 1, gdy brak w bazie pary klucz/dane mniejszej lub
większej niż podany lub bieżący 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, funkcje seq zwracają 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 struktury 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ą żadnych gwarancji dotyczących wyrównania
łańcuchów bajtowych.
BŁĘDY
Funkcja dbopen() może zawieść i ustawić errno na dowolny z błędów określonych dla funkcji
bibliotecznych open(2) i malloc(3) albo na jeden z następujących błędów:
EFTYPE Plik jest niepoprawnie sformatowany.
EINVAL Podano parametr (funkcję mieszającą, bajt wyrównania, itp.) niezgodny z bieżącą
specyfikacją pliku lub taki, który nie ma sensu dla funkcji (na przykład użycie
kursora bez uprzedniej inicjacji), 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) lub 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) lub 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).
BŁĘDY
Nazwa typu DBT jest skrótem od "data base thang", który był używany tylko dlatego, że nikt
nie wymyślił sensownej, jeszcze nieużywanej nazwy.
Interfejs wykorzystujący deskryptory plików stanowi 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.
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.
O STRONIE
Angielska wersja tej strony pochodzi z wydania 5.10 projektu Linux man-pages. Opis
projektu, informacje dotyczące zgłaszania błędów oraz najnowszą wersję oryginału można
znaleźć pod adresem https://www.kernel.org/doc/man-pages/.
T◈UMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Andrzej Krzysztofowicz
<ankry@green.mf.pg.gda.pl> i Robert Luberda <robert@debian.org>
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji
można uzyskać zapoznając się z GNU General Public License w wersji 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ lub nowszej. Nie przyjmuje się ŻADNEJ
ODPOWIEDZIALNOŚCI.
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej
⟨manpages-pl-list@lists.sourceforge.net⟩.