GDBM

GNU dbm — библиотека функций, реализующих хешированную базу данных на диске.

Введение в GNU dbm

GNU dbm (gdbm) — это библиотека функций базы данных, которая использует расширяемое хэширование и работает аналогично стандартным функциям dbm UNIX. Эти процедуры предоставляются программисту, которому необходимо создать и обработать хешированную базу данных. (gdbm не является полным пакетом базы данных для конечного пользователя).

Основное предназначение gdbm — хранить пары ключ/данные в файле данных. Каждый ключ должен быть уникальным и сопряженным только с одним элементом данных. Ключи не могут быть напрямую доступны в отсортированном порядке. Основной единицей данных в gdbm является структура: <syntaxhighlight lang="c">

 typedef struct {
             char * dptr;
             int dsize;
          } datum;

</syntaxhighlight> Эта структура позволяет использовать произвольные ключи и элементы данных.

Пара ключей/данных хранится в файле диска gdbm, который называется базой данных gdbm. Приложение должно открыть базу данных gdbm, чтобы иметь возможность манипулировать ключами и данными, содержащимися в базе данных. gdbm позволяет приложению одновременно открывать несколько баз данных. Когда приложение открывает базу данных gdbm, оно обозначается как reader или writer. База данных gdbm может открываться не более чем одним приложением типа writer, однако приложения, помеченные как reader, могут одновременно открывать базу данных. Приложения типа writer и reader не могут одновременно открывать базу данных gdbm.

Список функций

Ниже приведен краткий список функций, содержащихся в библиотеке gdbm. Заголовочный файл gdbm.h, который может быть включен пользователем, содержит определение этих функций. <syntaxhighlight lang="c">

1. include <gdbm.h>

GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func); void gdbm_close(dbf); int gdbm_store(dbf, key, content, flag); datum gdbm_fetch(dbf, key); int gdbm_delete(dbf, key); datum gdbm_firstkey(dbf); datum gdbm_nextkey(dbf, key); int gdbm_reorganize(dbf); void gdbm_sync(dbf); int gdbm_exists(dbf, key); char *gdbm_strerror(errno); int gdbm_setopt(dbf, option, value, size); int gdbm_fdesc(dbf); int gdbm_export (GDBM_FILE, const char *, int, int); int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp); int gdbm_import (GDBM_FILE, const char *, int); int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag); int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount); int gdbm_version_cmp (int const a[], int const b[]); </syntaxhighlight> Заголовочный файл gdbm.h часто находится в каталоге /usr/include (фактическое местоположение gdbm.h зависит от локальной установки gdbm).

Открытие базы данных

Интерфейс функции: <syntaxhighlight lang="c"> GDBM_FILE gdbm_open (const char * name , int block_size , int flags , int mode , void (* fatal_func) (const char *)) </syntaxhighlight> Функция gdbm_open инициализирует систему gdbm. Если файл имеет размер 0 байт, выполняется процедура инициализации файла, настройка исходной структуры в файле. Аргументы функции gdbm_open:

• name — имя файла (полное имя, gdbm не добавляет никаких символов к этому имени).
• block_size — используется во время инициализации для определения размера различных конструкций. Это размер одной передачи с диска на память. Этот параметр игнорируется, если файл был предварительно инициализирован. Если значение меньше 512, вместо этого используется размер блока файловой системы. Размер настраивается таким образом, чтобы блок мог содержать точное количество записей в каталоге, так что размер эффективного блока может быть немного большим, чем требуется. Однако, если установлен флаг GDBM_BSEXACT и размер должен быть скорректирован, функция вернется со статусом ошибки, установив значение переменной gdbm_errno в GDBM_BLOCK_SIZE_ERROR.
• flags — если flags установлен в GDBM_READER, пользователь хочет просто прочитать базу данных, и любой вызов gdbm_store или gdbm_delete завершится с ошибкой. Многие программы, помеченные как reader могут одновременно обращаться к базе данных. Если flags установлен в GDBM_WRITER, пользователь хочет как читать, так и записывать доступ к базе данных и требует эксклюзивного доступа. Если flags установлен в GDBM_WRCREAT, пользователь хочет получить доступ к чтению и записи в базу данных и хочет, чтобы он был создан, если он еще не существует. Если flags установлен в GDBM_NEWDB, пользователь хочет создать новую базу данных, независимо от того, существует ли она, и хоче получить доступ к чтению и записи к новой базе данных.

