GDBM_File

СОДЕРЖАНИЕ

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

НАЗВАНИЕ

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 переменная), связанный с этой базой данных,

описание_ошибки

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

отобразить_в_памяти

$db->mmap;

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

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

mmapразмер

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

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

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

recover

$db->recover(%args);

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

err => sub { ... }

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

backup => \$str

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

max_failed_keys => $n

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

max_failed_buckets => $n

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

max_failures => $n

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

stat => \%hash

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

recovered_keys

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

recovered_buckets

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

failed_keys

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

failed_buckets

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

convert

$db->convert($format);

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

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

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

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

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

dump

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

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

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

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

Эти значения по умолчанию могут быть изменены с помощью следующих %options:

binary => 1

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

mode => MODE

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

overwrite => 1

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

load

$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.