Provided by: manpages-ru-dev_4.21.0-2_all bug

ИМЯ

       dbopen - методы доступа к базе данных

LIBRARY

       Standard C library (libc, -lc)

СИНТАКСИС

       #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);

ОПИСАНИЕ

       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()   is  the  library  interface  to database files.  The supported file formats are
       btree, hashed, and UNIX file oriented.  The btree format is a representation of a  sorted,
       balanced tree structure.  The hashed format is an extensible, dynamic hashing scheme.  The
       flat-file format is a byte stream file with fixed or variable length records.  The formats
       and  file-format-specific  information  are described in detail in their respective manual
       pages btree(3), hash(3), and recno(3).

       dbopen() открывает file для чтения и/или записи. Файлы, не предназначенные для хранения на
       диске, могут быть созданы заданием параметру file значения NULL.

       Значения аргументов flags и mode те же, что у вызова open(2), однако имеют значение только
       флаги O_CREAT,  O_EXCL,  O_EXLOCK,  O_NONBLOCK,  O_RDONLY,  O_RDWR,  O_SHLOCK  и  O_TRUNC.
       Открытие файла базы данных с O_WRONLY невозможно.

       Аргумент  type  имеет  тип DBTYPE (определён в файле заголовков <db.h>) и может быть равен
       DB_BTREE, DB_HASH или DB_RECNO.

       Аргумент openinfo является указателем на структуру метода доступа, описанную в  справочной
       странице,  посвящённой методам доступа. Если значение openinfo равно NULL, то каждый метод
       доступа будет использовать установки по умолчанию для системы и метода доступа.

       При успешном выполнении dbopen() возвращает указатель на структуру DB и NULL  при  ошибке.
       Структура DB определена в файле <db.h> и содержит, как минимум, следующие поля:

           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;

       Эти  элементы  описывают  тип базы данных и набор функций, выполняющих различные действия.
       Функции используют указатель на  структуру,  возвращаемый  dbopen(),  и  иногда  один  или
       несколько указателей на структуры ключ/данные и на значения флагов.

       type   Тип лежащего в основе метода доступа (и формат файла).

       close  Указатель  на  функцию,  которая  записывает любую кэшированную информацию на диск,
              освобождает занятые  ресурсы  и  закрывает  используемый  файл(-ы).  Так  как  пары
              ключ/данные могут быть кэшированы в памяти, ошибка синхронизации файла при функциях
              close или sync может привести  к  повреждению  или  потере  данных.  Функция  close
              возвращает  -1  при  ошибках  (меняя  при этом, соответственно, значение переменной
              errno) и 0 при успешном выполнении.

       del    Указатель на функцию для удаления пар ключ/данные из базы данных.

              Значение параметра flag может быть следующим:

              R_CURSOR
                     Удаление записи, на которую ссылается курсор. Курсор  предварительно  должен
                     быть инициализирован.

              Функция delete возвращает -1 при ошибке (изменяет errno), 0 при успешном выполнении
              и 1, если указанного ключа key нет в файле.

       fd     Указатель  на  функцию,  которая  возвращает   дескриптор   файла,   представляющий
              используемую  базу  данных.  Дескриптор  файла,  ссылающийся  на тот же файл, будет
              возвращаться всем процессам, которые вызывают dbopen() с этим  именем  файла  file.
              Этот  дескриптор  файла может быть использован как аргумент для блокирующих функций
              fcntl(2) и flock(2). Файловый дескриптор необязательно связывать с  какими-либо  из
              файлов,  лежащих  в  основе  используемого  метода доступа. Для баз данных в памяти
              файловые дескрипторы недоступны. Функция fd возвращает -1 при  ошибке  (меняет  при
              этом,  соответственно, значение переменной errno) или дескриптор файла при успешном
              выполнении.

       get    Указатель на функцию, которая является интерфейсом  для  поиска  по  ключу  в  базе
              данных.  Адрес  и  размер  данных, связанных с указанным ключом key, возвращается в
              структуре, указываемой data. Функция get возвращает -1 при ошибке (меняя при  этом,
              соответственно,  значение  переменной  errno),  0 при успешном выполнении и 1, если
              ключа key нет в файле.

       put    Указатель на функцию, сохраняющую пары ключ/данные в базе данных.

              Значение параметра flag может быть одним из следующих:

              R_CURSOR
                     Замена пары ключ/данные, на которую ссылается курсор. Курсор  предварительно
                     должен быть инициализирован.

              R_IAFTER
                     Добавление  данных  сразу  после  тех  данных, которые связаны с ключом key;
                     создание новой пары ключ/данные. Номер записи добавленной  пары  ключ/данные
                     возвращается  в  структуре  key  (применимо  только  в случае метода доступа
                     DB_RECNO).

              R_IBEFORE
                     Вставка данных перед данными, связанными с ключом key; создание  новой  пары
                     ключ/данные.  Номер  записи  добавленной  пары  ключ/данные  возвращается  в
                     структуре key (применимо только в случае метода доступа DB_RECNO).

              R_NOOVERWRITE
                     Добавление новой пары ключ/данные, только если ключ ещё не существовал.

              R_SETCURSOR
                     Сохранение пары ключ/данные, установка или инициализация позиции курсора для
                     ссылки  на  неё  (применимо  только  в  случае  метода  доступа  DB_BTREE  и
                     DB_RECNO).

              Значение R_SETCURSOR доступно только в случае методов доступа DB_BTREE и  DB_RECNO,
              поскольку  они  предполагают,  что  ключи  имеют  определённый  порядок, который не
              изменяется.

              Значения R_IAFTER и R_IBEFORE доступны только в  случае  метода  доступа  DB_RECNO,
              поскольку  предполагается,  что  метод доступа позволяет создавать новые ключи. Это
              возможно, только  если  ключи  отсортированы  и  независимы,  например,  они  могут
              представлять собой номера записей.

              Поведение  по  умолчанию  функции  put предусматривает ввод новой пары ключ/данные,
              заменяя при этом уже существующий ключ.

              Функция put возвращает -1 при ошибке  (меняя  при  этом,  соответственно,  значение
              переменной  errno),  0  при  успешном  выполнении  и  1,  если  значение flag равно
              R_NOOVERWRITE и ключ в файле уже существует.

       seq    Указатель на функцию, которая является интерфейсом для последовательной  выборки  в
              базе  данных.  Адрес  и  размер ключа возвращается в структуре, определяемой key, а
              адрес и размер данных — в структуре, определяемой data.

              Последовательная выборка пар ключ/данные  может  быть  начата  в  любой  момент,  и
              позиция  «курсора»  не подвергнется изменениям при вызове функций del, get, put или
              sync. Изменение базы данных в процессе  последовательного  просмотра  отразится  на
              просмотре,  т.  е. запись, вставленная позади курсора, не будет возвращена, пока не
              будет возвращена запись, вставленная перед курсором.

              Значение флага должно быть равно одному из следующих значений:

              R_CURSOR
                     Возвращаются данные, связанные с указанным ключом. Отличается от функции get
                     тем,  что  дополнительно  происходит  установка  или  инициализация курсора.
                     Заметим, что при методе доступа DB_BTREE необязательно,  чтобы  возвращаемый
                     ключ  в  точности  соответствовал указанному. Возвращаемый ключ — наименьший
                     ключ из больших или равных указанному ключу. При этом допускается  частичное
                     соответствие ключей и поиск их в диапазонах.

              R_FIRST
                     Возвращается   первая   пара   ключ/данные   из   базы   данных,   а  курсор
                     устанавливается или инициализируется для ссылки на него.

              R_LAST Возвращается  последняя  пара  ключ/данные  из   базы   данных,   а   курсор
                     устанавливается  или  инициализируется  для ссылки на него. Применимо только
                     для методов доступа DB_BTREE и DB_RECNO.

              R_NEXT Возвращается пара ключ/данные, стоящая непосредственно после  курсора.  Если
                     курсор ещё не был установлен, выполняется тоже, что при флаге R_FIRST.

              R_PREV Возвращается  пара ключ/данные, стоящая непосредственно перед курсором. Если
                     курсор ещё не был  установлен,  выполняется  тоже,  что  при  флаге  R_LAST.
                     Применимо только для методов доступа DB_BTREE и DB_RECNO.

              Флаги  R_LAST  и  R_PREV  подходят  только для методов доступа DB_BTREE и DB_RECNO,
              поскольку при этом предполагается,  что  ключи  расположены  в  строгом  неизменном
              порядке.

              Функция  seq возвращает -1 при ошибке (изменяя при этом значение переменной errno),
              0 при успешном выполнении и 1, если не обнаруживается пары ключ/данные, меньшей или
              большей  по  значению,  чем  указанный  или  текущий  ключ. Если используется метод
              доступа DB_RECNO, а файл базы данных представляет собой специальный символьный файл
              (и нет доступных полных пар ключ/данные), то функция seq возвращает значение 2.

       sync   Указатель  на  функцию,  которая записывает любые кэшированные данные на диск. Если
              база данных находится только в памяти, функция sync не выполняет никаких действий и
              всегда выполняется без ошибок.

              Значение параметра flag может быть следующим:

              R_RECNOSYNC
                     При  методе  доступа  DB_RECNO  этот флаг служит причиной применения функции
                     sync к файлу btree, лежащему в основе файла recno, а не к самому файлу recno
                     (см. поле bfname в справочной странице recno(3)).

              Функция  sync  возвращает  -1 при ошибке (меняя при этом значение переменной errno)
              или 0 при успешном выполнении.

   Пары ключ/данные
       Доступ ко всем типам файлов основан  на  парах  ключ/данные.  Ключ  и  данные  описываются
       следующей структурой данных:

           typedef struct {
               void  *data;
               size_t size;
           } DBT;

       Элементы структуры DBT определяются так:

       data   Указатель на строку байтов.

       size   Размер строки байтов.

       Байтовые строки ключа и данных могут ссылаться на строки практически неограниченной длины,
       хотя любые две из них должны помещаться в доступной памяти одновременно. Не забывайте, что
       методы доступа не гарантируют выравнивания байтовых строк.

