man pages section 3: Basic Library Functions

Exit Print View

Updated: July 2014



hsearch, hcreate, hdestroy - manage hash search tables


#include <search.h>

ENTRY *hsearch(ENTRY item, ACTION action);
int hcreate(size_t mekments);
void hdestroy(void);


The hsearch() function is a hash-table search routine generalized from Knuth (6.4) Algorithm D. It returns a pointer into a hash table indicating the location at which an entry can be found. The comparison function used by hsearch() is strcmp() (see string(3C)). The item argument is a structure of type ENTRY (defined in the <search.h> header) containing two pointers: item.key points to the comparison key, and points to any other data to be associated with that key. (Pointers to types other than void should be cast to pointer-to-void.) The action argument is a member of an enumeration type ACTION (defined in <search.h>) indicating the disposition of the entry if it cannot be found in the table. ENTER indicates that the item should be inserted in the table at an appropriate point. Given a duplicate of an existing item, the new item is not entered and hsearch() returns a pointer to the existing item. FIND indicates that no entry should be made. Unsuccessful resolution is indicated by the return of a null pointer.


The hdestroy() function destroys the search table, and may be followed by another call to hcreate().

Return Values


The hcreate() function returns 0 if it cannot allocate sufficient space for the table.


The hsearch() and hcreate() functions use malloc(3C) to allocate space.



Example 1 Example to read in strings.


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

main( )
                        /* space to store strings */
        char string_space[NUM_EMPL*20];
                        /* space to store employee info */
        struct info info_space[NUM_EMPL];
                        /* next avail space in string_space */
        char *str_ptr = string_space;
                        /* next avail space in info_space */
        struct info *info_ptr = info_space;
        ENTRY item, *found_item;
                        /* name to look for in table */
        char name_to_find[30];
        int i = 0;

                        /* create table */
        (void) hcreate(NUM_EMPL);
        while (scanf("%s%d%d", str_ptr, &info_ptr−>age,
               &info_ptr−>room) != EOF && i++ < NUM_EMPL) {
                item.key = str_ptr;
       = (void *)info_ptr;
                str_ptr += strlen(str_ptr) + 1;
                        /* put item into table */
                (void) hsearch(item, ENTER);

                        /* access table */
        item.key = name_to_find;
                        /* if item is in the table */
                        ((struct info *)found_item−>data)−>age,
                        ((struct info *)found_item−>data)−>room);
            } else {
        return 0;


See attributes(5) for descriptions of the following attributes:

Interface Stability

See also

bsearch(3C), lsearch(3C), malloc(3C), string(3C), tsearch(3C), malloc(3MALLOC), attributes(5), standards(5)