Если открытый вызов хоста поддерживает флаг O_CLOEXEC, параметр GDBM_CLOEXEC может быть включен во флаги, чтобы включить флаг закрытия для дескриптора файла базы данных.

• mode — режим файла, который используется, если файл создан.
• fatal_func — функция, которая вызывается gdbm в случае фатальной ошибки. Единственным параметром этой функции является строка. Если задано значение NULL, gdbm будет использовать функцию по умолчанию.

Закрытие базы данных

Важно, чтобы все открытые файлы также были закрыты. Это необходимо для обновления количества программ типа reader/writer в файле. Интерфейс функции gdbm_close: <syntaxhighlight lang="c"> void gdbm_close (GDBM_FILE dbf) </syntaxhighlight> Эта функция закрывает файл gdbm и освобождает всю связанную с ним память. Параметры:

• DBF — указатель, возвращаемый функцией gdbm_open.

Количество записей

Интерфейс функции gdbm_count: <syntaxhighlight lang="c"> int gdbm_count (GDBM_FILE dbf , gdbm_count_t* pcount) </syntaxhighlight> Подсчитывает количество записей в базе данных dbf. При успехе сохраняет её в ячейке памяти, на которую указывает pcount, и возвращает 0. При ошибке устанавливает gdbm_errno и возвращает −1.

Вставка и замена записей в базе данных

Функция gdbm_store вставляет или заменяет записи в базе данных. Интерфейс функции: <syntaxhighlight lang="c"> int gdbm_store (GDBM_FILE dbf, datum key, datum content, int flag) </syntaxhighlight> Параметры:

• DBF — указатель, возвращаемый функцией gdbm_open.
• key — ключ поиска.
• content — данные, которые должны быть связаны с ключом.
• flag — определяет действие, которое необходимо предпринять, когда ключ уже находится в базе данных. Значение GDBM_REPLACE (определенное в gdbm.h) требует, чтобы старые данные были заменены новыми. Значение GDBM_INSERT запрашивает возврат ошибки и никаких действий, если ключ уже существует.

Эта функция может возвращать следующие значения:

• «−1» — элемент не был сохранен в базе данных, потому что вызывающая программа не была подтверждена как writer, либо ключ или контент имеют значение NULL поля dptr. Ключ и содержимое должны иметь значение поля dptr как NULL. Поскольку значение NULL поля dptr используется другими функциями для указания ошибки, оно не может быть достоверным.
• «+1» — элемент не был сохранен, потому что флаг аргумента имел значение GDBM_INSERT, и ключ был уже в базе данных.
• «0» — нет ошибки. Значение содержимого задается ключом. Файл на диске обновляется, чтобы отразить структуру новой базы данных перед возвратом из этой функции.

Поиск записей в базе данных

Интерфейс функции: <syntaxhighlight lang="c"> datum gdbm_fetch (GDBM_FILE dbf, datum key) </syntaxhighlight> Выбирает заданный ключ и возвращает связанную с ним информацию. Поле dptr в возвращаемой структуре указывает на блок памяти, выделенный функцией malloc. Обязанностью вызывающего абонента является освободить его, когда он больше не нужен. Если значение dptr NULL, проверьте значение переменной gdbm_errno. Если это GDBM_ITEM_NOT_FOUND, данные не найдены. Любое другое значение означает, что произошла ошибка. Используйте функцию gdbm_strerror для преобразования gdbm_errno в удобочитаемую строку. Параметры:

• DBF — указатель, возвращаемый функцией gdbm_open.
• key — ключ поиска.

Пример использования этой функции: <syntaxhighlight lang="c"> content = gdbm_fetch (dbf, key); if (content.dptr == NULL)

 {
   fprintf (stderr, "ключ не найден \n");

else

 {
   /* сделать что-то с content.dptr */
 }

</syntaxhighlight>

Удаление записей из базы данных

Чтобы удалить некоторые данные из базы данных, используйте функцию gdbm_delete. Интерфейс функции: <syntaxhighlight lang="c"> int gdbm_delete (GDBM_FILE dbf, datum key) </syntaxhighlight> Удаляет данные, связанные с данным ключом, если он существует в базе данных dbf. Файл на диске обновляется, чтобы отразить структуру новой базы данных перед возвратом из этой функции. Параметры:

• DBF — указатель, возвращаемый функцией gdbm_open.
• datum key — ключ поиска.