GDBM_File

СОДЕРЖАНИЕ

• ИМЯ
• СИНТАКСИС
• ОПИСАНИЕ
  • Связывание
• СТАТИЧЕСКИЕ МЕТОДЫ
  • GDBM_version
• ОБРАБОТКА ОШИБОК
  • $GDBM_File::gdbm_errno
  • gdbm_check_syserr
• МЕТОДЫ БАЗЫ ДАННЫХ
  • закрыть
  • ошибка
  • sysошибка
  • strerror
  • очистить_ошибку
  • нужна_восстановление
  • перестроить
  • синхронизировать
  • счёт
  • флаги
  • имя_базы
  • размер_кеша
  • размер_блока
  • режим_синхронизации
  • centfree
  • объединить
  • mmap
  • mmapsize
  • восстановить
  • конвертировать
  • выгрузка
  • загрузка
• УСТОЙЧИВОСТЬ К АВАРИЯМ
  • состояние_устойчивости_к_авариям
  • атомарность_ошибки
  • последний_снимок
• ДОСТУПНОСТЬ
• БЕЗОПАСНОСТЬ И ПЕРЕНОСИМОСТЬ
• СМОТРИТЕ ТАКЖЕ

ИМЯ

GDBM_File - доступ к библиотеке gdbm из Perl5.

СИНТАКСИС

use GDBM_File;
[$db =] tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640
            or die "$GDBM_File::gdbm_errno";
# Use the %hash...

$e = $db->errno;
$e = $db->syserrno;
$str = $db->strerror;
$bool = $db->needs_recovery;

$db->clear_error;

$db->reorganize;
$db->sync;

$n = $db->count;

$n = $db->flags;

$str = $db->dbname;

$db->cache_size;
$db->cache_size($newsize);

$n = $db->block_size;

$bool = $db->sync_mode;
$db->sync_mode($bool);

$bool = $db->centfree;
$db->centfree($bool);

$bool = $db->coalesce;
$db->coalesce($bool);

$bool = $db->mmap;

$size = $db->mmapsize;
$db->mmapsize($newsize);

$db->recover(%args);

untie %hash ;

ОПИСАНИЕ

GDBM_File — модуль, который позволяет программам Perl использовать возможности библиотеки GNU gdbm. Если вы планируете использовать этот модуль, у вас должна быть под рукой справка по gdbm. Справка доступна онлайн по адресу https://www.gnu.org.ua/software/gdbm/manual.

Большинство функций gdbm доступны через интерфейс GDBM_File.

В отличие от встроенных хэшей Perl, не безопасно delete текущий элемент из хэша GDBM_File во время итерации по нему с each. Это ограничение библиотеки gdbm.

Связывание

Используйте встроенную Perl функцию tie для ассоциации базы данных GDBM с Perl хэшем:

tie %hash, 'GDBM_File', $filename, $flags, $mode;

Здесь, $filename — имя файла базы данных для открытия или создания. $flags — побитовое ИЛИ из режима доступа и необязательных модификаторов. Режим доступа может быть:

GDBM_READER

Открыть существующий файл базы данных в режиме только для чтения.

GDBM_WRITER

Открыть существующий файл базы данных в режиме чтения-записи.

GDBM_WRCREAT

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

GDBM_NEWDB

Создать новую базу данных и открыть её в режиме чтения-записи. Если база данных уже существует, сначала обнулить её.

