Разработка приложений в среде Linux. Второе издание - Майкл Джонсон

Если последний параметр, 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

$ ./phones -a Barbara 227-2272

$ ./phones -q Larry

Larry 527-7976

$ ./phones -l

Larry 527-7976

Erik 374-5876

Michael 642-4235

Barbara 227-2272

$ ./phones -d Michael

$ ./phones -l

Larry 527-7976

Erik 374-5876

Barbara 227-2272

Эта программа выполняет определенные полезные действия, состоит менее чем из 200 строк исходного кода, и с успехом может применяться для работы с большим количеством пар "ключ-значение", четко раскрывая назначение библиотеки qdbm.

  1: /* phones.с */

  2:

  3: /* Программа реализует очень простую базу данных телефонных номеров.

  4: Всю необходимую информацию по ее использованию можно найти в тексте. */

  5:

  6: #include <alloca.h>

  7: #include <depot.h>

  8: #include <errno.h>

  9: #include <fcntl.h>

 10: #include <stdio.h>

 11: #include <stdlib.h>

 12: #include <string.h>

 13: #include <unistd.h>

 14:

 15: void usage(void) {

 16:  fprintf(stderr, "использование: phones -a [-f] <имя> <телефон>n");

 17:  fprintf(stderr, " -d <имя>n");

 18:  fprintf(stderr, " -q <имя>n");

 19:  fprintf(stderr, " -ln");

 20:  exit(1);

 21: }

 22:

 23: /* Открыть базу данных $НОМЕ/.phonedb. Если writeable имеет ненулевое

 24:    значение, база данных открывается для обновления. Если writeable

 25:    равен 0, база данных открывается только для чтения. */

 26: DEPOT * openDatabase(int writeable) {

 27:  DEPOT * dp;

 28:  char * filename;

 29:  int flags;

 30:

 31:  /* Установить режим открытия */

 32:  if (writeable) {

 33:   flags = DP_OWRITER | DP_OCREAT;

 34:  } else {

 35:   flags = DP_OREADER;

 36:  }

 37:

 38:  filename = alloca(strlen(getenv("HOME")) + 20);

 39:  strcpy(filename, getenv("HOME"));

 40:  strcat(filename, "/.phonedb");

 41:

 42:  dp = dpopen(filename, flags, 0);