Computer Science
HSEARCH(3) Linux Programmer's Manual HSEARCH(3)
NAME
hcreate, hdestroy, hsearch - hash table management
SYNOPSIS
#include <search.h>
ENTRY *hsearch(ENTRY item, ACTION action);
int hcreate(unsigned nel);
void hdestroy(void);
DESCRIPTION
These three functions allow the user to create a hash
table which associates a key with any data.
First the table must be created with the function hcre-
ate(). nel is an estimate of the number of entries in the
table. hcreate() may adjust this value upward to improve
the performance of the resulting hash table. The GNU
implementation of hsearch() will also enlarge the table if
it gets nearly full. malloc(3) is used to allocate space
for the table.
The corresponding function hdestroy() frees the memory
occupied by the hash table so that a new table can be con-
structed.
item is of type ENTRY, which is a typedef defined in
<search.h> and includes these elements:
typedef struct entry
{
char *key;
char *data;
} ENTRY;
key points to the zero-terminated ASCII string which is
the search key. data points to the data associated with
that key. (A pointer to a type other than character
should be cast to pointer-to-character.) hsearch()
searches the hash table for an item with the same key as
item, and if successful returns a pointer to it. action
determines what hsearch() does after an unsuccessful
search. A value of ENTER instructs it to insert the new
item, while a value of FIND means to return NULL.
RETURN VALUE
hcreate() returns NULL if the hash table cannot be suc-
cessfully installed.
hsearch() returns NULL if action is ENTER and there is
insufficient memory to expand the hash table, or action is
FIND and item cannot be found in the hash table.
CONFORMS TO
SVID, except that in SysV, the hash table cannot grow.
BUGS
The implementation can manage only one hash table at a
time. Individual hash table entries can be added, but not
deleted.
EXAMPLE
The following program inserts 24 items in to a hash table,
then prints some of them.
#include <stdio.h>
#include <search.h>
char *data[]={ "alpha", "bravo", "charley", "delta",
"echo", "foxtrot", "golf", "hotel", "india", "juliette",
"kilo", "lima", "mike", "november", "oscar", "papa",
"quebec", "romeo", "sierra", "tango", "uniform",
"victor", "whiskey", "x-ray", "yankee", "zulu"
};
int main()
{
ENTRY e, *ep;
int i;
/* start with small table, and let it grow */
hcreate(3);
for (i = 0; i < 24; i++)
{
e.key = data[i];
/* data is just an integer, instead of a pointer
to something */
e.data = (char *)i;
ep = hsearch(e, ENTER);
/* there should be no failures */
if(ep == NULL) {fprintf(stderr, "entry failed\n"); exit(1);}
}
for (i = 22; i < 26; i++)
/* print two entries from the table, and show that
two are not in the table */
{
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);
}
return 0;
}
SEE ALSO
bsearch(3), lsearch(3), tsearch(3), malloc(3)
GNU September 30, 1995 1
Back to the index