dbopen(3) Library Functions Manual dbopen(3) NAZWA dbopen - metody dostepu do baz danych BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include #include #include #include DB *dbopen(const char *file, int flags, int mode, DBTYPE type, const void *openinfo); OPIS Note well: This page documents interfaces provided up until glibc 2.1. Since glibc 2.2, glibc no longer provides these interfaces. Probably, you are looking for the APIs provided by the libdb library instead. dbopen() jest funkcja biblioteczna stanowiaca interfejs do plikow baz danych. Obslugiwane formaty plikow to: btree, rozproszony (hashed) i uniksowy zorientowany na pliki. Format btree stanowi reprezentacje posortowanej, zrownowazonej struktury drzewa. Format rozproszony (hashed) jest rozszerzalnym, dynamicznym schematem mieszania. Format plaskiego pliku jest plikiem stanowiacym strumien bajtow z rekordami o stalej lub zmiennej dlugosci. Informacje o formatach i specyficzne dla poszczegolnych formatow plikow sa szczegolowo opisane na odpowiednich stronach podrecznika: btree(3), hash(3) i recno(3) dbopen() otwiera plik podany w parametrze file do odczytu i/lub do zapisu. Pliki, ktorych zachowywanie na dysku nie jest zamierzone, moga byc tworzone przez ustawienie parametru file na NULL. Argumenty flags i mode sa takie same, jak w funkcji open(2), jednakze brane pod uwage sa jedynie znaczniki O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK oraz O_TRUNC. (Nalezy zauwazyc, ze nie jest mozliwe otwarcie pliku bazy danych jako O_WRONLY). Argument type jest typu DBTYPE (ktory jest zdefiniowany w pliku naglowkowym ) i moze przybierac wartosci DB_BTREE, DB_HASH lub DB_RECNO. Argument openinfo jest wskaznikiem do struktury specyficznej dla metody dostepu, opisanej na stronie podrecznika danej metody dostepu. Jesli openinfo jest rowne NULL, to kazda z metod dostepu bedzie korzystac z wartosci domyslnych, wlasciwych dla systemu i tej metody dostepu. dbopen() po pomyslnym zakonczeniu zwraca wskaznik do struktury DB, a NULL w przypadku bledu. Struktura DB jest zdefiniowana w pliku naglowkowym i zawiera przynajmniej nastepujace 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 opisuja rodzaj bazy danych i zestaw funkcji wykonujacych rozne operacje. Funkcje te biora jako argument wskaznik do struktury takiej, jak zwracana przez dbopen() i - czasami - jeden lub wiecej wskaznikow do struktur klucz/dane oraz wartosc znacznika. type Rodzaj wlasciwej metody dostepu (i format plikow). close Wskaznik do funkcji zrzucajacej zbuforowane informacje ma dysk, zwalniajacej przydzielone zasoby i zamykajacej podlegle pliki. Ze wzgledu na to, ze pary klucz/dane moga byc buforowane w pamieci, niepomyslne zrzucenie buforow pliku za pomoca funkcji close lub sync moze prowadzic do niespojnosci lub utraty informacji. Funkcje close zwracaja -1 w przypadku bledu (ustawiajac errno), a 0 w przypadku pomyslnego zakonczenia. del Wskaznik do funkcji usuwajacej pary klucz/dane z bazy danych. Argument flag moze miec jedna z nastepujacych wartosci: R_CURSOR Usuwa rekord wskazywany przez kursor. Kursor musi zostac wczesniej zainicjowany. Funkcje delete zwracaja -1 w przypadku bledu (ustawiajac errno), 0 w przypadku pomyslnego zakonczenia albo 1, gdy klucz podany w parametrze key nie wystepuje w pliku. fd Wskaznik do funkcji zwracajacej deskryptor pliku odpowiadajacy uzywanej bazie danych. Dla wszystkich procesow wywolujacych dbopen() dla tej samej nazwy pliku file zostanie zwrocony deskryptor pliku wskazujacy na ten sam plik. Tego deskryptora pliku mozna bezpiecznie uzywac jako argumentu funkcji blokujacych fcntl(2) i flock(2). Deskryptor pliku nie musi byc zwiazany z ktorymkolwiek z plikow uzywanych przez dana metode dostepu. Deskryptor pliku nie jest dostepny dla baz danych zawartych w pamieci. Funkcje fd zwracaja -1 w przypadku bledu (ustawiajac errno), a deskryptor pliku w przypadku pomyslnego zakonczenia. get Wskaznik do funkcji stanowiacej interfejs dla pobierania danych z bazy wedlug klucza. Adres i rozmiar danych zwiazanych z podanym kluczem key sa zwracane w strukturze wskazywanej przez data. Funkcje get zwracaja -1 w przypadku bledu (ustawiajac errno), 0 w przypadku pomyslnego zakonczenia albo 1, gdy podany key nie wystepuje w pliku. put Wskaznik do funkcji przechowujacej pary klucz/dane w bazie danych. Parametr flag moze miec jedna z nastepujacych wartosci: R_CURSOR Zastepuje pare klucz/dane wskazywana przez kursor. Kursor musi zostac wczesniej zainicjowany. R_IAFTER Dolacza dane bezposrednio po danych wskazywanych przez key, tworzac nowa pare klucz/dane. Numer rekordu dodanej pary klucz/dane jest zwracany w strukturze key. (Dotyczy jedynie metody dostepu DB_RECNO). R_IBEFORE Wstawia dane bezposrednio przed danymi wskazywanymi przez key, tworzac nowa pare klucz/dane. Numer rekordu wstawionej pary klucz/dane jest zwracany w strukturze key. (Dotyczy jedynie metody dostepu DB_RECNO). R_NOOVERWRITE Wprowadza nowa pare klucz/dane tylko gdy klucz wczesniej nie istnial. R_SETCURSOR Przechowuje pare klucz/dane, ustawiajac lub inicjujac pozycje kursora tak, aby na nia wskazywala. (Dotyczy jedynie metod dostepu DB_BTREE i DB_RECNO). R_SETCURSOR jest dostepne jedynie dla metod dostepu DB_BTREE i DB_RECNO, gdyz zaklada, ze klucze maja ustalona, niezmienna kolejnosc. R_IAFTER i R_IBEFORE sa dostepne jedynie dla metody dostepu DB_RECNO, gdyz kazde z nich zaklada, ze metoda dostepu umozliwia tworzenie nowych kluczy. Jest to prawda jedynie w przypadku, gdy klucze sa uporzadkowane i niezalezne, na przyklad numery rekordow. Domyslne zachowanie funkcji put polega na wprowadzeniu nowej pary klucz/dane, zastepujac uprzednio istniejacy klucz. Funkcje put zwracaja -1 w przypadku bledu (ustawiajac errno), 0 w przypadku pomyslnego zakonczenia oraz 1, gdy flag jest ustawiony na R_NOOVERWRITE, a klucz juz istnieje w pliku. seq Wskaznik do funkcji stanowiacej interfejs dla sekwencyjnego pobierania danych z bazy. Adres i dlugosc klucza sa zwracane w strukturze wskazywanej przez key, a adres i rozmiar danych sa zwracane w strukturze wskazywanej przez data. Sekwencyjne pobieranie par klucz/dane moze sie rozpoczac w dowolnym momencie, a wywolania funkcji del, get, put i sync nie maja wplywu na pozycje "kursora". Zmiany bazy danych podczas sekwencyjnego czytania beda odwzorowane podczas odczytow, tzn. rekordy wstawione za kursorem nie beda zwrocone, podczas gdy rekordy wstawione przed kursorem zostana zwrocone. Wartosc argumentu flag musi byc ustawiona na jedna z ponizszych wartosci: R_CURSOR Zwracane sa dane stowarzyszone z podanym kluczem. Rozni sie to od funkcji get tym, ze rowniez ustawia lub inicjuje kursor w pozycji klucza. (Nalezy zauwazyc, ze dla metody dostepu DB_BTREE zwracany klucz nie musi byc identyczny z kluczem podanym. Zwracany klucz jest najmniejszym kluczem wiekszym lub rownym podanemu kluczowi, dopuszczajac czesciowe dopasowywanie klucza i przeszukiwanie zakresow). R_FIRST Zwracana jest pierwsza para klucz/dane wystepujaca w bazie danych. Kursor jest ustawiany lub inicjowany tak, by wskazywal te pare. R_LAST Zwracana jest ostatnia para klucz/dane wystepujaca w bazie danych. Kursor jest ustawiany lub inicjowany tak, by wskazywal te pare. (Dotyczy jedynie metod dostepu DB_BTREE oraz DB_RECNO). R_NEXT Pobiera pare klucz/dane znajdujaca sie bezposrednio po pozycji kursora. Jesli kursor nie zostal jeszcze ustawiony, zachowuje sie tak samo, jak znacznik R_FIRST. R_PREV Pobiera pare klucz/dane znajdujaca sie bezposrednio przed pozycja kursora. Jesli kursor nie zostal jeszcze ustawiony, zachowuje sie tak samo jak znacznik R_LAST. (Dotyczy jedynie metod dostepu DB_BTREE i DB_RECNO). R_LAST i R_PREV sa dostepne jedynie dla metod dostepu DB_BTREE i DB_RECNO, gdyz zakladaja, ze klucze maja ustalona, niezmienna kolejnosc. Funkcje seq zwracaja -1 w przypadku bledu (ustawiajac errno), 0 w przypadku pomyslnego zakonczenia albo 1, gdy brak w bazie pary klucz/dane mniejszej lub wiekszej niz podany lub biezacy klucz. Dla metody dostepu DB_RECNO, gdy plik bazy danych jest specjalnym plikiem znakowym, a zadna pelna para klucz/dane nie jest w danej chwili dostepna, funkcje seq zwracaja 2. sync Wskaznik do funkcji zrzucajacej zbuforowane informacje na dysk. Jesli baza danych znajduje sie wylacznie w pamieci, to funkcja sync nic nie robi i konczy sie zawsze pomyslnie. Wartosc znacznika moze byc jedna z nastepujacych wartosci: R_RECNOSYNC Jesli uzywana jest metoda DB_RECNO, ten znacznik powoduje, ze funkcja sync dotyczy pliku btree stanowiacego baze pliku numerow rekordow, nie zas samego pliku numerow rekordow. (Wiecej informacji znajduje sie w opisie pola bfname na stronie podrecznika recno(3)). Funkcje sync zwracaja -1 w przypadku bledu (ustawiajac errno), 0 w przypadku pomyslnego zakonczenia. Pary klucz/dane Dostep do wszystkich rodzajow plikow jest oparty na parach klucz/dane. Zarowno klucze, jak i dane sa reprezentowane za pomoca nastepujacej struktury danych: typedef struct { void *data; size_t size; } DBT; Elementy struktury DBT sa zdefiniowane nastepujaco: data Wskaznik do lancucha bajtow. size Dlugosc lancucha bajtow. Lancuchy bajtowe klucza i danych zasadniczo moga wskazywac na lancuchy o nieograniczonej dlugosci, ale dowolne dwa z nich musza sie miescic jednoczesnie w dostepnej pamieci. Nalezy zauwazyc, ze metody dostepu nie daja zadnych gwarancji dotyczacych wyrownania lancuchow bajtowych. BLEDY Funkcja dbopen() moze zawiesc i ustawic errno na dowolny z bledow okreslonych dla funkcji bibliotecznych open(2) i malloc(3) albo na jeden z nastepujacych bledow: EFTYPE Plik jest niepoprawnie sformatowany. EINVAL Podano parametr (funkcje mieszajaca, bajt wyrownania, itp.) niezgodny z biezaca specyfikacja pliku lub taki, ktory nie ma sensu dla funkcji (na przyklad uzycie kursora bez uprzedniej inicjacji), lub wystepuje niezgodnosc wersji pomiedzy plikiem i oprogramowaniem. Funkcje close moga zawiesc i ustawic w errno dowolny z bledow okreslonych dla funkcji bibliotecznych close(2), read(2), write(2), free(3) lub fsync(2). Funkcje del, get, put i seq moga zawiesc i ustawic w errno dowolny z bledow okreslonych dla funkcji bibliotecznych read(2), write(2), free(3) lub malloc(3). Funkcje fd moga zawiesc i ustawic errno na ENOENT dla baz danych w pamieci. Funkcje sync moga zawiesc i ustawic w errno dowolny z bledow okreslonych dla funkcji bibliotecznej fsync(2). USTERKI Nazwa typu DBT jest skrotem od "data base thang", ktory byl uzywany tylko dlatego, ze nikt nie wymyslil sensownej, jeszcze nieuzywanej nazwy. Interfejs wykorzystujacy deskryptory plikow stanowi obejscie i bedzie w przyszlosci usuniety. Zadna z metod dostepu nie zapewnia jakiejkolwiek formy dostepu rownoleglego, blokowania ani transakcji. ZOBACZ TAKZE btree(3), hash(3), mpool(3), recno(3) LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Andrzej Krzysztofowicz i Robert Luberda Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . 4.4 Berkeley Distribution 31 pazdziernika 2023 r. dbopen(3)