ОШИБКИ

       Функция  dbopen()  может  завершиться  с  ошибкой  и  присвоить переменной errno значения,
       определённые в библиотечных функциях open(2) и malloc(3), а также дополнительно:

       EFTYPE Файл неверного формата.

       EINVAL Указанный параметр (функция хэширования, байт заполнения и т. д.)  не  совместим  с
              текущими   установками  файла,  не  имеет  смысла  для  данной  функции  (например,
              использование  курсора  без  его  предварительной   инициализации),   или   имеется
              несоответствие версии файла и программного обеспечения.

       Функция  close  может завершиться с ошибкой и присвоить переменной errno любое значение из
       определённых в библиотечных функциях close(2), read(2), write(2), free(3) или fsync(2).

       The del, get, put, and seq routines may fail and set errno for any of the errors specified
       for the library routines read(2), write(2), free(3), or malloc(3).

       Функция  fd  может завершиться с ошибкой и присвоить переменной errno значение ENOENT (для
       баз данных, находящихся в памяти).

       Функции sync могут завершиться с ошибкой и присвоить errno любое значение из  определённых
       для библиотеки функций fsync(2).

ДЕФЕКТЫ

       Название  типа  DBT  является  сокращением от «data base thang» и используется в настоящее
       время, поскольку никто ещё не придумал подходящего для него имени, которое ранее нигде  не
       применялось.

       Доступ через дескриптор файла устарел и будет удалён в будущей версии интерфейса.

       Ни  один  из  методов доступа не предоставляет пользователю каких-либо форм одновременного
       доступа, блокировок или транкзаций.

СМ. ТАКЖЕ

       btree(3), hash(3), mpool(3), recno(3)

       LIBTP: Portable, Modular Transactions for  UNIX,  Margo  Seltzer,  Michael  Olson,  USENIX
       proceedings, Winter 1992.

ПЕРЕВОД

       Русский  перевод  этой  страницы руководства был сделан Yuri Kozlov <yuray@komyakino.ru> и
       Иван Павлов <pavia00@gmail.com>

       Этот  перевод  является  бесплатной  документацией;  прочитайте  Стандартную  общественную
       лицензию GNU версии 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ или более позднюю, чтобы
       узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

       Если вы обнаружите ошибки в переводе  этой  страницы  руководства,  пожалуйста,  отправьте
       электронное письмо на ⟨man-pages-ru-talks@lists.sourceforge.net⟩.