---

   hcreate_r - операции над

---

Other Alias

---

ОБЗОР

#include <search.h>

---

ОПИСАНИЕ

Функции hcreate_r(), hsearch_r() и hdestroy_r() являются реентерабильными версиями, позволяющими программе создавать более одного массива поиска одномоментно. Последний параметр, htab, указывает на структуру, описывающую массив, с которым работает функция. Программист должен считать, что не знает её формат (т. е., не должен пытаться напрямую читать и изменять её поля).

Сначала, хэш должен быть создан с помощью функции hcreate(). В аргументе nel указывается предполагаемое максимальное количество элементов в массиве (данный максимум нельзя изменить позже, указывайте значение с запасом). Реализация функции может изменить этот параметр для повышения быстродействия массива.

Функция hcreate_r() выполняет тоже, что и hcreate(), но для массива, описанного в структуре *htab. Перед вызовом hcreate_r() структура, на которую указывает htab, должна быть обнулена.

Функция hdestroy() освобождает память, занимаемую массивом, созданным hcreate(). После вызова hdestroy() функцией hcreate() можно создать новый массив. Функция hdestroy_r() выполняет аналогичную задачу для массива, описанного в *htab, который был ранее создан hcreate_r().

Функция hsearch() ищет в массиве элемент с ключом, равным item («равенство» определяется функцией strcmp(3)), и, в случае удачного завершения операции, возвращает указатель на него.

Аргумент item имеет тип ENTRY, который определён в <search.h> следующим образом:

typedef struct entry {
    char *key;
    void *data;
} ENTRY;

Поле key указывает на оканчивающуюся null строку, используемую в качестве ключа для поиска. Поле data указывает на данные, связанные с ключом.

Аргумент action определяет действие, выполняемое hsearch() после неудачного поиска. Его значением должно быть ENTER (указывает, что нужно вставить копию item и вернуть указатель на новый элемент массива) или FIND (нужно вернуть NULL). Если значение action равно FIND, то поле data игнорируется.

Функция hsearch_r() подобна hsearch(), но работает с массивом, указанным в *htab. Функция hsearch_r() отлична от hsearch() в том, что указатель найденного элемента возвращается в *retval, а не как результат работы функции.

---

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Функция hsearch() при успешном выполнении возвращает указатель на элемент массива. При ошибке возвращается NULL, то есть, если action равно ENTER массив полон, или, если action равно FIND и item не может быть найден в массиве. Функция hsearch_r() возвращает 0 в случае ошибки или ненулевое значение при успешном выполнении. При ошибке данные функции присваивают errno код ошибки.

---

ОШИБКИ

Функции hcreate_r() и hdestroy_r() могут завершиться с ошибкой по следующим причинам:

EINVAL Значение htab равно NULL.

Функции hsearch() и hsearch_r() могут завершиться с ошибкой по следующим причинам:

ENOMEM Значение action равно ENTER, значение key не найдено в массиве и в массиве нет места под новый элемент.

ESRCH Значение action равно FIND и значение key не найдено в массиве.

В POSIX.1 определена только ошибка ENOMEM.

---

АТРИБУТЫ

Интерфейс Атрибут Значение
hcreate(), hsearch(),
hdestroy() безвредность в потоках: небезопасно (MT-Unsafe race:hsearch)
hcreate_r(), hsearch_r(),
hdestroy_r() безвредность в потоках: безвредно (MT-Safe race:htab)

---

СООТВЕТСТВИЕ СТАНДАРТАМ

Функции hcreate_r(), hsearch_r() и hdestroy_r() являются расширениями GNU.

---

ЗАМЕЧАНИЯ

Функции hdestroy() и hdestroy_r() не освобождают буферы, на которые указывают элементы key и data в массиве (это невозможно сделать, так как неизвестно, были ли выделены эти буферы динамически). Если эти буферы требуется освобождать (возможно, из-за того, что программа много раз создаёт и удаляет массивы, а не создаёт один массив на всё время работы), то программа должна предусмотреть хранилище под используемые структуры, которое позволило бы их освободить.

ДЕФЕКТЫ

Можно добавлять элементы массива, но не удалять.

---

ПРИМЕР

Следующая программа вставляет в массив 24 элемента, а затем выводит на печать некоторые из них:

#include <stdio.h>
#include <stdlib.h>
#include <search.h>
static char *data[] = { "alpha", "bravo", "charlie", "delta",
     "echo", "foxtrot", "golf", "hotel", "india", "juliet",
     "kilo", "lima", "mike", "november", "oscar", "papa",
     "quebec", "romeo", "sierra", "tango", "uniform",
     "victor", "whisky", "x-ray", "yankee", "zulu"
};
int
main(void)
{
    ENTRY e, *ep;
    int i;
    hcreate(30);
    for (i = 0; i < 24; i++) {
        e.key = data[i];
        /* data — это просто целое число, а не
           указатель на что-то */
        e.data = (void *) i;
        ep = hsearch(e, ENTER);
        /* здесь ошибки быть не должно */
        if (ep == NULL) {
            fprintf(stderr, "ошибка элемента\n");
            exit(EXIT_FAILURE);
        }
    }
    for (i = 22; i < 26; i++) {
        /* показать два элемента массива и
           два не из массива */
        e.key = data[i];
        ep = hsearch(e, FIND);
        printf("%9.9s -> %9.9s:%d\n", e.key,
               ep ? ep->key : "NULL", ep ? (int)(ep->data) : 0);
    }
    hdestroy();
    exit(EXIT_SUCCESS);
}