hsearch

, hcreate

, hdestroy

- manage hash search tables

Synopsis

#include <search.h>
ENTRY *hsearch(ENTRYitem, ACTIONaction);

inthcreate(size_tmekments);

voidhdestroy(void);

Description

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 item.data 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 hcreate() function allocates sufficient space for the table, and must be
called before hsearch() is used. The nel argument is an estimate
of the maximum number of entries that the table will contain. This
number may be adjusted upward by the algorithm in order to obtain certain
mathematically favorable circumstances.

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

Return Values

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.

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

Usage

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

Only one hash search table may be active at any given time.

Examples

Example 1 Example to read in strings.

The following example will read in strings followed by two numbers and
store them in a hash table, discarding duplicates. It will then read
in strings and find the matching entry in the hash table and
print it.