Manual Pages  — HCREATE

hcreate, hcreate_r, hdestroy, hdestroy_r, hsearch, hsearch_r – manage hash search table

LIBRARY SYNOPSIS DESCRIPTION RETURN VALUES EXAMPLES ERRORS SEE ALSO STANDARDS HISTORY BUGS

Standard C Library (libc, -lc)

#include <search.h>

int
hcreate(size_t nel);

int
hcreate_r(size_t nel, struct hsearch_data *table);

void
hdestroy(void);

void
hdestroy_r(struct hsearch_data *table);

ENTRY *
hsearch(ENTRY item, ACTION action);

int
hsearch_r(ENTRY item, ACTION action, ENTRY ** itemp, struct hsearch_data *table);

The hcreate() and hcreate_r() functions return 0 if the table creation failed and the global variable errno is set to indicate the error; otherwise, a non-zero value is returned.

The hdestroy() and hdestroy_r() functions return no value.

The hsearch() and hsearch_r() functions return a NULL pointer if either the action is FIND and the item could not be found or the action is ENTER and the table is full.

The following example reads in strings followed by two numbers and stores them in a hash table, discarding duplicates. It then reads in strings and finds the matching entry in the hash table and prints it out.

#include <stdio.h>
#include <search.h>
#include <string.h>
#include <stdlib.h>

struct info {                   /* This is the info stored in the table */
        int age, room;          /* other than the key. */
};

#define NUM_EMPL        5000    /* # of elements in search table. */

int
main(void)
{
        char str[BUFSIZ]; /* Space to read string */
        struct info info_space[NUM_EMPL]; /* Space to store employee info. */
        struct info *info_ptr = info_space; /* Next space in info_space. */
        ENTRY item;
        ENTRY *found_item; /* Name to look for in table. */
        char name_to_find[30];
        int i = 0;

        /* Create table; no error checking is performed. */
        (void) hcreate(NUM_EMPL);

        while (scanf("%s%d%d", str, &info_ptr->age,
            &info_ptr->room) != EOF && i++ < NUM_EMPL) {
                /* Put information in structure, and structure in item. */
                item.key = strdup(str);
                item.data = info_ptr;
                info_ptr++;
                /* Put item into table. */
                (void) hsearch(item, ENTER);
        }

        /* Access table. */
        item.key = name_to_find;
        while (scanf("%s", item.key) != EOF) {
                if ((found_item = hsearch(item, FIND)) != NULL) {
                        /* If item is in the table. */
                        (void)printf("found %s, age = %d, room = %d\n",
                            found_item->key,
                            ((struct info *)found_item->data)->age,
                            ((struct info *)found_item->data)->room);
                } else
                        (void)printf("no such employee %s\n", name_to_find);
        }
        hdestroy();
        return 0;
}

The hcreate(), hcreate_r(), hsearch(), and hsearch_r() functions will fail if:

[ENOMEM]
	Insufficient memory is available.

The hsearch() and hsearch_r() functions will also fail if the action is FIND and the element is not found:

[ESRCH]
	The item given is not found.

The hcreate(), hdestroy(), and hsearch() functions conform to -xpg4.2.

The hcreate(), hdestroy(), and hsearch() functions first appeared in AT&T V . The hcreate_r(), hdestroy_r() and hsearch_r() functions are GNU extensions.

The original, non- GNU interface permits the use of only one hash table at a time.