DragonFly On-Line Manual Pages

HCREATE(3)            DragonFly Library Functions Manual            HCREATE(3)

NAME
     hcreate, hdestroy, hsearch - manage hash search table

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <search.h>

     int
     hcreate(size_t nel);

     void
     hdestroy(void);

     ENTRY *
     hsearch(ENTRY item, ACTION action);

DESCRIPTION
     The hcreate(), hdestroy(), and hsearch() functions manage hash search
     tables.

     The hcreate() function allocates sufficient space for the table, and the
     application should ensure it is called before hsearch() is used.  The nel
     argument is an estimate of the maximum number of entries that the table
     should contain.  This number may be adjusted upward by the algorithm in
     order to obtain certain mathematically favorable circumstances.

     The hdestroy() function disposes of the search table, and may be followed
     by another call to hcreate().  After the call to hdestroy(), the data can
     no longer be considered accessible.

     The hsearch() function is a hash-table search routine.  It returns a
     pointer into a hash table indicating the address of an item.  The item
     argument is of type ENTRY, defined in the <search.h> header.  This is a
     structure type that contains two pointers:

           char *key   comparison key; the comparison function is strcmp(3)
           void *data  pointer to data associated with key

     The action argument is of type ACTION, an enumeration type which defines
     the following values:

           ENTER  Insert item into the hash table.  If an existing item with
                  the same key is found, it is not replaced.  Note that the
                  key and data elements of item are used directly by the new
                  table entry.  The storage for the key must not be modified
                  during the lifetime of the hash table.

           FIND   Search the hash table without inserting item.

RETURN VALUES
     The hcreate() function returns 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() function does not return a value.

     The hsearch() function returns 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.  If the action is ENTER and an entry already existed in the
     table matching the given key, the existing entry is returned and is not
     replaced.

EXAMPLES
     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 string_space[NUM_EMPL*20];         /* Space to read string */
             struct info info_space[NUM_EMPL];       /* Space to store employee info */
             char *str_ptr = string_space;           /* Next space in string_space */
             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_ptr, &info_ptr->age,
                 &info_ptr->room) != EOF && i++ < NUM_EMPL) {
                     /* Put information in structure, and structure in item. */
                     item.key = str_ptr;
                     item.data = info_ptr;
                     str_ptr += strlen(str_ptr) + 1;
                     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. */
                             printf("found %s, age = %d, room = %d\n",
                                 found_item->key,
                                 ((struct info *)found_item->data)->age,
                                 ((struct info *)found_item->data)->room);
                     } else
                             printf("no such employee %s\n", name_to_find);
             }

             hdestroy();
             return 0;
     }

ERRORS
     The hcreate() and hsearch() functions may fail if:

     [ENOMEM]           Insufficient storage space is available.

     [EINVAL]           A table already exists.

SEE ALSO
     bsearch(3), lsearch(3), malloc(3), strcmp(3), tsearch(3)

STANDARDS
     The hcreate(), hdestroy(), and hsearch() functions conform to X/Open
     Portability Guide Issue 4, Version 2 ("XPG4.2").

HISTORY
     The hcreate(), hdestroy(), and hsearch() functions first appeared in AT&T
     System V UNIX.

BUGS
     The interface permits the use of only one hash table at a time.

DragonFly 6.5-DEVELOPMENT       October 4, 2026      DragonFly 6.5-DEVELOPMENT