Ряд модификаторов может быть объединён побитовым ИЛИ с режимом доступа. Большинство из них редко необходимы (см. https://www.gnu.org.ua/software/gdbm/manual/Open.html для полного списка), но один стоит отметить. Модификатор GDBM_NUMSYNC, когда используется с GDBM_NEWDB, инструктирует GDBM создать базу данных в расширенном (так называемом numsync) формате. Этот формат лучше всего подходит для реализаций, устойчивых к сбоям. См. раздел УСТОЙЧИВОСТЬ К АВАРИЯМ ниже для получения дополнительной информации.

Параметр $mode — режим файла для создания нового файла базы данных. Используйте восьмеричную константу или комбинацию S_I* констант из модуля Fcntl. Этот параметр используется, если $flags равен GDBM_NEWDB или GDBM_WRCREAT.

При успешном выполнении tie возвращает объект класса GDBM_File. В случае ошибки возвращает undef. Рекомендуется всегда проверять возвращаемое значение, чтобы убедиться, что ваш хэш успешно связан с файлом базы данных. См. ОБРАБОТКУ ОШИБОК ниже для примеров.

СТАТИЧЕСКИЕ МЕТОДЫ

GDBM_version

$str = GDBM_File->GDBM_version;
@ar = GDBM_File->GDBM_version;

Возвращает номер версии лежащей в основе библиотеки libgdbm. В скалярном контексте возвращает строковое представление версии библиотеки:

MINOR.MAJOR[.PATCH][ (GUESS)]

где MINOR, MAJOR и PATCH — номера версии, а GUESS — уровень угадывания (см. ниже).

В контексте списка возвращает список:

( MINOR, MAJOR, PATCH [, GUESS] )

Компонент GUESS присутствует только если версия libgdbm 1.8.3 или старше. Это связано с тем, что более ранние версии libgdbm не включали информацию о своей версии, и модуль GDBM_File должен реализовать определённые догадки, чтобы её определить. GUESS представляет собой текстовое описание в скалярном контексте и положительное число, указывающее насколько приблизительное угадывание в контексте списка. Возможные значения:

1 - точное угадывание

Гарантируется корректность основных и второстепенных номеров версии. Вероятнее всего, фактический номер патча угадан правильно, но может быть на 1-2 меньше, чем указано.

2 - приблизительное

Гарантируется корректность основных и второстепенных номеров версии. Номер патча устанавливается до верхней границы.

3 - приблизительное угадывание

Гарантируется, что версия не новее MAJOR.MINOR.

ОБРАБОТКА ОШИБОК

$GDBM_File::gdbm_errno

При использовании в числовом контексте возвращает текущее значение переменной gdbm_errno, т.е. числовой код, описывающий состояние последней операции с любой базой данных gdbm. Каждый числовой код имеет связанное с ним символическое имя. Полный список см. на https://www.gnu.org.ua/software/gdbm/manual/Error-codes.html. Обратите внимание, что этот список включает все коды ошибок, определённые для последней версии gdbm. В зависимости от фактической версии библиотеки GDBM_File, некоторые из них могут отсутствовать.

В строковом контексте $gdbm_errno возвращает удобочитаемое описание ошибки. При необходимости это описание включает значение $!. Это позволяет использовать его в диагностических сообщениях. Например, обычная последовательность привязки:

tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640
     or die "$GDBM_File::gdbm_errno";

Следующий более сложный пример иллюстрирует, как можно перейти к режиму только для чтения, если права доступа к файлу базы данных запрещают чтение-запись:

use Errno qw(EACCES);
unless (tie(%hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640)) {
    if ($GDBM_File::gdbm_errno == GDBM_FILE_OPEN_ERROR
        && $!{EACCES}) {
        if (tie(%hash, 'GDBM_File', $filename, GDBM_READER, 0640)) {
            die "$GDBM_File::gdbm_errno";
        }
    } else {
        die "$GDBM_File::gdbm_errno";
    }
}

gdbm_check_syserr

if (gdbm_check_syserr(gdbm_errno)) ...

Возвращает true, если номер системной ошибки ($!) даёт больше информации о причине ошибки.

МЕТОДЫ БАЗЫ ДАННЫХ

закрыть

$db->close;

Закрывает базу данных. Обычно достаточно просто использовать untie. Однако, вам понадобится использовать эту функцию, если вы явно присвоили результат tie переменной и хотите освободить базу данных для других пользователей. Рассмотрите следующий код:

$db = tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640;
# Do something with %hash or $db...
untie %hash;
$db->close;

В этом примере, просто untie недостаточно, так как база данных будет оставаться ссылаемой на $db и, следовательно, файл базы данных останется заблокированным. Вызов $db->close гарантирует, что файл базы данных закрыт и разблокирован.

ошибка

$db->errno

Возвращает последний статус ошибки, связанный с этой базой данных. В строковом контексте возвращает удобочитаемое описание ошибки. См. также переменную $GDBM_File::gdbm_errno выше.

sysошибка

$db->syserrno

Возвращает последний статус системной ошибки (переменная C errno ), связанную с этой базой данных,

strerror

$db->strerror

Возвращает текстовое описание последней ошибки, произошедшей в этой базе данных.

очистить_ошибку

$db->clear_error

Очистить статус ошибки.

нужна_восстановление

$db->needs_recovery

Возвращает true, если база данных нуждается в восстановлении.

перестроить

$db->reorganize;

Перестраивает базу данных.

синхронизировать

$db->sync;

Синхронизирует недавние изменения в базе данных с её копией на диске.

счёт

$n = $db->count;

Возвращает количество ключей в базе данных.

флаги

$db->flags;

Возвращает флаги, переданные в качестве 4-го аргумента функции tie.

имя_базы

$db->dbname;

Возвращает имя базы данных (т.е. 3-й аргумент функции tie).

размер_кеша

$db->cache_size;
$db->cache_size($newsize);

Возвращает размер внутреннего кеша GDBM для этой базы данных.

Вызов с аргументом устанавливает размер в $newsize.

размер_блока

$db->block_size;

Возвращает размер блока базы данных.

режим_синхронизации

$db->sync_mode;
$db->sync_mode($bool);

Возвращает состояние автоматического режима синхронизации. Вызов с аргументом включает или отключает режим синхронизации в зависимости от того, является ли $bool true или false.

При включённом режиме синхронизации (true), любые изменения в базе данных сразу записываются на диск. Это гарантирует целостность базы данных в случае непредвиденных ошибок (например, сбоя питания), за счёт заметного замедления операций.

Режим синхронизации выключен по умолчанию.

centfree

$db->centfree;
$db->centfree($bool);

Возвращает состояние центрального пула свободных блоков (0 - выключен, 1 - включен).

С аргументом изменяет его состояние.

По умолчанию центральный пул свободных блоков выключен.

объединить

$db->coalesce;
$db->coalesce($bool);

mmap

$db->mmap;

Возвращает true, если включено отображение памяти.

Этот метод вернёт ошибку, если библиотека libgdbm скомпилирована без поддержки отображения памяти.

mmapsize

$db->mmapsize;
$db->mmapsize($newsize);

Если включена адресация памяти, возвращает размер отображения памяти. С аргументом задаёт размер на $newsize.

Этот метод вызовет croak, если библиотека libgdbm скомпилирована без поддержки адресации памяти.

восстановить

$db->recover(%args);

Восстанавливает данные из повреждённой базы данных. %args необязателен и может содержать следующие ключи:

err => sub { ... }

Ссылка на код для подробного отчёта об ошибках. При возникновении ошибки, восстановить вызовет этот подпрограмму с одним аргументом — описанием ошибки.

backup => \$str

Создаёт резервную копию базы данных перед восстановлением и возвращает имя файла в $str.

max_failed_keys => $n

Максимальное допустимое количество неверных ключей. Если фактическое количество станет равно $n, восстановить прервётся и вернёт ошибку.

max_failed_buckets => $n

Максимальное допустимое количество неверных корзинок. Если фактическое количество станет равно $n, восстановить прервётся и вернёт ошибку.

max_failures => $n

Максимальное допустимое количество сбоев во время восстановления.

stat => \%hash

Возвращает статистику восстановления в %hash. После возврата будут присутствовать следующие ключи:

recovered_keys

Количество успешно восстановленных ключей.

recovered_buckets

Количество успешно восстановленных корзинок.

failed_keys

Количество ключей, которые не удалось получить.

failed_buckets

Количество корзинок, которые не удалось получить.

преобразовать

$db->convert($format);

Изменяет формат файла базы данных, на который ссылается $db.

Начиная с версии 1.20, gdbm поддерживает два формата файлов базы данных: стандартный и расширенный. Первый — это традиционный формат базы данных, используемый предыдущими версиями gdbm. Формат расширенный содержит дополнительные данные и рекомендуется для использования в приложениях, устойчивых к сбоям.

https://www.gnu.org.ua/software/gdbm/manual/Numsync.html, для обсуждения обоих форматов.

Аргумент $format задаёт новый желаемый формат базы данных. Он равен GDBM_NUMSYNC для преобразования базы данных из стандартного в расширенный формат и 0 для преобразования из расширенного в стандартный формат.

Если база данных уже в запрошенном формате, функция возвращает успех без выполнения каких-либо действий.

сбросить

$db->dump($filename, %options)

Создаёт дамп файла базы данных в $filename. Такой файл может быть использован как резервная копия или передан по сети для создания базы данных на другом компьютере. Для создания базы данных из файла дампа используйте метод load.

GDBM поддерживает два формата дампа: старый бинарный и новый текстовый. Бинарный формат не переносится между архитектурами и устарел. Он поддерживается для обратной совместимости. Текстовый формат переносится и хранит дополнительные метаданные о файле. Он был введён с версией gdbm 1.11 и является предпочтительным форматом дампа. Метод dump создаёт дампы в текстовом формате по умолчанию.

Если файл с указанным именем уже существует, функция откажется от перезаписи и вернёт ошибку. Если его не существует, он будет создан с режимом 0666, изменённым текущим umask.

Эти значения по умолчанию можно изменить, используя следующие %options:

binary => 1

Создать дамп в бинарном формате.

mode => MODE

Установить режим файла на MODE.

overwrite => 1

Без предупреждений перезаписать существующие файлы.

загрузить

$db->load($filename, %options)

Загружает данные из файла дампа $filename в базу данных $db. Файл должен быть предварительно создан с помощью метода dump. Формат файла распознаётся автоматически. По умолчанию функция будет вызывать ошибку, если дамп содержит ключ, который уже существует в базе данных. Она будет игнорировать сбои при восстановлении режима и/или владельца базы данных. Эти значения по умолчанию можно изменить, используя следующие %options:

replace => 1

Заменить существующие ключи.

restore_mode => 0 | 1

Если 0, не пытаться восстановить режим файла базы данных до режима, сохранённого в дампе.

restore_owner => 0 | 1

Если 0, не пытаться восстановить владельца файла базы данных до владельца, сохранённого в дампе.

strict_errors => 1

Вызвать ошибку, если не удалось восстановить права владения и/или режим.

Обычная последовательность действий для восстановления базы данных из файла дампа:

my %hash;
my $db = tie %hash, 'GDBM_File', 'a.db', GDBM_NEWDB, 0640;
$db->load('a.dump');

УСТОЙЧИВОСТЬ К СБОЯМ

Устойчивость к сбоям — это новая функция, которая, при соответствующей поддержке со стороны ОС и файловой системы, гарантирует, что можно восстановить логически согласованное последнее состояние базы данных после сбоя, например, при отключении питания, панике ядра ОС и т. п.

Поддержка устойчивости к сбоям появилась в версии gdbm 1.21. Теория, лежащая в её основе, изложена в статье «Crashproofing the Original NoSQL Key-Value Store» Теренса Келси (https://queue.acm.org/detail.cfm?id=3487353). Подробное обсуждение реализации gdbm доступно в руководстве GDBM (https://www.gnu.org.ua/software/gdbm/manual/Crash-Tolerance.html). Ниже приведена информация об интерфейсе Perl.

Для максимальной надёжности рекомендуется использовать расширенный формат базы данных для баз данных, устойчивых к сбоям. Для создания базы данных в расширенном формате используйте GDBM_NEWDB|GDBM_NUMSYNC при открытии базы данных, например:

$db = tie %hash, 'GDBM_File', $filename,
          GDBM_NEWDB|GDBM_NUMSYNC, 0640;

Для преобразования существующей базы данных в расширенный формат используйте метод convert, описанный выше, например:

$db->convert(GDBM_NUMSYNC);

crash_tolerance_status

GDBM_File->crash_tolerance_status;

Этот статический метод возвращает состояние поддержки устойчивости к сбоям. ненулевое значение означает, что устойчивость к сбоям скомпилирована и поддерживается операционной системой.

failure_atomic

$db->failure_atomic($even, $odd)

Включает устойчивость к сбоям для базы данных $db. Аргументы — имена путей двух файлов, которые будут созданы и заполнены мгновенными снимками файла базы данных. Эти файлы не должны существовать при вызове этого метода и должны находиться в той же файловой системе, что и файл базы данных. Эта файловая система должна поддерживать операцию reflink (https://www.gnu.org.ua/software/gdbm/manual/Filesystems-supporting-crash-tolerance.html>.

После успешного вызова failure_atomic каждый вызов метода $db-sync> создаст эффективный мгновенный снимок файла базы данных в одном из этих файлов; последовательные вызовы sync чередуются между двумя файлами, отсюда и названия.

Самый последний из этих файлов можно использовать для восстановления базы данных после сбоя. Для выбора правильного снимка используйте статический метод latest_snapshot.

latest_snapshot

$file = GDBM_File->latest_snapshot($even, $odd);

($file, $error) = GDBM_File->latest_snapshot($even, $odd);

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

В скалярном контексте возвращает выбранное имя файла или undef в случае неудачи.

В контексте массива возвращает список из двух элементов: имя файла и код состояния. При успехе имя файла определено, а код равен GDBM_SNAPSHOT_OK. При ошибке имя файла равно undef, а состояние — одно из следующих:

GDBM_SNAPSHOT_BAD

Ни один из файлов снимка неприменим. Это означает, что сбой произошёл до завершения вызова failure_atomic. В этом случае лучше всего обратиться к безопасной резервной копии файла данных.

GDBM_SNAPSHOT_ERR

Произошла системная ошибка. Проверьте $! для получения подробностей. См. <https://www.gnu.org.ua/software/gdbm/manual/Crash-recovery.html> для получения полного списка кодов ошибок и их значений.

GDBM_SNAPSHOT_SAME

Режимы файлов и даты изменения обоих файлов снимка идентичны. Это может произойти только для баз данных в стандартном формате.

GDBM_SNAPSHOT_SUSPICIOUS

Счётчики numsync двух снимков отличаются более чем на один. Наиболее вероятная причина — ошибка программиста: два параметра относятся к снимкам, принадлежащим различным файлам базы данных.

ДОСТУПНОСТЬ

gdbm доступен из любого архива GNU. Основной сайт — ftp.gnu.org, но настоятельно рекомендуется использовать один из многочисленных зеркал. Список зеркал можно получить по адресу http://www.gnu.org/order/ftp.html.

БЕЗОПАСНОСТЬ И ПЕРЕНОСИМОСТЬ

Файлы GDBM не переносятся между платформами. Если вы хотите передать файл GDBM по сети, сначала преобразуйте его в переносимый формат.

Не принимайте файлы GDBM из ненадежных источников.

Надёжность GDBM при повреждении баз данных сильно зависит от версии. Версии до 1.15 не реализовывали проверки достоверности, поэтому повреждённый или специально составленный файл базы данных мог привести к сбою perl или даже к раскрытию уязвимости. Версии между 1.15 и 1.20 постепенно усиливались для защиты от недействительных входных данных. Наконец, версия 1.21 прошла обширные проверки на наличие ошибок, которые подтвердили её способность противостоять любому типу входных данных без сбоев.

СМОТРИТЕ ТАКЖЕ

perl(1), DB_File(3), perldbmfilter, gdbm(3), https://www.gnu.org.ua/software/gdbm/manual.html.