.\" -*- coding: UTF-8 -*-
.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" SPDX-License-Identifier: BSD-4-Clause-UC
.\"
.\"	@(#)dbopen.3	8.5 (Berkeley) 1/2/94
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH dbopen 3 "4 grudnia 2022 r." "Linux man\-pages 6.03" 
.UC 7
.SH NAZWA
dbopen \- metody dostępu do baz danych
.SH BIBLIOTEKA
Standardowa biblioteka C (\fIlibc\fP, \fI\-lc\fP)
.SH SKŁADNIA
.nf
\fB#include <sys/types.h>\fP
\fB#include <limits.h>\fP
\fB#include <db.h>\fP
\fB#include <fcntl.h>\fP
.PP
\fBDB *dbopen(const char *\fP\fIfile\fP\fB, int \fP\fIflags\fP\fB, int \fP\fImode\fP\fB, DBTYPE \fP\fItype\fP\fB,\fP
\fB           const void *\fP\fIopeninfo\fP\fB);\fP
.fi
.SH OPIS
\fINote well\fP: 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 \fIlibdb\fP library instead.
.PP
\fBdbopen\fP() 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:
\fBbtree\fP(3), \fBhash\fP(3) i \fBrecno\fP(3)
.PP
\fBdbopen\fP() otwiera plik podany w parametrze \fIfile\fP do odczytu i/lub do
zapisu. Pliki, których zachowywanie na dysku nie jest zamierzone, mogą być
tworzone przez ustawienie parametru \fIfile\fP na NULL.
.PP
.\"Three additional options may be specified by ORing
.\"them into the
.\".I flags
.\"argument.
.\".TP
.\"DB_LOCK
.\"Do the necessary locking in the database to support concurrent access.
.\"If concurrent access isn't needed or the database is read-only this
.\"flag should not be set, as it tends to have an associated performance
.\"penalty.
.\".TP
.\"DB_SHMEM
.\"Place the underlying memory pool used by the database in shared
.\"memory.
.\"Necessary for concurrent access.
.\".TP
.\"DB_TXN
.\"Support transactions in the database.
.\"The DB_LOCK and DB_SHMEM flags must be set as well.
Argumenty \fIflags\fP i \fImode\fP są takie same, jak w funkcji \fBopen\fP(2),
jednakże brane pod uwagę są jedynie znaczniki  \fBO_CREAT\fP, \fBO_EXCL\fP,
\fBO_EXLOCK\fP, \fBO_NONBLOCK\fP, \fBO_RDONLY\fP, \fBO_RDWR\fP, \fBO_SHLOCK\fP oraz
\fBO_TRUNC\fP. (Należy zauważyć, że nie jest możliwe otwarcie pliku bazy danych
jako \fBO_WRONLY\fP).
.PP
Argument \fItype\fP jest typu \fIDBTYPE\fP (który jest zdefiniowany w pliku
nagłówkowym \fI<db.h>\fP) i może przybierać wartości \fBDB_BTREE\fP,
\fBDB_HASH\fP lub \fBDB_RECNO\fP.
.PP
Argument \fIopeninfo\fP jest wskaźnikiem do struktury specyficznej dla metody
dostępu, opisanej na stronie podręcznika danej metody dostępu. Jeśli
\fIopeninfo\fP 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.
.PP
\fBdbopen\fP() po pomyślnym zakończeniu zwraca wskaźnik do struktury \fIDB\fP, a
NULL w przypadku błędu. Struktura \fIDB\fP jest zdefiniowana w pliku
nagłówkowym \fI<db.h>\fP i zawiera przynajmniej następujące pola:
.PP
.in +4n
.EX
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;
.EE
.in
.PP
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 \fBdbopen\fP() i \- czasami \- jeden lub więcej wskaźników do
struktur klucz/dane oraz wartość znacznika.
.TP 
\fItype\fP
Rodzaj właściwej metody dostępu (i format plików).
.TP 
\fIclose\fP
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 \fIclose\fP lub \fIsync\fP może prowadzić do niespójności
lub utraty informacji. Funkcje \fIclose\fP zwracają \-1 w przypadku błędu
(ustawiając \fIerrno\fP), a 0 w przypadku pomyślnego zakończenia.
.TP 
\fIdel\fP
Wskaźnik do funkcji usuwającej pary klucz/dane z bazy danych.
.IP
Argument \fIflag\fP może mieć jedną z następujących wartości:
.RS
.TP 
\fBR_CURSOR\fP
Usuwa rekord wskazywany przez kursor.  Kursor musi zostać wcześniej
zainicjowany.
.RE
.IP
Funkcje \fIdelete\fP zwracają \-1 w przypadku błędu (ustawiając \fIerrno\fP), 0 w
przypadku pomyślnego zakończenia albo 1, gdy klucz podany w parametrze
\fIkey\fP nie występuje w pliku.
.TP 
\fIfd\fP
Wskaźnik do funkcji zwracającej deskryptor pliku odpowiadający używanej
bazie danych. Dla wszystkich procesów wywołujących \fBdbopen\fP() dla tej samej
nazwy pliku \fIfile\fP zostanie zwrócony deskryptor pliku wskazujący na ten sam
plik. Tego deskryptora pliku można bezpiecznie używać jako argumentu funkcji
blokujących \fBfcntl\fP(2) i \fBflock\fP(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 \fIfd\fP zwracają \-1 w przypadku błędu (ustawiając \fIerrno\fP), a
deskryptor pliku w przypadku pomyślnego zakończenia.
.TP 
\fIget\fP
Wskaźnik do funkcji stanowiącej interfejs dla pobierania danych z bazy
według klucza. Adres i rozmiar danych związanych z podanym kluczem \fIkey\fP są
zwracane w strukturze wskazywanej przez \fIdata\fP.  Funkcje \fIget\fP zwracają \-1
w przypadku błędu (ustawiając \fIerrno\fP), 0 w przypadku pomyślnego
zakończenia albo 1, gdy podany \fIkey\fP nie występuje w pliku.
.TP 
\fIput\fP
Wskaźnik do funkcji przechowującej pary klucz/dane w bazie danych.
.IP
Parametr \fIflag\fP może mieć jedną z następujących wartości:
.RS
.TP 
\fBR_CURSOR\fP
Zastępuje parę klucz/dane wskazywaną przez kursor. Kursor musi zostać
wcześniej zainicjowany.
.TP 
\fBR_IAFTER\fP
Dołącza dane bezpośrednio po danych wskazywanych przez \fIkey\fP, tworząc nową
parę klucz/dane. Numer rekordu dodanej pary klucz/dane jest zwracany w
strukturze \fIkey\fP. (Dotyczy jedynie metody dostępu \fBDB_RECNO\fP).
.TP 
\fBR_IBEFORE\fP
Wstawia dane bezpośrednio przed danymi wskazywanymi przez \fIkey\fP, tworząc
nową parę klucz/dane.  Numer rekordu wstawionej pary klucz/dane jest
zwracany w strukturze \fIkey\fP. (Dotyczy jedynie metody dostępu \fBDB_RECNO\fP).
.TP 
\fBR_NOOVERWRITE\fP
Wprowadza nową parę klucz/dane tylko gdy klucz wcześniej nie istniał.
.TP 
\fBR_SETCURSOR\fP
Przechowuje parę klucz/dane, ustawiając lub inicjując pozycję kursora tak,
aby na nią wskazywała. (Dotyczy jedynie metod dostępu  \fBDB_BTREE\fP i
\fBDB_RECNO\fP).
.RE
.IP
\fBR_SETCURSOR\fP jest dostępne jedynie dla metod dostępu \fBDB_BTREE\fP i
\fBDB_RECNO\fP, gdyż zakłada, że klucze mają ustaloną, niezmienną kolejność.
.IP
\fBR_IAFTER\fP i \fBR_IBEFORE\fP są dostępne jedynie dla metody dostępu
\fBDB_RECNO\fP, 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.
.IP
Domyślne zachowanie funkcji \fIput\fP polega na wprowadzeniu nowej pary
klucz/dane, zastępując uprzednio istniejący klucz.
.IP
Funkcje \fIput\fP zwracają \-1 w przypadku błędu (ustawiając \fIerrno\fP), 0 w
przypadku pomyślnego zakończenia oraz 1, gdy \fIflag\fP jest ustawiony na
\fBR_NOOVERWRITE\fP, a klucz już istnieje w pliku.
.TP 
\fIseq\fP
Wskaźnik do funkcji stanowiącej interfejs dla sekwencyjnego pobierania
danych z bazy. Adres i długość klucza są zwracane w strukturze wskazywanej
przez \fIkey\fP, a adres i rozmiar danych są zwracane w strukturze wskazywanej
przez \fIdata\fP.
.IP
Sekwencyjne pobieranie par klucz/dane może się rozpocząć w dowolnym
momencie, a wywołania funkcji \fIdel\fP, \fIget\fP, \fIput\fP i \fIsync\fP 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.
.IP
Wartość argumentu \fIflag\fP \fBmusi\fP być ustawiona na jedną z poniższych
wartości:
.RS
.TP 
\fBR_CURSOR\fP
Zwracane są dane stowarzyszone z podanym kluczem. Różni się to od funkcji
\fIget\fP tym, że również ustawia lub inicjuje kursor w pozycji klucza. (Należy
zauważyć, że dla metody dostępu \fBDB_BTREE\fP 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).
.TP 
\fBR_FIRST\fP
Zwracana jest pierwsza para klucz/dane występująca w bazie danych. Kursor
jest ustawiany lub inicjowany tak, by wskazywał tę parę.
.TP 
\fBR_LAST\fP
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  \fBDB_BTREE\fP oraz \fBDB_RECNO\fP).
.TP 
\fBR_NEXT\fP
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 \fBR_FIRST\fP.
.TP 
\fBR_PREV\fP
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 \fBR_LAST\fP. (Dotyczy jedynie metod dostępu \fBDB_BTREE\fP i
\fBDB_RECNO\fP).
.RE
.IP
\fBR_LAST\fP i \fBR_PREV\fP są dostępne jedynie dla metod dostępu \fBDB_BTREE\fP i
\fBDB_RECNO\fP, gdyż zakładają, że klucze mają ustaloną, niezmienną kolejność.
.IP
Funkcje \fIseq\fP zwracają \-1 w przypadku błędu (ustawiając \fIerrno\fP), 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
\fBDB_RECNO\fP, gdy plik bazy danych jest specjalnym plikiem znakowym, a żadna
pełna para klucz/dane nie jest w danej chwili dostępna, funkcje \fIseq\fP
zwracają 2.
.TP 
\fIsync\fP
Wskaźnik do funkcji zrzucającej zbuforowane informacje na dysk.  Jeśli baza
danych znajduje się wyłącznie w pamięci, to funkcja \fIsync\fP nic nie robi i
kończy się zawsze pomyślnie.
.IP
Wartość znacznika może być jedną z następujących wartości:
.RS
.TP 
\fBR_RECNOSYNC\fP
Jeśli używana jest metoda \fBDB_RECNO\fP, 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
\fIbfname\fP na stronie podręcznika \fBrecno\fP(3)).
.RE
.IP
Funkcje \fIsync\fP zwracają \-1 w przypadku błędu (ustawiając \fIerrno\fP), 0 w
przypadku pomyślnego zakończenia.
.SS "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:
.PP
.in +4n
.EX
typedef struct {
    void  *data;
    size_t size;
} DBT;
.EE
.in
.PP
Elementy struktury \fIDBT\fP są zdefiniowane następująco:
.TP 
\fIdata\fP
Wskaźnik do łańcucha bajtów.
.TP 
\fIsize\fP
Długość łańcucha bajtów.
.PP
Ł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.
.SH BŁĘDY
Funkcja \fBdbopen\fP() może zawieść i ustawić \fIerrno\fP na dowolny z błędów
określonych dla funkcji bibliotecznych \fBopen\fP(2) i \fBmalloc\fP(3) albo na
jeden z następujących błędów:
.TP 
\fBEFTYPE\fP
Plik jest niepoprawnie sformatowany.
.TP 
\fBEINVAL\fP
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.
.PP
Funkcje \fIclose\fP mogą zawieść i ustawić w \fIerrno\fP dowolny z błędów
określonych dla funkcji bibliotecznych \fBclose\fP(2), \fBread\fP(2), \fBwrite\fP(2),
\fBfree\fP(3) lub \fBfsync\fP(2).
.PP
Funkcje \fIdel\fP, \fIget\fP, \fIput\fP i \fIseq\fP mogą zawieść i ustawić w \fIerrno\fP
dowolny z błędów określonych dla funkcji bibliotecznych \fBread\fP(2),
\fBwrite\fP(2), \fBfree\fP(3) lub \fBmalloc\fP(3).
.PP
Funkcje \fIfd\fP mogą zawieść i ustawić \fIerrno\fP na \fBENOENT\fP dla baz danych w
pamięci.
.PP
Funkcje \fIsync\fP mogą zawieść i ustawić w \fIerrno\fP dowolny z błędów
określonych dla funkcji bibliotecznej \fBfsync\fP(2).
.SH BŁĘDY
Nazwa typu \fIDBT\fP jest skrótem od "data base thang", który był używany tylko
dlatego, że nikt nie wymyślił sensownej, jeszcze nieużywanej nazwy.
.PP
Interfejs wykorzystujący deskryptory plików stanowi obejście i będzie w
przyszłości usunięty.
.PP
Żadna z metod dostępu nie zapewnia jakiejkolwiek formy dostępu równoległego,
blokowania ani transakcji.
.SH "ZOBACZ TAKŻE"
\fBbtree\fP(3), \fBhash\fP(3), \fBmpool\fP(3), \fBrecno\fP(3)
.PP
\fILIBTP: Portable, Modular Transactions for UNIX\fP, Margo Seltzer, Michael
Olson, USENIX proceedings, Winter 1992.
.PP
.SH 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>
.
.PP
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach
licencji można uzyskać zapoznając się z
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License w wersji 3
.UE
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
.PP
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy
dyskusyjnej
.MT manpages-pl-list@lists.sourceforge.net
.ME .
