Если последний параметр, dataSize
, не будет равен NULL
, то целое число, на которое он указывает, будет соответствовать количеству прочитанных байтов.
В случае сбоя эта функция возвращает NULL
, а в случае успешного завершения она возвращает указатель на прочитанные данные. В случае сбоя dpcode
сообщает о том, что стало причиной сбоя. В частности, если элемент не существует или имеет менее start
байтов данных, dpcode
будет присвоено DP_ENOITEM
.
Когда функция dpget()
возвращает данные, к ним добавляется байт 0
, позволяя работать с ними как со строкой. Размещение указателя производится с помощью функции malloc()
, и приложение отвечает за освобождение памяти после завершения своей работы. Если приложениям необходимо поместить данные в буфер, вместо того чтобы Depot
размещала его с помощью функции malloc()
, то они должны использовать функцию dpgetwb()
.
int dpgetwb(DEPOT * depot, const char * key, int keySize, int start,
int max, const char * data);
Функции dpgetwb()
и dpget()
отличаются друг от друга только двумя параметрами: max
(который интерпретируется по-разному) и data
(который заменяет параметр dataSize
из функции dpgetwb()
). Параметр data
должен указывать на буфер из max
байтов, в который функция dpgetwb()
будет помещать данные, прочитанные из базы данных. В функции dpgetwb()
параметр max
не должен иметь значение -1
, и буфер не будет иметь байт 0
, автоматически добавляемый в него этой функцией. Функция dpgetwb()
возвращает количество байтов, хранящихся в data
, и -1
, если запись не была найдена, если данных оказалось меньше start
байтов или если возникла ошибка.
25.3.2. Последовательное чтение записей
С помощью функций dpiterinit()
и dpiternext()
приложения могут производить итерации по всем ключам в базе данных. Ключи не возвращаются в каком-то определенном порядке[180], а базу данных не нужно модифицировать во время итераций, производимых приложением.
int dpiterinit(DEPOT * depot);
char * dpiternext(DEPOT * depot, int * keySize);
В результате вызова функции dpiterinit() qdbm
вернет первый ключ в базе данных во время следующего вызова функции dpiternext()
.
Функция dpiternext()
возвращает указатель либо на первый ключ в базе данных (если только что была вызвана функция dpiterinit()
), либо ключ в базе данных, который следует за ключом, возвращенным в последний раз. Если же в базе данных больше не окажется ключей, будет возвращено NULL
. Если keySize
не равен NULL
, то целочисленное значение, на которое указывает этот параметр, будет задано в качестве размера возвращаемого ключа.
Функция dpiternext()
буфера возвращает указатель на размещение, выполненное функцией malloc()
; после того как приложение завершит работу с ключом, указатель необходимо освободить функцией free()
. Буфер также завершается NULL
, поэтому при необходимости его можно трактовать как строку.
25.4. Модификация базы данных
Предусмотрены две операции, которые модифицируют базу данных qdbm
: добавление записей и удаление записей. Обновление записей производится с помощью той же функции, что и добавления записей.
25.4.1. Добавление записей
Новые и обновленные записи заносятся в базу данных с использованием функции dpput()
.
int dpput(DEPOT * dfepot, const char * key, int keySize, const char * data,
int dataSize, int dmode);
key
представляет собой значение индекса, который впоследствии может использоваться для получения информации, на которую указывает data
. Параметры keySize
и dataSize
могут иметь значение -1
, при котором функция dpput()
будет использовать функцию strlen()
для получения размера данного поля. Проверка параметра dmode
производится только в том случае, если параметр key
в базе данных уже связан с элементом данных. Параметр dmode
может иметь одно из перечисленных ниже значений.
DP_DCAT |
Новые данные добавляются в конец данных, которые уже находятся в базе данных. |
DP_DKEEP |
База данных не модифицируется; функция dpput() возвращает сбой, а параметру dpecode присваивается значение DP_EKEEP . |
DP_DOVER |
Вместо существующего значения записывается новое. |
Функция dpput()
возвращает нулевое значение в случае возникновения ошибки (или если ключ уже существует, и было определено значение DP_DKEEP
), и ненулевое значение, если данные для ключа были успешно обновлены.
25.4.2. Удаление записей
Удаление записей из базы данных осуществляется путем вызова функции dpout()
и передачи ей ключа, данные которого необходимо удалить.
int dpout(DEPOT * depot, const char * key, int keySize);
Заданный ключ и связанные с ним данные удаляются из базы, после чего возвращается ненулевое значение. Если для заданного ключа данные не существовали, возвращается нулевое значение. Как и для всех остальных функций, принимающих ключ, если параметр keySize
равен -1
, то функция dpout()
использует strlen()
для определения длины ключа.
25.5. Пример
Для закрепления материала этой главы ниже приводится пример приложения, в котором задействовано большинство функциональных возможностей qdbm
. Подразумевается, что в результате выполнения этого приложения будет создана простая база данных телефонных номеров, хотя ее можно использовать и для хранения любых простых пар "имя-значение". Приложение хранит базу данных в домашнем каталоге пользователя как .phonedb
.
Флаг -а
добавляет запись в базу данных. Если будет указан флаг -f
, то любой существующий элемент будет заменен новыми данными. Следующий параметр представляет собой значение ключа, которое необходимо использовать, а последний параметр — собственно данные (номер телефона).
Флаг -q
запрашивает в базе данных определенный ключ, который должен быть представлен другим указанным параметром. Записи удаляются из базы данных с помощью флага -d
, который принимает значение ключа для удаления в другом параметре.
Если задать флаг -l
, то будут перечислены все пары "ключ-значение", имеющиеся в базе данных.
Вот как выглядят пример использования phones
.
$ ./phones -a Erik 374-5876
$ ./phones -a Michael 642-4235
$ ./phones -a Larry 527-7976
180
Вернее, они возвращаются в том порядке, в котором производятся ссылки на элементы из хеш-области. Хотя это и есть порядок, он является совершенно бесполезным.